For AI agents and LLMs: a structured documentation index is available at /llms.txt. Every page has a Markdown sibling — append .md to any URL. To search these docs, send a GET request to https://paddle-docs-retrieval.kapa-paddle.workers.dev/?q=<question> with a URL-encoded question. No authentication needed.

Skip to content
Paddle Docs home

List grants for a usage balance

Returns a paginated list of grants for a usage balance.

Join usage-based billing early access (beta)

Usage-based billing is in early access (beta). Read how it works, then apply to join. We'll reach out if you meet the program requirements.

GET/customers/{customer_id}/usage-balances/{usage_balance_id}/grants

Returns a paginated list of grants for a usage balance. Use the query parameters to page through results.

A grant is an amount of a usage balance unit that funds a usage balance, like the allowance from a subscription. Usage balances belong to customers rather than subscriptions, so a customer with more than one subscription that includes the same usage balance unit has a grant from each. Use grants to show customers how much of each subscription's allowance is left and when it expires.

Grants stay in the list until they expire or a renewal replaces them, including grants that are used up. Paddle doesn't return expired or replaced grants, so you can't use grants to get the history of a usage balance.

Added together, amount.remaining across all grants equals balance.remaining.total on the usage balance. Paddle updates grants and usage balances shortly after it processes events, so a new grant might take a moment to appear, and the totals might not match until it does. Grants don't include overage, which is usage recorded after the customer's grants are used up.

Paddle creates grants automatically, so you can't create or update them using the API.

Requires usage_balance.read permission.

Path parameters

customer_idstringrequired
Example: ctm_01grnn4zta5a1mf02jjze7y2ys
Unique Paddle ID for this customer entity, prefixed with ctm_.
Pattern: ^ctm_[a-z\d]{26}$
usage_balance_idstringrequired
Paddle ID of the usage balance entity to work with.
Pattern: ^ubl_[a-z\d]{26}$

Query parameters

idarray
Return only the IDs specified. Use a comma-separated list to get multiple entities.
afterstring
Return entities after the specified Paddle ID when working with paginated endpoints. Used in the meta.pagination.next URL in responses for list operations.
per_pageinteger
Default: 50

Set how many entities are returned per page. Paddle returns the maximum number of results if a number greater than the maximum is requested. Check meta.pagination.per_page in the response to see how many were returned.

Default: 50; Maximum: 200.

Max: 200
source_idarray
Return entities that come from the specified source, like a subscription. Use a comma-separated list to specify multiple source IDs.
source_typearray
Return entities that match the specified source type. Use a comma-separated list to specify multiple source types.
Values
  • subscription
    Allowance from a price on a subscription. source.id is the Paddle ID of the subscription.
order_bystring
Default: id[DESC]

Order returned entities by the specified field and direction ([ASC] or [DESC]). For example, ?order_by=id[ASC].

Valid fields for ordering: expires_at, granted_at, and id.

Header parameters

Skip-Countstring
Set to true to skip the count query on list operations. When set, meta.pagination.estimated_total returns -1 instead of an exact count.

Response (200)

dataarrayrequired
idstringrequired
Example: ucb_01jqr8m0k3z9v6x2c4b7n5d8e1
Unique Paddle ID for this usage balance grant, prefixed with ucb_.
Pattern: ^ucb_[a-z\d]{26}$
usage_balance_idstringrequired
Example: ubl_01h9zx4p8q2r5t7v9w1y3z5b7d
Paddle ID of the usage balance this grant funds.
Pattern: ^ubl_[a-z\d]{26}$
usage_balance_unit_idstringrequired
Example: ubu_01kw8ta2j8x5t7q4v9m1kd6phz
Paddle ID of the usage balance unit for this grant. Always the same as the usage balance's unit, so you don't need to get the usage balance to find it.
Pattern: ^ubu_[a-z\d]{26}$
sourceobjectrequired
Source of this grant, like the subscription whose allowance funded it.
typestringrequired
Type of entity that this grant comes from.
Values
  • subscription
    Allowance from a price on a subscription. source.id is the Paddle ID of the subscription.
idstringrequired
Example: sub_01h04vsc0qhwtsbsxh3422wjs4
Paddle ID of the entity that this grant comes from. A subscription ID when type is subscription.
Pattern: ^[a-z]+_[a-z\d]{26}$
amountobjectrequired
Amounts for this grant. Added together, remaining across all grants for a usage balance equals balance.remaining.total on the usage balance.
grantedstringrequired
How much of the usage balance unit this grant started with. Doesn't change.
Max length: 45
Pattern: ^(0|[1-9][0-9]{0,34})(\.[0-9]{1,9})?$
usedstringrequired
How much of this grant the customer has used.
Max length: 45
Pattern: ^(0|[1-9][0-9]{0,34})(\.[0-9]{1,9})?$
remainingstringrequired
How much of this grant is left. Equal to granted minus used.
Max length: 45
Pattern: ^(0|[1-9][0-9]{0,34})(\.[0-9]{1,9})?$
priorityintegerrequired
Order that Paddle draws down this grant in, compared with other grants for the same usage balance. Paddle draws down grants with lower values first. When grants have the same priority, Paddle draws down the grant that expires soonest first.
periodobject | nullrequired
Billing period of the subscription that funded this grant. null if a subscription didn't fund this grant.
starts_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this period starts.
ends_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this period ends.
granted_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this grant became available to draw down.
expires_atstring (date-time) | nullrequired
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this grant expires. Any of the grant that's left expires at this time. null if this grant doesn't expire. When set, it's always in the future, because expired grants aren't returned.
contributionsarrayrequired
Breakdown of amount.granted by the price whose allowance granted it. Empty if this grant doesn't come from an allowance on a price.
price_idstringrequired
Example: pri_01gsz8z1q1n00f12qt82y31smh
Paddle ID of the price whose allowance granted this amount.
Pattern: ^pri_[a-z\d]{26}$
amountstringrequired
How much of amount.granted comes from this price.
Max length: 45
Pattern: ^(0|[1-9][0-9]{0,34})(\.[0-9]{1,9})?$
metaobjectrequired
Information about this response.
request_idstringrequired
Example: b15ec92e-8688-40d4-a04d-f44cbec93355
Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.
paginationobjectrequired
Keys used for working with paginated results.
per_pageintegerrequired
Number of entities per page for this response. May differ from the number requested if the requested number is greater than the maximum.
nextstring (uri)required
URL containing the query parameters of the original request, along with the after parameter that marks the starting point of the next page. Always returned, even if has_more is false.
has_morebooleanrequired
Whether this response has another page.
estimated_totalinteger
Example: 999

Estimated number of entities for this response.

For datasets with 100,000 or fewer matches, returns the exact count. For datasets with more than 100,000 matches, returns 100001 to indicate that more than 100,000 entities match. Returns -1 when counting is skipped or couldn't be calculated.

Use has_more and next to page through all results rather than relying on estimated_total for an exact count.

Response
{
  "data": [
    {
      "id": "ucb_01jqr8m0k3z9v6x2c4b7n5d8e1",
      "usage_balance_id": "ubl_01h9zx4p8q2r5t7v9w1y3z5b7d",
      "usage_balance_unit_id": "ubu_01kw8ta2j8x5t7q4v9m1kd6phz",
      "source": {
        "type": "subscription",
        "id": "sub_01h04vsc0qhwtsbsxh3422wjs4"
      },
      "amount": {
        "granted": "3000",
        "used": "3000",
        "remaining": "0"
      },
      "priority": 1,
      "period": {
        "starts_at": "2026-09-02T00:00:00Z",
        "ends_at": "2026-10-02T00:00:00Z"
      },
      "granted_at": "2026-09-02T10:00:04Z",
      "expires_at": "2026-10-02T00:00:00Z",
      "contributions": [
        {
          "price_id": "pri_01gsz8z1q1n00f12qt82y31smh",
          "amount": "3000"
        }
      ]
    },
    {
      "id": "ucb_01jqr8s5m1a8b2c6d9e3f7g4h0",
      "usage_balance_id": "ubl_01h9zx4p8q2r5t7v9w1y3z5b7d",
      "usage_balance_unit_id": "ubu_01kw8ta2j8x5t7q4v9m1kd6phz",
      "source": {
        "type": "subscription",
        "id": "sub_01h8bx8fmywym11t6swgzba704"
      },
      "amount": {
        "granted": "7000",
        "used": "500",
        "remaining": "6500"
      },
      "priority": 2,
      "period": {
        "starts_at": "2026-09-10T00:00:00Z",
        "ends_at": "2026-10-10T00:00:00Z"
      },
      "granted_at": "2026-09-10T00:00:03Z",
      "expires_at": "2026-10-10T00:00:00Z",
      "contributions": [
        {
          "price_id": "pri_01gsz98e27ak2tyhexptwc58yk",
          "amount": "7000"
        }
      ]
    }
  ],
  "meta": {
    "request_id": "b8f0c2a1-9d3e-4f7a-8c1b-2e5a6d4f9017",
    "pagination": {
      "per_page": 50,
      "next": "https://api.paddle.com/customers/ctm_01gw9m680k848184fpttwr0b7z/usage-balances/ubl_01h9zx4p8q2r5t7v9w1y3z5b7d/grants?after=ucb_01jqr8s5m1a8b2c6d9e3f7g4h0",
      "has_more": false,
      "estimated_total": 2
    }
  }
}

Was this page helpful?