# Alerts

> For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt).


An alert defines a threshold rule for usage, spend, or credit balance. When the configured threshold is crossed, Chargebee triggers a webhook notification so that you can take action such as notifying the customer, upgrading the plan, or pausing further consumption.

Common examples of alerts include:

-   Notifying a customer when they have consumed 90% of their monthly API call quota.
-   Alerting your operations team when a customer's spend exceeds a monthly limit.
-   Warning a customer when their prepaid credit balance drops to or below a replenishment threshold.

The alert resource represents configuration only. To check the current runtime state of an alert for a subscription (whether it is `within_limit` or `in_alarm`), use the [Alert Status](/docs/api/alert_statuses) endpoints.

#### Global vs. subscription-scoped alerts[](#global-vs-subscription-scoped-alerts)

Alerts can be created at two levels:

-   **Global alerts** apply across all relevant subscriptions. To restrict a global alert to specific plans, use `filter_conditions` with the `plan_price_id` field. When multiple filter conditions are provided, they are evaluated with OR semantics: the alert applies if any condition matches.
-   **Subscription-scoped alerts** apply to a single subscription only. Set `subscription_id` when creating the alert. Subscription-scoped alerts cannot have `filter_conditions`.

**Important**

A global alert and a subscription-scoped alert are mutually exclusive in their parameters: if `subscription_id` is set, `filter_conditions` must not be provided, and vice versa.

#### Alert types[](#alert-types)

The `type` attribute determines what an alert measures, which input it requires, and how the threshold is interpreted.

usage\_exceeded

Monitors consumption of a [metered feature](/docs/api/usages) for a subscription.

-   **Required input:** `metered_feature_id`.
-   **Fires when:** measured usage reaches or exceeds the configured threshold.
-   **Threshold modes:** `percentage` (of the plan or feature quota) or `absolute` (a usage quantity).
-   **Example:** notify a customer when they reach 90% of their monthly API-call quota.

Usage alerts are evaluated as [usage data](/docs/api/usage_events) is processed for the subscription.

spend\_exceeded

Monitors the total usage-based spend accumulated from metered addons on a subscription. This is the same overage concept surfaced by [usage charges](/docs/api/usage_charges): the monetary overage spend corresponds to the [amount](/docs/api/usage_charges/usage-charge-object#amount) field on the usage charge object (in major units of the currency).

-   **Required input:** `currency_code` — the ISO [currency code](/docs/api/currencies/currency-object#currency_code) in which overage spend is tracked.
-   **Fires when:** accumulated overage spend reaches or exceeds the configured threshold.
-   **Threshold mode:** always `absolute` (an amount in `currency_code`).
-   **Example:** alert the customer when their spending exceeds a 500 USD limit during the current usage cycle.

Spend alerts are evaluated as usage and overage charge data is processed for the subscription.

credit\_balance\_dropped

Monitors the prepaid credit balance of a subscription for a specific credit unit. See [ledger account balances](/docs/api/ledger_account_balances) for how credit balances are tracked.

-   **Required input:** `unit_id` — the [credit unit](/docs/api/ledger_account_balances/ledger-account-balance-object#unit_id) the alert applies to (for example, `ai_credits`).
-   **Fires when:** the credit balance drops to or below the configured threshold. This is the opposite direction to the `usage_exceeded` and `spend_exceeded` types, which fire when a value rises.
-   **Threshold mode:** always `absolute` (a credit-balance floor). `percentage` mode is not supported.
-   **Example:** warn a customer when their remaining AI credits drop to or below 10.

Credit-balance alerts are evaluated as [ledger operations](/docs/api/ledger_operations) update the balance.

#### Threshold modes[](#threshold-modes)

The `threshold` object defines when the alert should fire. It has two fields:

-   `mode`: Either `percentage` or `absolute`.
    -   `percentage`: The alert fires when the measured value reaches the specified percentage threshold. The `value` must be between 0 and 100 (inclusive). Supported only for `usage_exceeded` alerts.
    -   `absolute`: The alert fires when the measured value reaches an absolute quantity. The `value` must be >= 0.
-   `value`: The numeric threshold at which the alert triggers.

The supported modes depend on the alert `type`:

-   `usage_exceeded`: `percentage` or `absolute`.
-   `spend_exceeded`: `absolute` only.
-   `credit_balance_dropped`: `absolute` only.

**See also**

-   [Alert Statuses](/docs/api/alert_statuses) — runtime state of alerts per subscription.
-   [Usage Events](/docs/api/usage_events) — usage ingestion for `usage_exceeded` alerts.
-   [Ledger account balances](/docs/api/ledger_account_balances) — credit balances for `credit_balance_dropped` alerts.

## Sample Alert

```json
{
  "id": "alert___dev__3Nl7purV3LwbKYH",
  "name": "GPT-4o usage threshold",
  "description": "Notify when usage crosses 90% of quota",
  "type": "usage_exceeded",
  "metered_feature_id": "gpt4o-usage",
  "threshold": {
    "mode": "percentage",
    "value": 90
  },
  "filter_conditions": [
    {
      "field": "plan_price_id",
      "operator": "equals",
      "value": "enterprise"
    },
    {..}
  ],
  "subscription_id": null,
  "status": "enabled",
  "object": "alert",
  "resource_version": 1763879971000,
  "created_at": 1763879971,
  "updated_at": 1763879971
}
```

## Alerts attributes

## Input Parameters

- `id` (required, string, max chars=40)
  Uniquely identifies the alert configuration.

- `type` (required, enumerated string)
  The type of alert. Determines what the alert measures, which input it requires, and how the `threshold` is interpreted.
  Possible enum values:
    - `usage_exceeded`
      The alert fires when usage of the [metered feature](/docs/api/usages) (identified by `metered_feature_id`) reaches or exceeds the configured threshold. Supports both `percentage` and `absolute` threshold modes.
    - `spend_exceeded`
      The alert fires when the total usage-based spend accumulated from metered addons reaches or exceeds the configured threshold. Only spend from usage beyond the included entitlement is counted. See [usage charges](/docs/api/usage_charges) for how overage spend is computed. The `threshold` mode is always `absolute`.
    - `credit_balance_dropped`
      The alert fires when the [credit balance](/docs/api/ledger_account_balances) for the configured credit unit drops to or below the configured threshold. The `threshold` mode is always `absolute`.

- `name` (required, string, max chars=50)
  A human-readable name for the alert, shown in the Chargebee UI and webhook payloads. Maximum 50 characters.

- `description` (optional, string, max chars=65k)
  An optional description providing additional context about the alert. Maximum 65,000 characters.

- `metered_feature_id` (optional, string, max chars=50)
  Identifier of the [metered feature](/docs/api/usages) that this alert monitors. Present only for `usage_exceeded` alerts.

- `currency_code` (optional, string, max chars=3)
  The ISO [currency code](/docs/api/currencies/currency-object#currency_code) in which the metered-addon overage spend is measured. Present only for `spend_exceeded` alerts.

- `unit_id` (optional, string, max chars=50)
  Identifier of the credit unit that this alert monitors. Present only for `credit_balance_dropped` alerts.

- `subscription_id` (optional, string, max chars=50)
  The identifier of the [subscription](/docs/api/subscriptions) this alert is scoped to. Present only for subscription-scoped alerts; `null` for global alerts.

- `status` (optional, enumerated string, default=enabled)
  Whether the alert is currently active. A `disabled` alert is not evaluated.
  Possible enum values:
    - `enabled`
      The alert is active and will trigger when the threshold is breached.
    - `disabled`
      The alert is inactive and will not trigger.

- `meta` (optional, string, max chars=65k)
  An optional string field for storing custom metadata with the alert (for example, JSON serialized by your integration). Maximum 65,000 characters.

- `created_at` (required, timestamp(UTC) in seconds)
  Timestamp (UTC, in seconds) indicating when the alert was created.

- `updated_at` (required, timestamp(UTC) in seconds)
  Timestamp (UTC, in seconds) indicating when the alert was last updated.

- `threshold` (optional, threshold)
  The threshold configuration that defines when this alert fires.
  - `mode` (required, enumerated string)
    How the threshold `value` is interpreted. `usage_exceeded` alerts support `percentage` or `absolute`. `spend_exceeded` and `credit_balance_dropped` alerts always use `absolute`.
    Possible enum values:
      - `absolute`
        The threshold `value` represents an absolute quantity: a usage quantity for `usage_exceeded`, an overage spend amount for `spend_exceeded`, or a credit-balance floor for `credit_balance_dropped`. For `spend_exceeded`, the amount is expressed in the major units of `currency_code` (for example, dollars—not cents—for `USD`, so `500.0` means 500 USD).
      - `percentage`
        The threshold `value` represents a percentage (0-100) of the plan or feature quota. Supported only for `usage_exceeded` alerts.
  - `value` (required, double)
    The numeric threshold at which the alert fires. For `percentage` mode, this must be between 0 and 100 inclusive. For `absolute` mode, this must be >= 0.

- `filter_conditions` (optional, list of filter_condition)
  An array of conditions that restrict which subscriptions a global alert applies to. Multiple conditions are evaluated with OR logic. Cannot be set when `subscription_id` is provided.
  - `field` (required, enumerated string)
    The subscription attribute to filter on. Currently only `plan_price_id` is supported.
    Possible enum values:
      - `plan_price_id`
        Filters by the plan price associated with the subscription.
  - `operator` (required, enumerated string)
    The comparison operator for the filter condition.
    Possible enum values:
      - `equals`
        The subscription attribute must equal the specified `value`.
      - `not_equals`
        The subscription attribute must not equal the specified `value`.
  - `value` (required, string, max chars=50)
    The value to compare against, for example, a specific plan price identifier. Maximum 50 characters.