subscription_item_usage_record registra uso para um
subscription_item com usage_type: "metered". Ele é o evento que diz: “neste
momento, este cliente consumiu esta quantidade”. No fechamento do período, a
Chargefy agrega esses registros conforme aggregate_usage do item e gera a
linha correspondente na invoice.
Use usage records para produtos com cobrança por consumo: chamadas de API,
mensagens enviadas, créditos usados, GB processados, usuários ativos no período
ou qualquer métrica que só é conhecida depois que a assinatura já está ativa.
O registro sempre aponta para o item medido, e a subscription é derivada
automaticamente. Você não precisa enviar a assinatura no create.
Objeto subscription_item_usage_record
Este é o formato retornado emcreate, get e itens de list.
Objeto livre para correlacionar o registro com o evento do seu sistema. Quando
vazio, retorna
{}.Momento em que o uso ocorreu, em ISO 8601. O timestamp precisa cair dentro do
período de uso atual do item e não pode estar no futuro.
Data da última atualização em ISO 8601. Registros de uso normalmente são
imutáveis depois de criados, então pode vir
null.Como escolher action
Como processar
- Crie ou atualize o
subscription_itemcomometered. - Envie usage records conforme o consumo acontece, de preferência com
Idempotency-Keyem retentativas. - No fechamento do ciclo, a Chargefy agrega os registros conforme
subscription_item.aggregate_usagee inclui o resultado na invoice. - Use
GET /v1/subscription-item-usage-recordspara auditar o consumo de um item em uma janela de tempo.
Pontos de atenção
- Usage records só são aceitos para item
metered; itemlicensedretorna erro400. - O
timestampdefine em qual período de uso o registro entra. Um registro fora do período atual é recusado. - Em retentativas do seu worker, envie uma chave de idempotência estável para não duplicar consumo.
- O valor final cobrado não vive no usage record isolado. Ele aparece na invoice depois que a Chargefy agrega o período.

