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

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