Facturation basée sur les crédits - Dodo Payments Documentation

Événements webhook de facturation basés sur les crédits

Les événements webhook suivants sont disponibles pour suivre les changements du cycle de vie de la facturation basée sur les crédits. Ces événements s’appliquent aux droits de crédits virtuels (appels d’API, jetons, heures de calcul), pas aux Customer Wallets (soldes monétaires).

Événement	Description
`credit.added`	Des crédits sont accordés à un client (via abonnement, achat ponctuel, module complémentaire ou API)
`credit.deducted`	Les crédits sont consommés par l’utilisation ou un débit manuel
`credit.expired`	Les crédits non utilisés expirent après la période d’expiration configurée
`credit.rolled_over`	Les crédits non utilisés sont reportés sur une nouvelle attribution à la fin du cycle
`credit.rollover_forfeited`	Crédits confisqués car le nombre maximal de reports a été atteint
`credit.overage_charged`	Des frais supplémentaires sont appliqués lorsque l’utilisation se poursuit au-delà d’un solde nul
`credit.manual_adjustment`	Ajustement manuel de crédit ou de débit effectué via le tableau de bord ou l’API
`credit.balance_low`	Le solde de crédit tombe en dessous du seuil de solde bas configuré

Événements du grand livre

Tous les événements du grand livre (credit.added à credit.manual_adjustment) partagent la même charge utile CreditLedgerEntryResponse documentée dans le schéma ci-dessous.

Événement de solde bas (credit.balance_low)

L’événement credit.balance_low utilise une charge utile différente (CreditBalanceLowPayload) axée sur les alertes de seuil :

{
  "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

Le client dont le solde de crédits a déclenché l’alerte.

subscription_id

string

L’abonnement associé à ce droit de crédit.

credit_entitlement_id

string

Le droit de crédit dont le solde est bas.

credit_entitlement_name

string

Nom d’affichage du droit de crédit.

available_balance

string

Solde de crédits actuel au moment de l’alerte.

subscription_credits_amount

string

Crédits totaux émis par cycle de facturation pour cet abonnement.

threshold_percent

integer

Le pourcentage de seuil de solde bas configuré.

threshold_amount

string

Le montant absolu de crédits auquel correspond le seuil.

Utiliser `credit.balance_low` pour les alertes proactives

Utilisez le webhook credit.balance_low pour informer les clients avant qu’ils n’épuisent leurs crédits :

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 });
});

Abonnez-vous à credit.balance_low pour alerter de manière proactive les clients avant qu’ils n’épuisent leurs crédits. Combinez-le avec credit.deducted pour suivre les schémas de consommation en temps réel.

Get Customer Balance

Vérifiez le solde actuel d’un client via l’API.

Create Ledger Entry

Créditez ou débitez manuellement le solde d’un client.

Schéma de charge utile du webhook

Response for a ledger entry

amount

string

requis

balance_after

string

requis

balance_before

string

requis

business_id

string

requis

created_at

string<date-time>

requis

credit_entitlement_id

string

requis

customer_id

string

requis

string

requis

is_credit

boolean

requis

overage_after

string

requis

overage_before

string

requis

transaction_type

enum<string>

requis

Options 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

Documentation Index

​Événements webhook de facturation basés sur les crédits

​Événements du grand livre

​Événement de solde bas (credit.balance_low)

​Utiliser credit.balance_low pour les alertes proactives

Get Customer Balance

Create Ledger Entry

​Schéma de charge utile du webhook

Événements webhook de facturation basés sur les crédits

Événements du grand livre

Événement de solde bas (credit.balance_low)

Utiliser `credit.balance_low` pour les alertes proactives

Schéma de charge utile du webhook