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.

Skip to content
Paddle Docs home

Update a usage balance unit

Updates a usage balance unit using its ID.

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.

PATCH/usage-balance-units/{usage_balance_unit_id}

Updates a usage balance unit using its ID.

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

Requires usage_balance_unit.write permission.

Path parameters

usage_balance_unit_idstringrequired
Paddle ID of the usage balance unit entity to work with.
Pattern: ^ubu_[a-z\d]{26}$

Request body

statusstring
Whether this entity can be used in Paddle.
Values
  • active
    Entity is active and can be used.
  • archived
    Entity is archived, so can't be used.
namestring
Name of this usage balance unit, like API calls. Typically short and describes what customers hold a balance of.
Length: 1–500
unit_namestring
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

Response (200)

dataobjectrequired
Represents a usage balance unit entity. Usage balance units describe what customers hold a balance of, like API calls, tokens, or credits.
idstringrequired
Example: ubu_01kw8ta2j8x5t7q4v9m1kd6phz
Unique Paddle ID for this usage balance unit entity, prefixed with ubu_.
Pattern: ^ubu_[a-z\d]{26}$
namestringrequired
Name of this usage balance unit, like API calls. Typically short and describes what customers hold a balance of.
Length: 1–500
unit_namestringrequired
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
statusstringrequired
Whether this entity can be used in Paddle.
Values
  • active
    Entity is active and can be used.
  • archived
    Entity is archived, so can't be used.
created_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example: 2024-10-13T07:20:50.52Z
RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
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.
Request
{
  "status": "archived"
}
Response
{
  "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"
  }
}

Was this page helpful?