Usage alerting
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 evaluated in real-time, allowing you to build spend management workflows integrated into your product experience that are nearly instantaneous. Orb also supports periodic evaluation for more complex metrics, even allowing you to set up alerting over metrics that require a view of the full billing period to evaluate. In this case, the alert is evaluated periodically, and the Orb dashboard will indicate the difference in evaluation cadence eligibility. Note that an alert that composes multiple metrics (e.g. a balance alert that depends on drawdowns on all metrics or an invoice costs alerts that depends on the sum of all line items) will still be evaluated in real-time on the basis of the metrics that support incremental computation. In other words, if a large majority of your usage comes from simple, incrementally computable metrics, the alert will be evaluated in near real-time. The Orb dashboard will indicate that a subset of metrics are incrementally computable and cause the alert to be evaluated in real-time.| Path | Eligibility | Latency |
|---|---|---|
| Real‑time | Draft invoices for the customer contain only decomposable line items (metrics that are possible to incrementally compute, e.g., SUM or COUNT). | Seconds to minutes |
| Periodic | A metric (e.g., COUNT DISTINCT, percentile metrics) is present that requires scanning the full events dataset for the billing period. | Periodically, but Orb provides an option for 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.