Faturamento baseado em créditos

O payload enviado ao seu endpoint webhook quando eventos de faturamento baseado em créditos ocorrem — créditos virtuais (chamadas de API, tokens, horas de computação) concedidos, consumidos, expirados, transferidos ou alertas de saldo. Esses webhooks não estão relacionados às Carteiras do Cliente (saldos monetários).

​

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.

​

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, overage_reset, auto_top_up, manual_adjustment, refund

description · string | null

grant_id · string | null

reference_id · string | null

reference_type · string | null