> ## 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.
# 基于信用的计费
> 通过回滚、超额和过期控制来发行、管理和跟踪跨订阅、一次性产品和基于使用的计费的信用额度。
基于信用的计费允许您向客户授予信用余额——API 调用、令牌、计算单元或任何自定义指标——并在他们使用您的服务时从该余额中扣除。信用适用于所有产品类型：订阅、一次性购买和基于使用的计费。
## 什么是基于信用的计费？
基于信用的计费为您提供了一种灵活的系统，以信用权利作为产品的一部分授予客户。与其按使用量收费或通过功能标志限制访问，不如分配一定数量的信用，客户在使用您的服务时会从中扣除。
信用非常适合：
* **AI 和 LLM 平台**：根据计划级别授予令牌或生成信用
* **API 服务**：分配 API 调用信用并设置超额定价
* **基础设施平台**：发行计算时间或存储信用
* **通信服务**：为每个订阅提供信息或分钟数信用
* **具有消费层的 SaaS**：将包含的使用量捆绑到信用池中
## 核心概念
### 信用类型
创建信用时，您可以选择两种类型：
定义您自己的单位中的信用——令牌、API 调用、计算时间或对您的产品有意义的任何指标。自定义单位使用您设置的精度（0 到 10 小数位）。
**最佳用途**：API 调用、AI 令牌、计算时间、存储单位、消息
信用代表实际货币价值（例如，美金，欧元）。客户会收到一个货币信用余额，在他们使用您的服务时按您定义的价格扣除。
**最佳用途**：预付余额、促销信用、服务补偿
### 信用生命周期
信用从发行到消费遵循明确的生命周期：
当客户购买附加信用权利的产品（订阅或一次性）时，就会授予信用。对于订阅，信用在每个计费周期重新发放。
随着客户使用您的服务，信用会被扣除。对于使用基产品，计量器会根据实时事件自动扣除信用。您也可以通过仪表板或 API 手动扣除信用。
在计费周期结束（或配置的过期期限后），未使用的信用根据您的设置将过期或转入下一个周期。
如果信用在周期中途用完，您可以允许超额（余额之外的持续使用）并选择如何处理超额 - 原谅、不计费或推迟不足额。
### 授予来源
信用可以从多个来源授予：
| 来源 | 描述 |
| ------- | --------------------- |
| **订阅** | 随订阅购买发行的信用，每个计费周期重新发行 |
| **一次性** | 随一次性支付产品发行的信用 |
| **API** | 通过 API 或仪表板手动授予信用 |
| **转移** | 从上一个计费周期转入的信用 |
***
## 创建信用
在仪表板的 **产品 → 信用** 部分创建信用权利。每个信用定义单位、精度、过期规则和生命周期行为。
进入仪表板的 **产品** 并选择 **信用** 标签。点击 **创建信用** 以开始。
输入 **信用名称** - 这是信用的内部标识符。
配置信用类型和显示属性：
选择 **自定义单位** 或 **法定货币信用**。
* **自定义单位** - 定义您自己的指标（令牌、API 调用、计算时间）。需要 **单位名称**（例如，“平台令牌”）和 **精度** 设置。
* **法定货币信用** - 信用代表实际货币价值。需要 **单位货币** 选择（美金，欧元，英镑，INR，等等）。
仅适用于自定义单位信用。客户看到的信用标签（例如，“AI 令牌”，“API 调用”）。在结帐和客户门户中显示。
仅适用于自定义单位信用。允许的小数位数，从 `0` 到 `10`：
* `0` - 整数（适合可计数项，如 API 调用）
* `1` - 一位小数 (0.0)
* `2` - 两位小数 (0.00) - **默认**
* `3` - 三位小数 (0.000)
* 最多为 `10` - 高精度单位（例如，分数令牌或微用量）
创建信用后不能更改精度。
信用发放后有效的时间长度：
* **7天**, **30天** (默认), **60天**, **90天**, **自定义**, 或 **从不**
选择 **自定义** 可以指定自定义天数（最少 1 天）。
这些设置控制定期订阅中的信用行为：
允许未使用的信用携带到下一个计费周期。启用后，配置：
* **最大转移百分比**（0%-100%）- 限制可携带多少
* **转移时间范围** - 转移信用的有效时长（例如，1个月）
* **最大转移次数** - 信用被没收之前的最大连续转移次数
**当信用用完或订阅过期时：**
让客户在信用余额为零后继续使用您的服务。启用时，配置：
* **超额限制** - 客户可以使用的超余额最大信用
* **单价** - 启用超额时每额外信用的成本（附带币种选择）
控制计费周期结束时如何处理超额：
* **重置时原谅超额**（默认）- 超出信用限额的使用会被跟踪但不计费。每个周期余额重置。
* **账单时计费超额** - 超出信用限额的使用在下一个发票上计费，然后余额重置。
* **带过不足额** - 超出信用限额的使用会作为负余额带入下一个周期。
* **带过不足额（自动还款）** - 不足额带入并在下一个周期自动从新信用中偿还。
点击 **创建信用** 保存。该信用现在可以附加到任何产品。
您的信用权利已准备好。将其附加到产品以开始向客户发放信用。
从简单设置开始 - 无转移，无超额 - 并在了解客户如何使用信用后增加复杂性。大多数设置可以在任何时候更新而不影响现有的授予。请注意，创建信用后**精度无法更改**。
***
## 向产品附加信用
信用作为 **权利** 附加到产品的创建或编辑流程中。您可以为每个产品附加最多 **5 种信用**。信用适用于所有三种定价类型。
### 订阅产品
对于订阅，信用按 **计费周期** 发放，并可以配置按比例分配、试用信用和周期特定设置。
前往 **产品 → 创建产品** 或编辑现有产品。选择 **订阅** 作为定价类型并配置经常性价格。
展开 **权利** 部分，点击 **信用** 旁边的 **附加** 按钮。
会打开一个 **添加信用** 面板。您可以从下拉列表中选择现有信用，或点击 **创建新信用** 即时定义一个。
您可以为每个产品附加最多 5 种信用。每种信用可以有自己的配置。
为每个附加的信用配置：
在每个计费周期内授予客户的信用数量。
当信用低于此数量时通知。这有助于在客户用完之前提醒他们。
为试用期设置不同的信用金额。启用 **试用结束后试用信用过期** 以在试用转为付费订阅时撤销未用的试用信用。
在客户升级或降级订阅计划时按比例分配剩余信用。
使用信用权利中的默认转移、超额和到期设置。关闭此选项可单独为此产品自定义设置。
查看附加信用，显示名称、金额和到期。点击 **添加到订阅** 以确认。
### 一次性付款产品
对于一次性付款，信用在购买时 **一次性** 发放。
创建具有 **单次付款** 定价类型的产品。
打开 **权利** 部分并附加信用。在购买时配置 **发行信用数量**（总一次性发放）。
一次性信用产品非常适合信用充值包、促销捆绑包或预付信用购买。
### 基于使用的计费产品
对于基于使用的产品，信用 **链接到计量器** 并根据实时消费事件自动扣除。
选择 **基于使用的计费** 作为定价类型。配置基础价格和计费频率。
点击 **选择计量器** 部分中的 **+** 按钮添加计量器。一个订阅最多可以有 **3 个计量器**。
切换 **以信用计费** 以附加信用到计量器。从下拉菜单中选择信用权利。
在开始扣除信用之前免费使用的单位数。
启用后，计量器使用会从客户的信用余额中扣除而不是按单元收费。
所需的使用单位数以扣除 1 个信用。例如，设置为 `1000`，则 1,000 次 API 调用消耗 1 个信用。
设置发行的信用数量，并可自定义此产品的信用设置。
配置完毕后，计量器显示附加的信用名称、单价和免费阈值。
当信用与计量器连接时，系统会根据已摄取的使用事件自动扣除信用。后台工作程序每分钟处理事件，依据计量器配置进行汇总，并应用 FIFO（先进先出）扣除客户最旧的未过期授予。
***
## 信用设置
### 转移
转移允许未使用的信用带入下一个计费周期而不是过期。
| 设置 | 描述 |
| ----------- | ------------------------------------- |
| **启用转移** | 切换以允许未使用的信用携带 |
| **最大转移百分比** | 限制携带多少（0-100%）。在 50% 情况下，只有一半的未使用信用转移 |
| **转移时间范围** | 转移信用的有效时长（天、周、月、年） |
| **最大转移次数** | 信用可连续转移的最大次数。超过此限制后，剩余信用被没收 |
**示例**：客户在周期结束时有 200 个未使用的信用。在 75% 转移下，150 个信用会携带，50 个会被没收。
### 超额
超额控制当客户的信用余额在周期中达到零时会发生什么。
| 设置 | 描述 |
| -------- | ---------------------- |
| **允许超额** | 切换让客户在信用余额耗尽后继续使用服务 |
| **超额限制** | 客户可以使用的最大超余额信用 |
| **单价** | 作为超额消费的每个额外信用的成本（附带币种） |
| **超额行为** | 控制计费周期结束时对超额的处理（见下文） |
**超额行为选项：**
| 行为 | 描述 |
| --------------------------------------------------------------- | -------------------------- |
| **重置时原谅超额** | 超出信用限额的使用会被跟踪但不计费。每个周期余额重置 |
| **账单时计费超额** | 超出信用限额的使用在下一个发票上计费，然后余额重置 |
| **带过不足额** | 超额作为负余额带入下一个周期 |
| **带过不足额（自动还款）** | 不足额带入并在下一个周期自动从新信用中偿还 |
| 当超额被禁用时，客户在信用余额为零后无法使用服务。选择符合您计费模型的超额行为 - **重置时原谅** 是默认和最简单的选项。 | |
### 到期
| 设置 | 描述 |
| --------------- | ----------------------------------------- |
| **信用到期** | 发行后信用到期的时间（7 天、30 天、60 天、90 天、自定义天数或永不过期） |
| **试用结束后试用信用过期** | 试用期结束时试用特定信用是否过期 |
过期信用会创建一个 `CreditExpired` 账本条目。如果启用了转移，在到期之前应用转移百分比，只有剩余部分会过期。
***
## 使用信用的计费
当信用与使用计量器连接时，系统会创建一个强大的基于消费的计费模型。客户会获得一个信用分配，使用事件会自动从他们的余额中扣除。
### 基于计量的信用扣除如何工作
1. **您的应用程序发送使用事件** - 每个事件包括客户 ID、事件名称和元数据
2. **计量器聚合事件** - 使用计数、求和、最大值或最后一个值进行聚合
3. **信用自动扣除** - 一个后台工作程序每分钟处理事件，使用您配置的费率将计量单位转换为信用，并使用 FIFO 顺序（最老授予优先）从客户的余额中扣除
4. **超额被跟踪** - 如果信用余额达到零并且启用了超额，系统会跟踪超额使用以便在周期结束时计费
### 计量器面板
使用计费仪表板包含一个 **计量器** 面板，其中列出了所有定义的计量器及其聚合类型：
| 聚合 | 描述 | 示例 |
| --------- | ------- | ------- |
| **计数** | 事件总数 | API 调用 |
| **求和** | 数值字段的总和 | 总字节传输 |
| **最大值** | 记录的最高值 | 最高并发用户数 |
| **最后一个值** | 最近的值 | 当前使用的存储 |
***
## 客户体验
### 结帐
当客户购买一个附带信用的产品时，结帐页面会显示包含的信用作为产品提供的一部分。
信用会显示在产品描述下方的一个 **包含** 部分中，显示信用金额和类型（例如，“\$1000 API 调用”）。
### 客户门户
客户可以在客户门户的 **信用** 部分查看和管理他们的信用余额。
门户显示：
* **可用余额** - 以显著展示当前信用余额
* **信用标签** - 在不同信用类型之间切换（例如，“OpenAI 信用”，“使用令牌”）
* **最近交易** - 包括日期、交易 ID、类型、金额和运行余额的完整历史记录
向客户显示的交易类型包括：
| 类型 | 描述 | 金额 |
| ---------- | --------------- | ------ |
| **带订阅的信用** | 随订阅购买/续订发行的信用 | 绿色 (+) |
| **一次性信用** | 来自一次性采购或手动授予的信用 | 绿色 (+) |
| **使用扣除** | 通过服务使用消耗的信用 | 红色 (-) |
| **超额** | 超出信用余额的使用 | 红色 (-) |
### 订阅详情
订阅详情页面显示信用权利以及其他计划信息。
显示的关键信息：
* **每个计费周期的信用分配**（例如，“每个周期 1000 信用”）
* **剩余余额**（例如，“剩余 7500 信用”）
* **下次信用发放的续订日期**
* **使用历史** 标签，显示计量器级别的消耗单位、阈值、单位价格和总成本
### 交易详情
支付交易页面包含一个 **权利** 部分，显示所有随付款交付的权利，包括信用。
***
## 管理信用
### 仪表板视图
#### 信用权利列表
在 **产品 → 信用** 中查看您所有的信用权利。表格显示信用名称、到期设置，并提供编辑或存档的快速操作。
#### 客户信用详情
从 **客户 → \[客户名称] → 信用** 查看特定客户的信用余额和交易历史。
客户信用视图包括：
* **信用选择器** - 在不同信用权利之间切换
* **可用余额** - 以大而显著的显示当前余额
* **应用信用/借方** - 按钮用于手动调整客户的余额
* **最近交易** - 包括日期、交易ID、类型、金额和运行余额的完整账本
### 手动调整
您可以通过仪表板直接手动增加或减少客户的余额：
前往 **客户** 并选择客户。
点击 **信贷** 标签并从钱包选择器中选择适当的信用权利。
点击 **应用信用/借方** 打开调整界面。
选择 **信用** 以增加信用或 **借方** 以从客户的余额中扣除信用。
要增加或删除的信用数量。
调整的可选解释（例如，“服务补偿”，“促销奖励”）。
检查并应用调整。更改立即反映在客户的余额中，并记录在信贷账本中。
手动调整会创建一个 `ManualAdjustment` 账本条目并提供完整的审计跟踪。
### 信用账本
每个信用操作都记录在信用账本中，提供完整的审计跟踪：
| 交易类型 | 描述 |
| -------- | ------------------ |
| **增加信用** | 授予的信用（订阅、一次性或 API） |
| **扣除信用** | 通过使用或手动借记而消耗的信用 |
| **信用过期** | 未使用的信用过期而未转移 |
| **信用转移** | 将信用带入下一个周期 |
| **转移没收** | 在达到最大转移次数后没收的转移信用 |
| **超额计费** | 启用了超额的信用余额以上的使用 |
| **自动补充** | 余额较低时自动补充信用 |
| **手动调整** | 商家手动应用的信用或借记 |
| **退款** | 信用退款 |
每个账本条目记录交易前后的余额、超额前后、描述和来源引用（付款、订阅等）。
***
## Webhooks
基于信用的计费会在每次信用生命周期更改时触发 Webhook 事件。使用这些来保持应用程序与信用余额同步，触发通知，或构建自定义计费工作流。
| 事件 | 描述 |
| --------------------------- | --------------- |
| `credit.added` | 授予给客户的信用 |
| `credit.deducted` | 通过使用或手动借记消耗的信用 |
| `credit.expired` | 未使用的信用过期 |
| `credit.rolled_over` | 将信用带入新的授予 |
| `credit.rollover_forfeited` | 在达到最大转移次数时没收的信用 |
| `credit.overage_charged` | 应用超额费用 |
| `credit.manual_adjustment` | 进行的手动信用/借记调整 |
| `credit.balance_low` | 余额降到配置的阈值以下 |
所有账本事件（`credit.added` 到 `credit.manual_adjustment`）包括完整的 `CreditLedgerEntry` 有效负载，涵盖交易前后余额，超额前后，来源引用，以及授予来源订阅或付款的 `metadata` （API直接创建的授予为空）。`credit.balance_low` 事件包括阈值配置和当前余额。
查看所有信用 Webhook 事件的完整有效负载架构、字段说明和集成示例。
***
## API 管理
使用 API 程序化创建信用权利，具备全面控制的转移、超额和到期设置。
创建具有转移、超额和到期配置的新信用权利。
检索业务下的所有信用权利。
检索、更新或删除信用权利。已删除的权利可以恢复。
按 ID 检索特定信用权利。
更新转移、超额、到期或其他设置。
软删除一个信用权利。
恢复之前删除的信用权利。
直接向客户的余额授予信用而无需购买，或创建用于计费调整的手动借记条目。
以完整的审计跟踪和幂等性支持信用或借记客户的余额。
检索客户当前的信用余额、授予历史和任何信用权利的完整交易记录。
列出信用权利的所有客户余额。
获取特定客户的余额。
查看客户的所有信用授予。
客户的完整交易历史。
### 集成示例
初始化 Dodo Payments 客户端：
```typescript theme={null}
import DodoPayments from 'dodopayments';
const client = new DodoPayments({
bearerToken: process.env['DODO_PAYMENTS_API_KEY'],
environment: 'test_mode', // defaults to 'live_mode'
});
```
在结账时将信用附加到订阅产品：
```typescript theme={null}
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'
});
```
发送自动扣除信用的使用事件：
```typescript theme={null}
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 }
}]
});
```
***
## 真实案例
**定价结构：**
| 计划 | 价格 | 每月信用 | 超额 |
| -- | ------- | ------------ | ---------- |
| 入门 | \$29/月 | 10,000 令牌 | \$0.003/令牌 |
| 专业 | \$99/月 | 100,000 令牌 | \$0.002/令牌 |
| 企业 | \$499/月 | 1,000,000 令牌 | \$0.001/令牌 |
**配置：**
* 信用类型：自定义单位（“AI 令牌”）
* 精度：0（完整令牌）
* 转移：最大 25%，1 个月时间范围
* 超额：启用，账单时计费超额
* 计量器：`ai.generation`，按 `tokens` 字段聚合求和
**定价结构：**
| 计划 | 价格 | 每月信用 | 超额 |
| --- | ------ | ----------- | ------------ |
| 免费 | \$0/月 | 1,000 次调用 | 阻止 |
| 开发者 | \$19/月 | 50,000 次调用 | \$0.001/次调用 |
| 业务 | \$99/月 | 500,000 次调用 | \$0.0005/次调用 |
**配置：**
* 信用类型：自定义单位（“API 调用”）
* 精度：0（完整调用）
* 转移：禁用
* 超额：开发者以上计划允许超额（重置时原谅），免费计划不允许超额
* 计量器：`api.request`，使用计数聚合
**定价结构：**
| 计划 | 价格 | 每月信用 | 超额 |
| -- | ------ | ----------- | ------------ |
| 个人 | \$9/月 | 100 GB-小时 | \$0.05/GB-小时 |
| 团队 | \$49/月 | 1,000 GB-小时 | \$0.03/GB-小时 |
**配置：**
* 信用类型：自定义单位（“GB-小时”）
* 精度：2（两位小数）
* 转移：最大 50%，只转移一次
* 超额：启用，限制 200%
* 计量器：`storage.usage`，使用聚合求和
***
## 最佳实践
* **从简单开始**：从单一种信用类型和无转移开始。根据客户反馈和使用模式增加复杂性。
* **设定明确的期望**：在产品页面和客户门户中突出显示信用分配、剩余余额和超额定价。
* **使用有意义的单位**：将信用命名为它们代表的内容（例如，“API 调用”，“AI 令牌”）而不是泛泛之词。这有助于客户理解价值。
* **认真配置过期**：较短的过期时间窗（7 天）可激发紧迫感，但可能让客户感到沮丧。较长的时间窗（30-90 天）对于大多数 SaaS 产品更为用户友好。
* **监控低余额**：设置低余额阈值以在客户用完前提醒他们，从而减少意外超额费用。
* **在测试模式下测试**：创建信用，将其附加到测试产品，并在上线前模拟完整的购买 → 使用 → 扣除 → 过期周期。
Credit-Based Billing 能够无缝与所有其他 Dodo Payments 功能配合使用 - 带试用的订阅，按比例分配的计划变更，以及客户门户。开始时采用基本设置，并随着您的定价模式发展进行扩展。