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

# What Are Spend Alerts?

> Threshold-based alerts that track billed spend at the subscription, line item, or group level, with webhook notifications on every state change

Spend alerts monitor usage-based spend against configured thresholds and notify you by webhook when a threshold is crossed. Unlike wallet and feature-usage alerts, which track balance or raw usage, spend alerts track **billed spend**: the same invoicing-grade calculation used to generate invoices, including commitments and overage.

Spend alerts have three independent scopes:

* **Subscription**: total usage-based spend across the whole subscription
* **Subscription line item**: spend on a single line item
* **Group**: spend summed across every line item whose feature belongs to a given group

All three scopes share the same configuration shape, the same three-level alert model (`info` → `warning` → `critical`), and the same webhook delivery mechanism. Pick a scope based on how granular the budget you're protecting actually is: a whole subscription, one metered charge, or a set of related meters.

**Benefits:**

* **Budget enforcement**: Catch spend overruns before the invoice is generated
* **Granular scope**: Monitor an entire subscription, a single line item, or a feature group independently
* **Invoicing-grade accuracy**: Thresholds compare against the same commitment- and overage-aware spend calculation used for billing
* **Real-time evaluation**: Spend is recalculated and compared against thresholds as usage events arrive, not on a delay

## Alert Scopes at a Glance

| Scope | What is monitored | Webhook event |
| - | - | - |
| [Subscription](https://docs.tirdad.ai/docs/subscriptions/how-to-configure-spend-alerts/how-to-configure-subscription-spend-alerts.md) | Total usage-based spend across the subscription | `subscription.spend.threshold_reached` / `.threshold_recovered` |
| [Subscription line item](https://docs.tirdad.ai/docs/subscriptions/how-to-configure-spend-alerts/how-to-configure-subscription-line-item-spend-alerts.md) | Spend on one usage-priced line item | `subscription.line_item_spend.threshold_reached` / `.threshold_recovered` |
| [Group](https://docs.tirdad.ai/docs/subscriptions/how-to-configure-spend-alerts/how-to-configure-group-spend-alerts.md) | Spend summed across every line item in a group | `subscription.group_spend.threshold_reached` / `.threshold_recovered` |

## Alert Levels and Conditions

Every alert configuration supports up to three independent threshold levels:

| Level | API state | Purpose |
| - | - | - |
| **Info** | `info` | Early milestone: spend is approaching a limit |
| **Warning** | `warning` | Action needed: spend is significantly high |
| **Critical** | `in_alarm` | Immediate action required |
| (none breached) | `ok` | Healthy, no thresholds breached |

> [!WARNING]
>
> Spend alerts only support the **above** condition: an alert fires when spend rises above the threshold. The `below` condition (used by wallet balance alerts) is rejected for subscription, line item, and group scopes.

Because every threshold uses `above`, ordering runs from smallest to largest:

```
Info < Warning < Critical
```

> [!NOTE]
>
> A **Warning** threshold requires a **Critical** threshold to also be set. You cannot configure Warning without Critical. **Info** can be set independently of the other two.

## Configuration API

All three scopes are configured through the same `alert_settings` resource:

| Action | Method | Endpoint |
| - | - | - |
| Create alert setting | POST | `/v1/alerts/setting` |
| Get alert setting | GET | `/v1/alerts/setting/:id` |
| Query alert settings | POST | `/v1/alerts/setting/search` |
| Update alert setting | PUT | `/v1/alerts/setting/:id` |
| Delete alert setting | DELETE | `/v1/alerts/setting/:id` |

**Create request body:**

```json theme={null}
{
  "entity_type": "subscription",
  "entity_id": "subs_01K7YQ8ZR4M3V2N1XA9C6D0EFG",
  "config": {
    "alert_enabled": true,
    "info":     { "threshold": "100",  "condition": "above" },
    "warning":  { "threshold": "500",  "condition": "above" },
    "critical": { "threshold": "1000", "condition": "above" }
  }
}
```

| Field | Description |
| - | - |
| `entity_type` | `subscription`, `subscription_line_item`, or `group` |
| `entity_id` | ID of the monitored entity, matching `entity_type`: subscription ID, subscription line item ID, or group ID |
| `parent_entity_type` | `subscription` for line item and group alerts; omitted for subscription-level alerts |
| `parent_entity_id` | The subscription ID that owns a line item or group alert; omitted for subscription-level alerts |
| `config.alert_enabled` | Turns evaluation on or off for this alert setting |
| `config.critical` / `config.warning` / `config.info` | Threshold objects: `{ "threshold": "<amount>", "condition": "above" }` |

> [!WARNING]
>
> `PUT /v1/alerts/setting/:id` replaces the stored `config` wholesale. It does not merge with the existing configuration. Send the complete set of thresholds you want on every update; a threshold left out of the request is cleared, not left unchanged.

## Validation

| Rule | Detail |
| - | - |
| **Condition** | Every threshold's `condition` must be `above` |
| **Warning requires Critical** | A `warning` threshold cannot exist without a `critical` threshold |
| **Info stands alone** | `info` can be configured with or without `warning`/`critical` |
| **Ordering** | `info` \< `warning` \< `critical`, when each is set |
| **One setting per entity** | At most one alert setting per `(entity_type, entity_id, parent_entity_type, parent_entity_id)`; creating a duplicate is rejected |
| **Line item scope** | `entity_id` must be a line item that belongs to the subscription identified by `parent_entity_id` |
| **Group scope** | `parent_entity_id` is mandatory; a group alert always belongs to exactly one subscription |

## What's Next

* [Subscription spend alerts](https://docs.tirdad.ai/docs/subscriptions/how-to-configure-spend-alerts/how-to-configure-subscription-spend-alerts.md): monitor total subscription spend, via UI or API
* [Line item spend alerts](https://docs.tirdad.ai/docs/subscriptions/how-to-configure-spend-alerts/how-to-configure-subscription-line-item-spend-alerts.md): monitor one line item's spend, via UI or API
* [Group spend alerts](https://docs.tirdad.ai/docs/subscriptions/how-to-configure-spend-alerts/how-to-configure-group-spend-alerts.md): monitor spend across a feature group, via API


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.