Alerting overview
Configure cost, usage, and balance alerts and understand their evaluation SLAs.
Alert types
| Alert type | Scope | Fires when… | Webhook event(s) |
|---|---|---|---|
| Subscription usage | Upcoming subscription invoice + billable metric | Usage for the metric on the draft invoice crosses any configured threshold. | subscription.usage_exceeded |
| Subscription cost | Upcoming subscription invoice | Running invoice total (after any credit offsets) crosses any configured monetary threshold. | subscription.cost_exceeded |
| Credit balance depleted | Customer | Prepaid balance transitions > 0 → 0. | customer.credit_balance_depleted |
| Credit balance dropped | Customer | Prepaid balance transitions ≥ threshold → below threshold. | customer.credit_balance_dropped |
| Credit balance recovered | Customer | Prepaid balance transitions 0 → above 0. | customer.credit_balance_recovered |
Managing alert states
Alerts are often tied to a specific plan or type of subscription. Accordingly, Orb allows you to configure alerts on the plan itself and automatically propagates them to all subscriptions of that plan. This allows you to quickly add an alert to an existing plan without having to run a migration over existing subscriptions. Similarly, when an alert is disabled, this change applies to all subscriptions.
Note that alerts can be created, enabled, disabled, or modified either through the Orb UI (at the plan or subscription level) or through the API.
It’s often useful to set ad hoc alerts for specific customers (especially when dealing with Enterprise contracts), so alerts can also be managed at the individual subscription level. Orb’s subscription card allows you to view alerts inherited from the plan and change them for the specific subscription instance. With this workflow, you can create alerts that correspond to a customer’s usage patterns, even if they differ from other subscriptions to the same plan.
Viewing triggered alerts
Each subscription card on the customer page in Orb shows which alerts have been triggered during the current billing period, and the time at which the threshold was exceeded.
Evaluation mechanics & SLAs
Most alerts and related usage monitoring actions like threshold invoicing and automatic top‑ups are evalated in real-time, allowing you to build spend management workflows integrated into your product experience that are nearly instantaneous.
Orb also supports batch evaluation for more complex use cases, even allowing you to set up alerting over metrics that require a view of the full billing period to evaluate.
| Path | Eligibility | Latency |
|---|---|---|
| Real‑time | Draft invoices for the customer contain only decomposable line items (metrics that are possible to stream‑compute, e.g., SUM or COUNT). | Seconds to minutes |
| Batch | A non‑decomposable metric (e.g., COUNT DISTINCT, percentile metrics) is present that require scanning the full events dataset for the billing period. | Periodically, but Orb provides commercial add-ons on advanced and enterprise agreements that guarantee tight SLAs. |
Creating a new alert or modifying an existing alert’s thresholds immediately invalidates the customer so the alert is re‑evaluated on the appropriate path, but this may take several minutes to complete.
Consuming alerts via webhooks
All alerts generate a webhook event when they fire, and your system can use this event to trigger actions. If several thresholds are crossed in rapid succession, Orb sends only the event for the highest threshold.