Credit-Based Billing

Issue, manage, and track credit entitlements across subscriptions, one-time products, and usage-based billing with rollover, overage, and expiration controls.

Credit-Based Billing lets you 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. Credits work across all product types: subscriptions, one-time purchases, and usage-based billing.

​

What is Credit-Based Billing?

Credit-Based Billing gives you a flexible system to issue credit entitlements to customers as part of your products. Instead of charging per-use or limiting access through feature flags, you allocate a pool of credits that customers draw from as they use your service.

Credits are ideal for:

• 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

Credits appear as entitlements on your products and show in checkout, customer portal, and subscription details.

​

Core Concepts

​

Credit Types

When creating a credit, you choose between two types:

Custom Unit

Define credits in your own unit - tokens, API calls, compute hours, or any metric meaningful to your product. Custom units use the precision you set (0 to 3 decimal places).

Best for: API calls, AI tokens, compute hours, storage units, messages

Fiat Credits

Credits represent actual currency value (e.g., USD, EUR). Customers receive a monetary credit balance that depletes as they use your service at your defined pricing.

Best for: Prepaid balances, promotional credits, service compensation

​

Credit Lifecycle

Credits follow a clear lifecycle from issuance through consumption:

1. Credits Issued

   Credits are granted when a customer purchases a product (subscription or one-time) with attached credit entitlements. For subscriptions, credits are re-issued each billing cycle.

2. Credits Consumed

   As customers use your service, credits are deducted. For usage-based products, meters automatically deduct credits based on real-time events. You can also deduct credits manually via the dashboard or API.

3. Credits Expire or Roll Over

   At the end of the billing cycle (or after the configured expiry period), unused credits either expire or roll over to the next period based on your settings.

4. Overage Handling

   If credits run out mid-cycle, you can allow overage (continued usage beyond the balance) and choose how overage is handled - forgive it, bill it, or carry the deficit forward.

​

Grant Sources

Credits can be granted from multiple sources:

Source	Description
Subscription	Credits issued with subscription purchase, re-issued each billing cycle
One-Time	Credits issued with a one-time payment product
API	Credits granted manually via API or dashboard
Rollover	Credits carried over from a previous billing cycle

---

​

Creating Credits

Create credit entitlements in the Products → Credits section of your dashboard. Each credit defines the unit, precision, expiry rules, and lifecycle behavior.

The Credits tab under Products shows all your credit entitlements.

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.

   

   The credit creation form with all configuration sections.

3. Set General Settings

   Configure the credit type and display properties:

   Credit Type · string · obrigatório

   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 · obrigatório

   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.

Start with simple settings - no rollover, no overage - and add complexity as you learn how customers use credits. Most settings can be updated at any time without affecting existing grants. Note that precision cannot be changed after a credit is created.

---

​

Attaching Credits to Products

Créditos são anexados aos produtos como direitos no fluxo de criação ou edição do produto. Você pode anexar até 5 créditos por produto. Créditos funcionam com todos os três tipos de precificação.

​

Subscription Products

For subscriptions, credits are issued per billing cycle and can be configured with proration, trial credits, and cycle-specific settings.

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.

   

   The Entitlements section in the product form with Credits, License Key, and Digital Product Delivery options.

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.

   

   The Add Credits panel lets you select existing credits or create new ones.

   Você pode anexar até 5 créditos por produto. Cada crédito pode ter sua própria configuração.

4. Configure Credit Settings

   For each attached credit, configure:

   Credits issued per billing cycle · number · obrigatório

   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.

   

   Credit configuration showing per-cycle amount, trial credits, proration, and custom settings.

5. Review and Add

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

   

   Review attached credits before adding them to the subscription.

​

One-Time Payment Products

For one-time payments, credits are issued once at the time of purchase.

1. Create a One-Time Product

   Create a product with Single Payment pricing type.

   

   Single Payment pricing selected for a one-time credit product.

2. Attach Credits

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

One-time credit products are ideal for credit top-up packs, promotional bundles, or prepaid credit purchases.

​

Usage-Based Billing Products

For usage-based products, credits are linked to meters and automatically deducted based on real-time consumption events.

1. Create a Usage-Based Product

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

   

   Usage Based Billing pricing type with meter configuration.

2. Add a Meter

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

   

   The Select Meter panel with meter configuration and credit toggle.

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 · obrigatório

   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 · obrigatório

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

   

   Credit attached to a meter with per-unit conversion rate.

4. Configure Credit Issuance

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

   

   Configure how many credits to issue and whether to use default settings.

5. Verify Attachment

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

   

   Meter with credit attached showing price, threshold, and credit name.

When credits are linked to meters, the system automatically deducts credits based on ingested usage events. A background worker processes events every minute, aggregates them according to the meter’s configuration, and applies FIFO (first-in, first-out) deduction from the customer’s oldest non-expired grants.

---

​

Credit Settings

​

Rollover

Rollover lets unused credits carry forward to the next billing cycle instead of expiring.

Setting	Description
Rollover Enabled	Toggle to allow unused credits to carry forward
Max Rollover Percentage	Limit how much carries over (0–100%). At 50%, only half of unused credits roll over
Rollover Timeframe	How long rolled-over credits remain valid (day, week, month, year)
Max Rollover Count	Maximum number of times credits can be consecutively rolled over. After this limit, remaining credits are forfeited

Example: A customer has 200 unused credits at cycle end. With 75% rollover, 150 credits carry forward and 50 are forfeited.

​

Overage

Overage controls what happens when a customer’s credit balance reaches zero mid-cycle.

Setting	Description
Allow Overage	Toggle to let customers continue using the service beyond their credit balance
Overage Limit	Maximum credits customers can consume beyond their balance
Price Per Unit	Cost per additional credit consumed as overage (with currency)
Overage Behavior	Controls what happens to overage at the end of the billing cycle (see below)

Overage Behavior options:

Behavior	Description
Forgive overage at reset	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	Overage 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

When overage is disabled, customers cannot use the service once their credit balance reaches zero. Choose an overage behavior that matches your billing model - Forgive at reset is the default and simplest option.

​

Expiration

Setting	Description
Credit Expiry	Duration after issuance before credits expire (7, 30, 60, 90, custom days, or never)
Trial Credits Expire After Trial	Whether trial-specific credits expire when the trial period ends

Expired credits create a CreditExpired ledger entry. If rollover is enabled, the rollover percentage is applied before expiration, and only the remainder expires.

---

​

Usage Billing with Credits

When credits are linked to usage meters, the system creates a powerful consumption-based billing model. Customers receive a credit allocation, and usage events automatically deduct from their balance.

The Usage Billing dashboard shows meter events with units consumed, credits consumed, and customer details.

​

How Meter-Based Credit Deduction Works

1. Seu aplicativo envia eventos de uso - Cada evento inclui um ID de cliente, nome de evento e metadados
2. Medições agregam eventos - Usando Contagem, Soma, Máximo ou Último
3. Créditos são deduzidos automaticamente - Um trabalhador em segundo plano processa eventos a cada minuto, converte unidades de medição em créditos usando sua taxa configurada e deduz do saldo do cliente usando FIFO (primeiro a entrar, primeiro a sair)
4. Excedente é monitorado - Se o saldo de crédito chegar a zero e o excedente estiver habilitado, o sistema rastreia o uso excedente para faturamento no final do ciclo

​

Meters Panel

The Usage Billing dashboard includes a Meters panel listing all defined meters with their aggregation type:

Agregação	Descrição	Exemplo
Contagem	Número total de eventos	Chamadas de API
Soma	Soma de um campo de valor	Total de bytes transferidos
Máximo	Maior valor registrado	Picos de usuários simultâneos
Último	Valor mais recente	Armazenamento atual usado

---

​

Customer Experience

​

Checkout

When a customer purchases a product with attached credits, the checkout page displays the included credits as part of the product offering.

Checkout shows included credits with the product, making the value proposition clear.

Credits appear in an Includes section below the product description, showing the credit amount and type (e.g., “$1000 API calls”).

​

Customer Portal

Customers can view and manage their credit balances in the Customer Portal under the Credits section.

The Customer Portal shows available balance and full transaction history.

The portal displays:

• 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

Transaction types shown to customers include:

Type	Description	Amount
Credits with Subscription	Credits issued with subscription purchase/renewal	Green (+)
One-Time Credits	Credits from one-time purchases or manual grants	Green (+)
Usage Deduction	Credits consumed through service usage	Red (-)
Overage	Usage beyond credit balance	Red (-)

​

Subscription Details

The subscription detail page shows credit entitlements alongside other plan information.

Subscription details show credit allocation, remaining balance, and renewal date.

Key information displayed:

• 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

Payment transaction pages include an Entitlements section showing all entitlements delivered with the payment, including credits.

Transaction details show credits alongside other entitlements like license keys and digital downloads.

---

​

Managing Credits

​

Dashboard Views

​

Credit Entitlements List

View all your credit entitlements in Products → Credits. The table shows credit name, expiry settings, and provides quick actions for editing or archiving.

Credits listing with total count, creation button, and management actions.

​

Customer Credit Details

View a specific customer’s credit balances and transaction history from Customers → [Customer Name] → Credits.

Customer detail page showing credit balance and full transaction ledger.

The customer credit view includes:

• 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

You can manually credit or debit a customer’s balance directly from the dashboard:

1. Navigate to Customer

   Go to Customers and select the customer.

2. Open Credits Tab

   Click the Credits tab and select the appropriate credit entitlement from the wallet selector.

3. Apply Credit or Debit

   Click Apply Credit/Debit to open the adjustment interface.

   Transaction Type · string · obrigatório

   Select Credit to add credits or Debit to remove credits from the customer’s balance.

   Amount · number · obrigatório

   The number of credits to add or remove.

   Reason · string

   Optional explanation for the adjustment (e.g., “Service compensation”, “Promotional bonus”).

4. Confirm

   Review and apply the adjustment. The change is reflected immediately in the customer’s balance and recorded in the credit ledger.

   Manual adjustments create a ManualAdjustment ledger entry with full audit trail.

​

Credit Ledger

Every credit operation is recorded in the credit ledger, providing a complete 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 rollover 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 the balance before and after the transaction, overage before and after, a description, and reference to the source (payment, subscription, etc.).

---

​

Webhooks

Credit-Based Billing fires webhook events for every credit lifecycle change. Use these to keep your application in sync with credit balances, trigger notifications, or build custom billing workflows.

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

Todos os eventos do razão (credit.added até credit.manual_adjustment) incluem a carga completa CreditLedgerEntry com saldo antes/depois, excesso antes/depois, referência de origem e o metadata da assinatura ou pagamento da fonte da concessão (vazio para concessões criadas diretamente via API). O evento credit.balance_low inclui a configuração de limite e o saldo atual.

Credit Webhook Payloads

View full payload schemas, field descriptions, and integration examples for all credit webhook events.

---

​

API Management

Create Credit Entitlements

Use the API to create credit entitlements programmatically with full control over rollover, overage, and expiration settings.

Create Credit Entitlement

Create a new credit entitlement with rollover, overage, and expiry configuration.

List Credit Entitlements

Retrieve all credit entitlements for your business.

Manage Credit Entitlements

Retrieve, update, or delete credit entitlements. Deleted entitlements can be restored.

Get Credit Entitlement

Retrieve a specific credit entitlement by ID.

Update Credit Entitlement

Update rollover, overage, expiry, or other settings.

Delete Credit Entitlement

Soft-delete a credit entitlement.

Undelete Credit Entitlement

Restore a previously deleted credit entitlement.

Grant and Adjust Credits

Grant credits directly to a customer’s balance without requiring a purchase, or create manual debit entries for billing adjustments.

Create Ledger Entry

Credit or debit a customer’s balance with full audit trail and idempotency support.

Query Balances and Ledger

Retrieve a customer’s current credit balance, grant history, and full ledger of transactions for any credit entitlement.

List Balances

List all customer balances for a credit entitlement.

Get Customer Balance

Get a specific customer’s balance.

List Customer Grants

View all credit grants for a customer.

List Customer Ledger

Full transaction history for a customer.

​

Integration Example

Initialize the Dodo Payments client:

import DodoPayments from 'dodopayments';

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

Attach credits to a subscription product during checkout:

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

Send usage events that deduct credits automatically:

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

AI SaaS Platform

Pricing Structure:

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

Configuration:

• Credit Type: Custom Unit (“AI Tokens”)
• Precision: 0 (whole tokens)
• Rollover: 25% max, 1-month timeframe
• Overage: Enabled, bill overage at billing
• Meter: ai.generation with Sum aggregation on tokens field

API Gateway

Pricing Structure:

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

Configuration:

• Credit Type: Custom Unit (“API Calls”)
• Precision: 0 (whole calls)
• Rollover: Disabled
• Overage: Developer+ plans allow overage (forgive at reset), Free plan disables overage
• Meter: api.request with Count aggregation

Cloud Storage Service

Pricing Structure:

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

Configuration:

• Credit Type: Custom Unit (“GB-hours”)
• Precision: 2 (two decimal places)
• Rollover: 50% max, carries over once
• Overage: Enabled with 200% limit
• Meter: storage.usage with Sum aggregation

---

​

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.

Credit-Based Billing works seamlessly with all other Dodo Payments features - subscriptions with trials, plan changes with proration, and the customer portal. Start with a basic setup and expand as your pricing model evolves.