> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withorb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Spend alerts

> Evaluate rated spend—the pricing subtotal before credits and invoice‑level adjustments—instead of the net invoice total.

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.

<Info>
  **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.
</Info>

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](/usage-alerting/grouped-cost-alerts): a subscription can run all three at once.

## Configuration

| Field           | Required | Description                                                                                                                                                                                                                                |
| --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `type`          | Yes      | `spend_exceeded`.                                                                                                                                                                                                                          |
| `thresholds`    | Yes      | Monetary values in the alert's currency. The alert fires when rated spend reaches or exceeds a threshold. Duplicate values are rejected.                                                                                                   |
| `currency`      | Yes      | The case‑sensitive currency or custom pricing unit to scope the alert to. Only line items priced in this unit contribute, since subtotals can't be summed across pricing units.                                                            |
| `price_filters` | No       | Restricts *which* prices contribute. Each filter matches on `price_id`, `item_id`, or `price_type` with an `includes` or `excludes` operator, combined with AND. For example, exclude a platform fee so it does not count against the cap. |

To evaluate the same subtotal broken out by an event property, use a [grouped cost alert](/usage-alerting/grouped-cost-alerts) instead.

## Spend and cost alerts

| Behavior                  | `cost_exceeded`                      | `spend_exceeded`                   |
| ------------------------- | ------------------------------------ | ---------------------------------- |
| Evaluates                 | The running draft invoice total      | The rated subtotal in one currency |
| Credit draw‑down          | Included—the total is net of credits | Excluded—the subtotal is gross     |
| Invoice‑level adjustments | Included                             | Excluded                           |
| Fixed fees                | Included                             | Excluded                           |
| `currency`                | Not accepted                         | Required                           |
| `price_filters`           | Not accepted                         | Supported                          |
| Webhook                   | `subscription.cost_exceeded`         | `subscription.spend_exceeded`      |

## 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](/invoicing/threshold-invoicing) already issued in the billing period do not reduce the value either.

<Note>
  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](/usage-alerting/grouped-cost-alerts), where per‑group subtotals are a `quantity × rate` estimate that ignores pool drawdowns.
</Note>

## Examples

Create a subscription spend alert with [`POST /v1/alerts/subscription_id/{subscription_id}`](/api-reference/alert/create-subscription-alert) that fires at \$10,000 and \$25,000 of USD usage spend, ignoring non‑usage prices:

```json theme={null}
{
  "type": "spend_exceeded",
  "thresholds": [{ "value": "10000.00" }, { "value": "25000.00" }],
  "currency": "USD",
  "price_filters": [
    { "field": "price_type", "operator": "includes", "values": ["usage"] }
  ]
}
```

The same body creates a plan‑level alert at [`POST /v1/alerts/plan_id/{plan_id}`](/api-reference/alert/create-plan-alert), which Orb propagates to every subscription on that plan version.

Raise the thresholds later with [`PUT /v1/alerts/{alert_configuration_id}`](/api-reference/alert/update-alert). Omitting `price_filters` leaves the existing filters in place:

```json theme={null}
{
  "thresholds": [{ "value": "20000.00" }, { "value": "50000.00" }]
}
```

## 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}`](/api-reference/alert/update-alert) updates `thresholds` and `price_filters`; omit `price_filters` to leave them unchanged, or pass an empty list to clear them. The [enable](/api-reference/alert/enable-alert) and [disable](/api-reference/alert/disable-alert) 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](/usage-alerting/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](#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`](/integrations-and-exports/webhooks#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.