Zum Hauptinhalt springen

​
Kreditbasierte Abrechnung Webhook-Ereignisse

Die folgenden Webhook-Ereignisse stehen zur Verfügung, um Änderungen im Lebenszyklus der kreditbasierten Abrechnung nachzuverfolgen. Diese Ereignisse gelten für virtuelle Credit-Berechtigungen (API-Aufrufe, Tokens, Compute-Stunden), nicht für Customer Wallets (monetäre Guthaben).
EreignisBeschreibung
credit.addedGutschriften werden einem Kunden gewährt (über Abonnement, Einmalkauf, Add-on oder API)
credit.deductedGutschriften werden durch Nutzung oder manuelle Belastung verbraucht
credit.expiredUnbenutzte Gutschriften sind nach der konfigurierten Verfallsfrist verfallen
credit.rolled_overUnbenutzte Gutschriften werden am Zyklusende in eine neue Gewährung übertragen
credit.rollover_forfeitedGutschriften verfallen, weil die maximale Übertragsanzahl erreicht wurde
credit.overage_chargedÜberlastungsgebühren werden erhoben, wenn die Nutzung über den Nullsaldo hinaus fortgesetzt wird
credit.overage_resetAufgelaufene Überlastungsgebühren werden zurückgesetzt (z. B. zu Beginn eines neuen Abrechnungszeitraums)
credit.manual_adjustmentManuelle Gutschrift oder Belastungsanpassung über Dashboard oder API vorgenommen
credit.balance_lowGuthaben fällt unter die konfigurierte Schwelle für niedrigen Saldo

​
Ledger-Ereignisse

Alle Ledger-Ereignisse (credit.added bis credit.manual_adjustment) verwenden dieselbe CreditLedgerEntryResponse-Nutzlast, die im untenstehenden Schema dokumentiert ist. Die Nutzlast enthält ein metadata Feld, das aus der Quelle des Kreditgewährung aufgelöst wurde — dem bei der Kasse erstellten Abonnement oder der Zahlung. Dies ermöglicht es Ihnen, Wallet-Guthaben von Ihrem eigenen Checkout metadata (zum Beispiel ein orgId) zu verknüpfen, anstatt dem von Dodo ausgegebenen customer_id: Kredite aus Abonnements zeigen das Abonnement’s metadata und Kredite aus Zahlungen zeigen das Zahlung’s metadata. Das Feld ist leer, wenn die Kredite keine auflösbare Quelle haben (zum Beispiel, Kredite, die direkt über die API gewährt wurden).

​
Niedriges Guthaben Ereignis (credit.balance_low)

Das credit.balance_low Ereignis verwendet eine andere Nutzlast (CreditBalanceLowPayload), die sich auf Schwellenwert-Warnungen konzentriert: 
{
  "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
Der Kunde, dessen Guthaben die Warnung ausgelöst hat.
​
subscription_id
string
Das Abonnement, das mit diesem Kreditanspruch verbunden ist.
​
credit_entitlement_id
string
Der Kreditanspruch, der ein niedriges Guthaben hat.
​
credit_entitlement_name
string
Anzeigename des Kreditanspruchs.
​
available_balance
string
Aktuelles Guthaben zum Zeitpunkt der Warnung.
​
subscription_credits_amount
string
Gesamtausgabe von Guthaben pro Abrechnungszyklus für dieses Abonnement.
​
threshold_percent
integer
Der konfigurierte Prozentsatz für den niedrigen Guthabensschwellenwert.
​
threshold_amount
string
Der absolute Kreditbetrag, dem der Schwellenwert entspricht.

​
Verwenden von credit.balance_low für proaktive Warnungen

Verwenden Sie das credit.balance_low Webhook, um Kunden zu benachrichtigen, bevor sie ihr Guthaben aufbrauchen: 
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 });
});
Abonnieren Sie credit.balance_low, um Kunden proaktiv zu warnen, bevor sie ihr Guthaben erschöpfen. Kombinieren Sie es mit credit.deducted, um Echtzeit-Verbrauchsmuster zu verfolgen.

Get Customer Balance

Überprüfen Sie den aktuellen Kontostand eines Kunden über die API.

Create Ledger Entry

Manuell den Kontostand eines Kunden gutschreiben oder belasten.

​
Webhook-Payload-Schema

Response for a ledger entry

​
amount
string
erforderlich
​
balance_after
string
erforderlich
​
balance_before
string
erforderlich
​
brand_id
string
erforderlich

Brand id this credit ledger entry belongs to

​
business_id
string
erforderlich
​
created_at
string<date-time>
erforderlich
​
credit_entitlement_id
string
erforderlich
​
customer_id
string
erforderlich
​
id
string
erforderlich
​
is_credit
boolean
erforderlich
​
metadata
object
erforderlich

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

​
overage_after
string
erforderlich
​
overage_before
string
erforderlich
​
transaction_type
enum<string>
erforderlich
Verfügbare Optionen:
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
Zuletzt geändert am 26. Juni 2026