Introducing OpenTelemetry for Chargebee SDKs — trace every API call in any telemetry tool.
Chargebeechargebee API

Create an alert

Idempotency Supported

Creates a new alert configuration. Depending on type, the alert can monitor usage or spend, and it can be global or subscription-scoped depending on whether subscription_id is provided.

Note: Creating an alert defines the threshold rule only. After an alert is created, Chargebee begins evaluating it as relevant billing data changes are processed. Alert statuses are created and updated during alert evaluation. The runtime evaluation state for each subscription is available via the Alert Status endpoints.

Prerequisites & Constraints

  • For usage_exceeded alerts, metered_feature_id must reference an existing metered feature configured on your site.
  • For spend_exceeded alerts, provide currency_code.
  • Provide only the input that matches the alert type: metered_feature_id and currency_code are mutually exclusive.
  • For spend_exceeded alerts, threshold mode is optional and defaults to absolute when omitted; if provided, it must be absolute. Only usage_exceeded alerts support percentage mode.
  • For filter_conditions, only plan_price_id is supported as the field, with operator equals or not_equals.

Use Cases

Create a usage alert

Set type to usage_exceeded and provide metered_feature_id. Use a percentage threshold to fire relative to the plan or feature quota (for example, at 90%), or an absolute threshold to fire at a specific usage quantity.

Create a spend alert

Set type to spend_exceeded and provide currency_code. The alert monitors the usage-based spend accumulated from metered addons (counting only usage beyond the included entitlement) and fires when it reaches the absolute threshold amount in that currency.

Sample Request

Create a spend alert

Sample Result[JSON]

URL Format

POST https://[site].chargebee.com/api/v2/alerts

Input Parameters

type
required, enumerated string

The type of alert to create. Determines what the alert measures, which input it requires, and how the threshold is interpreted.

Enum Values
usage_exceeded

The alert fires when usage of the metered feature (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 for how overage spend is computed. The threshold mode is always absolute.

name
required, string, max chars=50

A human-readable name for the alert. 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 that the alert should monitor. Required when type is usage_exceeded; do not set it for other alert types.

currency_code
optional, string, max chars=3

The ISO currency code in which the metered-addon overage spend is measured. Required when type is spend_exceeded; do not set it for other alert types.

subscription_id
optional, string, max chars=50

The identifier of the subscription to scope this alert to. If omitted, the alert is created as a global alert. If provided, filter_conditions must not be set.

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.

threshold
Parameters for threshold
pass parameters as threshold[<param name>]
filter_conditions[0..n]
Parameters for filter_conditions. Multiple filter_conditions can be passed by specifying unique indices.
pass parameters as filter_conditions[<param name>][<idx:0..n>]

Returns

alert
Alert object
Resource object representing alert