> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flexprice.io/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

<Steps>
  <Step title="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.
  </Step>

  <Step title="Open Alert Settings">
    Click the **three-dot menu (⋮)** on the subscription and select **Alert Settings**.

    <Frame>
      <img src="https://mintcdn.com/flexprice/P1L_rWLeLZRmem0f/public/images/docs/Subscriptions/Spend/three-dot-subscription-alert-settings.png?fit=max&auto=format&n=P1L_rWLeLZRmem0f&q=85&s=07d1d070592782c542fb767e2568e8c0" alt="Open Alert Settings" width="2142" height="1206" data-path="public/images/docs/Subscriptions/Spend/three-dot-subscription-alert-settings.png" />
    </Frame>
  </Step>

  <Step title="Enable alerts">
    Turn **Enable Alerts** on.

    <Frame>
      <img src="https://mintcdn.com/flexprice/P1L_rWLeLZRmem0f/public/images/docs/Subscriptions/Spend/enable-subscription-alert-settings.png?fit=max&auto=format&n=P1L_rWLeLZRmem0f&q=85&s=f680d90c502aa1b6dae59fa0eeb4ac99" alt="Enable Alerts" width="2512" height="1240" data-path="public/images/docs/Subscriptions/Spend/enable-subscription-alert-settings.png" />
    </Frame>
  </Step>

  <Step title="Configure thresholds">
    Set **Threshold Value** for the levels you want (Critical, Warning, Info). Condition is fixed to **Above**. Use **Remove** to drop a level you don't need, then click **Save Changes**.

    <Frame>
      <img src="https://mintcdn.com/flexprice/P1L_rWLeLZRmem0f/public/images/docs/Subscriptions/Spend/configure-subscription-alert-settings.png?fit=max&auto=format&n=P1L_rWLeLZRmem0f&q=85&s=1516174d38f9cf7428684b91560f6903" alt="Configure thresholds" width="1278" height="1472" data-path="public/images/docs/Subscriptions/Spend/configure-subscription-alert-settings.png" />
    </Frame>
  </Step>
</Steps>

## 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" }
  }
}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST 'https://api.cloud.flexprice.io/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" }
      }
    }'
  ```
</CodeGroup>

<Note>
  No `parent_entity_type` or `parent_entity_id` is sent for subscription-level alerts. `entity_id` is the subscription itself.
</Note>

## Alert Behavior

Once configured and enabled, Flexprice:

* **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

<Steps>
  <Step title="Open the subscription">
    Open the subscription and click the **three-dot menu (⋮)**.
  </Step>

  <Step title="Open Alert Settings">
    Select **Alert Settings**. The dialog shows **Enable Alerts** and all configured threshold levels with their values.
  </Step>
</Steps>

### Changing thresholds

<Steps>
  <Step title="Open Alert Settings">
    Click the **three-dot menu (⋮)** on the subscription and select **Alert Settings**.
  </Step>

  <Step title="Adjust values">
    Change **Enable Alerts** or any threshold value in the dialog.
  </Step>

  <Step title="Save">
    Click **Save Changes**.
  </Step>
</Steps>

### Removing a threshold

<Steps>
  <Step title="Open Alert Settings">
    Click the **three-dot menu (⋮)** on the subscription and select **Alert Settings**.
  </Step>

  <Step title="Remove the level">
    Click **Remove** on the threshold level you want to drop.
  </Step>

  <Step title="Save">
    Click **Save Changes**. Removed thresholds are cleared, not just hidden, so send the complete remaining configuration.
  </Step>
</Steps>

### Disabling alerts

<Steps>
  <Step title="Open Alert Settings">
    Click the **three-dot menu (⋮)** on the subscription and select **Alert Settings**.
  </Step>

  <Step title="Turn off Enable Alerts">
    Set **Enable Alerts** to off (or set `alert_enabled` to `false` via API).
  </Step>

  <Step title="Save">
    Click **Save Changes**.
  </Step>
</Steps>

## 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?](/docs/subscriptions/how-to-configure-spend-alerts/what-are-spend-alerts): all three alert scopes, shared validation, and the full API reference
* [Line item spend alerts](/docs/subscriptions/how-to-configure-spend-alerts/how-to-configure-subscription-line-item-spend-alerts): monitor one line item instead of the whole subscription
* [Group spend alerts](/docs/subscriptions/how-to-configure-spend-alerts/how-to-configure-group-spend-alerts): monitor spend across a feature group
* [Webhooks](/docs/webhook/webhooks): endpoint setup, payload signatures, and retry behavior