Limits and alerts
Overage rules, spend limits, usage caps per window, usage alerts and auto top ups.
Set them on a plan (defaults for every customer on it), on a customer, or on an entity. A rule on the customer replaces the plan's rule for the same feature; a rule on an entity replaces the customer's. customers.get returns the effective rules with a source on each.
{
"customer_id": "user_123",
"billing_controls": {
"overage_allowed": [{ "feature_id": "api_calls", "enabled": true }],
"spend_limits": [{ "feature_id": "api_calls", "enabled": true, "overage_limit": 5000 }],
"usage_limits": [{ "feature_id": "messages", "limit": 50, "interval": "day" }],
"usage_alerts": [{ "feature_id": "api_calls", "threshold": 80, "threshold_type": "usage_percentage", "name": "80 percent warning" }],
"auto_topups": [{ "feature_id": "credits", "enabled": true, "threshold": 500, "quantity": 1000, "purchase_limit": { "interval": "month", "limit": 5 } }]
}
}Overage allowed
Pay as you go items may go past the included amount; everything else stops at zero. overage_allowed flips either way for one feature. Allowing it on an included item lets the balance go negative without charging for it; blocking it on a pay as you go item makes a hard stop.
Spend limits
How far past the included amount a pay as you go feature may go, in the feature's own units. It wins over the plan's max_purchase. At the cap, check answers spend_limit_reached.
Usage limits
A hard cap per day, week, month or year, even when balance is left. Windows follow the UTC calendar. Editing a limit keeps what was already counted in the window; turn it off with enabled: false to stop it gating. On a credit system you can cap the whole pool or one feature that spends from it. Each balance in customers.get shows usage_limits with the live usage, so you can render "37 of 50 today".
Usage alerts
Fire balances.usage_alert_triggered once when usage crosses the line, by count (usage) or by percent of the allowance (usage_percentage). They never block. An alert fires again only after usage drops below the line, such as after a reset. When a customer has no alerts for a feature, the workspace alert percent from Settings applies.
Auto top ups
When a balance drops below threshold, Revenue buys quantity units from your one off plan that sells the feature as prepaid packs, and charges the saved card. purchase_limit stops runaway spending. You get billing.auto_topup_succeeded or billing.auto_topup_failed with a reason: payment_method_required, payment_failed, authentication_required, purchase_limit_reached or no_top_up_plan. Auto top ups belong to the customer, not to entities.
Limit reached
balances.limit_reached fires when a customer goes from allowed to blocked, with limit_type included, spend_limit, max_purchase or usage_limit. It fires once until the balance is refilled or reset.