UsageBalance

A usage balance represent the amount of usage consumed from an Allowance for a given Subscription in a certain Period.

Name
object
Type
string
Description
Type of object is always usageBalance.
Allowed values: usageBalance
Name
id
Type
string
Description
Unique identifier for the usage balance.
Example: "ubl_0V9n0zo90CE0NuvcsN0j88"
Name
allowance
Type
Allowance
Description
The Allowance this usage balance is tracking.
Name
subscription
Type
string
Description
Unique identifier of the Subscription the usage balance is related to.
Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
Name
source
Type
UsageBalanceSource
Description
The entity providing the allowance to the Subscription.
Example: {"type":"subscriptionPeriod","subscriptionPeriod":4,"subscriptionAddon":null},{"type":"subscriptionAddon","subscriptionPeriod":null,"subscriptionAddon":"sad_0SNlurA049MEWV2UNWPbDfW5B40U"}
Name
type
Type
string
Description
The entity type providing the allowance.
Allowed values: subscriptionPeriod subscriptionAddon
Name
subscriptionPeriod
Type
nullable integer
Description
When the allowance is provided by the subscription's plan, the subscription period this usage balance is bound by.
Optional: This property may not always be included.
Example: 4
Name
subscriptionAddon
Type
nullable string
Description
When the allowance is provided by a Subscription Add-on, the subscription add-on this usage balance is provided by.
Optional: This property may not always be included.
Example: "sad_0SNlurA049MEWV2UNWPbDfW5B40U"
Name
unit
Type
string
Description
The unit the usage is counted in.
Allowed values: bytes seconds messages
Name
used
Type
integer
Description
The amount of usage consumed, counted in unit.
Example: 230
Name
limit
Type
nullable integer
Description
The amount of usage permitted by the associated allowance counted in unit. A value of null indicates an unlimited allowance.
Example: 500
Name
remaining
Type
nullable integer
Description
The amount remaining that can still be consumed, counted in unit. A value of null indicates an unlimited allowance.
Example: 270
Name
usedPercent
Type
nullable integer
Description
The percent of limit that has been used. A value of null indicates an unlimited allowance.
Example: 46
Name
remainingPercent
Type
nullable integer
Description
The percent of limit that has not been used. A value of null indicates an unlimited allowance.
Example: 54
Name
usableFrom
Type
string
Description
Timestamp representing the beginning of this usage balance's validity.
Example: "2026-01-03T13:41:24Z"
Name
usableUntil
Type
string
Description
Timestamp representing the end of this usage balance's validity.
Example: "2026-02-03T13:41:24Z"

Example

{
  "object": "usageBalance",
  "id": "ubl_0V9n0zo90CE0NuvcsN0j88",
  "allowance": {
    "object": "allowance",
    "name": "Long distance calls while roaming in Germany",
    "type": "data",
    "coverage": {
      "object": "coverage",
      "id": "de",
      "countries": [
        "DE",
        "FR",
        "US"
      ],
      "name": "Europe"
    },
    "limit": 500,
    "unit": "bytes"
  },
  "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "source": {
    "type": "subscriptionPeriod",
    "subscriptionPeriod": 4,
    "subscriptionAddon": null
  },
  "unit": "bytes",
  "used": 230,
  "limit": 500,
  "remaining": 270,
  "usedPercent": 46,
  "remainingPercent": 54,
  "usableFrom": "2026-01-03T13:41:24Z",
  "usableUntil": "2026-02-03T13:41:24Z"
}