# Usage alerts

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

Source: https://help.boltapp.com/products/bolt-subscriptions/usage-alerts

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 [#thresholds]

Set alert thresholds on the plan's **Alerts** step when [setting up the plan](/products/bolt-subscriptions/set-up-usage-based-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 [#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:

```json title="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"
  }
}
```

| 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 [#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.

## Related [#related]

* [Usage-based billing](/products/bolt-subscriptions/usage-based-billing)
* [Report usage events](/products/bolt-subscriptions/usage-events)
* [Webhooks](/developers/webhooks)
