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.addedCredits werden einem Kunden gewährt (über Abonnement, einmaligen Kauf, Add-on oder API)
credit.deductedCredits werden durch Nutzung oder manuelle Abbuchung verbraucht
credit.expiredUnverwendete Credits verfallen nach der konfigurierten Ablaufzeit
credit.rolled_overUnverwendete Credits werden am Ende des Zyklus in eine neue Gewährung übertragen
credit.rollover_forfeitedCredits verfallen, weil die maximale Anzahl an Rollovers erreicht wurde
credit.overage_chargedÜberziehungsgebühren werden angewendet, wenn die Nutzung über das Nullsaldo hinausgeht
credit.manual_adjustmentManuelle Kredit- oder Debit-Anpassung über Dashboard oder API
credit.balance_lowDas Credit-Guthaben fällt unter den konfigurierten Schwellenwert für niedrigen Kontostand

​
Ledger-Ereignisse

Alle Ledger-Ereignisse (credit.added bis credit.manual_adjustment) verwenden dieselbe CreditLedgerEntryResponse-Nutzlast, die im untenstehenden Schema dokumentiert ist.

​
Event bei niedrigem Guthaben (credit.balance_low)

Das credit.balance_low-Ereignis verwendet eine andere Nutzlast (CreditBalanceLowPayload), die sich auf Schwellenwertwarnungen 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 Kreditguthaben den Alarm ausgelöst hat.
​
subscription_id
string
Das mit dieser Credit-Berechtigung verknüpfte Abonnement.
​
credit_entitlement_id
string
Die Credit-Berechtigung, deren Guthaben niedrig ist.
​
credit_entitlement_name
string
Anzeigename der Credit-Berechtigung.
​
available_balance
string
Aktuelles Credit-Guthaben zum Zeitpunkt der Warnung.
​
subscription_credits_amount
string
Gesamte Credits, die pro Abrechnungszyklus für dieses Abonnement ausgegeben werden.
​
threshold_percent
integer
Der konfigurierte Schwellenwert in Prozent für niedrigen Kontostand.
​
threshold_amount
string
Der absolute Credit-Betrag, dem der Schwellenwert entspricht.

​
Verwendung von credit.balance_low für proaktive Warnungen

Verwenden Sie den credit.balance_low-Webhook, um Kunden zu benachrichtigen, bevor ihnen die Credits ausgehen: 
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 ihre Credits erschöpft sind. Kombinieren Sie es mit credit.deducted, um Echtzeit-Nutzungsmuster zu verfolgen.

Get Customer Balance

Ermitteln Sie das aktuelle Guthaben eines Kunden über die API.

Create Ledger Entry

Buchen Sie manuell ein Credit oder Debit auf das Guthaben eines Kunden.

​
Webhook-Payload-Schema

Response for a ledger entry

​
amount
string
erforderlich
​
balance_after
string
erforderlich
​
balance_before
string
erforderlich
​
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
​
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,
auto_top_up,
manual_adjustment,
refund
​
description
string | null
​
grant_id
string | null
​
reference_id
string | null
​
reference_type
string | null