Usage Balances

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

Properties

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 percentage of limit that has been used, expressed as an integer between 0 and 100. A value of null indicates an unlimited allowance.
Example: 46
Name
remainingPercent
Type
nullable integer
Description
The percentage of limit that has not been used, expressed as an integer between 0 and 100. 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. A value of null indicates a pending balance that is not yet active, for example when a customer purchases an add-on ahead of use.
Example: "2026-01-03T13:41:24Z"
Name
usableUntil
Type
string
Description
Timestamp representing the end of this usage balance's validity. A value of null indicates a pending balance that is not yet active, for example when a customer purchases an add-on ahead of use.
Example: "2026-02-03T13:41:24Z"

Example

{
  "object": "usageBalance",
  "id": "ubl_0V9n0zo90CE0NuvcsN0j88",
  "allowance": {
    "object": "allowance",
    "id": "alw_0SNlurA049MEWV3OMTRrGKbd99GH",
    "name": "Roaming data in Europe",
    "type": "data",
    "coverage": {
      "object": "coverage",
      "id": "de",
      "countries": [
        "DE",
        "FR",
        "US"
      ],
      "name": "Europe"
    },
    "limit": 500,
    "unit": "bytes",
    "priority": 1
  },
  "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"
}

GET/projects/{project}/usageBalances

List all usage balances

Returns a list of usage balances for the given project. The list can be filtered by subscription, subscription period, or subscription add-on. When filtering by subscription without specifying subscriptionPeriod or subscriptionAddon, all usage balances for the subscription are returned regardless of source type or period.

Preview

This endpoint is currently in preview and might change in the future.

We’re excited to hear your feedback and ideas. Please send an email to support@gigs.com to share your thoughts.

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: "gigs"

Query Parameters

Name
subscription
Type
string
Description
Filter usage balances by Subscription ID.
Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
Name
subscriptionPeriod
Type
string
Description
Filter usage balances by subscription period. Requires the subscription parameter. Accepts a positive integer, the special value current, or a negative integer to request previous periods (e.g., -1 for the previous period). Cannot be combined with subscriptionAddon. A usage balance is sourced from either a subscription period or a subscription add-on, never both - combining these will return an error.
Example: "current"
Name
subscriptionAddon
Type
string
Description
Filter usage balances by Subscription Add-on ID. Can be combined with subscription but not with subscriptionPeriod. A usage balance is sourced from either a subscription period or a subscription add-on, never both — combining these will return an error.
Example: "sad_0SNlurA049MEWV2UNWPbDfW5B40U"
Name
after
Type
string
Description
A cursor for use in pagination. The after parameter takes an object ID that defines the position in the list, only items immediately following the item with that ID will be returned.
Name
before
Type
string
Description
A cursor for use in pagination. The before parameter takes an object ID that defines the position in the list, only items immediately preceding the item with that ID will be returned.
Name
limit
Type
integer
Description
The limit of items to be returned in the list, between 0 and 200.
Default: 10
>= 0
<= 200

Responses

Returns a list of usage balances.

Name
object
Type
string
Description
Type of object is always list.
Allowed values: list
Name
items
Type
array
Description
List of objects of type usageBalance.
Name
moreItemsAfter
Type
nullable string
Description
A unique identifier to be used as after pagination parameter if more items are available sorted after the current batch of items.
Name
moreItemsBefore
Type
nullable string
Description
A unique identifier to be used as before pagination parameter if more items are available sorted before the current batch of items.

Request

GET

/projects/{project}/usageBalances

curl https://api.gigs.com/projects/${GIGS_PROJECT}/usageBalances \
-X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${GIGS_TOKEN}" \
-H "Accept: application/json"

Responses

{
  "object": "list",
  "items": [
    {
      "object": "usageBalance",
      "id": "ubl_0V9n0zo90CE0NuvcsN0j88",
      "allowance": {
        "object": "allowance",
        "id": "alw_0SNlurA049MEWV3OMTRrGKbd99GH",
        "name": "Roaming data in Europe",
        "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"
    }
  ],
  "moreItemsAfter": null,
  "moreItemsBefore": null
}

GET/projects/{project}/usageBalances/{usageBalance}

Retrieve a usage balance

Returns the details of an existing usage balance.

Preview

This endpoint is currently in preview and might change in the future.

We’re excited to hear your feedback and ideas. Please send an email to support@gigs.com to share your thoughts.

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: "gigs"
Name
usageBalance
Type
string
required
Description
The unique identifier for the usage balance.
Example: "ubl_0V9n0zo90CE0NuvcsN0j88"

Responses

Returns the usage balance.

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 percentage of limit that has been used, expressed as an integer between 0 and 100. A value of null indicates an unlimited allowance.
Example: 46
Name
remainingPercent
Type
nullable integer
Description
The percentage of limit that has not been used, expressed as an integer between 0 and 100. 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. A value of null indicates a pending balance that is not yet active, for example when a customer purchases an add-on ahead of use.
Example: "2026-01-03T13:41:24Z"
Name
usableUntil
Type
string
Description
Timestamp representing the end of this usage balance's validity. A value of null indicates a pending balance that is not yet active, for example when a customer purchases an add-on ahead of use.
Example: "2026-02-03T13:41:24Z"

Request

GET

/projects/{project}/usageBalances/{usageBalance}

curl https://api.gigs.com/projects/${GIGS_PROJECT}/usageBalances/{usageBalance} \
-X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${GIGS_TOKEN}" \
-H "Accept: application/json"

Responses

{
  "object": "usageBalance",
  "id": "ubl_0V9n0zo90CE0NuvcsN0j88",
  "allowance": {
    "object": "allowance",
    "id": "alw_0SNlurA049MEWV3OMTRrGKbd99GH",
    "name": "Roaming data in Europe",
    "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": "sad_0SNlurA049MEWV2UNWPbDfW5B40U"
  },
  "unit": "bytes",
  "used": 230,
  "limit": 500,
  "remaining": 270,
  "usedPercent": 46,
  "remainingPercent": 54,
  "usableFrom": "2026-01-03T13:41:24Z",
  "usableUntil": "2026-02-03T13:41:24Z"
}