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.

​
Evento de saldo baixo (credit.balance_low)

O evento credit.balance_low utiliza um payload diferente (CreditBalanceLowPayload) focado 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éditos disparou o alerta.
​
subscription_id
string
A assinatura associada a esse direito de crédito.
​
credit_entitlement_id
string
O direito de crédito que está com saldo baixo.
​
credit_entitlement_name
string
Nome exibido do direito de crédito.
​
available_balance
string
Saldo atual de créditos 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éditos que corresponde ao limite.

​
Usando credit.balance_low para Alertas Proativos

Use o webhook credit.balance_low para notificar clientes antes que eles acabem os 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 evento credit.balance_low para alertar proativamente os clientes antes que eles esgotem seus créditos. Combine com credit.deducted para acompanhar padrões de consumo em tempo real.

Get Customer Balance

Verifique o saldo atual de um cliente via API.

Create Ledger Entry

Credite ou debite manualmente o 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
​
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
​
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,
auto_top_up,
manual_adjustment,
refund
​
description
string | null
​
grant_id
string | null
​
reference_id
string | null
​
reference_type
string | null