Usage Alerts

When you bill customers based on usage, having real-time visibility into consumption is critical, not just for accurate billing, but for delivering a predictable and trustworthy customer experience. Without proactive monitoring, customers can be caught off guard by unexpectedly high invoices, or a prepaid credit balance can run out before anyone notices. At the same time, your business may miss opportunities to guide customers toward better-fitting plans, prevent excessive usage, or identify accounts that need attention.

An alert lets you define a threshold and take action when a subscription crosses it. Chargebee Billing supports three alert types: Usages, Spends, and Credits. Alerts for Usages and Spends are currently in beta and are available when Usage-Based Billing is enabled. Credits alerts are in early access and requires Prepaid Creditsfeature to be enabled.

You can use Alerts to:

Notify customers before they reach their usage limits.
Notify your team when accrued usage charges cross a spend amount.
Identify subscriptions whose prepaid credit balance needs a top-up.
Prevent overages by enforcing hard caps.
Trigger automatic plan upgrades or addons.
Monitor usage trends for customer success and sales teams.
Detect unusual spikes or drops in usage.
Enable proactive billing transparency and reduce disputes.

Alert types

Choose the alert type when you create the alert. Each type watches a different value and uses its own criteria.

Alert type	When it triggers	Criteria you set
Usages	A subscription's usage of a metered feature reaches the threshold. Use this type to watch usage quantity, such as a percentage of included usage.	Select the metered feature. The form shows exceeds, a percentage, and of included usage.
Spends	Usage charges from metered addons reach the amount you set. Chargebee counts only usage beyond the included entitlement. Other charges on the subscription are outside this threshold.	Select the currency, such as USD - $ US Dollars. The form shows exceeds and an amount in that currency.
Credits	The prepaid credit balance for one credit unit on a subscription drops to or below the amount you set. Prepaid Credits must be enabled before you can use this alert type. Each credit alert applies to a subscription and a credit unit. Use this type to find subscriptions that need a top-up before credits run out.	Select the credit unit. The form shows drops to and an amount in that unit.

Under Apply Alert to, Usages and Spends can apply to All Subscriptions or to Subscriptions containing specific items. For Credits, only All Subscriptions is available.

See Setting up Alerts for the steps to create each type.

How it works

Alerts build on your existing usage-based billing setup.

Define an alert
Choose Usages, Spends, or Credits, set the threshold, and choose which subscriptions the alert applies to.
Activity reaches Chargebee Billing
- For Usages, your application sends usage events.
- For Spends, Chargebee Billing tracks accrued usage charges on the subscription.
- For Credits, Prepaid Credits ledger activity updates the balance for the credit unit.
Evaluate the value against the threshold
Chargebee Billing checks whether a subscription has crossed the threshold for that alert.
Trigger alert status change and webhook
When the threshold is crossed:
- The alert status changes from within_limit to in_alarm.
- Chargebee sends an alert_status_changed webhook.
Take action in your system
Based on the webhook, your system can:
- Notify customers (email, in-app, SMS).
- Restrict or pause usage.
- Upgrade plans automatically.
- Alert internal teams so they can remind a customer to top up credits.

For a Usages alert, when usage resets at the start of a new billing cycle, the alert status returns to within_limit.

Key concepts

Alerts and alert statuses

Concept	What it represents	How you interact with it
Alert	The rule: which alert type, what threshold, and which subscriptions it applies to.	Create, update, enable/disable, delete via UI or API.
Alert Status	The live state: is this subscription within limit or in alarm?	Read-only, automatically computed by Chargebee.

Webhook Notifications

When an alert status changes, either:

within_limit → in_alarm (threshold breached), or
in_alarm → within_limit (usage reset)

Chargebee sends an alert_status_changed webhook to your configured endpoint.

The webhook payload includes:

Alert configuration
Current alert status
Subscription context

This ensures your system has all the information needed to take immediate action.

Global alerts vs. subscription-scoped alerts

	Global Alert	Subscription-scoped Alert
Scope	Usages: subscriptions that use the selected metered feature. Spends: subscriptions in the currency you select. In the API, that currency is `currency_code`. Credits: subscriptions that use the selected credit unit. In the API, that unit is `unit_id`.	Applies to a single subscription only.
Filter conditions	Optionally narrow to specific plans using plan_price_id. Supports OR logic.	Not supported. The alert is tied directly to the subscription_id.
Alert status	Created per matching subscription.	Single alert status.
Best for	Scaling across plans.	Custom monitoring for specific customers.

Behavior during subscription changes

Change	Global alert	Subscription-scoped alert
New subscription on matching plan	Automatically applies and creates alert status.	No effect.
Subscription changes to a different plan	Usages: continues when the new plan uses the metered feature and matches the filter conditions. Spends: follows the selected currency and any plan filter. Credits: follows the selected credit unit and any plan filter.	Usages: persists when the metered feature is still on the new plan. Spends: follows the selected currency. Credits: follows the selected credit unit.

Common use cases

Overage prevention and customer notifications

Set thresholds at key milestones:

80% → early warning
100% → final alert or upgrade prompt

When Chargebee sends the alert_status_changed webhook, you can trigger an email to the customer, show an in-app banner, or trigger any workflow automation.

Hard usage caps

Set an absolute threshold at the maximum usage you want to allow.

When the alert transitions to in_alarm, your application can block further access or queue the request. This is commonly used in API platforms or infrastructure services that need to enforce rate limits per billing period.

Plan-specific monitoring

Use global alerts with filters to define different thresholds based on the plan.

For example:

Starter plan → alert at 80%
Enterprise plan → alert at 95%

This avoids creating individual alerts for every subscription — one global alert per plan covers all customers on that plan.

Customer success and internal monitoring

Track usage patterns to identify:

High-usage accounts(upsell opportunities)
Low-usage accounts(risk of churn or underutilization)

Customer success teams can prioritize outreach based on alert activity.

Spend thresholds

Create a Spends alert at the metered-addon overage amount where you want to contact the customer. Chargebee counts usage beyond the included entitlement. When the alert changes to in_alarm, your team can reach out or adjust the plan before rising usage becomes an unexpected invoice.

Low prepaid credit balance

Create a Credits alert at the balance where a subscription needs a top-up. When the balance drops to or below that amount, the alert changes to in_alarm and Chargebee sends alert_status_changed. Your team can remind the customer before the credits run out. See Prepaid Credits.