Meters

Looks up a meter by its UUID and returns the subscriptions (with their products) that can report usage to it — i.e. subscriptions holding a product whose price is linked to this meter. Paused subscriptions are excluded.

Returns an empty subscriptions array when no product price uses the meter. Responds 404 with code METER_NOT_FOUND if the meter does not exist in your company.

Required Scope

• meter-report

Required License

• Metered Products and Subscription — the tenant must hold both module licenses, or the request returns 403 LICENSE.REQUIRED.

Reports a usage event to a meter for metered subscription billing. Ingestion is asynchronous: a successful report returns 202 with status: queued and a requestId — the event is not yet visible the moment the call returns.

The Idempotency-Key header is required (400 when missing). Replaying a request with the same key returns 200 with status: duplicate and the event is not ingested twice, so retries are always safe.

Use the meter-subscriptions endpoints to discover which subscriptions and products can report usage to a given meter.

How usage is aggregated

Each meter has an aggregation method, fixed when the meter is created, that determines how the events you report become the single quantity billed for the period:

• sum — adds every reported value together (e.g. tokens used, GB transferred).
• count — counts how many events you report; the value you send is ignored.
• last — uses the value of the most recent event in the period, by event timestamp (e.g. a current seat count).

value is always required by this endpoint, but for a count meter it is not used in the calculation — send any non-negative number.

The aggregation method can't be changed once usage has been reported to a meter; create a new meter to bill the same events a different way.

Required Scope

• meter-report

Required License

• Metered Products — the tenant must also hold this module license, or the request returns 403 LICENSE.REQUIRED.

Looks up a meter by its name (?meterName=) and returns the subscriptions (with their products) that can report usage to it — useful when your integration knows the meter's name (e.g. api_calls) but not its UUID. Paused subscriptions are excluded.

Returns an empty subscriptions array when no product price uses the meter. Responds 400 with code METER_IDENTIFIER_REQUIRED when meterName is missing, and 404 with code METER_NOT_FOUND if no meter has that name in your company.

Required Scope

• meter-report

Required License

• Metered Products and Subscription — the tenant must hold both module licenses, or the request returns 403 LICENSE.REQUIRED.