Skip to main content

​
Overview

Usage alerts notify you when a subscription’s usage crosses thresholds you define. Common use cases:
  1. Allow customers to set and manage their own usage limits and budgets, empowering them to control their consumption;
  2. Alert customers with skyrocketing usage to prevent unexpected costs or overages on their bills; or
  3. Implement entitlement logic to halt usage tracking when a customer reaches their predefined limit, ensuring accurate billing and compliance.
Usage alerts are a premium feature. Free users cannot create alerts on a subscription.

​
Create an alert

An alert must be tied to a specific subscription. To create an alert for a particular subscription, follow these steps:
  1. Access the specific subscription view;
  2. Click on the Alerts tab;
  3. Click on the Create alerts button;
  4. Select the type of alert (e.g., Lifetime usage amount);
  5. Set the progressive thresholds and code for the alert;
  6. Define the optional recurring threshold for the alert; and
  7. Click on the Create alert button to confirm.
The alert threshold code helps distinguish between different types of alert notifications. For example, some notifications may indicate a soft limit, while others may trigger a hard limit, each with different levels of urgency or action required.
The Alerts on subscription form, with the alert name, the alert type and the threshold triggers

Create an alert

​
Alert types

Lago supports the following usage alert types. You can also create multiple alerts at once by sending an alerts array to the same create endpoint, or delete all alerts for a subscription in a single API call.
  • Lifetime usage amount (lifetime_usage_amount): Triggered when a subscription’s lifetime usage exceeds predefined thresholds.
  • Current usage amount (current_usage_amount): Triggered when a subscription’s usage exceeds predefined thresholds for the current billing period.
  • Billable metric current usage amount (billable_metric_current_usage_amount): Triggered when the usage of a specific billable metric exceeds predefined thresholds for the current billing period.
  • Billable metric current usage units (billable_metric_current_usage_units): Triggered when the number of units of a specific billable metric exceeds predefined thresholds for the current billing period.
  • Billable metric lifetime usage units (billable_metric_lifetime_usage_units): Triggered when the lifetime number of units of a specific billable metric exceeds predefined thresholds.
The two lifetime alert types also need a premium add-on. lifetime_usage_amount needs the lifetime usage add-on or progressive billing, and billable_metric_lifetime_usage_units needs the granular lifetime usage add-on. Without it, creating the alert fails with a feature_not_available error.

​
Alert notifications

After configuring an alert and starting to ingest usage, you can listen for the alert.triggered webhook message. These webhooks serve as notifications sent to your system, indicating when an alert threshold has been crossed, along with all the relevant alert details.

​
Limitations

  • Alerts only evaluate usage data reported after their creation;
  • Alerts are processed close to real time; and
  • Each alert code must be unique per subscription, and only one alert per type (per billable metric for metric-scoped types) can exist on a subscription.