Kreditbasierte Abrechnung

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

Ereignis	Beschreibung
`credit.added`	Gutschriften werden einem Kunden gewährt (über Abonnement, Einmalkauf, Add-on oder API)
`credit.deducted`	Gutschriften werden durch Nutzung oder manuelle Belastung verbraucht
`credit.expired`	Unbenutzte Gutschriften sind nach der konfigurierten Verfallsfrist verfallen
`credit.rolled_over`	Unbenutzte Gutschriften werden am Zyklusende in eine neue Gewährung übertragen
`credit.rollover_forfeited`	Gutschriften 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_reset`	Aufgelaufene Überlastungsgebühren werden zurückgesetzt (z. B. zu Beginn eines neuen Abrechnungszeitraums)
`credit.manual_adjustment`	Manuelle Gutschrift oder Belastungsanpassung über Dashboard oder API vorgenommen
`credit.balance_low`	Guthaben 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"
  }
}

string

Der Kunde, dessen Guthaben die Warnung ausgelöst hat.

string

Das Abonnement, das mit diesem Kreditanspruch verbunden ist.

string

Der Kreditanspruch, der ein niedriges Guthaben hat.

string

Anzeigename des Kreditanspruchs.

string

Aktuelles Guthaben zum Zeitpunkt der Warnung.

string

Gesamtausgabe von Guthaben pro Abrechnungszyklus für dieses Abonnement.

integer

Der konfigurierte Prozentsatz für den niedrigen Guthabensschwellenwert.

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

string

erforderlich

is_credit

boolean

erforderlich

metadata

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

Show child attributes

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

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous