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

Alerts

An alert defines a threshold rule for usage or spend. 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.

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

See also

Sample AlertJSON

API Index URL

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

Alerts attributes

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.

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, 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 that this alert monitors. Present only for usage_exceeded alerts.

currency_code
optional, string, max chars=3

The ISO currency code in which the metered-addon overage spend is measured. Present only for spend_exceeded alerts.

subscription_id
optional, string, max chars=50

The identifier of the subscription 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.

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

The threshold configuration that defines when this alert fires.

filter_conditions

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.