# Credits

Source: https://jointextkit.com/docs/credits
Index: https://jointextkit.com/llms.txt

TextKit is prepaid. You buy credits with a card, usage draws your balance
down, and a call your balance cannot cover is refused instead of being sent
on account. Add credits in [Console → Billing](/console/billing).

## Buying credits

- Pick $10, $20, $50 or $100, or any amount from $5 to $1,000.
- Your card is saved by the purchase so auto-recharge can use it.
- Your first purchase moves the account off the free tier: every cap is
  lifted, you can text any number, and live carrier lookups are unlocked.
  It is also needed before you can buy a number. A balance of zero does not move you back; calls are refused with
  a `402` until you add credits.
- Promotional credit (a grant from us) does not count as that first
  purchase: on its own it does not buy a number. After your first purchase it
  is drawn like any other credit.
- Credits do not expire while your account is open.

## What draws credits

| | Drawn |
| --- | --- |
| Outbound SMS | $0.0032 per segment, plus the carrier fee per segment, when the carrier accepts it. Drawn before the send and returned if the carrier rejects it or every automatic retry fails. |
| Phone number | $0.95 when you buy a number and every month after, on the same day. Not prorated. |
| Carrier lookup | $0.008 per lookup; returned if the lookup fails. |
| Verification | $0.025 per successful verification only. |
| Inbound SMS | Nothing. Inbound messages are never refused or delayed for lack of credits. |
| Sandbox (test keys) | Nothing, ever. |
| Free-tier allowance | Nothing. |

Carrier fees are passed through at cost, per segment ([the table](/docs/pricing)). Registration fees (brand,
vetting, the monthly campaign fee) are separate and are
**never drawn from credits**: they go on their own invoice, charged to your
saved card or emailed with 14 days to pay. They are listed under
**Registration fees** on Billing. See
[Compliance & registration](/docs/compliance#registration-fees).

Each month you get a statement that itemises usage; your credits pay it.

## When the balance cannot cover a call

The call answers `402` and nothing is sent or charged:

```json
{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits: your balance is $0.00 and this message costs $0.0082, so it was not done and you were not charged. Add credits in the console (Billing), or turn on auto-recharge there.",
    "balance_micro_usd": 4000,
    "required_micro_usd": 8200,
    "top_up_url": "https://jointextkit.com/console/billing",
    "failure": { "code": "insufficient_credits", "title": "Out of credits", "explanation": "...", "action": "Recommended: ...", "carrier_code": null }
  }
}
```

Amounts are micro-dollars (millionths of a dollar). The same code comes back
from every billable call: sending a message, starting a verification, a
lookup, and buying a number.

With auto-recharge on, a call the balance cannot cover first adds your
auto-recharge amount from the saved card and then goes ahead (buying a
number included). Only if that charge fails is the call refused: the 402
then also carries `auto_recharge`: `declined` (the card was refused and
auto-recharge is now off) or `unavailable` (the card could not be reached;
it stays on).

Queued work is not dropped silently and is not retried for you:

- **Scheduled messages** that come due with too few credits fail with
  `insufficient_credits`. Schedule them again after topping up.
- **Batches and broadcasts** keep running; each row the balance cannot cover
  fails with `insufficient_credits` and the results say so. Use "Retry
  failed" (or `POST /v1/batches/{id}/retry`) after topping up.
- **Automations** fail the step with `insufficient_credits`.
- **Number renewals**: if a number's monthly fee cannot be covered, the
  number is kept, never released. Outbound from the account is paused until
  you add credits, and the fee is taken then.

## Alerts

Each fires once, and is re-armed when a top-up lifts the balance back over
the mark. We email the account's owner and admins and send a [webhook event](/docs/webhooks):

| Event | When |
| --- | --- |
| `credits.low` | The balance fell below your alert threshold ($5 unless you change it in Billing). |
| `credits.depleted` | The first call refused for lack of credits (or a number fee that could not be covered: `reason` is `number_fee`). |
| `credits.auto_recharge_failed` | Your card was declined; auto-recharge has been switched off. |
| `credits.topped_up` | Credits were added (`source`: `topup`, `auto_recharge` or `grant`). |

```json
{ "type": "credits.low",
  "data": { "balance_usd": 4.99, "balance_micro_usd": 4991000, "threshold_usd": 5, "top_up_url": "https://jointextkit.com/console/billing" } }
```

## Receipts

Every payment is confirmed by email to the account's owner and admins,
once, however many ways the payment reaches us:

- **Credits bought** (a top-up or an auto-recharge): the amount, the card's
  brand and last four, the date, the balance after, and a link to the
  payment's receipt page.
- **A monthly statement** your credits did not cover: the amount and the invoice.
- **A refund**: the amount and the card it goes back to. Banks usually show
  it within 5 to 10 business days. The credits it bought come off the balance.
- **A live number** bought (the first month, taken from credits, and when it
  renews) or released (its monthly fee stops).

Promotional credits send no receipt. Billing email is sent whatever your
email preferences: it is how you know what was charged.

## Auto-recharge

Off by default. Turn it on in Billing: "when the balance falls below $X, add
$Y", charged to your saved card. If the card is declined, auto-recharge
switches itself off, you are told, and it stays off until you turn it back on.

## Disputed payments

If a payment to us is disputed with the card issuer (a chargeback),
auto-recharge switches off and anything that draws on your credits is
refused with `insufficient_credits` and a message saying a payment is
disputed, until the dispute is resolved (or we lift the pause sooner).
If the dispute is decided in the cardholder's favor, the credits that
payment bought that are still unused come off the balance. Number renewals
continue.

## Balance API

```bash
curl https://api.jointextkit.com/v1/balance -H "Authorization: Bearer ssms_sk_live_..."
```

```json
{
  "object": "balance",
  "balance_micro_usd": 12340000,
  "balance_usd": 12.34,
  "currency": "usd",
  "low_balance_usd": 5,
  "auto_recharge": { "enabled": false, "threshold_usd": 10, "amount_usd": 20 },
  "top_up_url": "https://jointextkit.com/console/billing"
}
```

A restricted key needs the `billing` scope. The credit history is available
as CSV from `GET /v1/exports/credit_history`.

Credits work alongside a [spend limit](/docs/spend-limits): the limit is
checked first, then the balance.