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",
    "brand_id": "brd_123",
    "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

Die Marke, zu der dieses Credit-Entitlement gehört.

string

Der Kunde, dessen Credit-Guthaben den Alert ausgelöst hat.

string

Das mit diesem Credit-Entitlement verknüpfte Abonnement.

string

Das Credit-Entitlement mit einem niedrigen Guthaben.

string

Anzeigename des Credit-Entitlements.

string

Aktuelles Credit-Guthaben zum Zeitpunkt des Alerts.

string

Gesamtzahl der pro Abrechnungszyklus für dieses Abonnement ausgegebenen Credits.

integer

Der konfigurierte Schwellenwert für ein niedriges Guthaben in Prozent.

string

Der absolute Credit-Betrag, dem dieser Schwellenwert entspricht.

Verwendung von `credit.balance_low` für proaktive Alerts

Verwenden Sie den credit.balance_low-Webhook, um Kunden zu benachrichtigen, bevor ihre Credits aufgebraucht sind:

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 benachrichtigen, bevor sie ihre Credits aufbrauchen. Kombinieren Sie dies mit credit.deducted, um Verbrauchsmuster in Echtzeit zu verfolgen.

Get Customer Balance

Rufen Sie das aktuelle Guthaben eines Kunden über die API ab.

Create Ledger Entry

Gutschreiben oder belasten Sie das Guthaben eines Kunden manuell.

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