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.

DefinitionEffect
Plan levelEvery subscription created on the plan inherits the alert configuration.
Subscription levelThe alert applies only to the targeted subscription and can override or augment plan‑level alerts.

Behaviour during subscription changes

ChangeCost alertsUsage alerts
Plan changePersist automatically.Persist if the referenced billable metric still exists on the new plan.
Migration to a new plan versionPersist 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.

Relationship to threshold 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.