Pular para o conteúdo principal

​
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).
EventDescription
credit.addedCredits are granted to a customer (via subscription, one-time purchase, add-on, or API)
credit.deductedCredits are consumed through usage or manual debit
credit.expiredUnused credits expired after the configured expiry period
credit.rolled_overUnused credits are carried forward to a new grant at cycle end
credit.rollover_forfeitedCredits forfeited because the max rollover count was reached
credit.overage_chargedOverage charges applied when usage continues beyond zero balance
credit.manual_adjustmentManual credit or debit adjustment made via dashboard or API
credit.balance_lowCredit 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",
    "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"
  }
}
​
customer_id
string
O cliente cujo saldo de crédito acionou o alerta.
​
subscription_id
string
A assinatura associada a esse direito de crédito.
​
credit_entitlement_id
string
O direito de crédito que tem saldo baixo.
​
credit_entitlement_name
string
Nome de exibição do direito de crédito.
​
available_balance
string
Saldo atual de crédito no momento do alerta.
​
subscription_credits_amount
string
Total de créditos emitidos por ciclo de faturamento para essa assinatura.
​
threshold_percent
integer
A porcentagem de limite de saldo baixo configurada.
​
threshold_amount
string
O valor absoluto de crédito ao qual o limite corresponde.

​
Usando credit.balance_low para Alertas Próativos

Use o webhook credit.balance_low para notificar os clientes antes que eles 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 });
});
Assine o credit.balance_low para alertar próativamente os clientes antes que esgotem seus créditos. Combine com credit.deducted para rastrear padrões de consumo em tempo real.

Get Customer Balance

Verifique o saldo atual de um cliente via API.

Create Ledger Entry

Credito ou debito manualmente o saldo de um cliente.

​
Esquema da Carga Útil 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
​
id
string
obrigatório
​
is_credit
boolean
obrigatório
​
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).

​
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
Última modificação em 26 de junho de 2026