# Usage Events and Notifications

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][events] 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.

```mermaid
sequenceDiagram
    actor User
    participant Carrier as Carrier
    participant Gigs as Gigs Platform
    participant App as Your App

    User->>App: Purchases roaming add-on
    App->>Gigs: Activate the add-on via Gigs API
    User->>Carrier: Arrives in France, starts using data
    Carrier->>Gigs: deliver Usage Data
    Note left of Gigs: a few minutes later
    Note left of App: Subscribed to webhooks
    Gigs->>App: usageNotification.created (type: started)
    Note over App: First usage detected
    User->>Carrier: Continues consuming data
    Carrier->>Gigs: more Usage Data
    Gigs->>App: usageBalance.thresholdReached (50%)
    Gigs->>App: usageBalance.thresholdReached (70%)
    Note over App: Send push notification
    Gigs->>App: usageBalance.thresholdReached (90%)
    Note over App: Prompt add-on upsell
    Gigs->>App: usageBalance.thresholdReached (100%)
    Note over App: Allowance fully depleted
```

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][threshold-event] for the full payload structure.

<Note type="info">

This is the recommended event for percentage-based usage tracking in new integrations. It fires at consistent thresholds across all configurations and provides full balance context in every payload.

</Note>

### usageNotification.created

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

| Type | Description |
|---|---|
| `started` | First usage detected on a subscription |
| `throttled` | Data throttled to lower bandwidth after allowance depletion |
| `thresholdExceeded` | 70/90/100% allowance exceeded (older format, limited provider support) |

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][notification-event] for the full payload structure.

<Note type="warning">

The `thresholdExceeded` notification type has limited provider support and does not work with all configurations. For percentage-based tracking, use `usageBalance.thresholdReached` instead.

</Note>

## Deprecated: usageThreshold.exceeded

<Note type="warning">

The `usageThreshold.exceeded` event is deprecated. Do not subscribe to it in new integrations. Use `usageNotification.created` for first-use and throttling detection, and `usageBalance.thresholdReached` for percentage-based depletion tracking. The [event schema][deprecated-event] remains available for reference only.

</Note>

## 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][events] - Learn how to access events and configure webhooks in Gigs.
- [`com.gigs.usageBalance.thresholdReached`][threshold-event] - schema documentation
- [`com.gigs.usageNotification.created`][notification-event] - schema documentation

[events]: /docs/core/events/events-webhooks
[threshold-event]: /api/latest/events/schemas/com.gigs.usageBalance.thresholdReached
[notification-event]: /api/latest/events/schemas/com.gigs.usageNotification.created
[deprecated-event]: /api/latest/events/schemas/com.gigs.usageThreshold.exceeded