Passer au contenu principal

É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énementDescription
credit.addedDes crédits sont accordés à un client (via abonnement, achat ponctuel, module complémentaire ou API)
credit.deductedLes crédits sont consommés par l’utilisation ou un débit manuel
credit.expiredLes crédits non utilisés expirent après la période d’expiration configurée
credit.rolled_overLes crédits non utilisés sont reportés sur une nouvelle attribution à la fin du cycle
credit.rollover_forfeitedCrédits confisqués car le nombre maximal de reports a été atteint
credit.overage_chargedDes frais supplémentaires sont appliqués lorsque l’utilisation se poursuit au-delà d’un solde nul
credit.manual_adjustmentAjustement manuel de crédit ou de débit effectué via le tableau de bord ou l’API
credit.balance_lowLe 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.

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
id
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,
auto_top_up,
manual_adjustment,
refund
description
string | null
grant_id
string | null
reference_id
string | null
reference_type
string | null