Skip to main content

​
Credit-Based Billing Webhook Events

The following webhook events are available for tracking credit-based billing lifecycle changes. These events apply to virtual credit entitlements (API calls, tokens, compute hours), not to Customer Wallets (monetary balances).
EventDescription
credit.addedCredits are granted to a customer (via subscription, one-time purchase, add-on, or API)
credit.deductedCredits are consumed through usage or manual debit
credit.expiredUnused credits expired after the configured expiry period
credit.rolled_overUnused credits are carried forward to a new grant at cycle end
credit.rollover_forfeitedCredits forfeited because the max rollover count was reached
credit.overage_chargedOverage charges applied when usage continues beyond zero balance
credit.overage_resetAccumulated overage charges are reset (for example, at the start of a new billing cycle)
credit.manual_adjustmentManual credit or debit adjustment made via dashboard or API
credit.balance_lowCredit balance drops below the configured low balance threshold

​
Ledger Events

All ledger events (credit.added through credit.manual_adjustment) share the same CreditLedgerEntryResponse payload documented in the schema below. The payload includes a metadata field resolved from the credit grant’s source — the subscription or payment created at checkout. This lets you key wallet credits off your own checkout metadata (for example, an orgId) rather than the Dodo-issued customer_id: subscription-sourced grants surface the subscription’s metadata and payment-sourced grants surface the payment’s metadata. The field is empty when the grant has no resolvable source (for example, credits granted directly via the API).

​
Balance Low Event (credit.balance_low)

The credit.balance_low event uses a different payload (CreditBalanceLowPayload) focused on threshold alerting: 
{
  "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
The customer whose credit balance triggered the alert.
​
subscription_id
string
The subscription associated with this credit entitlement.
​
credit_entitlement_id
string
The credit entitlement that has a low balance.
​
credit_entitlement_name
string
Display name of the credit entitlement.
​
available_balance
string
Current credit balance at the time of the alert.
​
subscription_credits_amount
string
Total credits issued per billing cycle for this subscription.
​
threshold_percent
integer
The configured low balance threshold percentage.
​
threshold_amount
string
The absolute credit amount that the threshold corresponds to.

​
Using credit.balance_low for Proactive Alerts

Use the credit.balance_low webhook to notify customers before they run out of credits: 
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 });
});
Subscribe to credit.balance_low to proactively alert customers before they exhaust their credits. Combine with credit.deducted to track real-time consumption patterns.

Get Customer Balance

Check a customer’s current balance via API.

Create Ledger Entry

Manually credit or debit a customer’s balance.

​
Webhook Payload Schema

Response for a ledger entry

​
amount
string
required
​
balance_after
string
required
​
balance_before
string
required
​
brand_id
string
required

Brand id this credit ledger entry belongs to

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

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
required
​
overage_before
string
required
​
transaction_type
enum<string>
required
Available options:
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 June 25, 2026