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

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

2. Send usage events
   As customers use your product, usage events are sent to Chargebee Billing through your existing ingestion setup.

3. Evaluate usage against thresholds
   Chargebee evaluates incoming usage events and checks whether any subscription has crossed a defined threshold.

4. Trigger alert status change and webhook
   When usage crosses a threshold:

   • The alert status changes from within_limit to in_alarm.
   • Chargebee sends an alert_status_changed webhook.

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

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

Behavior during subscription changes

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.