Skip to main content

​
Esquema

CampoTipoDescrição
costIdUUIDv7Identificador único
organizationIdUUIDv7FK para Organization
feeIdUUIDv7FK para Fee
tokenIdUUIDv7FK para Token
costBatchIdUUIDv7?FK para CostBatch
costBatchWindowRefstringReferência única da janela de agrupamento
quantityintegerUnidades consumidas
unitAmountdecimalPreço por unidade
unitAmountCurrencyenumMoeda do token
subtotalAmountdecimalquantity * unitAmount
exchangeRatedecimalTaxa de conversão
exchangeRateProviderstringProvedor da taxa
totalAmountdecimalValor final na moeda da organização
totalAmountCurrencyenumMoeda da organização
createdAtdatetimeCriação
updatedAtdatetimeÚltima atualização
O cálculo do custo segue o fluxo: quantity * unitAmount = subtotalAmount (na moeda do token), depois subtotalAmount * exchangeRate = totalAmount (na moeda da organização). Se as moedas forem iguais, o exchangeRate é 1.0.

​
Relacionamentos

​
Regras de Negócio

  • Só é criado se a organização tem subscription ativa
  • Token precisa estar ACTIVE
  • Fee precisa ser compatível com a moeda da organização
  • Taxa de câmbio: moeda do token → moeda da organização
  • costBatchWindowRef gerado a partir de hash(eventName, orgId, janela de tempo)
  • Agrupado para liquidação em lote via CostBatch
Custos só são criados para organizações com subscription ativa. Se a subscription entrar em PAST_DUE ou PAUSED, novos custos são rejeitados — o consumo continua mas não é faturado até a regularização.
O costBatchWindowRef agrupa custos da mesma janela temporal para envio em lote ao Stripe via billing meters. Isso otimiza chamadas à API e evita throttling em cenários de alto volume.

​
Exemplo

{
  "costId": "019528c4-6f70-7c8a-e7b5-1d3f9b5c7e0a",
  "organizationId": "019526a0-1a20-7d3b-a1c9-5f7e9b0d3f5b",
  "feeId": "019527a2-4e50-7b6f-d5a3-0b1d7e3a5c8e",
  "tokenId": "019527b1-5d60-7a7e-c6b4-1c2e8a4b6d9f",
  "costBatchId": "019528c5-7a80-7d9b-f8c6-2e4a0c6d8f1b",
  "costBatchWindowRef": "a3f8c2e1d5b7094e6f1a2c3d4e5f6789",
  "quantity": 15230,
  "unitAmount": 0.00001,
  "unitAmountCurrency": "USD",
  "subtotalAmount": 0.15230,
  "exchangeRate": 5.7842,
  "exchangeRateProvider": "PTAX_API",
  "totalAmount": 0.88133,
  "totalAmountCurrency": "BRL",
  "createdAt": "2026-03-15T14:32:10Z",
  "updatedAt": "2026-03-15T14:32:10Z"
}