Spend alerts monitor usage-based spend against configured thresholds and notify you by webhook when a threshold is crossed. Unlike wallet and feature-usage alerts, which track balance or raw usage, spend alerts track billed spend: the same invoicing-grade calculation used to generate invoices, including commitments and overage.
Spend alerts have three independent scopes:
- Subscription: total usage-based spend across the whole subscription
- Subscription line item: spend on a single line item
- Group: spend summed across every line item whose feature belongs to a given group
All three scopes share the same configuration shape, the same three-level alert model (info → warning → critical), and the same webhook delivery mechanism. Pick a scope based on how granular the budget you’re protecting actually is: a whole subscription, one metered charge, or a set of related meters.
Benefits:
- Budget enforcement: Catch spend overruns before the invoice is generated
- Granular scope: Monitor an entire subscription, a single line item, or a feature group independently
- Invoicing-grade accuracy: Thresholds compare against the same commitment- and overage-aware spend calculation used for billing
- Real-time evaluation: Spend is recalculated and compared against thresholds as usage events arrive, not on a delay
Alert Scopes at a Glance
| Scope | What is monitored | Webhook event |
|---|
| Subscription | Total usage-based spend across the subscription | subscription.spend.threshold_reached / .threshold_recovered |
| Subscription line item | Spend on one usage-priced line item | subscription.line_item_spend.threshold_reached / .threshold_recovered |
| Group | Spend summed across every line item in a group | subscription.group_spend.threshold_reached / .threshold_recovered |
Alert Levels and Conditions
Every alert configuration supports up to three independent threshold levels:
| Level | API state | Purpose |
|---|
| Info | info | Early milestone: spend is approaching a limit |
| Warning | warning | Action needed: spend is significantly high |
| Critical | in_alarm | Immediate action required |
| (none breached) | ok | Healthy, no thresholds breached |
Spend alerts only support the above condition: an alert fires when spend rises above the threshold. The below condition (used by wallet balance alerts) is rejected for subscription, line item, and group scopes.
above, ordering runs from smallest to largest:
A Warning threshold requires a Critical threshold to also be set. You cannot configure Warning without Critical. Info can be set independently of the other two.
Configuration API
All three scopes are configured through the same alert_settings resource:
| Action | Method | Endpoint |
|---|
| Create alert setting | POST | /v1/alerts/setting |
| Get alert setting | GET | /v1/alerts/setting/:id |
| Query alert settings | POST | /v1/alerts/setting/search |
| Update alert setting | PUT | /v1/alerts/setting/:id |
| Delete alert setting | DELETE | /v1/alerts/setting/:id |
| Field | Description |
|---|
entity_type | subscription, subscription_line_item, or group |
entity_id | ID of the monitored entity, matching entity_type: subscription ID, subscription line item ID, or group ID |
parent_entity_type | subscription for line item and group alerts; omitted for subscription-level alerts |
parent_entity_id | The subscription ID that owns a line item or group alert; omitted for subscription-level alerts |
config.alert_enabled | Turns evaluation on or off for this alert setting |
config.critical / config.warning / config.info | Threshold objects: { "threshold": "<amount>", "condition": "above" } |
PUT /v1/alerts/setting/:id replaces the stored config wholesale. It does not merge with the existing configuration. Send the complete set of thresholds you want on every update; a threshold left out of the request is cleared, not left unchanged.
Validation
| Rule | Detail |
|---|
| Condition | Every threshold’s condition must be above |
| Warning requires Critical | A warning threshold cannot exist without a critical threshold |
| Info stands alone | info can be configured with or without warning/critical |
| Ordering | info < warning < critical, when each is set |
| One setting per entity | At most one alert setting per (entity_type, entity_id, parent_entity_type, parent_entity_id); creating a duplicate is rejected |
| Line item scope | entity_id must be a line item that belongs to the subscription identified by parent_entity_id |
| Group scope | parent_entity_id is mandatory; a group alert always belongs to exactly one subscription |
What’s Next
