Credit-Based Billing

Documentation Index

Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt

Use this file to discover all available pages before exploring further.

​

What is Credit-Based Billing?

• AI and LLM platforms: Grant tokens or generation credits per plan tier
• API services: Allocate API call credits with overage pricing
• Infrastructure platforms: Issue compute hours or storage credits
• Communication services: Provide message or minute credits per subscription
• SaaS with consumption tiers: Bundle included usage into credit pools

​

Core Concepts

​

Credit Types

​

Credit Lifecycle

​

Grant Sources

​

Creating Credits

1

Navigate to Credits

Go to Products in your dashboard and select the Credits tab. Click Create Credit to start.

2

Configure Basic Information

Enter a Credit Name - this is your internal identifier for the credit.

3

Set General Settings

Configure the credit type and display properties:

​

Credit Type

string

required

Choose Custom Unit or Fiat Credits.

• Custom Unit - Define your own metric (tokens, API calls, compute hours). Requires a Unit Name (e.g., “Platform tokens”) and a Precision setting.
• Fiat Credits - Credits represent real currency value. Requires a Unit Currency selection (USD, EUR, GBP, INR, etc.).

​

Unit Name

string

Only for Custom Unit credits. The label customers see for this credit (e.g., “AI Tokens”, “API Calls”). Shown in checkout and the customer portal.

​

Precision

number

Only for Custom Unit credits. Number of decimal places allowed:

• 0 - Whole numbers (best for countable items like API calls)
• 1 - One decimal (0.0)
• 2 - Two decimals (0.00) - default
• 3 - Three decimals (0.000)

Precision cannot be changed after the credit is created.

​

Credit Expiry

string

How long credits remain valid after issuance:

• 7 days, 30 days (default), 60 days, 90 days, Custom, or Never

Select Custom to specify a custom number of days (minimum 1).

4

Configure Subscription Settings (Optional)

These settings control credit behavior within recurring subscriptions:

​

Rollover

boolean

Allow unused credits to carry forward to the next billing cycle. When enabled, configure:

• Max Rollover Percentage (0–100%) - Limit how much carries over
• Rollover Timeframe - How long rolled-over credits remain valid (e.g., 1 Month)
• Max Rollover Count - Maximum consecutive rollovers before credits are forfeited

When Credits Run Out or Subscription Expires:

​

Allow Overage

boolean

Let customers continue using your service after their credit balance reaches zero. When enabled, configure:

• Overage Limit - Maximum credits customers can consume beyond their balance
• Price Per Unit - Cost per additional credit when overage is enabled (with currency selector)

​

Overage Behavior

string

required

Controls how overage is handled at the end of the billing cycle:

• Forgive overage at reset (default) - Usage beyond the credit limit is tracked but not billed. Balance resets each cycle.
• Bill overage at billing - Usage beyond the credit limit is charged on the next invoice, then the balance resets.
• Carry over deficit - Usage beyond the credit limit carries forward as a negative balance into the next cycle.
• Carry over deficit (auto-repay) - Deficit carries forward and is automatically repaid from new credits in the next cycle.

5

Create Credit

Click Create Credit to save. The credit is now available to attach to any product.

Your credit entitlement is ready. Attach it to products to start issuing credits to customers.

​

Attaching Credits to Products

​

Subscription Products

1

Create or Edit a Subscription Product

Go to Products → Create Product or edit an existing product. Select Subscription as the pricing type and configure your recurring price.

2

Open Entitlements Section

Expand the Entitlements section and click the Attach button next to Credits.

3

Select Credits to Attach

An Add Credits panel opens. You can select an existing credit from the dropdown or click Create new credit to define one on the spot.

You can attach up to 3 credits per product. Each credit can have its own configuration.

4

Configure Credit Settings

For each attached credit, configure:

​

Credits issued per billing cycle

number

required

The number of credits granted to the customer each billing period.

​

Low Balance Threshold

number

Notify when credits fall below this amount. Useful for alerting customers before they run out.

​

Credits During Free Trial

number

Set a different credit amount for trial periods. Enable Expire trial credits after trial ends to revoke unused trial credits when the trial converts to a paid subscription.

​

Allow Proration

boolean

Prorate remaining credits when a customer upgrades or downgrades their subscription plan.

​

Import Default Credit Settings

boolean

Use the default rollover, overage, and expiry settings from the credit entitlement. Turn this off to customize settings specifically for this product.

5

Review and Add

Review the attached credit showing name, amount, and expiration. Click Add to Subscription to confirm.

​

One-Time Payment Products

1

Create a One-Time Product

Create a product with Single Payment pricing type.

2

Attach Credits

Open the Entitlements section and attach credits. Configure the number of credits issued (total one-time grant) on purchase.

​

Usage-Based Billing Products

1

Create a Usage-Based Product

Select Usage Based Billing as the pricing type. Configure the base price and billing frequency.

2

Add a Meter

Click the + button in the Select meter section to add a meter. A subscription can have up to 3 meters.

3

Enable Credit Billing on the Meter

Toggle Bill usage in Credits to attach a credit to the meter. Select the credit entitlement from the dropdown.

​

Free Threshold

number

required

The number of units that are free before credit deduction begins.

​

Bill usage in Credits

boolean

When enabled, meter usage deducts from the customer’s credit balance instead of charging per-unit.

​

Meter units per credit

number

required

The number of usage units required to deduct 1 credit. For example, if set to 1000, then 1,000 API calls consume 1 credit.

4

Configure Credit Issuance

Set the number of credits issued and optionally customize the credit settings for this product.

5

Verify Attachment

Once configured, the meter shows the attached credit name, unit price, and free threshold.

​

Credit Settings

​

Rollover

​

Overage

​

Expiration

​

Usage Billing with Credits

​

How Meter-Based Credit Deduction Works

1. Your application sends usage events - Each event includes a customer ID, event name, and metadata
2. Meters aggregate events - Using Count, Sum, Max, Last, or Unique Count aggregation
3. Credits are deducted automatically - A background worker processes events every minute, converts meter units to credits using your configured rate, and deducts from the customer’s balance using FIFO ordering (oldest grants first)
4. Overage is tracked - If the credit balance reaches zero and overage is enabled, the system tracks overage usage for end-of-cycle billing

​

Meters Panel

​

Customer Experience

​

Checkout

​

Customer Portal

• Available Balance - Current credit balance displayed prominently
• Credit Tabs - Switch between different credit types (e.g., “OpenAI Credits”, “Usage Tokens”)
• Recent Transactions - Full history with date, transaction ID, type, amount, and running balance

​

Subscription Details

• Credit allocation per billing cycle (e.g., “1000 credits each cycle”)
• Remaining balance (e.g., “7500 credits remaining”)
• Renewal date for next credit issuance
• Usage History tab with meter-level breakdown showing units consumed, thresholds, unit prices, and total costs

​

Transaction Details

​

Managing Credits

​

Dashboard Views

​

Credit Entitlements List

​

Customer Credit Details

• Credit Selector - Switch between different credit entitlements
• Available Balance - Current balance in large, prominent display
• Apply Credit/Debit - Button to manually adjust the customer’s balance
• Recent Transactions - Full ledger with date, transaction ID, type, amount, and running balance

​

Manual Adjustments

​

Credit Ledger

​

Webhooks

​

API Management

​

Integration Example

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env['DODO_PAYMENTS_API_KEY'],
  environment: 'test_mode', // defaults to 'live_mode'
});

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

await client.usageEvents.ingest({
  events: [{
    event_id: `gen_${Date.now()}`,
    customer_id: 'cus_abc123',
    event_name: 'ai.generation',
    timestamp: new Date().toISOString(),
    metadata: { model: 'gpt-4', tokens: 1500 }
  }]
});

​

Real-World Examples

​

Best Practices

• Start simple: Begin with a single credit type and no rollover. Add complexity based on customer feedback and usage patterns.
• Set clear expectations: Display credit allocations, remaining balances, and overage pricing prominently in your product pages and customer portal.
• Use meaningful units: Name credits after what they represent (e.g., “API Calls”, “AI Tokens”) rather than generic terms. This helps customers understand value.
• Configure expiry thoughtfully: Short expiry windows (7 days) drive urgency but may frustrate customers. Longer windows (30–90 days) are more customer-friendly for most SaaS products.
• Monitor low balances: Set low balance thresholds to alert customers before they run out, reducing surprise overage charges.
• Test in test mode: Create credits, attach them to test products, and simulate the full purchase → usage → deduction → expiration cycle before going live.