Credit-Based Billing

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

Event	Description
`credit.added`	Credits are granted to a customer (via subscription, one-time purchase, add-on, or API)
`credit.deducted`	Credits are consumed through usage or manual debit
`credit.expired`	Unused credits expired after the configured expiry period
`credit.rolled_over`	Unused credits are carried forward to a new grant at cycle end
`credit.rollover_forfeited`	Credits forfeited because the max rollover count was reached
`credit.overage_charged`	Overage charges applied when usage continues beyond zero balance
`credit.overage_reset`	Accumulated overage charges are reset (for example, at the start of a new billing cycle)
`credit.manual_adjustment`	Manual credit or debit adjustment made via dashboard or API
`credit.balance_low`	Credit 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"
  }
}

string

The customer whose credit balance triggered the alert.

string

The subscription associated with this credit entitlement.

string

The credit entitlement that has a low balance.

string

Display name of the credit entitlement.

string

Current credit balance at the time of the alert.

string

Total credits issued per billing cycle for this subscription.

integer

The configured low balance threshold percentage.

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

string

required

is_credit

boolean

required

metadata

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

Show child attributes

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

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous