Usage Alerts
This feature is a Private Beta release. Contact Chargebee Support to enable Usage Alerts for your live and test sites.
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. 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.
Alerts help you stay ahead of these scenarios by allowing you to define thresholds on metered features and take action as customers approach or exceed them. Chargebee Billing evaluates alerts within seconds of receiving usage events, enabling near real-time monitoring and response.
You can use Alerts to:
- Notify customers before they reach their usage limits.
- Prevent overages by enforcing hard caps.
- Trigger automatic plan upgrades or add-ons.
- Monitor usage trends for customer success and sales teams.
- Detect unusual spikes or drops in usage.
- Enable proactive billing transparency and reduce disputes.
How it works
Alerts build on your existing usage-based billing setup.
-
Define an alert
Choose a metered feature, set a threshold (for example, 80% of a quota or an absolute value like 10,000 API calls), and define whether the alert applies globally or to a specific subscription. -
Send usage events
As customers use your product, usage events are sent to Chargebee Billing through your existing ingestion setup. -
Evaluate usage against thresholds
Chargebee evaluates incoming usage events and checks whether any subscription has crossed a defined threshold. -
Trigger alert status change and webhook
When usage crosses a threshold:- The alert status changes from
within_limittoin_alarm. - Chargebee sends an
alert_status_changedwebhook.
- The alert status changes from
-
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.
When usage resets at the start of a new billing cycle, alert statuses automatically return to within_limit.
Key concepts
Alerts and alert statuses
| Concept | What it represents | How you interact with it |
|---|---|---|
| Alert | The rule: which feature, what threshold, what scope. | 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), orin_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 | Applies to all subscriptions using the specified metered feature. | 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 | Continues if the new plan uses the metered feature and matches filter conditions. | Persists if the metered feature still exists on the new plan. |
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.
Was this article helpful?