> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

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

**List usage balances for a customer**

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

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

Paddle creates usage balances automatically when a customer subscribes to a price with an allowance, and they're read-only. A customer has one usage balance for each usage balance unit.

During beta, Paddle never blocks usage, so use `balance.remaining.total` to decide whether to keep providing metered features to a customer. To show how much of their allowance a customer has used, compare `balance.used.total` with the allowance, which is `balance.used.total` plus `balance.remaining.total`. Paddle records usage after the allowance runs out in `balance.overage`, but doesn't bill for it.

**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}$`) |

## 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`) |
| `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: `created_at`, `id`, and `updated_at`. (default: `"id[DESC]"`) |

## Response (200)

- `data`: array (required)
  - `id`: string (required) — Unique Paddle ID for this usage balance entity, prefixed with `ubl_`. (pattern: `^ubl_[a-z\d]{26}$`)
  - `customer_id`: string (required) — Paddle ID of the customer this usage balance belongs to. (pattern: `^ctm_[a-z\d]{26}$`)
  - `usage_balance_unit_id`: string (required) — Paddle ID of the usage balance unit that this usage balance is for. A customer has one usage balance for each usage balance unit, and usage events draw it down using the meters for that unit. (pattern: `^ubu_[a-z\d]{26}$`)
  - `balance`: object (required) — Amounts for a customer's usage balance in the current billing period. Amounts are in the usage balance unit, not currency. The allowance isn't returned directly. To get it, add `used.total` and `remaining.total`.
    - `used`: object (required) — How much of the allowance the customer has used in the current billing period, broken down by source. Doesn't include overage.
      - `total`: string (required) — Total across all sources, for example `"1000"` or `"1000.5"`. (Max length: 45; pattern: `^(0|[1-9][0-9]{0,34})(\.[0-9]{1,9})?$`)
      - `subscription`: string (required) — Amount from allowances on the customer's subscriptions. (Max length: 45; pattern: `^(0|[1-9][0-9]{0,34})(\.[0-9]{1,9})?$`)
    - `remaining`: object (required) — How much of the allowance is left in the current billing period, broken down by source. Counts down as usage is recorded and stops at `"0"`, after which Paddle records usage in `overage`. During beta, Paddle never blocks usage, so restrict access to metered features in your app when `remaining.total` reaches `"0"`.
      - `total`: string (required) — Total across all sources, for example `"1000"` or `"1000.5"`. (Max length: 45; pattern: `^(0|[1-9][0-9]{0,34})(\.[0-9]{1,9})?$`)
      - `subscription`: string (required) — Amount from allowances on the customer's subscriptions. (Max length: 45; pattern: `^(0|[1-9][0-9]{0,34})(\.[0-9]{1,9})?$`)
    - `overage`: object (required) — Usage recorded after `remaining` reached `"0"` in the current billing period. Paddle doesn't bill for overage, and clears it when the subscription renews.
      - `total`: string (required) — Total overage recorded in the current billing period, for example `"0"` or `"25.5"`. (Max length: 45; pattern: `^(0|[1-9][0-9]{0,34})(\.[0-9]{1,9})?$`)
      - `started_at`: string (date-time) — When this usage balance first went into overage in the current billing period. Not returned when `total` is `"0"`.
  - `created_at`: string (date-time) (required) — RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
  - `updated_at`: string (date-time) (required) — RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
- `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": "ubl_01h9zx4p8q2r5t7v9w1y3z5b7d",
      "customer_id": "ctm_01gw9m680k848184fpttwr0b7z",
      "usage_balance_unit_id": "ubu_01kw8ta2j8x5t7q4v9m1kd6phz",
      "balance": {
        "used": {
          "total": "3500",
          "subscription": "3500"
        },
        "remaining": {
          "total": "6500",
          "subscription": "6500"
        },
        "overage": {
          "total": "0"
        }
      },
      "created_at": "2026-09-02T10:00:00Z",
      "updated_at": "2026-09-15T10:15:00Z"
    },
    {
      "id": "ubl_01h9zx4p8q2r5t7v9w1y3z5b7e",
      "customer_id": "ctm_01gw9m680k848184fpttwr0b7z",
      "usage_balance_unit_id": "ubu_01kw8tc7p4z8d5s2x6n3lf8rkb",
      "balance": {
        "used": {
          "total": "100000",
          "subscription": "100000"
        },
        "remaining": {
          "total": "0",
          "subscription": "0"
        },
        "overage": {
          "total": "2500",
          "started_at": "2026-09-12T14:32:07Z"
        }
      },
      "created_at": "2026-09-02T10:00:00Z",
      "updated_at": "2026-09-15T08:00:00Z"
    }
  ],
  "meta": {
    "request_id": "bb093d50-ddb5-401a-a5ba-034b187b396e",
    "pagination": {
      "per_page": 50,
      "next": "https://api.paddle.com/customers/ctm_01gw9m680k848184fpttwr0b7z/usage-balances?after=ubl_01h9zx4p8q2r5t7v9w1y3z5b7e",
      "has_more": false,
      "estimated_total": 2
    }
  }
}
```