Skip to main content
A standard cost alert evaluates the running total of the subscription’s draft invoice, measured after prepaid credits are drawn down. A spend alert instead evaluates rated spend—the sum of that invoice’s line item subtotals in a single currency, measured before credit draw‑down and before invoice‑level adjustments.
This feature is in private preview.Spend alerts are not included with all Orb billing plans by default. Contact your Orb account team to learn more.
Use a spend alert when you want to know what a customer consumed, independently of how that consumption is paid for:
  • Customers on prepaid credits. While credits cover usage, they reduce the draft invoice total, so a cost alert may never fire for that consumption. A spend alert tracks the consumption itself, so you can warn a customer at $10,000 of usage whether or not they have prepaid for it.
  • Spend caps on part of a subscription. price_filters restrict which prices contribute, so a cap can cover inference usage and ignore a platform fee.
Spend is its own alert type, spend_exceeded, set at creation time. It is independent of the subscription’s cost alert and of any grouped cost alerts: a subscription can run all three at once.

​
Configuration

To evaluate the same subtotal broken out by an event property, use a grouped cost alert instead.

​
Spend and cost alerts

​
Which prices contribute

Within the alert’s currency (and any price_filters), every usage‑based and license price on the draft invoice contributes its line item subtotal. Fixed fees and composite prices are excluded—a fixed fee is not rated from usage, and a composite price is derived from other line items rather than from an independent metric. Because only metric‑backed prices contribute, a price_filters entry that includes only fixed_in_advance or fixed_in_arrears matches no prices and the alert never fires. Those subtotals are summed before credit draw‑down, before invoice‑level adjustments such as discounts, minimums, and maximums, before conversion to the subscription’s invoicing currency, and before taxes. Note that threshold invoices already issued in the billing period do not reduce the value either.
For license prices, the contributed amount is the line item’s overage subtotal—the amount remaining after the license allocation is drawn down. This differs from grouped cost alerts, where per‑group subtotals are a quantity × rate estimate that ignores pool drawdowns.

​
Examples

Create a subscription spend alert with POST /v1/alerts/subscription_id/{subscription_id} that fires at $10,000 and $25,000 of USD usage spend, ignoring non‑usage prices:
The same body creates a plan‑level alert at POST /v1/alerts/plan_id/{plan_id}, which Orb propagates to every subscription on that plan version. Raise the thresholds later with PUT /v1/alerts/{alert_configuration_id}. Omitting price_filters leaves the existing filters in place:

​
Managing spend alerts

The Orb dashboard displays spend alerts on the subscription’s alerts card, alongside the thresholds crossed during the current billing period. PUT /v1/alerts/{alert_configuration_id} updates thresholds and price_filters; omit price_filters to leave them unchanged, or pass an empty list to clear them. The enable and disable endpoints work as they do for every other alert. A plan‑level spend alert can also be disabled for an individual subscription. Evaluation timing, behavior during plan changes, and real‑time versus periodic eligibility are the same as for other subscription alerts; see subscription alerts.

​
Limitations

  • A subscription (or plan version) can have one spend alert per currency. A second alert in the same currency is rejected. Spend alerts do not count against the limit of 3 grouped cost alerts.
  • currency cannot be changed after creation. Create a new alert instead.
  • metric_id, grouping_keys, and threshold_overrides are rejected on a spend alert.
  • Fixed fees and composite prices never contribute, whatever the price_filters say—see which prices contribute.
  • Spend alerts are created through the API. The dashboard displays them but has no creation flow for them.

​
Webhooks

When rated spend crosses a threshold, Orb sends a subscription.spend_exceeded webhook with the evaluation timeframe, the threshold that was crossed, and the evaluated amount. If several thresholds are crossed in rapid succession, Orb sends only the event for the highest threshold.