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

# PATCH /meters/{meter_id}

**Update a meter**

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

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.

**Required permissions:** `meter.write`

## Path parameters

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

## Request body

- `action`: string — 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_]*$`)
- `name`: string — Name of this meter, shown in the Paddle dashboard. (Length: 1–255; pattern: `.*\S.*`)
- `description`: string | null — Short description for this meter. (Max length: 2048)
- `unit_name`: string — 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)
- `rate`: string — 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_data`: object | null — Your own structured key-value data.
- `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.

### Request example

```json
{
  "name": "Public API calls",
  "description": "Calls to the v2 public API"
}
```

## Response (200)

- `data`: object (required) — Represents a meter entity. Meters describe how usage events draw down customers' usage balances.
  - `id`: string (required) — Unique Paddle ID for this meter entity, prefixed with `mtr_`. (pattern: `^mtr_[a-z\d]{26}$`)
  - `usage_balance_unit_id`: string (required) — 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}$`)
  - `name`: string (required) — Name of this meter, shown in the Paddle dashboard. (Length: 1–255; pattern: `.*\S.*`)
  - `action`: string (required) — 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_]*$`)
  - `description`: string | null (required) — Short description for this meter. (Max length: 2048)
  - `aggregation`: string (required) — How this meter aggregates usage events into a usage total. (default: `"sum"`)
    - `sum` — Adds up the `quantity` of each usage event.
  - `unit_name`: string (required) — 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)
  - `rate`: string (required) — 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]))$`)
  - `status`: string (required) — Whether this entity can be used in Paddle. (default: `"active"`)
    - `active` — Entity is active and can be used.
    - `archived` — Entity is archived, so can't be used.
  - `custom_data`: object | null (required) — Your own structured key-value data.
  - `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": "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"
  }
}
```