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

# POST /meters

**Create a meter**

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

Creates a new meter.

Meters describe how usage events draw down customers' usage balances. Each meter links an `action` to a usage balance unit. When you record a usage event for that `action`, Paddle draws down the customer's usage balance for the meter's usage balance unit. Create the usage balance unit first, then include its ID as `usage_balance_unit_id`.

`rate` sets how much of the usage balance unit each unit of usage draws down. You can create more than one meter with the same `action`, as long as each draws down a different usage balance unit.

You can't change a meter's `usage_balance_unit_id` or `aggregation` after you create it.

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

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

## Request body

- `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 later, so create a new meter to draw down a different usage balance unit. (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 — Short description for this meter. (Max length: 2048)
- `aggregation`: string — How this meter aggregates usage events into a usage total. If omitted, defaults to `sum`. Can't be changed later. (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]))$`)
- `custom_data`: object | null — Your own structured key-value data.

### Request example

```json
{
  "usage_balance_unit_id": "ubu_01kw8ta2j8x5t7q4v9m1kd6phz",
  "name": "API calls",
  "action": "api_call",
  "description": "Calls to the public API",
  "aggregation": "sum",
  "unit_name": "call",
  "rate": "1",
  "custom_data": null
}
```

## Response (201)

- `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": "API calls",
    "action": "api_call",
    "description": "Calls to the 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-01T09:10:00Z"
  },
  "meta": {
    "request_id": "cf40234b-e140-44d1-a83f-7bbdedd88589"
  }
}
```