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

# PATCH /usage-balance-units/{usage_balance_unit_id}

**Update a usage balance unit**

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

Updates a usage balance unit using its ID.

If successful, your response includes a copy of the updated usage balance unit entity.

**Required permissions:** `usage_balance_unit.write`

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `usage_balance_unit_id` | string | required | Paddle ID of the usage balance unit entity to work with. (pattern: `^ubu_[a-z\d]{26}$`) |

## Request body

- `status`: string — Whether this entity can be used in Paddle.
  - `active` — Entity is active and can be used.
  - `archived` — Entity is archived, so can't be used.
- `name`: string — Name of this usage balance unit, like `API calls`. Typically short and describes what customers hold a balance of. (Length: 1–500)
- `unit_name`: string — Plural name of what customers hold a balance of, like `calls` or `credits`. Different from a meter's `unit_name`, which is the singular name of what the meter measures. (Length: 1–500)

### Request example

```json
{
  "status": "archived"
}
```

## Response (200)

- `data`: object (required) — Represents a usage balance unit entity. Usage balance units describe what customers hold a balance of, like API calls, tokens, or credits.
  - `id`: string (required) — Unique Paddle ID for this usage balance unit entity, prefixed with `ubu_`. (pattern: `^ubu_[a-z\d]{26}$`)
  - `name`: string (required) — Name of this usage balance unit, like `API calls`. Typically short and describes what customers hold a balance of. (Length: 1–500)
  - `unit_name`: string (required) — Plural name of what customers hold a balance of, like `calls` or `credits`. Different from a meter's `unit_name`, which is the singular name of what the meter measures. (Length: 1–500)
  - `status`: string (required) — Whether this entity can be used in Paddle.
    - `active` — Entity is active and can be used.
    - `archived` — Entity is archived, so can't be used.
  - `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": "ubu_01kw8tc7p4z8d5s2x6n3lf8rkb",
    "name": "AI tokens",
    "unit_name": "tokens",
    "status": "archived",
    "created_at": "2026-09-01T09:02:00.000Z",
    "updated_at": "2026-09-20T16:41:08.223Z"
  },
  "meta": {
    "request_id": "1681f87f-9c36-4557-a1da-bbb622afa0cc"
  }
}
```