Dodo Payments Credit-Based Billing

Reference: docs.dodopayments.com/features/credit-based-billing

Grant customers a balance of credits (API calls, tokens, compute units, or any custom metric) and deduct from that balance as they consume your service.

Overview

Credit-based billing lets you:

• Issue credits with subscriptions, one-time purchases, or via API

• Deduct automatically via usage meters or manually via API

• Configure rollover to carry unused credits forward

• Handle overage when credits run out mid-cycle

• Set expiration rules per credit entitlement

• Track everything via a full audit ledger

Credits work across all product types: subscriptions, one-time purchases, and usage-based billing.

Core Concepts

Credit Types

Type Description Best For

Custom Unit Your own metric (tokens, API calls, compute hours) with configurable precision (0–3 decimals) API calls, AI tokens, compute hours, messages

Fiat Credits Real currency value (USD, EUR, etc.) that depletes as customers use your service Prepaid balances, promotional credits, compensation

Credit Lifecycle

• Credits Issued — Granted on purchase (subscription cycle or one-time) or via API

• Credits Consumed — Deducted via meter events or manual API calls

• Credits Expire or Roll Over — At cycle end, unused credits expire or carry forward

• Overage Handling — If balance hits zero, overage is forgiven, billed, or carried as deficit

Grant Sources

Source Description

Subscription Credits issued each billing cycle

One-Time Credits issued with a one-time payment

API Credits granted manually via API or dashboard

Rollover Credits carried over from a previous billing cycle

Quick Start

1. Create a Credit Entitlement

import DodoPayments from 'dodopayments';

const client = new DodoPayments({ bearerToken: process.env.DODO_PAYMENTS_API_KEY, });

const credit = await client.creditEntitlements.create({ name: 'API Credits', credit_type: 'custom_unit', unit_name: 'API Calls', precision: 0, expiry_duration: 30, // days rollover_enabled: false, allow_overage: false, });

2. Attach Credits to a Product

In Dashboard → Products → Create/Edit Product → Entitlements → Attach Credits:

• Select the credit entitlement

• Set credits issued per billing cycle (subscriptions) or total (one-time)

• Configure trial credits, proration, low balance threshold

3. Create Checkout with Credit Product

const session = await client.checkoutSessions.create({ product_cart: [ { product_id: 'prod_ai_pro_plan', // Product with credits attached quantity: 1, } ], customer: { email: 'customer@example.com' }, return_url: 'https://yourapp.com/success', });

// Redirect to session.checkout_url

4. Deduct Credits via Usage Events

// Meter linked to credit entitlement deducts automatically await client.usageEvents.ingest({ events: [{ event_id: gen_${Date.now()}_${crypto.randomUUID()}, customer_id: 'cus_abc123', event_name: 'ai.generation', timestamp: new Date().toISOString(), metadata: { model: 'gpt-4', tokens: '1500' } }] });

5. Check Balance

const balance = await client.creditEntitlements.balances.get( 'cent_credit_id', 'cus_abc123' );

console.log(Available: ${balance.available_balance}); console.log(Overage: ${balance.overage_balance});

API Reference

Credit Entitlement CRUD

Operation Method Endpoint

Create POST

/credit-entitlements

List GET

/credit-entitlements

Get GET

/credit-entitlements/{id}

Update PATCH

/credit-entitlements/{id}

Delete DELETE

/credit-entitlements/{id}

Undelete POST

/credit-entitlements/{id}/undelete

Balance & Ledger Operations

Operation Method Endpoint

List All Balances GET

/credit-entitlements/{id}/balances

Get Customer Balance GET

/credit-entitlements/{id}/balances/{customer_id}

Create Ledger Entry POST

/credit-entitlements/{id}/balances/{customer_id}/ledger-entries

List Customer Ledger GET

/credit-entitlements/{id}/balances/{customer_id}/ledger

List Customer Grants GET

/credit-entitlements/{id}/balances/{customer_id}/grants

Implementation Examples

TypeScript/Node.js

Create Credit Entitlement

import DodoPayments from 'dodopayments';

const client = new DodoPayments({ bearerToken: process.env.DODO_PAYMENTS_API_KEY!, });

// Custom unit credit (AI tokens) const tokenCredit = await client.creditEntitlements.create({ name: 'AI Tokens', credit_type: 'custom_unit', unit_name: 'tokens', precision: 0, expiry_duration: 30, rollover_enabled: true, max_rollover_percentage: 25, rollover_timeframe: 'month', max_rollover_count: 3, allow_overage: true, overage_limit: 50000, price_per_unit: 0.001, overage_behavior: 'bill_overage_at_billing', });

// Fiat credit (USD balance) const usdCredit = await client.creditEntitlements.create({ name: 'Platform Credits', credit_type: 'fiat', unit_currency: 'USD', expiry_duration: 90, rollover_enabled: false, allow_overage: false, });

Manual Credit/Debit via Ledger Entry

// Grant credits manually (e.g., promotional bonus) await client.creditEntitlements.balances.createLedgerEntry( 'cent_credit_id', 'cus_abc123', { type: 'credit', amount: '500', description: 'Welcome bonus - 500 free API credits', idempotency_key: welcome_bonus_${customerId}, } );

// Debit credits manually (e.g., service compensation deduction) await client.creditEntitlements.balances.createLedgerEntry( 'cent_credit_id', 'cus_abc123', { type: 'debit', amount: '100', description: 'Manual deduction for premium support', idempotency_key: support_deduction_${Date.now()}, } );

Query Customer Balance and Ledger

// Get current balance const balance = await client.creditEntitlements.balances.get( 'cent_credit_id', 'cus_abc123' ); console.log(Balance: ${balance.available_balance});

// List all balances for a credit entitlement const allBalances = await client.creditEntitlements.balances.list( 'cent_credit_id' );

// Get full transaction history const ledger = await client.creditEntitlements.balances.listLedger( 'cent_credit_id', 'cus_abc123' );

for (const entry of ledger.items) { console.log(${entry.type}: ${entry.amount} | Balance: ${entry.balance_after}); }

// List credit grants const grants = await client.creditEntitlements.balances.listGrants( 'cent_credit_id', 'cus_abc123' );

Update Credit Entitlement Settings

await client.creditEntitlements.update('cent_credit_id', { rollover_enabled: true, max_rollover_percentage: 50, allow_overage: true, overage_limit: 10000, price_per_unit: 0.002, overage_behavior: 'bill_overage_at_billing', });

Python

from dodopayments import DodoPayments import os import uuid from datetime import datetime

client = DodoPayments(bearer_token=os.environ["DODO_PAYMENTS_API_KEY"])

Create credit entitlement

credit = client.credit_entitlements.create( name="AI Tokens", credit_type="custom_unit", unit_name="tokens", precision=0, expiry_duration=30, rollover_enabled=True, max_rollover_percentage=25, allow_overage=True, overage_limit=50000, price_per_unit=0.001, overage_behavior="bill_overage_at_billing", )

Grant credits manually

client.credit_entitlements.balances.create_ledger_entry( credit_entitlement_id="cent_credit_id", customer_id="cus_abc123", type="credit", amount="500", description="Promotional bonus", idempotency_key=f"promo_{uuid.uuid4()}", )

Check balance

balance = client.credit_entitlements.balances.get( credit_entitlement_id="cent_credit_id", customer_id="cus_abc123", ) print(f"Available: {balance.available_balance}")

Send usage events that deduct credits

client.usage_events.ingest(events=[{ "event_id": f"api_{datetime.now().timestamp()}_{uuid.uuid4()}", "customer_id": "cus_abc123", "event_name": "ai.tokens", "timestamp": datetime.now().isoformat(), "metadata": {"tokens": "1500", "model": "gpt-4"} }])

Go

package main

import ( "context" "fmt" "os" "time"

"github.com/dodopayments/dodopayments-go"
"github.com/google/uuid"

)

func main() { client := dodopayments.NewClient( option.WithBearerToken(os.Getenv("DODO_PAYMENTS_API_KEY")), )

ctx := context.Background()

// Create credit entitlement
credit, err := client.CreditEntitlements.Create(ctx, &dodopayments.CreditEntitlementCreateParams{
    Name:       "AI Tokens",
    CreditType: "custom_unit",
    UnitName:   "tokens",
    Precision:  0,
})
if err != nil {
    panic(err)
}

// Get customer balance
balance, err := client.CreditEntitlements.Balances.Get(ctx, credit.ID, "cus_abc123")
if err != nil {
    panic(err)
}
fmt.Printf("Balance: %s\n", balance.AvailableBalance)

// Send usage events
_, err = client.UsageEvents.Ingest(ctx, &dodopayments.UsageEventIngestParams{
    Events: []dodopayments.UsageEvent{{
        EventID:    fmt.Sprintf("api_%d_%s", time.Now().Unix(), uuid.New().String()),
        CustomerID: "cus_abc123",
        EventName:  "ai.tokens",
        Timestamp:  time.Now().Format(time.RFC3339),
        Metadata: map[string]string{
            "tokens": "1500",
            "model":  "gpt-4",
        },
    }},
})
if err != nil {
    panic(err)
}

}

Credit Settings

Rollover

Carry unused credits forward to the next billing cycle:

Setting Description

Rollover Enabled Toggle to allow unused credits to carry forward

Max Rollover Percentage Limit how much carries over (0–100%)

Rollover Timeframe How long rolled-over credits remain valid (day, week, month, year)

Max Rollover Count Maximum consecutive rollovers before credits are forfeited

Example: 200 unused credits at cycle end, 75% rollover → 150 credits carry forward, 50 forfeited.

Overage

Controls what happens when a customer's balance reaches zero mid-cycle:

Setting Description

Allow Overage Let customers continue past zero balance

Overage Limit Max credits consumable beyond balance

Price Per Unit Cost per additional credit (with currency)

Overage Behavior How overage is handled at cycle end

Overage Behaviors:

Behavior Description

Forgive overage at reset Overage tracked but not billed (default)

Bill overage at billing Overage charged on next invoice

Carry over deficit Negative balance carries into next cycle

Carry over deficit (auto-repay) Deficit auto-repaid from new credits next cycle

Expiration

Setting Description

Credit Expiry Duration after issuance: 7, 30, 60, 90, custom days, or never

Trial Credits Expire After Trial Whether trial-specific credits expire when trial ends

Webhook Events

Credit-based billing fires these webhook events:

Event Description

credit.added

Credits granted to a customer

credit.deducted

Credits consumed through usage or manual debit

credit.expired

Unused credits expired

credit.rolled_over

Credits carried forward to a new grant

credit.rollover_forfeited

Credits forfeited at max rollover count

credit.overage_charged

Overage charges applied

credit.manual_adjustment

Manual credit/debit adjustment made

credit.balance_low

Balance dropped below configured threshold

Webhook Handler Example

// app/api/webhooks/dodo/route.ts import { NextRequest, NextResponse } from 'next/server';

export async function POST(req: NextRequest) { const event = await req.json();

switch (event.type) { case 'credit.added': await handleCreditAdded(event.data); break; case 'credit.deducted': await handleCreditDeducted(event.data); break; case 'credit.balance_low': await handleBalanceLow(event.data); break; case 'credit.expired': await handleCreditExpired(event.data); break; case 'credit.overage_charged': await handleOverageCharged(event.data); break; }

return NextResponse.json({ received: true }); }

async function handleCreditAdded(data: any) { const { customer_id, credit_entitlement_id, amount, balance_after } = data;

// Update internal records await prisma.creditBalance.upsert({ where: { customerId_creditId: { customerId: customer_id, creditId: credit_entitlement_id } }, create: { customerId: customer_id, creditId: credit_entitlement_id, balance: balance_after }, update: { balance: balance_after }, }); }

async function handleCreditDeducted(data: any) { const { customer_id, credit_entitlement_id, amount, balance_after } = data;

await prisma.creditBalance.update({ where: { customerId_creditId: { customerId: customer_id, creditId: credit_entitlement_id } }, data: { balance: balance_after }, }); }

async function handleBalanceLow(data: any) { const { customer_id, credit_entitlement_name, available_balance, threshold_percent, } = data;

// Notify the customer await sendEmail(customer_id, { subject: Your ${credit_entitlement_name} balance is running low, body: You have ${available_balance} credits remaining (${threshold_percent}% threshold reached). Consider upgrading your plan or purchasing additional credits., }); }

async function handleCreditExpired(data: any) { const { customer_id, credit_entitlement_id, amount, balance_after } = data;

await prisma.creditBalance.update({ where: { customerId_creditId: { customerId: customer_id, creditId: credit_entitlement_id } }, data: { balance: balance_after }, });

// Optionally notify customer await sendCreditExpiryNotification(customer_id, amount); }

async function handleOverageCharged(data: any) { const { customer_id, credit_entitlement_id, amount, overage_after } = data;

// Track overage for billing await prisma.overageRecord.create({ data: { customerId: customer_id, creditId: credit_entitlement_id, amount, overageBalance: overage_after, }, }); }

Balance Low Payload

The credit.balance_low event has a distinct payload:

{ "business_id": "bus_xxxxx", "type": "credit.balance_low", "timestamp": "2025-08-04T06:15:00.000000Z", "data": { "payload_type": "CreditBalanceLow", "customer_id": "cus_xxxxx", "subscription_id": "sub_xxxxx", "credit_entitlement_id": "cent_xxxxx", "credit_entitlement_name": "API Credits", "available_balance": "15", "subscription_credits_amount": "100", "threshold_percent": 20, "threshold_amount": "20" } }

Usage Billing with Credits

When credits are linked to usage meters, meter events automatically deduct credits. A background worker processes events every minute, converts meter units to credits using your configured rate, and deducts using FIFO ordering (oldest grants first).

How It Works

• Your app sends usage events — Each event includes customer ID, event name, and metadata

• Meters aggregate events — Using Count, Sum, Max, Last, or Unique Count

• Credits are deducted automatically — Converted at your configured meter_units_per_credit rate

• Overage is tracked — If balance reaches zero and overage is enabled, usage continues

Meter-Credit Configuration

In Dashboard → Products → Usage-Based Product → Select Meter:

• Toggle Bill usage in Credits

• Select the credit entitlement

• Set Meter units per credit (e.g., 1000 API calls = 1 credit)

• Set Free Threshold (units free before credit deduction begins)

AI Token Billing Example

import DodoPayments from 'dodopayments';

const client = new DodoPayments({ bearerToken: process.env.DODO_PAYMENTS_API_KEY!, });

// Track AI token usage — meter auto-deducts credits async function trackAIUsage( customerId: string, promptTokens: number, completionTokens: number, model: string ) { const totalTokens = promptTokens + completionTokens;

await client.usageEvents.ingest({ events: [{ event_id: ai_${Date.now()}_${crypto.randomUUID()}, customer_id: customerId, event_name: 'ai.tokens', timestamp: new Date().toISOString(), metadata: { tokens: totalTokens.toString(), prompt_tokens: promptTokens.toString(), completion_tokens: completionTokens.toString(), model, } }] }); }

// After AI completion await trackAIUsage('cus_abc123', 500, 1200, 'gpt-4');

API Rate Tracking Example

// Middleware to track and deduct API credits async function trackAPICredit(customerId: string, req: Request) { await client.usageEvents.ingest({ events: [{ event_id: api_${Date.now()}_${crypto.randomUUID()}, customer_id: customerId, event_name: 'api.call', timestamp: new Date().toISOString(), metadata: { endpoint: new URL(req.url).pathname, method: req.method, } }] }); }

Next.js Integration

Credit Balance API Route

// app/api/credits/balance/route.ts import { NextRequest, NextResponse } from 'next/server'; import DodoPayments from 'dodopayments';

const client = new DodoPayments({ bearerToken: process.env.DODO_PAYMENTS_API_KEY!, });

export async function GET(req: NextRequest) { const customerId = req.nextUrl.searchParams.get('customer_id'); const creditId = req.nextUrl.searchParams.get('credit_id');

if (!customerId || !creditId) { return NextResponse.json({ error: 'Missing parameters' }, { status: 400 }); }

try { const balance = await client.creditEntitlements.balances.get(creditId, customerId);

return NextResponse.json({
  available: balance.available_balance,
  overage: balance.overage_balance,
});

} catch (error: any) { return NextResponse.json({ error: error.message }, { status: 500 }); } }

Manual Credit Grant API Route

// app/api/credits/grant/route.ts import { NextRequest, NextResponse } from 'next/server'; import DodoPayments from 'dodopayments';

const client = new DodoPayments({ bearerToken: process.env.DODO_PAYMENTS_API_KEY!, });

export async function POST(req: NextRequest) { const { customerId, creditId, amount, description } = await req.json();

try { const entry = await client.creditEntitlements.balances.createLedgerEntry( creditId, customerId, { type: 'credit', amount: amount.toString(), description, idempotency_key: grant_${customerId}_${Date.now()}, } );

return NextResponse.json({ success: true, balance_after: entry.balance_after });

} catch (error: any) { return NextResponse.json({ error: error.message }, { status: 500 }); } }

Credit Balance Hook

// hooks/useCreditBalance.ts import useSWR from 'swr';

const fetcher = (url: string) => fetch(url).then(r => r.json());

export function useCreditBalance(customerId: string, creditId: string) { const { data, error, mutate } = useSWR( /api/credits/balance?customer_id=${customerId}&credit_id=${creditId}, fetcher, { refreshInterval: 30000 } // Refresh every 30s );

return { available: data?.available, overage: data?.overage, isLoading: !error && !data, isError: error, refresh: mutate, }; }

// Usage in component function CreditDisplay() { const { available, isLoading } = useCreditBalance('cus_abc123', 'cent_xxxxx');

if (isLoading) return <div>Loading...</div>;

return ( <div> <h3>Credits Remaining</h3> <p className="text-3xl font-bold">{available}</p> </div> ); }

Common Patterns

Credit Top-Up (One-Time Purchase)

Sell credit packs as one-time products:

// Product: "500 API Credit Pack" with 500 credits attached const session = await client.checkoutSessions.create({ product_cart: [ { product_id: 'prod_credit_pack_500', quantity: 1 } ], customer: { email: 'customer@example.com' }, return_url: 'https://yourapp.com/credits/success', });

Subscription with Credits + Overage

// Product: Pro Plan - $49/month, 10,000 tokens included, $0.002/token overage // Credits attached in dashboard with: // - Credits per cycle: 10000 // - Allow overage: true // - Price per unit: $0.002 // - Overage behavior: Bill overage at billing

const session = await client.checkoutSessions.create({ product_cart: [ { product_id: 'prod_pro_with_credits', quantity: 1 } ], subscription_data: { trial_period_days: 14 }, customer: { email: 'customer@example.com' }, return_url: 'https://yourapp.com/success', });

Access Control Based on Credits

// Middleware to check credit balance before allowing API access async function requireCredits(customerId: string, creditId: string): Promise<boolean> { try { const balance = await client.creditEntitlements.balances.get(creditId, customerId); const available = parseFloat(balance.available_balance); return available > 0; } catch { return false; } }

// Express middleware async function creditGate(req: Request, res: Response, next: Function) { const customerId = req.headers['x-customer-id'] as string; const hasCredits = await requireCredits(customerId, 'cent_api_credits');

if (!hasCredits) { return res.status(402).json({ error: 'Insufficient credits', message: 'Your credit balance is exhausted. Please upgrade your plan or purchase more credits.', }); }

next(); }

Promotional Credit Grants

// Grant promotional credits with idempotency async function grantPromoCredits( customerId: string, creditId: string, amount: number, promoCode: string ) { await client.creditEntitlements.balances.createLedgerEntry( creditId, customerId, { type: 'credit', amount: amount.toString(), description: Promotional credit: ${promoCode}, idempotency_key: promo_${promoCode}_${customerId}, // Prevents double-granting } ); }

Real-World Pricing Examples

AI SaaS Platform

Credit Config: Type: Custom Unit ("AI Tokens"), Precision: 0 Rollover: 25% max, 1-month timeframe Overage: Bill overage at billing Meter: ai.generation (Sum on tokens)

API Gateway

Credit Config: Type: Custom Unit ("API Calls"), Precision: 0 Rollover: Disabled Overage: Free=disabled, Dev+=forgive at reset Meter: api.request (Count)

Cloud Storage

Credit Config: Type: Custom Unit ("GB-hours"), Precision: 2 Rollover: 50% max, carries over once Overage: Enabled with 200% limit Meter: storage.usage (Sum)

Credit Ledger

Every credit operation is recorded with full audit trail:

Transaction Type Description

Credit Added Credits granted (subscription, one-time, or API)

Credit Deducted Credits consumed through usage or manual debit

Credit Expired Credits expired without rollover

Credit Rolled Over Credits carried forward to the next period

Rollover Forfeited Rolled credits forfeited after max count reached

Overage Charged Usage beyond credit balance with overage enabled

Auto Top-Up Automatic credit replenishment at low balance

Manual Adjustment Credit or debit applied manually by merchant

Refund Credits refunded

Each ledger entry records balance before/after, overage before/after, description, and reference to the source.

Best Practices

1. Start Simple

Begin with a single credit type and no rollover. Add complexity based on customer usage patterns.

2. Use Meaningful Units

Name credits after what they represent ("API Calls", "AI Tokens") not generic terms.

3. Set Low Balance Thresholds

Configure thresholds and subscribe to credit.balance_low to alert customers before they run out.

4. Use Idempotency Keys

Always include idempotency keys for manual ledger entries to prevent double-granting:

idempotency_key: promo_${promoCode}_${customerId}

5. Configure Expiry Thoughtfully

Short expiry (7 days) drives urgency but may frustrate. 30–90 days is customer-friendly for most SaaS.

6. Test the Full Cycle

In test mode: create credits → attach to product → purchase → send usage events → verify deduction → test expiration and rollover.

7. Monitor Overage

If using "Bill overage at billing", monitor overage amounts to avoid unexpected charges for customers.

Resources

• Credit-Based Billing Guide

• Credit Entitlements API

• Credit Webhook Events

• Usage-Based Billing

• Subscription Integration