Usage alerts
Get notified when a subscriber's metered usage crosses a threshold or reaches its cap.
A usage alert fires when a meter's running total crosses a threshold you set on the plan's usage configuration. Use alerts to notify yourself or the subscriber before the period closes, and to learn when a capped charge model has reached its limit.
Thresholds
Set alert thresholds on the plan's Alerts step when setting up the plan. When the metered total for the current period crosses a threshold, Bolt fires one alert for that threshold and period; the same threshold does not fire again until the next period.
On Bolt Cart, you can also add rolling-window alerts, for example 500 units in any 5-hour window, or a 2-week window for a longer view. Each window tracks independently, on top of the billing period.
Plans with a capped charge model also alert when the total reaches the limit. A cap alert carries is_cap: true and means the limit is reached: further usage in the period is recorded but never billed.
The webhook
Bolt delivers alerts to your configured webhook endpoint as the event subscription_usage_alert. The payload contains the full subscription object plus a usage_alert block:
{
"usage_alert": {
"event_id": "ua_evt_01H...",
"meter": {
"display_name": "API calls",
"event_type": "api_calls",
"aggregation_type": "sum"
},
"threshold": "900",
"current_total": "912",
"is_cap": false,
"cap": "1000",
"charge_model": "capped",
"period_start": "2026-09-01T00:00:00Z",
"period_end": "2026-10-01T00:00:00Z",
"breached_at": "2026-09-24T11:03:22Z"
}
}| Field | Notes |
|---|---|
event_id | Unique per breach. Use it to deduplicate redeliveries. |
meter | Which meter breached: display name, event type, and aggregation. |
threshold | The crossed threshold, as a numeric string. |
current_total | The metered total at breach time. Fractional for gauge-style meters. |
is_cap | true when the breach is the charge model's cap, meaning rating has stopped for the period. |
cap | The cap value; empty when the charge model has no cap. |
period_start, period_end | The billing period the total belongs to. Omitted for totals not bound to a period. |
breached_at | When the total crossed the threshold. |
Delivery
Alerts are delivered at least once: after a timeout or a non-2xx response, Bolt retries with exponential backoff starting at 1 minute, doubling per attempt, for up to 6 attempts. Your handler must tolerate duplicates; deduplicate on event_id. If no webhook endpoint is configured, alerts are skipped.