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. La charge utile inclut un champ metadata résolu à partir de la source de l’octroi de crédit — l’abonnement ou le paiement créé lors du passage en caisse. Cela vous permet d’associer vos crédits de portefeuille à votre propre checkout metadata (par exemple, un orgId) plutôt qu’à celui émis par Dodo : les octrois issus de l’abonnement affichent le metadata de l’abonnement et les octrois issus du paiement affichent le metadata du paiement. Le champ est vide lorsque l’octroi n’a pas de source résolvable (par exemple, des crédits accordés directement via l’API).

Événement de Solde Bas (credit.balance_low)

L’événement credit.balance_low utilise une charge utile différente (CreditBalanceLowPayload) axée sur l’alerte 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édit 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 qui a un solde faible.

credit_entitlement_name

string

Nom d’affichage du droit de crédit.

available_balance

string

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

subscription_credits_amount

string

Total des crédits é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édit auquel correspond le seuil.

Utilisation de `credit.balance_low` pour des Alertes Proactives

Utilisez le webhook credit.balance_low pour notifier 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 proactivement les clients avant qu’ils n’épuisent leurs crédits. Combinez 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

brand_id

string

requis

Brand id this credit ledger entry belongs to

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

metadata

object

requis

Metadata associated with the credit grant's source (the subscription or payment created at checkout). Empty when the grant has no resolvable source (e.g. credits granted directly via the API).

Show child attributes

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

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

​Événements du grand livre

​Événement de Solde Bas (credit.balance_low)

​Utilisation de credit.balance_low pour des 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)

Utilisation de `credit.balance_low` pour des Alertes Proactives

Schéma de Charge Utile du Webhook