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

# Facturación basada en créditos

> La carga útil que se envía a tu endpoint de webhook cuando ocurren eventos de facturación basada en créditos: créditos virtuales (llamadas a la API, tokens, horas de cómputo) concedidos, consumidos, caducados, transferidos o alertas de saldo. Estos webhooks no están relacionados con las [Billeteras de Cliente](/features/customer-wallet) (saldos monetarios).

## Eventos de Webhook de Facturación Basada en Créditos

Los siguientes eventos de webhook están disponibles para rastrear los cambios en el ciclo de vida de la facturación basada en créditos. Estos eventos se aplican a los derechos de crédito virtuales (llamadas a la API, tokens, horas de cómputo), no a las [Billeteras de Cliente](/features/customer-wallet) (saldos monetarios).

| Evento                      | Descripción                                                                                             |
| --------------------------- | ------------------------------------------------------------------------------------------------------- |
| `credit.added`              | Se otorgan créditos a un cliente (a través de suscripción, compra única, complemento, o API)            |
| `credit.deducted`           | Los créditos se consumen a través del uso o débito manual                                               |
| `credit.expired`            | Los créditos no utilizados caducan después del período de expiración configurado                        |
| `credit.rolled_over`        | Los créditos no utilizados se trasladan a una nueva concesión al final del ciclo                        |
| `credit.rollover_forfeited` | Los créditos se pierden porque se alcanzó el número máximo de traspasos                                 |
| `credit.overage_charged`    | Se aplican cargos por exceso cuando el consumo continúa más allá del saldo cero                         |
| `credit.overage_reset`      | Los cargos acumulados por exceso se reinician (por ejemplo, al inicio de un nuevo ciclo de facturación) |
| `credit.manual_adjustment`  | Ajuste manual de crédito o débito realizado a través del panel o API                                    |
| `credit.balance_low`        | El saldo de crédito cae por debajo del umbral de saldo bajo configurado                                 |

### Eventos del Libro Mayor

Todos los eventos del libro mayor (`credit.added` hasta `credit.manual_adjustment`) comparten la misma carga útil `CreditLedgerEntryResponse` documentada en el esquema a continuación.

La carga útil incluye un campo `metadata` resuelto desde la **fuente** del otorgamiento de crédito: la suscripción o el pago creado en el checkout. Esto te permite asociar créditos de billetera basados en tu propio checkout `metadata` (por ejemplo, un `orgId`) en lugar del emitido por Dodo `customer_id`: los otorgamientos basados en suscripción muestran el `metadata` de la suscripción y los basados en pago muestran el `metadata` del pago. El campo está vacío cuando el otorgamiento no tiene una fuente resoluble (por ejemplo, créditos otorgados directamente a través de la API).

### Evento de Bajo Saldo (credit.balance\_low)

El evento `credit.balance_low` utiliza una carga útil diferente (`CreditBalanceLowPayload`) enfocada en alertas de umbral:

```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">
  El cliente cuyo saldo de crédito activó la alerta.
</ParamField>

<ParamField body="subscription_id" type="string">
  La suscripción asociada con este derecho de crédito.
</ParamField>

<ParamField body="credit_entitlement_id" type="string">
  El derecho de crédito que tiene un saldo bajo.
</ParamField>

<ParamField body="credit_entitlement_name" type="string">
  Nombre para mostrar del derecho de crédito.
</ParamField>

<ParamField body="available_balance" type="string">
  Saldo de crédito actual en el momento de la alerta.
</ParamField>

<ParamField body="subscription_credits_amount" type="string">
  Total de créditos emitidos por ciclo de facturación para esta suscripción.
</ParamField>

<ParamField body="threshold_percent" type="integer">
  El porcentaje de umbral de bajo saldo configurado.
</ParamField>

<ParamField body="threshold_amount" type="string">
  La cantidad de crédito absoluta que corresponde al umbral.
</ParamField>

### Usando `credit.balance_low` para Alertas Proactivas

Utiliza el webhook `credit.balance_low` para notificar a los clientes antes de que se queden sin 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>
  Suscríbete a `credit.balance_low` para alertar proactivamente a los clientes antes de que agoten sus créditos. Combina con `credit.deducted` para rastrear patrones de consumo en tiempo real.
</Tip>

<CardGroup cols={2}>
  <Card title="Get Customer Balance" icon="wallet" href="/api-reference/credit-entitlements/get-customer-balance">
    Verifica el saldo actual de un cliente a través de la API.
  </Card>

  <Card title="Create Ledger Entry" icon="plus" href="/api-reference/credit-entitlements/create-ledger-entry">
    Acredita o debita manualmente el saldo de un cliente.
  </Card>
</CardGroup>

## Esquema de Carga Útil del Webhook