Faturamento baseado em créditos

Eventos de Webhook de Faturamento Baseado em Créditos

Os seguintes eventos de webhook estão disponíveis para acompanhar as alterações no ciclo de vida do faturamento baseado em créditos. Esses eventos se aplicam a direitos de créditos virtuais (chamadas de API, tokens, horas de computação), não às Carteiras do Cliente (saldos monetários).

Event	Description
`credit.added`	Credits are granted to a customer (via subscription, one-time purchase, add-on, or API)
`credit.deducted`	Credits are consumed through usage or manual debit
`credit.expired`	Unused credits expired after the configured expiry period
`credit.rolled_over`	Unused credits are carried forward to a new grant at cycle end
`credit.rollover_forfeited`	Credits forfeited because the max rollover count was reached
`credit.overage_charged`	Overage charges applied when usage continues beyond zero balance
`credit.manual_adjustment`	Manual credit or debit adjustment made via dashboard or API
`credit.balance_low`	Credit balance drops below the configured low balance threshold

Eventos do Livro-razão

Todos os eventos do livro-razão (credit.added através de credit.manual_adjustment) compartilham o mesmo payload CreditLedgerEntryResponse documentado no esquema abaixo. A carga inclui um campo metadata resolvido a partir da fonte da concessão de crédito — a assinatura ou pagamento criado no checkout. Isso permite que você vincule créditos de carteira ao seu próprio checkout metadata (por exemplo, um orgId) em vez do customer_id emitido pelo Dodo: concessões com fonte de assinatura mostram o metadata da assinatura e concessões com fonte de pagamento mostram o metadata do pagamento. O campo fica vazio quando a concessão não tem fonte resolvível (por exemplo, créditos concedidos diretamente via API).

Evento de Saldo Baixo (credit.balance_low)

O evento credit.balance_low usa uma carga diferente (CreditBalanceLowPayload) focada em alertas de limite:

{
  "business_id": "bus_H4ekzPSlcg",
  "type": "credit.balance_low",
  "timestamp": "2025-08-04T06:15:00.000000Z",
  "data": {
    "payload_type": "CreditBalanceLow",
    "brand_id": "brd_123",
    "customer_id": "cus_8VbC6JDZzPEqfBPUdpj0K",
    "subscription_id": "sub_7EeHq2ewQuadropD2ra",
    "credit_entitlement_id": "cent_9xY2bKwQn5MjRpL8d",
    "credit_entitlement_name": "API Credits",
    "available_balance": "15",
    "subscription_credits_amount": "100",
    "threshold_percent": 20,
    "threshold_amount": "20"
  }
}

string

A marca à qual esta concessão de créditos pertence.

string

O cliente cujo saldo de créditos acionou o alerta.

string

A assinatura associada a esta concessão de créditos.

string

A concessão de créditos que está com saldo baixo.

string

Nome de exibição da concessão de créditos.

string

Saldo de créditos atual no momento do alerta.

string

Total de créditos emitidos por ciclo de faturamento para esta assinatura.

integer

A porcentagem configurada do limite de saldo baixo.

string

O valor absoluto de créditos correspondente ao limite.

Usando `credit.balance_low` para alertas proativos

Use o webhook credit.balance_low para notificar os clientes antes que fiquem sem créditos:

app.post('/webhooks/dodo', async (req, res) => {
  const event = req.body;
  
  if (event.type === 'credit.balance_low') {
    const data = event.data;
    
    // Notify the customer their credits are running low
    await sendEmail(data.customer_id, {
      subject: `Your ${data.credit_entitlement_name} balance is running low`,
      body: `You have ${data.available_balance} credits remaining ` +
            `(${data.threshold_percent}% threshold reached). ` +
            `Consider upgrading your plan or purchasing additional credits.`
    });
    
    console.log(`Low balance alert for customer ${data.customer_id}`);
  }
  
  res.json({ received: true });
});

Inscreva-se em credit.balance_low para alertar proativamente os clientes antes que esgotem seus créditos. Combine-o com credit.deducted para acompanhar os padrões de consumo em tempo real.

Get Customer Balance

Verifique o saldo atual de um cliente via API.

Create Ledger Entry

Adicione ou debite créditos manualmente do saldo de um cliente.

Esquema do payload do webhook

Response for a ledger entry

amount

string

obrigatório

balance_after

string

obrigatório

balance_before

string

obrigatório

brand_id

string

obrigatório

Brand id this credit ledger entry belongs to

business_id

string

obrigatório

created_at

string<date-time>

obrigatório

credit_entitlement_id

string

obrigatório

customer_id

string

obrigatório

string

obrigatório

is_credit

boolean

obrigatório

metadata

Metadata · object

obrigatório

Metadata associated with the credit grant's source (the subscription or payment created at checkout). Empty when the grant has no resolvable source (e.g. credits granted directly via the API).

Show child attributes

overage_after

string

obrigatório

overage_before

string

obrigatório

transaction_type

enum<string>

obrigatório

Opções disponíveis:

credit_added,

credit_deducted,

credit_expired,

credit_rolled_over,

rollover_forfeited,

overage_charged,

overage_reset,

auto_top_up,

manual_adjustment,

refund

description

string | null

grant_id

string | null

reference_id

string | null

reference_type

string | null

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Eventos de Webhook de Faturamento Baseado em Créditos

Eventos do Livro-razão

Evento de Saldo Baixo (credit.balance_low)

Usando `credit.balance_low` para alertas proativos

Get Customer Balance

Create Ledger Entry

Esquema do payload do webhook

​Eventos de Webhook de Faturamento Baseado em Créditos

​Eventos do Livro-razão

​Evento de Saldo Baixo (credit.balance_low)

​Usando credit.balance_low para alertas proativos

Get Customer Balance

Create Ledger Entry

​Esquema do payload do webhook

Eventos de Webhook de Faturamento Baseado em Créditos

Eventos do Livro-razão

Evento de Saldo Baixo (credit.balance_low)

Usando `credit.balance_low` para alertas proativos

Esquema do payload do webhook