Bolt has moved to boltapp.com. Stores still using bolt.com hosts must update now: see the migration guide.

Skip to content

Usage alerts

Get notified when a subscriber's metered usage crosses a threshold or reaches its cap.

View As MarkdownMCP

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:

Webhook payload
{
  "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"
  }
}
FieldNotes
event_idUnique per breach. Use it to deduplicate redeliveries.
meterWhich meter breached: display name, event type, and aggregation.
thresholdThe crossed threshold, as a numeric string.
current_totalThe metered total at breach time. Fractional for gauge-style meters.
is_captrue when the breach is the charge model's cap, meaning rating has stopped for the period.
capThe cap value; empty when the charge model has no cap.
period_start, period_endThe billing period the total belongs to. Omitted for totals not bound to a period.
breached_atWhen 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.

On this page