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

# Subscription Spend Alerts

> Monitor total usage-based spend across a subscription and get notified by webhook when it crosses a configured threshold

Subscription spend alerts monitor the **total usage-based spend across an entire subscription** for the current billing period. This is the broadest of the three spend alert scopes: it catches overall budget overruns regardless of which line item drove the spend.

## Configuring via the Dashboard

**1. Open the subscription**

Go to **Billing** → **Subscriptions**, or open a customer and select their subscription, from either the **Subscription Details** page or the customer's **Overview** tab subscriptions list.

**2. Open Alert Settings**

Click the **three-dot menu (⋯)** on the subscription and select **Alert Settings**.

![Open Alert Settings](https://mintcdn.com/tirdad/Ca7Kginb789boSAj/images/docs/subscriptions/spend/three-dot-subscription-alert-settings.png?fit=max\&auto=format\&n=Ca7Kginb789boSAj\&q=85\&s=b905dfde304e3a5de62636b160010ccd)

**3. Enable alerts**

Turn **Enable Alerts** on.

![Enable Alerts](https://mintcdn.com/tirdad/Ca7Kginb789boSAj/images/docs/subscriptions/spend/enable-subscription-alert-settings.png?fit=max\&auto=format\&n=Ca7Kginb789boSAj\&q=85\&s=bd547112f404b93ad9eceb6112a2edc1)

**4. Configure thresholds**

Click **Add** next to each level you want (Critical, Warning, Info) and set its **Threshold Value**. Condition is fixed to **Above**. Use **Remove** to drop a level you don't need, then click **Save Changes**.

![Configure thresholds](https://mintcdn.com/tirdad/Ca7Kginb789boSAj/images/docs/subscriptions/spend/configure-subscription-alert-settings.png?fit=max\&auto=format\&n=Ca7Kginb789boSAj\&q=85\&s=dcfd8df43531a61763a57da4d444d29d)

## Configuring via API

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

```bash cURL theme={null}
curl -X POST 'https://api.tirdad.ai/v1/alerts/setting' \
  -H 'x-api-key: <api_key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "entity_type": "subscription",
    "entity_id": "subs_01K7YQ8ZR4M3V2N1XA9C6D0EFG",
    "config": {
      "alert_enabled": true,
      "info":     { "threshold": "250",  "condition": "above" },
      "warning":  { "threshold": "500",  "condition": "above" },
      "critical": { "threshold": "1000", "condition": "above" }
    }
  }'
```

> [!NOTE]
>
> No `parent_entity_type` or `parent_entity_id` is sent for subscription-level alerts. `entity_id` is the subscription itself.

## Alert Behavior

Once configured and enabled, Tirdad:

* **Recalculates spend**: On every usage event for the subscription, recomputes total usage-based spend using the same invoicing-grade calculation (commitment- and overage-aware) used to generate invoices
* **Compares against thresholds**: Evaluates the recalculated total against Critical, Warning, and Info
* **Updates state**: Reflects the current state (`ok`, `info`, `warning`, `in_alarm`) in alert history
* **Notifies**: Sends a webhook only when the state changes, not on every event

## Managing Alert Settings

### Viewing current configuration

**1. Open the subscription**

Open the subscription and click the **three-dot menu (⋯)**.

**2. Open Alert Settings**

Select **Alert Settings**. The dialog shows **Enable Alerts** and all configured threshold levels with their values.

### Changing thresholds

**1. Open Alert Settings**

Click the **three-dot menu (⋯)** on the subscription and select **Alert Settings**.

**2. Adjust values**

Change **Enable Alerts** or any threshold value in the dialog.

**3. Save**

Click **Save Changes**.

### Removing a threshold

**1. Open Alert Settings**

Click the **three-dot menu (⋯)** on the subscription and select **Alert Settings**.

**2. Remove the level**

Click **Remove** on the threshold level you want to drop.

**3. Save**

Click **Save Changes**. Removed thresholds are cleared, not just hidden, so send the complete remaining configuration.

### Disabling alerts

**1. Open Alert Settings**

Click the **three-dot menu (⋯)** on the subscription and select **Alert Settings**.

**2. Turn off Enable Alerts**

Set **Enable Alerts** to off (or set `alert_enabled` to `false` via API).

**3. Save**

Click **Save Changes**.

## Webhooks

| Event | Fires when |
| - | - |
| `subscription.spend.threshold_reached` | Spend crosses a threshold |
| `subscription.spend.threshold_recovered` | Spend recovers to `ok` |

## Use Cases

* **Overall budget cap**: Alert when a customer's total subscription spend approaches or exceeds a contracted limit
* **Early warning for usage spikes**: Set Info well below Critical to catch unexpected spend trends before they become a problem
* **Account health monitoring**: Route alerts to a support or account-management queue

## Related

* [What Are Spend Alerts?](https://docs.tirdad.ai/docs/subscriptions/how-to-configure-spend-alerts/what-are-spend-alerts.md): all three alert scopes, shared validation, and the full API reference
* [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 instead of the whole subscription
* [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
* [Webhooks](https://docs.tirdad.ai/docs/webhook/webhooks): endpoint setup, payload signatures, and retry behavior


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