Spend Caps & Usage Alerts
Opt-in controls for paid plans — block overage entirely or cap what it can cost, and get email alerts as you approach or reach your included volume.
Paid plans meter overage past the included allowance instead of blocking. If you'd rather trade availability for cost certainty, two self-serve controls on the billing page put you in charge — and usage alerts keep you informed either way.
The two spend caps
Both are set on Billing → Current plan in the portal (or via
POST /v1/portal/billing/limits), apply within seconds, and can be changed at
any time.
| Control | What it does |
|---|---|
| No overage (hard stop) | Metered requests are refused with quota-exceeded once your included volume is used up. Nothing past the included allowance is ever billed. |
| Overage spend cap | Overage flows normally until its accrued pre-tax cost reaches your cap (set in your billing currency), then metered requests are refused until you raise the cap, clear it, or upgrade. |
Details worth knowing:
- Caps are pre-tax: tax is computed by Stripe at invoice time and added on top, so a cap of 50.00 can invoice as slightly more with tax.
- Overage accrues against the cap per request, exactly as it is billed — so the cap buys precisely the usage it budgets. Requests stop at the first one that would reach the ceiling; the invoiced overage never exceeds it.
- Caps are enforced on the same fail-open footing as quotas: a billing-store outage never blocks your conversions, and Stripe only ever bills actual usage.
- Batch enqueues are pre-checked against your caps too — a large batch that would blow through a cap is refused up front rather than partially run.
- Upgrading clears an accrued-overage stop. If you've hit an overage spend cap (or a hard stop), upgrading takes effect immediately, carries this period's usage into the larger plan's included volume, and forgives the overage already accrued at your old plan's rate — so an upgrade both lifts the block and wipes the old-rate charge. See Changing plans.
Usage alert emails
Alert emails go to every portal user on your account, at most once per billing period per milestone:
| Milestone | |
|---|---|
| 75% of included volume | Heads-up |
| 90% of included volume | Heads-up |
| 100%, overage allowed | You're now billing overage (names your rate per 1,000) |
| 100%, hard stop on | API paused — turn off the hard stop to allow overage, or upgrade |
| Overage spend cap reached | API paused — raise the cap or upgrade |
For security, alert emails never contain sign-in links or tokens — they link to the portal login page and you sign in as usual.
Reading your state from the API
GET /v1/usage (and the portal's usage endpoint) reports everything the
dashboard shows:
{
"plan": "micro",
"monthly_quota": 5000,
"used": 5210,
"remaining": 0,
"overage_allowed": true,
"overage_blocked": false,
"overage_cap_cents": 5000,
"currency": "usd",
"period_start": "2026-06-12T09:30:00Z",
"period_end": "2026-07-12T09:30:00Z",
"resets_at": "2026-07-12T09:30:00Z"
}
overage_cap_cents is null when no cap is set. On paid plans the period is
your Stripe billing anniversary window; on Free it's the UTC calendar month.