Skip to main content
POST
Use POST /subscription/usage to report metered consumption against a subscription. Usage-based billing lets you charge a variable amount on top of the plan’s flat fee — for example a base subscription plus a per-request or per-gigabyte charge.
Usage meters and their per-plan pricing are configured in the Dashboard under Subscriptions → Usage Meters, not through the API. This endpoint only ingests the raw usage events. See Usage-based & hybrid billing for the full model.

​
How metered charges reach an invoice

  1. You define a meter (e.g. api_requests) with an aggregation mode, and price it on a plan.
  2. Throughout the billing period you call POST /subscription/usage for each usage event.
  3. At renewal, Therius aggregates that period’s events per the meter’s aggregation mode, subtracts the plan’s included units, applies the pricing scheme, and adds the result to the invoice as its own line item.
The billing period an event counts toward is determined by its occurredAt timestamp. Send an optional Idempotency-Key header when your reporting job may retry — a replay with the same (meterCode, Idempotency-Key) pair returns the original event with duplicate: true instead of recording a second one.

Authorizations

​
Authorization
string
header
required

Your secret API key: Bearer prv_production_xxx (production) or Bearer prv_sandbox_xxx (sandbox).

Headers

​
Idempotency-Key
string

Optional. A replay with the same (meterCode, Idempotency-Key) pair returns the original event instead of recording a second one. Use it when your reporting job may retry.

Body

application/json
​
subscriptionId
string
required

UUID of the subscription the usage is attributed to.

​
meterCode
string
required

The code of a usage meter belonging to your merchant account, e.g. api_requests.

Example:

"api_requests"

​
quantity
number
required

Non-negative quantity for this event, in the meter's units.

Example:

500

​
merchantCode
string

Your merchant account identifier.

​
occurredAt
string<date-time>

Optional RFC 3339 timestamp of when the usage occurred. Defaults to the time the request is received. Determines which billing period the event falls into.

Response

Event recorded, or the original event on an idempotent replay.

​
id
string

UUID of the usage event.

​
meterCode
string

The meter the event was recorded against.

​
quantity
number

The recorded quantity.

​
occurredAt
string<date-time>

Timestamp the event was attributed to (the billing-period key).

​
duplicate
boolean

true when this response is an idempotent replay of a previously recorded event.