Credits

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.

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

The per-message rate includes carrier fees. Registration and vetting fees are separate, charged at cost, and are not drawn from credits (see 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:

{
  "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:

{ "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

curl https://api.joinsimplesms.com/v1/balance -H "Authorization: Bearer ssms_sk_live_..."

{
  "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: the limit is checked first, then the balance.