> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/features/customer-wallet) (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](/features/customer-wallet) (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:

```json theme={null}
{
  "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"
  }
}
```

<ParamField body="customer_id" type="string">
  O cliente cujo saldo de crédito acionou o alerta.
</ParamField>

<ParamField body="subscription_id" type="string">
  A assinatura associada a esse direito de crédito.
</ParamField>

<ParamField body="credit_entitlement_id" type="string">
  O direito de crédito que tem saldo baixo.
</ParamField>

<ParamField body="credit_entitlement_name" type="string">
  Nome de exibição do direito de crédito.
</ParamField>

<ParamField body="available_balance" type="string">
  Saldo atual de crédito no momento do alerta.
</ParamField>

<ParamField body="subscription_credits_amount" type="string">
  Total de créditos emitidos por ciclo de faturamento para essa assinatura.
</ParamField>

<ParamField body="threshold_percent" type="integer">
  A porcentagem de limite de saldo baixo configurada.
</ParamField>

<ParamField body="threshold_amount" type="string">
  O valor absoluto de crédito ao qual o limite corresponde.
</ParamField>

### 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:

```javascript theme={null}
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 });
});
```

<Tip>
  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.
</Tip>

<CardGroup cols={2}>
  <Card title="Get Customer Balance" icon="wallet" href="/api-reference/credit-entitlements/get-customer-balance">
    Verifique o saldo atual de um cliente via API.
  </Card>

  <Card title="Create Ledger Entry" icon="plus" href="/api-reference/credit-entitlements/create-ledger-entry">
    Credito ou debito manualmente o saldo de um cliente.
  </Card>
</CardGroup>

## Esquema da Carga Útil do Webhook