Zum Hauptinhalt springen

Documentation Index

Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt

Use this file to discover all available pages before exploring further.

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.

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,
overage_reset,
auto_top_up,
manual_adjustment,
refund
description
string | null
grant_id
string | null
reference_id
string | null
reference_type
string | null
Last modified on May 22, 2026