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

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

**Get a usage balance for a customer**

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

Returns a usage balance for a customer using its ID and related customer ID.

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

## Path parameters

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

## Response (200)

- `data`: object (required) — Represents a customer's usage balance for one of your usage balance units. Paddle creates usage balances automatically when a customer subscribes to a price with an allowance, so you can't create or update them using the API. A customer has one usage balance for each usage balance unit.
  - `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.

### 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"
  },
  "meta": {
    "request_id": "bb093d50-ddb5-401a-a5ba-034b187b396e"
  }
}
```