Skip to main content
POST
Use POST /subscription/usage para reportar o consumo medido contra uma assinatura. O faturamento por uso permite cobrar um valor variável além da tarifa fixa do plano — por exemplo uma assinatura base mais uma cobrança por requisição ou por gigabyte.
Os medidores de uso e a sua precificação por plano são configurados no Dashboard, em Assinaturas → Medidores de uso, não pela API. Este endpoint só ingere os eventos de uso brutos. Consulte Faturamento por uso e híbrido para o modelo completo.

​
Como as cobranças medidas chegam a uma fatura

  1. Você define um medidor (ex.: api_requests) com um modo de agregação, e o precifica em um plano.
  2. Ao longo do período de faturamento você chama POST /subscription/usage para cada evento de uso.
  3. Na renovação, o Therius agrega os eventos daquele período conforme o modo de agregação do medidor, subtrai as unidades incluídas do plano, aplica o esquema de precificação e soma o resultado à fatura como uma linha própria.
O período de faturamento para o qual um evento conta é determinado pelo timestamp occurredAt dele. Envie um header Idempotency-Key opcional quando o seu job de reporte puder repetir — uma repetição com o mesmo par (meterCode, Idempotency-Key) devolve o evento original com duplicate: true em vez de registrar um segundo.

Autorizações

​
Authorization
string
header
obrigatório

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

Cabeçalhos

​
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.

Corpo

application/json
​
subscriptionId
string
obrigatório

UUID of the subscription the usage is attributed to.

​
meterCode
string
obrigatório

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

Exemplo:

"api_requests"

​
quantity
number
obrigatório

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

Exemplo:

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.

Resposta

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.