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

Get a usage balance unit

Returns 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.

GET/usage-balance-units/{usage_balance_unit_id}
Returns a usage balance unit using its ID.
Requires usage_balance_unit.read permission.

Path parameters

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

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.
Response
{
  "data": {
    "id": "ubu_01kw8ta2j8x5t7q4v9m1kd6phz",
    "name": "API calls",
    "unit_name": "calls",
    "status": "active",
    "created_at": "2026-09-01T09:00:00.000Z",
    "updated_at": "2026-09-01T09:00:00.000Z"
  },
  "meta": {
    "request_id": "d8f286a6-e049-4a6e-8fa8-a6f145ac3ecf"
  }
}

Was this page helpful?