# Credits

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

SimpleSMS 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. A
  balance of zero does not move you back; calls are refused with a `402`
  until you add credits.
- Credits do not expire while your account is open.

## What draws credits

| | Drawn |
| --- | --- |
| Outbound SMS | $0.009 per message 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. |

The per-message rate includes carrier fees. Registration and vetting fees are
separate, charged at cost, and are not drawn from credits (see
[Pricing](/docs/pricing)).

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.009, 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": 9000,
    "top_up_url": "https://joinsimplesms.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.

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://joinsimplesms.com/console/billing" } }
```

## 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.

## Balance API

```bash
curl https://api.joinsimplesms.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://joinsimplesms.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.