Registros de uso de item de assinatura

Um 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 em create, get e itens de list.

{
  "id": "ur_ZTGBxj4ixHHGoX6r",
  "object": "subscription_item_usage_record",
  "action": "increment",
  "created_at": "2026-05-20T12:00:00Z",
  "livemode": true,
  "metadata": {},
  "period_end": "2026-06-19T18:00:00Z",
  "period_start": "2026-05-19T18:00:00Z",
  "quantity": 42,
  "subscription": "sub_9Rzzu4WpxzUqosow",
  "subscription_item": "si_PpD32Ku4dBydtKN7",
  "timestamp": "2026-05-20T12:00:00Z",
  "updated_at": null
}

string

Identificador do registro de uso. Usa o prefixo ur_*.

string

Sempre "subscription_item_usage_record".

string

Como a quantidade é aplicada ao acumulado do período.

Valor	Descrição
`increment`	Soma `quantity` ao acumulado do período. Use para eventos de uso avulsos, como “+42 chamadas”.
`set`	Substitui o acumulado no ponto do registro. Use para medidores que reportam o total atual, como “o contador agora está em 100”.

string

Quando o registro foi criado na Chargefy.

boolean

true em produção; false em ambiente de teste.

object

Objeto livre para correlacionar o registro com o evento do seu sistema. Quando vazio, retorna {}.

string | null

Fim do período de uso em que o registro foi aceito.

string | null

Início do período de uso em que o registro foi aceito.

integer

Quantidade registrada. Deve ser um inteiro maior ou igual a 0.

string

Subscription dona do item medido. Derivada do subscription_item.

string

Item medido (si_*) que recebeu o uso. O item precisa ter usage_type: "metered".

string

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.

string | null

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`

Caso	Use	Exemplo
Você recebe eventos individuais de consumo	`increment`	Cada chamada de API cria um registro com `quantity: 1`.
Seu sistema fecha lotes de uso	`increment`	A cada hora, envia `quantity: 420` com o total daquele lote.
Você tem um contador cumulativo confiável	`set`	Todo dia, envia “o contador do mês está em 12000”.
Você quer corrigir o acumulado do período	`set`	Envia o total correto para substituir o acumulado calculado até aquele ponto.

Como processar

Crie ou atualize o subscription_item como metered.
Envie usage records conforme o consumo acontece, de preferência com Idempotency-Key em retentativas.
No fechamento do ciclo, a Chargefy agrega os registros conforme subscription_item.aggregate_usage e inclui o resultado na invoice.
Use GET /v1/subscription-item-usage-records para auditar o consumo de um item em uma janela de tempo.

Pontos de atenção

Usage records só são aceitos para item metered; item licensed retorna erro 400.
O timestamp define 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.

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Registros de uso de item de assinatura

Objeto subscription_item_usage_record

Como escolher `action`

Como processar

Pontos de atenção

​Objeto subscription_item_usage_record

​Como escolher action

​Como processar

​Pontos de atenção

Objeto subscription_item_usage_record

Como escolher `action`

Como processar

Pontos de atenção