Credit-Based Billing

​

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

输入 Credit Name——这是 credit 的内部标识符。

3

Set General Settings

Configure the credit type and display properties:

​

Credit Type

string

必填

Choose Custom Unit or Fiat Credits.

• Custom Unit：定义您自己的指标（tokens、API 调用、compute hours）。需要设置 Unit Name（例如，“Platform tokens”）和 Precision。
• Fiat Credits：Credits 代表实际货币价值。需要选择 Unit Currency（USD、EUR、GBP、INR 等）。

​

Unit Name

string

仅适用于 Custom Unit credits。客户看到的 credit 标签（例如，“AI Tokens” 或 “API Calls”）。该标签会显示在结账页面和客户门户中。

​

Precision

number

Only for Custom Unit credits. Number of decimal places allowed, from 0 to 10:

• 0：整数（适合 API 调用等可计数项目）
• 1：一位小数（0.0）
• 2：两位小数（0.00）——默认值
• 3：三位小数（0.000）
• 最多 10：适用于高精度单位（例如，分数 tokens 或微量使用量）

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%）：限制可结转的额度
• Rollover Timeframe：结转 credits 保持有效的时长（例如，1 Month）
• Max Rollover Count：credits 被作废前允许连续结转的最大次数

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：客户可在余额之外使用的最大 credits 数量
• Price Per Unit：启用超额使用时每个额外 credit 的费用（带货币选择器）

​

Overage Behavior

string

必填

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

• Forgive overage at reset（默认）：记录超过 credit 限额的使用量，但不计费。余额在每个周期重置。
• Bill overage at billing：超过 credit 限额的使用量会在下一张发票中计费，随后余额重置。
• Carry over deficit：超过 credit 限额的使用量会以负余额形式结转到下一周期。
• Carry over deficit (auto-repay)：欠额结转到下一周期，并自动从新 credits 中偿还。

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 5 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

必填

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

​

Low Balance Threshold

number

当余额低于此百分比（0–100）时发送通知。在客户用尽余额之前提醒他们很有用。

​

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

点击 Select meter 部分中的 + 按钮以添加 meter。一个订阅最多可以有 50 个 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

仅适用于 meter 以货币计费的情况。当 meter 以 credits 计费时，每个单位都会从 credit 余额中扣除。

​

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

必填

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

​

过期

​

使用 Credits 的用量计费

​

基于 Meter 的 Credit 扣除方式

1. 您的应用程序发送使用事件：每个事件包含客户 ID、事件名称和 metadata
2. Meters 聚合事件：使用 Count、Sum、Max 或 Last 聚合方式
3. Credits 自动扣除：后台 worker 每分钟处理一次事件，使用您配置的费率将 meter 单位转换为 credits，并按照 FIFO 顺序（最早过期的 grants 优先）从客户余额中扣除
4. 跟踪超额使用量：如果 credit 余额达到零且启用了超额使用，系统会跟踪超额使用量，以便在周期结束时计费

​

Meters 面板

​

客户体验

​

结账

​

Customer Portal

• Available Balance：醒目显示当前 credit 余额
• Credit Tabs：在不同 credit 类型之间切换（例如，“OpenAI Credits” 或 “Usage Tokens”）
• Recent Transactions：完整历史记录，包括日期、交易 ID、类型、金额和实时余额

​

订阅详情

• 每个计费周期的 Credit allocation（例如，“每个周期 1000 credits”）
• Remaining balance（例如，“剩余 7500 credits”）
• 下一次发放 credits 的 Renewal date
• Usage History 标签页，其中包含 meter 级别的明细，包括已消耗单位、阈值、单位价格和总费用

​

交易详情

​

管理 Credits

​

仪表板视图

​

Credit 权益列表

​

客户 Credit 详情

• Credit Selector - 在不同 credit 权益之间切换
• Available Balance - 以醒目的大尺寸显示当前余额
• Apply Credit/Debit - 手动调整客户余额的按钮
• Recent Transactions - 完整 ledger，包括日期、交易 ID、类型、金额和实时余额

​

手动调整

​

Credit Ledger

​

Webhooks

​

API 管理

​

集成示例

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: 'pdt_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 }
  }]
});

​

实际应用示例

​

最佳实践

• 从简单开始：从单一 credit 类型且不启用 rollover 开始。根据客户反馈和使用模式逐步增加复杂性。
• 设定清晰预期：在产品页面和客户门户中醒目显示 credit 配额、剩余余额和超额使用价格。
• 使用有意义的单位：根据 credits 所代表的内容命名（例如，“API Calls” 或 “AI Tokens”），而不是使用通用术语。这有助于客户理解其价值。
• 谨慎配置过期时间：较短的过期窗口（7 天）可以带来紧迫感，但可能让客户感到沮丧。对于大多数 SaaS 产品，较长的窗口（30–90 天）对客户更加友好。
• 监控低余额：设置低余额阈值，在客户用尽 credits 前发出提醒，减少意外的超额费用。
• 在测试模式中测试：创建 credits，将其附加到测试产品，并在正式上线前模拟完整的购买 → 使用 → 扣除 → 过期周期。