A user purchases a roaming add-on, arrives abroad, and starts consuming data. Your app needs to know when that happens so it can send a push notification or prompt an add-on upsell. Gigs fires webhook events at consumption milestones so you can react in real time without polling the API. See the events and webhooks guide for setup instructions.

How usage events work

The diagram below shows the lifecycle of a roaming add-on purchase, from activation through threshold events to full depletion.

Two event types work together to give you full visibility into user consumption. usageNotification.created detects first usage on a subscription and bandwidth throttling. usageBalance.thresholdReached tracks percentage-based depletion at fixed intervals as the user consumes their allowance.

Event reference

usageBalance.thresholdReached

Fires when a usage balance's consumed percentage first equals or exceeds a threshold: 50%, 70%, 90%, or 100%. The event payload contains the full UsageBalance object at the time the threshold was crossed, including allowance, source, used and remaining amounts, and percentage fields.

The usedPercent value in the payload may be higher than the exact threshold value. This happens because usage data arrives from network providers in batches rather than byte-by-byte. By the time Gigs receives an update, the user may have already consumed past the threshold. For example, if the 90% threshold is configured, the event may be delivered when usedPercent is 92% or higher, depending on the size of the last usage update received from the carrier.

This event fires per-allowance, not per-subscription. If a user has a base plan and an add-on, each allowance fires its own threshold events independently. This makes it straightforward to track depletion for each allowance source separately.

See the event schema reference for the full payload structure.

usageNotification.created

Fires when a usage notification is generated for a subscription. Three notification types exist:

Subscribe to started and throttled events for first-use detection and bandwidth changes. These have no equivalent in usageBalance events and are the only way to detect these conditions through webhooks.

See the event schema reference for the full payload structure.

Deprecated: usageThreshold.exceeded

Using both events together

You can subscribe to both usageBalance.thresholdReached and usageNotification.created at the same time. They serve different purposes and will not duplicate each other.

• Use usageNotification.created to detect when a user first uses their allowance (started) and when their bandwidth is reduced after depletion (throttled).
• Use usageBalance.thresholdReached to track percentage-based consumption when usage first equals or exceeds the 50%, 70%, 90%, and 100% thresholds.

Next Steps

• Events and Webhooks - Learn how to access events and configure webhooks in Gigs.
• com.gigs.usageBalance.thresholdReached - schema documentation
• com.gigs.usageNotification.created - schema documentation