> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).
>
> 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. It returns a JSON array of `{content, source_url}`, most relevant first.

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

**List grants for a usage balance**

> **Early access (beta): usage-based billing**

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.

**Required permissions:** `usage_balance.read`

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `customer_id` | string | required | Unique Paddle ID for this customer entity, prefixed with `ctm_`. (pattern: `^ctm_[a-z\d]{26}$`) |
| `usage_balance_id` | string | required | Paddle ID of the usage balance entity to work with. (pattern: `^ubl_[a-z\d]{26}$`) |

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | array | optional | Return only the IDs specified. Use a comma-separated list to get multiple entities. |
| `after` | string | optional | 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_page` | integer | optional | 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; default: `50`) |
| `source_id` | array | optional | Return entities that come from the specified source, like a subscription. Use a comma-separated list to specify multiple source IDs. |
| `source_type` | array | optional | Return entities that match the specified source type. Use a comma-separated list to specify multiple source types. |
| `order_by` | string | optional | 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`. (default: `"id[DESC]"`) |

Values for `source_type`:

- `subscription` — Allowance from a price on a subscription. `source.id` is the Paddle ID of the subscription.

## Response (200)

- `data`: array (required)
  - `id`: string (required) — Unique Paddle ID for this usage balance grant, prefixed with `ucb_`. (pattern: `^ucb_[a-z\d]{26}$`)
  - `usage_balance_id`: string (required) — Paddle ID of the usage balance this grant funds. (pattern: `^ubl_[a-z\d]{26}$`)
  - `usage_balance_unit_id`: string (required) — 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}$`)
  - `source`: object (required) — Source of this grant, like the subscription whose allowance funded it.
    - `type`: string (required) — Type of entity that this grant comes from.
      - `subscription` — Allowance from a price on a subscription. `source.id` is the Paddle ID of the subscription.
    - `id`: string (required) — Paddle ID of the entity that this grant comes from. A subscription ID when `type` is `subscription`. (pattern: `^[a-z]+_[a-z\d]{26}$`)
  - `amount`: object (required) — Amounts for this grant. Added together, `remaining` across all grants for a usage balance equals `balance.remaining.total` on the usage balance.
    - `granted`: string (required) — 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})?$`)
    - `used`: string (required) — How much of this grant the customer has used. (Max length: 45; pattern: `^(0|[1-9][0-9]{0,34})(\.[0-9]{1,9})?$`)
    - `remaining`: string (required) — 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})?$`)
  - `priority`: integer (required) — 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.
  - `period`: object | null (required) — Billing period of the subscription that funded this grant. `null` if a subscription didn't fund this grant.
    - `starts_at`: string (date-time) (required) — RFC 3339 datetime string of when this period starts.
    - `ends_at`: string (date-time) (required) — RFC 3339 datetime string of when this period ends.
  - `granted_at`: string (date-time) (required) — RFC 3339 datetime string of when this grant became available to draw down.
  - `expires_at`: string (date-time) | null (required) — 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.
  - `contributions`: array (required) — 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_id`: string (required) — Paddle ID of the price whose allowance granted this amount. (pattern: `^pri_[a-z\d]{26}$`)
    - `amount`: string (required) — How much of `amount.granted` comes from this price. (Max length: 45; pattern: `^(0|[1-9][0-9]{0,34})(\.[0-9]{1,9})?$`)
- `meta`: object (required) — Information about this response.
  - `request_id`: string (required) — Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.
  - `pagination`: object (required) — Keys used for working with paginated results.
    - `per_page`: integer (required) — Number of entities per page for this response. May differ from the number requested if the requested number is greater than the maximum.
    - `next`: string (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_more`: boolean (required) — Whether this response has another page.
    - `estimated_total`: integer — 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 example

```json
{
  "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
    }
  }
}
```