Saltar al contenido principal

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.

​
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 (saldos monetarios).
EventoDescripción
credit.addedSe otorgan créditos a un cliente (a través de suscripción, compra única, complemento, o API)
credit.deductedLos créditos se consumen a través del uso o débito manual
credit.expiredLos créditos no utilizados caducan después del período de expiración configurado
credit.rolled_overLos créditos no utilizados se trasladan a una nueva concesión al final del ciclo
credit.rollover_forfeitedLos créditos se pierden porque se alcanzó el número máximo de traspasos
credit.overage_chargedSe aplican cargos por exceso cuando el consumo continúa más allá del saldo cero
credit.overage_resetLos cargos acumulados por exceso se reinician (por ejemplo, al inicio de un nuevo ciclo de facturación)
credit.manual_adjustmentAjuste manual de crédito o débito realizado a través del panel o API
credit.balance_lowEl 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.

​
Evento de Saldo Bajo (credit.balance_low)

El evento credit.balance_low usa una carga útil diferente (CreditBalanceLowPayload) centrada en alertas de umbral: 
{
  "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
El cliente cuyo saldo de créditos activó la alerta.
​
subscription_id
string
La suscripción asociada a este derecho de crédito.
​
credit_entitlement_id
string
El derecho de crédito que tiene un saldo bajo.
​
credit_entitlement_name
string
Nombre visible del derecho de crédito.
​
available_balance
string
Saldo de créditos actual en el momento de la alerta.
​
subscription_credits_amount
string
Créditos totales emitidos por ciclo de facturación para esta suscripción.
​
threshold_percent
integer
El porcentaje de umbral de saldo bajo configurado.
​
threshold_amount
string
La cantidad absoluta de crédito a la que corresponde el umbral.

​
Uso de 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: 
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 });
});
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.

Get Customer Balance

Consulta el saldo actual de un cliente a través de la API.

Create Ledger Entry

Acredita o debita manualmente el saldo de un cliente.

​
Esquema de la carga útil del webhook

Response for a ledger entry

​
amount
string
requerido
​
balance_after
string
requerido
​
balance_before
string
requerido
​
business_id
string
requerido
​
created_at
string<date-time>
requerido
​
credit_entitlement_id
string
requerido
​
customer_id
string
requerido
​
id
string
requerido
​
is_credit
boolean
requerido
​
overage_after
string
requerido
​
overage_before
string
requerido
​
transaction_type
enum<string>
requerido
Opciones disponibles:
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
Last modified on May 22, 2026