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 meter

Updates a meter 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/meters/{meter_id}

Updates a meter using its ID.

A new rate applies to usage that occurs after the update. Paddle doesn't recalculate usage that's already recorded. If you change action, usage events that you send with the old action no longer draw down usage balances for this meter.

You can't change usage_balance_unit_id or aggregation. Create a new meter instead.

Archived meters still draw down usage balances for usage events with a matching action.

If successful, your response includes a copy of the updated meter entity.

Requires meter.write permission.

Path parameters

meter_idstringrequired
Paddle ID of the meter entity to work with.
Pattern: ^mtr_[a-z\d]{26}$

Request body

actionstring
Action that you record usage events for, like api_call. If you change it, usage events that you send with the old action no longer draw down usage balances for this meter. More than one meter can have the same action, as long as each draws down a different usage balance unit.
Length: 2–64
Pattern: ^[a-z][a-z0-9_]*$
namestring
Name of this meter, shown in the Paddle dashboard.
Length: 1–255
Pattern: .*\S.*
descriptionstring | null
Short description for this meter.
Max length: 2048
unit_namestring
Singular name of what this meter measures, like call or token. Shown alongside usage totals. Different from the usage balance unit's unit_name, which is the plural name of what customers hold a balance of.
Length: 1–64
ratestring
How much of the usage balance unit that one unit of usage draws down. For example, "1" draws down one unit of the balance for each unit of usage, and "0.001" draws down one unit of the balance for every 1,000 units of usage. A decimal string greater than zero, with up to 9 decimal places.
Max length: 45
Pattern: ^([1-9][0-9]{0,34}(\.[0-9]{1,9})?|0\.(?:[1-9][0-9]{0,8}|0[1-9][0-9]{0,7}|00[1-9][0-9]{0,6}|000[1-9][0-9]{0,5}|0000[1-9][0-9]{0,4}|00000[1-9][0-9]{0,3}|000000[1-9][0-9]{0,2}|0000000[1-9][0-9]?|00000000[1-9]))$
custom_dataobject | null
Example: {"customer_reference_id":"abcd1234"}
Your own structured key-value data.
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.

Response (200)

dataobjectrequired
Represents a meter entity. Meters describe how usage events draw down customers' usage balances.
idstringrequired
Example: mtr_01kvqjfc6eb9kzk7s2wvz2aamq
Unique Paddle ID for this meter entity, prefixed with mtr_.
Pattern: ^mtr_[a-z\d]{26}$
usage_balance_unit_idstringrequired
Example: ubu_01kw8ta2j8x5t7q4v9m1kd6phz
Paddle ID of the usage balance unit that this meter draws down, prefixed with ubu_. Can't be changed after you create the meter.
Pattern: ^ubu_[a-z\d]{26}$
namestringrequired
Name of this meter, shown in the Paddle dashboard.
Length: 1–255
Pattern: .*\S.*
actionstringrequired
Action that you record usage events for, like api_call. Paddle matches usage events to this meter using their action. More than one meter can have the same action, as long as each draws down a different usage balance unit. A usage event then draws down the customer's usage balance for each of them.
Length: 2–64
Pattern: ^[a-z][a-z0-9_]*$
descriptionstring | nullrequired
Short description for this meter.
Max length: 2048
aggregationstringrequired
Default: sum
How this meter aggregates usage events into a usage total.
Values
  • sum
    Adds up the quantity of each usage event.
unit_namestringrequired
Singular name of what this meter measures, like call or token. Shown alongside usage totals. Different from the usage balance unit's unit_name, which is the plural name of what customers hold a balance of.
Length: 1–64
ratestringrequired
How much of the usage balance unit that one unit of usage draws down. For example, "1" draws down one unit of the balance for each unit of usage, and "0.001" draws down one unit of the balance for every 1,000 units of usage. A decimal string greater than zero, with up to 9 decimal places.
Max length: 45
Pattern: ^([1-9][0-9]{0,34}(\.[0-9]{1,9})?|0\.(?:[1-9][0-9]{0,8}|0[1-9][0-9]{0,7}|00[1-9][0-9]{0,6}|000[1-9][0-9]{0,5}|0000[1-9][0-9]{0,4}|00000[1-9][0-9]{0,3}|000000[1-9][0-9]{0,2}|0000000[1-9][0-9]?|00000000[1-9]))$
statusstringrequired
Default: active
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.
custom_dataobject | nullrequired
Example: {"customer_reference_id":"abcd1234"}
Your own structured key-value data.
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
{
  "name": "Public API calls",
  "description": "Calls to the v2 public API"
}
Response
{
  "data": {
    "id": "mtr_01kvqjfc6eb9kzk7s2wvz2aamq",
    "usage_balance_unit_id": "ubu_01kw8ta2j8x5t7q4v9m1kd6phz",
    "name": "Public API calls",
    "action": "api_call",
    "description": "Calls to the v2 public API",
    "aggregation": "sum",
    "unit_name": "call",
    "rate": "1",
    "custom_data": null,
    "status": "active",
    "created_at": "2026-09-01T09:10:00Z",
    "updated_at": "2026-09-10T12:03:41Z"
  },
  "meta": {
    "request_id": "6e0077bb-9f36-465c-a303-eaaf9d4d44aa"
  }
}

Was this page helpful?