Usage Balances Core Concepts

This section covers the core concepts of the Usage Balances object model.

This page covers the data model of the Usage Balances API (GET /projects/{project}/usageBalances). The Usage Balance API returns an "allowance meter" for data, voice and SMS consumption on a user plan and add-on basis, ideal for showing to users. For aggregated consumption records that can be sliced by time range, country, and roaming status see Usage Records.

Getting Started with Usage Balances

Usage Balances give your app a single, pre-computed view of what each user has used and what they have left, broken down by the plans and add-ons the user has available to them. One API call returns consumed amounts, remaining amounts, and percentages for each allowance on a subscription.

Common use cases

• In-app usage display. Render progress bars per allowance, labels per coverage region, and separation between base-plan and add-on entitlements, all from one response.
• Threshold notifications and upselling. React to the usageBalance.thresholdReached webhook event when a user crosses 50%, 70%, 90% and 100% of an allowance, allow you to prompt add-on purchases in your app or by sending push notifications.
• Customer Support. Verify users have successfully used their purchased plans and add-ons.

Here we describe the main concepts of the Usage Balance object model.

Usage Balance vs. Allowance

An Allowance is the fixed definition what a product (plan or add-on) entitles a user to. A Usage Balance is the active "instance" of an Allowance, providing the consumption of data, voice and SMS allowed by the product.

• Allowance = the entitlement (e.g. "10 GB of data included")
• Usage Balance = the meter (e.g. "4.2 GB used of 10 GB")

The Usage Balance object

A Usage Balance is an activated instance of an Allowance, tied to a specific subscription, for a specific time window in the case of plans or to a specific add-on. It tracks how much of that Allowance has been consumed.

Usage Balances are created automatically when a subscription or subscription add-on activates. This means Usage Balances can exist before they are actually used. For example a user in the United States purchases a data roaming add-on before a trip to France; the Usage Balance will be created once the purchase is completed (activating the add-on) and show zero usage. Once the user lands in France, where the add-on applies, the Usage Balance will begin showing data consumption.

How Balances Map to Allowances

Each Allowance belongs to a subscription plan or add-on. There can be up to three Allowances per plan or add-on; one each for data, voice and SMS, depending one how the plan or add-on has been configured.

In the case of add-ons, the relationship between Allowances and Usage Balances is one-to-one, because add-ons are not recurring.

For subscription plans, there can be a one-to-many relationship between Allowances and Usage Balances, as the plan may recur over multiple subscription periods. Generally the Usage Balance API will return the data, voice and SMS balances for the current subscription plan period, although this can be steered with the subscriptionPeriod query parameter.

Usage Balance Fields

Allowance

An Allowance defines what a product (plan or add-on) entitles a user to. It is a definition: it describes what is included but does not track consumption.

Note a single plan or add-on can have multiple Allowances. For example: 20 GB roaming data, 3000 seconds of international voice and 100 international SMS, each a separate Allowance - see How Balances Map to Allowances.

Unlimited allowances

If the product is an unlimited plan, unlimited allowances return limit as null.

• When limit is null, remaining, usedPercent, and remainingPercent are all also null.
• The used field still increments.
• Check limit for null before doing arithmetic or rendering progress bars.

{
  "used": 52000000000,
  "limit": null,
  "remaining": null,
  "usedPercent": null,
  "remainingPercent": null
}

Coverage

A Coverage object describes the geographic scope of an Allowance.

Coverage helps determine which usage counts against which Allowance. Data used in France counts against an Allowance whose coverage includes "FR".

When multiple Allowances overlap geographically (e.g. "Europe" and "Global" both cover France), the carrier determines consumption priority. The Usage Balance API reflects the result but does not expose priority rules directly.

Source

Every Usage Balance has a source indicating where the allowance comes from, which contains the follow fields...

Subscription period

A subscription period is a billing cycle numbered sequentially starting from 1. Period 1 is the first billing cycle after activation, period 2 is the next, and so on. Each period has a start and end time determined by the plan's billing interval (e.g. monthly).

Period-sourced Usage Balances renew each period. When a new period starts, fresh Usage Balances are created with reset limits for that period's allowances.

Note subscription periods only apply to plans and not add-ons.

Period-sourced example:

{
  "type": "subscriptionPeriod",
  "subscriptionPeriod": 1
}

Add-on-sourced example:

{
  "type": "subscriptionAddon",
  "subscriptionAddon": "sad_0VEIgoYA3lDwMx1CEihKTo9joStp"
}

Units

The unit the usage is counted in. Allowed values:

Percentages

Percentages are all integers so usedPercent and remainingPercent will be between 0 and 100. A user at 46% usage will have "usedPercent": 46, not 46.0.

ID prefixes

Next steps

• Usage APIs - How to use the Usage Balance API and the Usage API
• Usage Events - Subscribe to webhook events for usage thresholds, first-use detection, and data throttling on Gigs subscriptions.
• Testing Usage Balances - How to test and simulate usage on Usage Balances.