Skip to main content
Cria um usage record para um subscription_item com usage_type: "metered". O uso registrado no período é agregado no fechamento do ciclo conforme o aggregate_usage do item. Obrigatórios: subscription_item e quantity (inteiro ≥ 0). O resto tem padrão — action é increment e timestamp é agora. Só itens metered aceitam registros: item licensed retorna erro 400, assim como assinaturas em estado terminal (canceled ou incomplete_expired). O endpoint suporta o header Idempotency-Key: reenviar o mesmo request com a mesma chave retorna o registro já criado, sem duplicar o uso.
​
string
required
Item medido (si_*), com usage_type: "metered".
​
integer
required
Quantidade de uso. Inteiro ≥ 0.
​
string
Como a quantidade é aplicada ao acumulado do período. Padrão: increment.
​
string
Timestamp ISO 8601 ou Unix seconds. Padrão: agora. Não pode estar no futuro e precisa cair dentro do período de uso atual do item — fora dele o request falha com 400.
​
object
Metadata livre. Padrão {}.

​
O que a Chargefy resolve sozinha

  • timestamp — sem valor explícito, o registro usa o horário do request.
  • action — sem valor explícito, a quantidade é somada (increment).
  • period_start / period_end — copiados do período de uso atual no momento do registro.
  • subscription — derivada do subscription_item; você não envia o ID da assinatura.
  • Deduplicação — com Idempotency-Key, requests repetidos retornam o mesmo registro em vez de criar outro.