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

Nhập Credit Name—đây là mã định danh nội bộ của credit.

3

Set General Settings

Configure the credit type and display properties:

​

Credit Type

string

bắt buộc

Choose Custom Unit or Fiat Credits.

• Custom Unit: Xác định chỉ số riêng của bạn (token, lượt gọi API, giờ điện toán). Yêu cầu Unit Name (ví dụ: “Platform tokens”) và thiết lập Precision.
• Fiat Credits: Credit đại diện cho giá trị tiền tệ thực. Yêu cầu chọn Unit Currency (USD, EUR, GBP, INR, v.v.).

​

Unit Name

string

Chỉ áp dụng cho credit Custom Unit. Đây là nhãn khách hàng nhìn thấy cho credit này (ví dụ: “AI Tokens” hoặc “API Calls”). Nhãn được hiển thị trong checkout và Customer Portal.

​

Precision

number

Chỉ áp dụng cho credits của Custom Unit. Số chữ số thập phân được phép, từ 0 đến 10:

• 0: Số nguyên (phù hợp nhất với các mục có thể đếm như lượt gọi API)
• 1: Một chữ số thập phân (0.0)
• 2: Hai chữ số thập phân (0.00)—mặc định
• 3: Ba chữ số thập phân (0.000)
• Tối đa 10: Dành cho các đơn vị yêu cầu độ chính xác cao (ví dụ: token phân số hoặc mức sử dụng rất nhỏ)

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%): Giới hạn lượng credit được chuyển sang kỳ tiếp theo
• Rollover Timeframe: Khoảng thời gian credit được chuyển tiếp còn hiệu lực (ví dụ: 1 Month)
• Max Rollover Count: Số lần chuyển tiếp liên tiếp tối đa trước khi credit bị mất

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: Số credit tối đa khách hàng có thể sử dụng vượt quá số dư
• Price Per Unit: Chi phí cho mỗi credit bổ sung khi bật overage (kèm bộ chọn tiền tệ)

​

Overage Behavior

string

bắt buộc

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

• Forgive overage at reset (mặc định): Mức sử dụng vượt quá giới hạn credit được ghi nhận nhưng không tính phí. Số dư được đặt lại sau mỗi chu kỳ.
• Bill overage at billing: Mức sử dụng vượt quá giới hạn credit được tính vào hóa đơn tiếp theo, sau đó số dư được đặt lại.
• Carry over deficit: Mức sử dụng vượt quá giới hạn credit được chuyển sang chu kỳ tiếp theo dưới dạng số dư âm.
• Carry over deficit (auto-repay): Phần thiếu được chuyển sang kỳ tiếp theo và tự động hoàn trả bằng credit mới trong chu kỳ đó.

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.

Bạn có thể gắn tối đa 5 tín dụng cho mỗi sản phẩm. Mỗi tín dụng có thể có cấu hình riêng.

4

Configure Credit Settings

For each attached credit, configure:

​

Credits issued per billing cycle

number

bắt buộc

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

​

Low Balance Threshold

number

Thông báo khi số dư giảm xuống dưới tỷ lệ phần trăm này (0–100). Hữu ích để cảnh báo khách hàng trước khi họ sử dụng hết.

​

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

Nhấp vào nút + trong phần Select meter để thêm meter. Một gói đăng ký có thể có tối đa 50 meter.

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

Chỉ áp dụng khi meter tính phí bằng tiền. Khi meter tính phí bằng credit, mỗi đơn vị sẽ được khấu trừ khỏi số dư 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

bắt buộc

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

​

Hết hạn

​

Billing dựa trên mức sử dụng với Credit

​

Cách khấu trừ Credit dựa trên Meter hoạt động

1. Ứng dụng của bạn gửi các sự kiện mức sử dụng: Mỗi sự kiện bao gồm customer ID, event name và metadata
2. Meter tổng hợp các sự kiện: Sử dụng phép tổng hợp Count, Sum, Max hoặc Last
3. Credit được khấu trừ tự động: Một background worker xử lý sự kiện mỗi phút, chuyển đổi đơn vị meter thành credit theo rate đã cấu hình và khấu trừ khỏi số dư của khách hàng theo thứ tự FIFO (grant hết hạn sớm nhất trước)
4. Overage được theo dõi: Nếu số dư credit bằng 0 và overage được bật, hệ thống theo dõi mức sử dụng overage để tính phí cuối chu kỳ

​

Bảng Meters

​

Trải nghiệm khách hàng

​

Checkout

​

Customer Portal

• Available Balance: Số dư credit hiện tại được hiển thị nổi bật
• Credit Tabs: Chuyển đổi giữa các loại credit khác nhau (ví dụ: “OpenAI Credits” hoặc “Usage Tokens”)
• Recent Transactions: Lịch sử đầy đủ gồm ngày, transaction ID, loại, số lượng và số dư lũy kế

​

Chi tiết gói đăng ký

• Credit allocation cho mỗi chu kỳ thanh toán (ví dụ: “1000 credits each cycle”)
• Remaining balance (ví dụ: “7500 credits remaining”)
• Renewal date cho lần cấp credit tiếp theo
• Tab Usage History với phân tích theo từng meter, hiển thị đơn vị đã tiêu thụ, ngưỡng, giá mỗi đơn vị và tổng chi phí

​

Chi tiết giao dịch

​

Quản lý Credit

​

Chế độ xem trên Dashboard

​

Danh sách quyền lợi Credit

​

Chi tiết Credit của khách hàng

• Credit Selector - Chuyển đổi giữa các quyền lợi credit khác nhau
• Available Balance - Số dư hiện tại được hiển thị lớn và nổi bật
• Apply Credit/Debit - Nút điều chỉnh thủ công số dư của khách hàng
• Recent Transactions - Ledger đầy đủ gồm ngày, transaction ID, loại, số lượng và số dư lũy kế

​

Điều chỉnh thủ công

​

Credit Ledger

​

Webhooks

​

Quản lý API

​

Ví dụ tích hợp

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

​

Ví dụ thực tế

​

Phương pháp hay nhất

• Bắt đầu đơn giản: Bắt đầu với một loại credit duy nhất và không rollover. Thêm độ phức tạp dựa trên phản hồi của khách hàng và mẫu sử dụng.
• Đặt kỳ vọng rõ ràng: Hiển thị nổi bật hạn mức credit, số dư còn lại và giá overage trên các trang sản phẩm và Customer Portal.
• Sử dụng đơn vị có ý nghĩa: Đặt tên credit theo ý nghĩa của chúng (ví dụ: “API Calls” hoặc “AI Tokens”) thay vì các thuật ngữ chung chung. Điều này giúp khách hàng hiểu giá trị.
• Cấu hình thời hạn một cách thận trọng: Thời hạn ngắn (7 ngày) tạo cảm giác cấp bách nhưng có thể khiến khách hàng khó chịu. Thời hạn dài hơn (30–90 ngày) thân thiện với khách hàng hơn đối với hầu hết sản phẩm SaaS.
• Theo dõi số dư thấp: Đặt ngưỡng số dư thấp để cảnh báo khách hàng trước khi credit hết, giúp giảm các khoản phí overage bất ngờ.
• Kiểm thử trong test mode: Tạo credit, đính kèm vào sản phẩm thử nghiệm và mô phỏng toàn bộ chu kỳ mua → sử dụng → khấu trừ → hết hạn trước khi triển khai chính thức.