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

# Line Item Spend Alerts

> Monitor spend on a single subscription line item and get notified by webhook when it crosses a configured threshold

Line item spend alerts monitor the **usage-based spend of a single line item** on a subscription, independently of the subscription's total. Use this when one specific charge (for example, a particular metered API) needs its own budget, separate from the rest of the subscription.

## Configuring via the Dashboard

**1. Open the subscription for editing**

Go to **Billing** → **Subscriptions**, open the subscription, and go to **Edit Subscription**.

**2. Open the line item's menu**

Find the line item to monitor, click its **three-dot menu (⋯)**, and select **Alert Settings**. It appears alongside **Edit** and **Terminate** for that line item.

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

**3. Enable alerts**

Turn **Enable Alerts** on.

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

**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-line-item-alert-settings.png?fit=max\&auto=format\&n=Ca7Kginb789boSAj\&q=85\&s=d14de7d2b250a4d66f73932126a6284e)

## Configuring via API

```json theme={null}
{
  "entity_type": "subscription_line_item",
  "entity_id": "subs_line_01K7YQ0000LINEITEM00001",
  "parent_entity_type": "subscription",
  "parent_entity_id": "subs_01K7YQ8ZR4M3V2N1XA9C6D0EFG",
  "config": {
    "alert_enabled": true,
    "warning":  { "threshold": "150", "condition": "above" },
    "critical": { "threshold": "300", "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_line_item",
    "entity_id": "subs_line_01K7YQ0000LINEITEM00001",
    "parent_entity_type": "subscription",
    "parent_entity_id": "subs_01K7YQ8ZR4M3V2N1XA9C6D0EFG",
    "config": {
      "alert_enabled": true,
      "warning":  { "threshold": "150", "condition": "above" },
      "critical": { "threshold": "300", "condition": "above" }
    }
  }'
```

> [!WARNING]
>
> `entity_id` must be a line item that belongs to the subscription identified by `parent_entity_id`. The API rejects a line item ID from a different subscription.

## Alert Behavior

Tirdad recalculates this line item's usage-based spend on every usage event affecting the subscription and sends a webhook only when the alert state changes.

> [!NOTE]
>
> Usage on a different line item in the same subscription does not affect this alert. It only tracks the one line item it's configured on.

## Managing Alert Settings

### Viewing current configuration

**1. Open the line item's menu**

Open **Edit Subscription**, find the line item, and click its **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**

Open **Edit Subscription**, find the line item, click its **three-dot menu (⋯)** → **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**

Open **Edit Subscription**, find the line item, click its **three-dot menu (⋯)** → **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**

Open **Edit Subscription**, find the line item, click its **three-dot menu (⋯)** → **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.line_item_spend.threshold_reached` | Spend crosses a threshold |
| `subscription.line_item_spend.threshold_recovered` | Spend recovers to `ok` |

## Use Cases

* **Per-charge budgets**: Alert on a specific metered charge (e.g. a particular API or compute meter) without noise from the rest of the subscription
* **High-cost line items**: Set tighter thresholds on line items with the highest per-unit cost or the most usage variance
* **Customer-specific overrides**: Combine with per-subscription price overrides to alert on a customer's negotiated rate independently

## 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
* [Subscription spend alerts](https://docs.tirdad.ai/docs/subscriptions/how-to-configure-spend-alerts/how-to-configure-subscription-spend-alerts.md): monitor the whole subscription instead of one line item
* [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.