> ## 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.

# Subscription alerts

> Configure cost and usage‑based alerts at the plan or individual subscription level.

## Defining subscription alerts

Both cost and usage alerts can be defined at the plan or subscription level. Plan alerts
can be disabled on a per-subscription basis, but cannot otherwise be modified without
creating a new subscription alert.

| Definition             | Effect                                                                                             |
| ---------------------- | -------------------------------------------------------------------------------------------------- |
| **Plan level**         | Every subscription created on the plan inherits the alert configuration.                           |
| **Subscription level** | The alert applies only to the targeted subscription and can override or augment plan‑level alerts. |

## Behaviour during subscription changes

| Change                              | Cost alerts            | Usage alerts                                                               |
| ----------------------------------- | ---------------------- | -------------------------------------------------------------------------- |
| **Plan change**                     | Persist automatically. | Persist if the referenced billable metric still exists on the new plan.    |
| **Migration to a new plan version** | Persist automatically. | Persist if the referenced billable metric still exists on the new version. |

## Evaluation mechanics

* Alerts are evaluated against the **current draft invoice** for the subscription.
* During the grace period after a billing period closes, Orb continues evaluating alerts on both:
  1. The final invoice of the closed period.
  2. The draft invoice for the new period.
* If a mid‑period plan change occurs, the billing period is split; Orb now evaluates alerts on the new draft invoice
  which will be for a new period on the new plan.

## Cost alert calculation

* **Net cost basis**: Orb measures cost **after** credit draw‑down and **ignores** threshold invoices already issued in the same billing period.
* **Illustrative example**\
  Assume an alert threshold of \$25 and a threshold invoice amount of \$10
  1. Two threshold invoices have issued (2 × \$10 = \$20).
  2. The draft invoice now shows \$5 in additional cost.
  3. The cost alert fires on that draft invoice because the running total reaches \$25.

## Spend alerts

A spend alert evaluates rated spend—the sum of line item subtotals in a single currency—before credit draw‑down and invoice‑level adjustments, rather than the net cost basis above, so prepaid credits do not mask consumption. See [spend alerts](/usage-alerting/spend-alerts).

## Grouped cost alerts

A cost alert can evaluate per‑group spend subtotals—for example cost per `seat_id` or per tenant—and fire once for each group that crosses a threshold, instead of watching the single invoice total. See [grouped cost alerts](/usage-alerting/grouped-cost-alerts).

## Relationship to threshold invoicing

[Threshold invoicing](/invoicing/threshold-invoicing) follows the **same evaluation semantics** as cost alerts, and are evaluated
on the same tight SLAs. You can think of a threshold invoice as a *material* side‑effect of a cost alert: in addition to dispatching a webhook, Orb immediately issues an invoice for the accrued amount.