Update meter

PATCH

/v1/meters/{id}

curl --request PATCH \
  --url http://localhost:8080/v1/meters/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "unit": "example", "aggregation": "sum" }'

• Local development

Fields omitted are left unchanged. A meter only counts: its prices are on the plans (/v1/plans/{id}/prices).

aggregation can change until the meter has a usage event, then it is fixed: a change is refused with 409 meter_has_usage. Usage events are counted under the aggregation the meter has; to count differently, make a new meter with another event name. Held usage for its event_name does not fix it: it is counted under the meter’s aggregation once released. name and unit can always change, at once.

Authorizations

• BearerAuth

Parameters

Path Parameters

id

required

string

Header Parameters

Idempotency-Key

string

Makes the call safe to retry. Send a unique value (a UUID works) and the same value on every retry. For 24 hours, a repeat with the same key, method, path and body gets the first response again, with an Idempotent-Replayed: true header, instead of running again. The error cases are in docs/api-surface.md. The usage routes do not take it: each usage event carries its own idempotency_key.

Request Body^required

Media typeapplication/json

object

name

string

unit

string

aggregation

string

Allowed values: sum count max last

Responses

200

Updated meter

Media typeapplication/json

object

id

required

string

tenant_id

string

event_name

required

The event_name usage events send for this meter.

string

name

required

string

unit

required

string

aggregation

required

How the meter rolls its events into one quantity per billing period. Every price of the meter bills under it. last is the latest event by timestamp, then by id. Fixed once the meter has a usage event (see has_usage).

string

Allowed values: sum count max last

has_usage

Whether the meter has usage events. Once it has, its aggregation cannot change. Held usage for its event_name does not count until it is released. Returned when you create, get or update one meter; the meter list leaves it out. A create or update that succeeded leaves it out if it could not be read.

boolean

created_at

required

string format: date-time

updated_at

required

string format: date-time

Example

{
  "aggregation": "sum"
}

404

Meter not found

409

meter_has_usage: the meter has usage events, so its aggregation cannot change. invalid_state: another write changed the meter during this one.

Media typeapplication/json

object

error

object

type

One of invalid_request_error, authentication_error, rate_limit_error or api_error. Every error the API answers has this shape, including an unknown path (404, code route_not_found) and a method the path does not take (405, code method_not_allowed, with an Allow header). The few exceptions are listed in docs/api-surface.md.

string

code

string

message

string

request_id

string

param

The request field the error is about. Sent only when the error names one. A request body may hold only the fields its operation lists, spelled and cased as listed: any other field, or one the server sets (such as id), is refused with 422 and param naming it. An operation with no request body lists no fields: send no body, {} or null. The Stripe and Postmark webhooks and the LiteLLM callback take their sender’s body as it comes.

string

Example

{
  "error": {
    "type": "invalid_request_error"
  }
}

422

Validation failure (bad aggregation, an empty name, or an unknown field)