Credit Based Billing

Dodo Payments Credit-Based Billing

Use this skill to build prepaid or included-credit billing for tokens, API calls, compute, storage, or currency-denominated value, with auditable grants and deductions.

When to use this skill

• Include a recurring credit allowance in a subscription.
• Sell one-time top-up packs or prepaid usage.
• Deduct credits from metered AI, API, or compute consumption.
• Grant promotional or support credits and record a reason.
• Configure expiry, rollover, low-balance alerts, or overage.
• Reconcile a customer's balance against an immutable ledger trail.

Choose the billing model

Credit-based and usage-based billing are complementary. Define and test meters with the usage-based-billing skill; this skill covers the credit side and the meter-to-credit link.

Core concepts

Credit entitlements and grants

A credit entitlement is the reusable definition of a credit unit and its lifecycle: name, unit, precision, expiry, rollover, and overage. A grant is an issuance of that credit to one customer. Grants can originate from:

• a subscription, reissued each billing cycle;
• a one-time product or add-on;
• a direct API ledger credit;
• rollover from an earlier grant.

Credits gate how much a customer can consume. The separate entitlements resource gates fulfillment such as feature access, files, or license delivery. Do not confuse these SDK namespaces:

client.creditEntitlements             credit definitions and balances
client.creditEntitlements.balances    customer credit balances and ledger
client.entitlements                   feature/file/license entitlements
client.entitlements.files             entitlement files
client.entitlements.grants            fulfillment grants

Use client.customers.listCreditEntitlements(customerID) for the customer-level credit-entitlement view. Do not substitute client.customers.listEntitlements(...), which reads the other entitlement system.

Custom-unit and fiat credits

Custom-unit precision is configurable from 0 through 10; the dashboard default is 2. Precision cannot be changed after creation, so choose it before issuing grants. Use 0 for indivisible units such as whole requests. Use decimal precision only when fractional credits are meaningful.

Fiat examples use currency minor units: 5,000 credits represents USD 50 in the documented OpenAI example. Do not infer a universal fiat precision rule beyond the documented minor-unit model. All monetary amounts are in the currency's smallest unit (for example, cents for USD).

A product can carry up to five credit entitlements. Each can have independent issuance and lifecycle settings.

Balance and ledger

The balance response includes balance, overage, last_transaction_at, identifiers, and timestamps. Treat credit amounts as decimal strings; do not pass them through binary floating-point arithmetic.

Every transaction has a ledger record with:

• balance_before and balance_after;
• overage_before and overage_after;
• amount and transaction type;
• source references and grant ID;
• description, metadata, and timestamp.

This ledger is the audit trail and provides transaction-level balance snapshots. There is no separately documented historical balance-snapshots endpoint.

Initialize the TypeScript SDK

Keep API keys server-side. Dodo Payments keys use dodo_test_... and dodo_live_... prefixes.

import DodoPayments from 'dodopayments';

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

The SDK defaults to live_mode when environment is omitted. Use test_mode explicitly during development.

Create and configure a credit entitlement

The confirmed TypeScript method is client.creditEntitlements.create(...).

import DodoPayments from 'dodopayments';

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

const tokenCredits = await client.creditEntitlements.create({
  name: 'AI Token Credits',
  description: 'Credits consumed by model token usage',
  unit: 'token credit',
  precision: 0,
  expires_after_days: 30,
  rollover_enabled: true,
  rollover_percentage: 25,
  rollover_timeframe_count: 1,
  rollover_timeframe_interval: 'Month',
  max_rollover_count: 2,
  overage_enabled: true,
  overage_behavior: 'invoice_at_billing',
  overage_limit: 100000,
  price_per_unit: '1',
  currency: 'USD',
});

console.log(tokenCredits.id);

price_per_unit is a decimal string in the configured currency; monetary values use the currency's smallest unit. In this example, '1' is one cent per overage credit for USD.

Confirmed create options

Configure rollover

Rollover carries eligible unused credits into a new grant. Configure:

1. rollover_enabled: true.
2. rollover_percentage as the carry-forward cap from 0 through 100.
3. Both rollover_timeframe_count and rollover_timeframe_interval; neither should be supplied alone.
4. max_rollover_count if credits may roll only a limited number of consecutive times.

Rollover is applied before expiry; only the remainder expires.

Configure expiry

The API represents expiry as nullable expires_after_days. The dashboard offers 7, 30, 60, 90, custom days, or never; its default is 30 days, and custom expiry has a one-day minimum. Use null for no API-configured expiry only where the current API form permits it.

Configure overage

When overage_enabled is true, price_per_unit is required; when a price is present, currency is required. Use overage_limit to cap allowed overage units.

When overage is disabled, Dodo stops deducting after the balance reaches zero. Meter processing is asynchronous, so this is not synchronous authorization for your application requests. Implement application-side enforcement when requests must be rejected immediately.

Attach credits to products and subscriptions

Credits are attached to products as credit entitlements in the product creation or edit flow. Do not use client.entitlements.grants to attach or issue credit balances.

Subscription product

In Products → Create Product or an existing product:

1. Choose subscription pricing.
2. Open Entitlements & Credits and attach an existing credit entitlement.
3. Set the credits issued each billing period.
4. Optionally set a low-balance notification amount, trial-credit amount, whether unused trial credits expire after trial, and credit proration for plan changes.
5. Keep the entitlement's default rollover, overage, and expiry rules or customize them for this product.

The customer receives a fresh grant each billing cycle.

One-time product or add-on

Attach the credit entitlement to a single-payment product or add-on and configure the one-time amount. The purchase issues one grant. This is the supported shape for prepaid packs, top-ups, and promotional bundles.

Usage-based product

Attach the credit entitlement to the same usage-based product as the meter. The confirmed meter attachment fields are:

Product attachment request shapes can evolve. Configure them in the dashboard or copy the current schema from the Create Product API; do not invent an entitlements, credits, or grants payload.

Start checkout for an attached product

Product purchase creates the customer grant; checkout does not accept an ad hoc credit amount.

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

console.log(session);

Use checkoutSessions.create, not the deprecated payments.create or subscriptions.create methods.

Discover a customer's credit entitlements

Use the customer resource when the application needs to discover all credit entitlements associated with a customer:

const customerCredits = await client.customers.listCreditEntitlements(
  'cus_TV52uJWWXt2yIoBBxpjaa',
);

console.log(customerCredits);

Use the balance resource below when the credit entitlement ID is already known and an exact balance is required.

Read a customer's balance

The confirmed method takes the customer ID first and the credit entitlement ID inside the options object:

const customerCreditBalance = await client.creditEntitlements.balances.retrieve(
  'cus_TV52uJWWXt2yIoBBxpjaa',
  { credit_entitlement_id: 'cde_ztxm5XJsKxWucRWA3rjdM' },
);

console.log({
  balance: customerCreditBalance.balance,
  overage: customerCreditBalance.overage,
  lastTransactionAt: customerCreditBalance.last_transaction_at,
});

balance and overage are decimal strings in the entitlement's credit unit. They are not currency amounts unless the entitlement itself represents fiat value.

Grant credits manually

Manual credits are appropriate for promotions, migrations, refunds implemented as credit, and support gestures. Use a stable idempotency key derived from the business operation so a retry cannot grant twice.

async function grantSupportCredits(
  customerId: string,
  creditEntitlementId: string,
  supportCaseId: string,
): Promise<string> {
  const entry = await client.creditEntitlements.balances.createLedgerEntry(
    customerId,
    {
      credit_entitlement_id: creditEntitlementId,
      amount: '500',
      entry_type: 'credit',
      expires_at: '2027-01-31T23:59:59Z',
      idempotency_key: `support-credit:${supportCaseId}`,
      reason: `Support gesture for case ${supportCaseId}`,
      metadata: { support_case_id: supportCaseId },
    },
  );

  return entry.id;
}

amount is a decimal string backed by NUMERIC(38,28); its integer part must be below 10^10. expires_at applies to credits. Keep the amount within the entitlement's configured precision.

If the same idempotency_key already exists, the API can return 409. Treat that as a signal to reconcile the original operation, not as permission to generate a new key and retry the grant.

Deduct credits manually

Use the same method with entry_type: 'debit'. Debits consume the earliest-expiring grants first and can return 400 when the balance is insufficient.

async function deductJobCredits(
  customerId: string,
  creditEntitlementId: string,
  jobId: string,
  amount: string,
): Promise<{ balanceAfter: string; overageAfter: string }> {
  const entry = await client.creditEntitlements.balances.createLedgerEntry(
    customerId,
    {
      credit_entitlement_id: creditEntitlementId,
      amount,
      entry_type: 'debit',
      idempotency_key: `job-debit:${jobId}`,
      reason: `Credit deduction for job ${jobId}`,
      metadata: { job_id: jobId },
    },
  );

  return {
    balanceAfter: entry.balance_after,
    overageAfter: entry.overage_after,
  };
}

Do not manually debit usage that is also connected to automatic meter-to-credit deduction; that charges the same consumption twice.

Read the ledger for an audit trail

The SDK returns an auto-paginating iterable:

for await (const entry of client.creditEntitlements.balances.listLedger(
  'cus_TV52uJWWXt2yIoBBxpjaa',
  { credit_entitlement_id: 'cde_ztxm5XJsKxWucRWA3rjdM' },
)) {
  console.log({
    id: entry.id,
    amount: entry.amount,
    balanceBefore: entry.balance_before,
    balanceAfter: entry.balance_after,
    overageBefore: entry.overage_before,
    overageAfter: entry.overage_after,
    createdAt: entry.created_at,
  });
}

Persist the Dodo ledger entry ID with internal order, support-case, or job IDs. Reconciliation should compare ledger entries and source references rather than overwrite history from a cached balance.