Credit Based Billing

Dodo Payments Credit-Based Billing

Reference: [docs.dodopayments.com/features/credit-based-billing](https://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

Credit Lifecycle

1. Credits Issued — Granted on purchase (subscription cycle or one-time) or via API 2. Credits Consumed — Deducted via meter events or manual API calls 3. Credits Expire or Roll Over — At cycle end, unused credits expire or carry forward 4. Overage Handling — If balance hits zero, overage is forgiven, billed, or carried as deficit

Grant Sources

---

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

Balance & Ledger Operations

---

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:

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:

Overage Behaviors:

Expiration

---

Webhook Events

Credit-based billing fires these webhook events:

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

1. Your app sends usage events — Each event includes customer ID, event name, and metadata 2. Meters aggregate events — Using Count, Sum, Max, Last, or Unique Count 3. Credits are deducted automatically — Converted at your configured meter_units_per_credit rate 4. Overage is tracked — If balance reaches zero and overage is enabled, usage continues

Meter-Credit Configuration

In Dashboard → Products → Usage-Based Product → Select Meter: 1. Toggle Bill usage in Credits 2. Select the credit entitlement 3. Set Meter units per credit (e.g., 1000 API calls = 1 credit) 4. 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

Plan      | Price    | Credits/Month  | Overage
----------|----------|----------------|----------
Starter   | $29/mo   | 10,000 tokens  | $0.003/token
Pro       | $99/mo   | 100,000 tokens | $0.002/token
Enterprise| $499/mo  | 1,000,000 tokens| $0.001/token

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

Plan      | Price    | Credits/Month  | Overage
----------|----------|----------------|----------
Free      | $0/mo    | 1,000 calls    | Blocked
Developer | $19/mo   | 50,000 calls   | $0.001/call
Business  | $99/mo   | 500,000 calls  | $0.0005/call

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

Cloud Storage

Plan      | Price    | Credits/Month  | Overage
----------|----------|----------------|----------
Personal  | $9/mo    | 100 GB-hours   | $0.05/GB-hour
Team      | $49/mo   | 1,000 GB-hours | $0.03/GB-hour

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:

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