# Spend limits

Source: https://joinsimplesms.com/docs/spend-limits
Index: https://joinsimplesms.com/llms.txt

Set a monthly cap in USD and live messages stop at it instead of running up
a bill. Alerts fire as you approach it. Set it in
[Console → Settings](/console/settings) (admins) or with the API.

## How it works

- Each live outbound message counts at the published rate
  ($0.009) against this month's estimated spend, **before** it is sent. If it
  would take you past the cap, it is not sent and you are not charged.
- A message the carrier rejects is refunded against the cap, as it is on your
  bill.
- The month resets on the 1st, UTC.
- Sandbox (test keys) is free and never counted. Free-tier accounts are
  capped by their quota and cost nothing.
- The cap covers outbound messages. Numbers, lookups, and verifications are
  billed as usual and are not counted toward it.
- The estimate is for your protection; your invoice is the source of truth.

When the cap is reached, sends answer:

```json
{
  "error": {
    "code": "spend_limit_reached",
    "message": "Monthly spend limit reached: $50.00 of your $50.00 limit is used this month, so this message was not sent and you were not charged. Sending resumes on the 1st (UTC). To keep sending now, raise or remove the limit in the console (Settings → Spend limit) or with PATCH /v1/spend-limit."
  }
}
```

(HTTP 403). Raising or removing the limit takes effect on the next send.

## Alerts

`alert_thresholds` are percentages of the cap (default 50, 80, and 100).
Each one fires once per month: an email to the account owner and a
`spend.threshold_reached` [webhook event](/docs/webhooks):

```json
{ "type": "spend.threshold_reached",
  "data": { "threshold_percent": 80, "spent_usd": 40.01, "limit_usd": 50, "month": "2026-10" } }
```

Changing the cap re-arms the alerts for the new amount.

## API

```bash
curl https://api.joinsimplesms.com/v1/spend-limit -H "Authorization: Bearer ssms_sk_live_..."

curl -X PATCH https://api.joinsimplesms.com/v1/spend-limit \
  -H "Authorization: Bearer ssms_sk_live_..." -H "Content-Type: application/json" \
  -d '{"monthly_limit_usd": 50, "alert_thresholds": [50, 80, 100]}'
```

```json
{
  "object": "spend_limit",
  "monthly_limit_usd": 50,
  "alert_thresholds": [50, 80, 100],
  "applies_to": ["outbound_sms"],
  "estimated_cost_per_message_usd": 0.009,
  "current_month": { "month": "2026-10", "spent_usd": 12.6, "remaining_usd": 37.4 },
  "updated_at": "2026-10-01T17:02:11.000Z"
}
```

`monthly_limit_usd` is 1 to 1,000,000, or `null` for no cap. Up to 5
thresholds, whole percentages from 1 to 100. Needs the `billing` scope on a
restricted key. Every change is recorded in the [audit log](/docs/audit-logs).