需要为 tokens、API 调用、计算…

在 Dodo Payments 中实现可审计的积分/预付余额计费，覆盖 grant、balance、ledger、rollover、expiry、low-balance 告警、overage 和 meter-to-credit 扣减。

适用场景

解决思路

1. 选择计费模型：固定产品且无消耗跟踪时，用普通订阅或一次性支付，不建余额/用量管道。
2. 要按每个计量单位直接按金额计费时，用纯 usage-based billing 和 `price_per_unit`，不建预付池。
3. 要包含或预售可消耗额度时，用 credit-based billing，由 grants 创建供用量消耗的 balance。
4. 要包含 credits 且超出后收费时，用 credits with overage，先消耗 credit pool，再由 overage 处理赤字。
5. 要组合基础费、包含 credits 和计量使用时，把 usage-based product 链接到 credit entitlement，由 meter 把 usage units 转为 credit deductions。
6. 把 credit-based 与 usage-based 视为互补；用 `usage-based-billing` 技能定义和测试 meters，本技能覆盖 credit 侧和 meter-to-credit 链接。
7. credit entitlement 是 credit unit 及其生命周期定义：name、unit、precision、expiry、rollover、overage。
8. grant 是向单个客户发行 credit；来源包括订阅每计费周期重发、一次性产品或 add-on、直接 API ledger credit、先前 grant 的 rollover。
9. credits 控制客户可消费多少；独立的 `entitlements` 资源控制 feature access、files、license delivery 等 fulfillment。
10. 不要混淆 SDK 命名空间：`client.creditEntitlements`、`client.creditEntitlements.balances`、`client.entitlements`、`client.entitlements.files`、`client.entitlements.grants`。
11. 用 `client.customers.listCreditEntitlements(customerID)` 获取客户级 credit-entitlement 视图；不要用 `client.customers.listEntitlements(...)`。
12. custom unit 用应用定义单位如 tokens、calls、compute hours、GB-hours；fiat 用 USD/EUR 等货币价值作为预付余额。
13. 设置 custom-unit precision 为 0 到 10；dashboard 默认 2；创建后不能改，发行 grant 前先选好。
14. 不可分割单位如 whole requests 用 precision 0；只有 fractional credits 有意义时才用小数精度。
15. fiat 使用货币 minor units；示例中 `5,000` credits 表示 USD 50；不要超出文档推断通用 fiat precision；所有金额用最小货币单位。
16. 一个 product 最多附带五个 credit entitlements，每个可独立设置发行和生命周期。
17. balance 响应包含 `balance`、`overage`、`last_transaction_at`、identifiers、timestamps。
18. credit 金额按 decimal strings 处理，不要经过二进制浮点运算。
19. 每条 transaction 都有 ledger 记录：`balance_before`、`balance_after`、`overage_before`、`overage_after`、amount、transaction type、source references、grant ID、description、metadata、timestamp。
20. 用 ledger 作为审计轨迹和交易级余额快照；没有单独记录的历史余额快照 endpoint。
21. 初始化 TypeScript SDK 时把 API key 放服务端；Dodo keys 前缀为 `dodo_test_...` 和 `dodo_live_...`。
22. 用 `new DodoPayments({ bearerToken: process.env['DODO_PAYMENTS_API_KEY'], environment: 'test_mode' })`；省略 `environment` 时 SDK 默认 `live_mode`，开发显式用 `test_mode`。
23. 创建 credit entitlement 用 `client.creditEntitlements.create(...)`。
24. 创建参数：`name` 必填；`unit` 必填；`precision` 必填 0–10 且创建后不可变；`description` 可选；`expires_after_days` 可选 nullable。
25. 创建参数：`rollover_enabled` 必填；`rollover_percentage` 可选 0–100；`rollover_timeframe_count` 可选；`rollover_timeframe_interval` 可选 `Day`/`Week`/`Month`/`Year`；`max_rollover_count` 可选。
26. 创建参数：`overage_enabled` 必填；`overage_behavior` 可选且用精确 enum；`overage_limit` 可选。
27. 创建参数：启用 overage 时 `price_per_unit` 条件必填；有价格时 `currency` 条件必填；`price_per_unit` 是配置货币的 decimal string，金额用最小货币单位；USD 下 `'1'` 是每个 overage credit 一美分。
28. 配置 rollover：设 `rollover_enabled: true`。
29. 配置 rollover：设 `rollover_percentage` 作为 0–100 的结转上限。
30. 配置 rollover：同时提供 `rollover_timeframe_count` 和 `rollover_timeframe_interval`，不要只提供一个。
31. 配置 rollover：若 credits 只能 rollover 有限连续次数，设 `max_rollover_count`。
32. rollover 先于 expiry 应用；只有剩余部分 expires。
33. 配置 expiry：API 用 nullable `expires_after_days`。
34. dashboard 提供 7、30、60、90、custom days 或 never，默认 30 天，custom expiry 最小一天。
35. 仅在当前 API 形式允许时用 `null` 表示无 API 配置 expiry。
36. 配置 overage：`forgive_at_reset` 期末不收费也不保留赤字，默认。
37. 配置 overage：`invoice_at_billing` 期末收费后重置。
38. 配置 overage：`carry_deficit` 保留负余额。
39. 配置 overage：`carry_deficit_auto_repay` 保留赤字并从新发 credits 偿还。
40. 启用 overage 时要求 `price_per_unit`；有价格时要求 `currency`；用 `overage_limit` 限制允许的 overage units。
41. overage 禁用时 Dodo 在 balance 到零后停止扣减；meter 处理异步，不是应用请求的同步授权；需要立即拒绝请求时实现应用侧 enforcement。
42. 把 credits 作为 credit entitlements 在产品创建或编辑流程中附加到产品；不要用 `client.entitlements.grants` 附加或发行 credit balances。
43. 订阅产品：在 Products → Create Product 或已有产品中选择 subscription pricing。
44. 订阅产品：打开 Entitlements & Credits 并附加已有 credit entitlement。
45. 订阅产品：设置每个 billing period 发放的 credits。
46. 订阅产品：可选设置 low-balance notification amount、trial-credit amount、trial 后未用 trial credits 是否过期、plan change 的 credit proration。
47. 订阅产品：保留 entitlement 默认 rollover/overage/expiry 规则或按产品自定义；客户每计费周期收到新 grant。
48. 一次性产品或 add-on：把 credit entitlement 附加到 single-payment product 或 add-on，并配置 one-time amount；购买发行一次 grant；用于 prepaid packs、top-ups、promotional bundles。
49. 用量型产品：把 credit entitlement 附加到与 meter 相同的 usage-based product。
50. meter attachment 字段：`meter_id`；可选 `free_threshold`；`credit_entitlement_id`；设置 `credit_entitlement_id` 时必填 `meter_units_per_credit`；纯 usage 定价时用 decimal string `price_per_unit`。
51. 产品附加 request shapes 可能变化；在 dashboard 配置或从 Create Product API 复制当前 schema；不要臆造 `entitlements`、`credits` 或 `grants` payload。
52. 启动 checkout：产品购买创建客户 grant；checkout 不接受 ad hoc credit amount。
53. 用 `client.checkoutSessions.create({ product_cart: [{ product_id, quantity }], customer: { email }, return_url })`；不要用已废弃的 `payments.create` 或 `subscriptions.create`。
54. 发现客户 credit entitlements：用 `client.customers.listCreditEntitlements(customerID)` 获取客户关联的所有 credit entitlements。
55. 已知 credit entitlement ID 且需要精确余额时，用 balance resource。
56. 读取客户余额：调用 `client.creditEntitlements.balances.retrieve(customerId, { credit_entitlement_id })`。
57. 读取 `balance`、`overage`、`last_transaction_at`；`balance` 和 `overage` 是 entitlement credit unit 的 decimal strings，除非 entitlement 代表 fiat，否则不是货币金额。
58. 手动发放 credits 用于 promotions、migrations、以 credit 实现的 refunds、support gestures。
59. 手动发放时用从业务操作派生的稳定 idempotency key。
60. 调用 `client.creditEntitlements.balances.createLedgerEntry(customerId, { credit_entitlement_id, amount: '500', entry_type: 'credit', expires_at, idempotency_key, reason, metadata })` 并保存 `entry.id`。
61. `amount` 是 decimal string，底层 `NUMERIC(38,28)`，整数部分必须小于 `10^10`。
62. `expires_at` 应用于 credits；金额保持在 entitlement 配置的 precision 内。
63. 如果相同 `idempotency_key` 已存在，API 可能返回 `409`；去对账原操作，不要换新 key 重试 grant。
64. 手动扣减 credits：同一方法使用 `entry_type: 'debit'`。
65. debits 按 FIFO 先消耗最旧 grants；余额不足可能返回 `400`。
66. 扣减后返回 `balance_after` 和 `overage_after`。
67. 不要对已经连接自动 meter-to-credit 扣减的用量再手动 debit，否则重复计费。
68. 读取 ledger：用 `client.creditEntitlements.balances.listLedger('cus...', { credit_entitlement_id })` 的 auto-paginating iterable；在 `for await` 中记录 `id`、`amount`、`balance_before`、`balance_after`、`overage_before`、`overage_after`、`created_at`。
69. 把 Dodo ledger entry ID 与内部 order、support-case、job ID 一起持久化。
70. 对账时比较 ledger entries 和 source references，不要用缓存 balance 覆盖历史。
71. 配置自动 meter-to-credit 扣减：把 credit entitlement 附加到 usage-based product。
72. 配置自动扣减：把 meter 加到同一 product。
73. 配置自动扣减：为该 meter 启用 Bill usage in Credits。
74. 配置自动扣减：设置 `credit_entitlement_id` 和 `meter_units_per_credit`。
75. 配置自动扣减：可选设置 `free_threshold`；低于该值的 usage 被排除。
76. 配置自动扣减：ingest 的 event 的 case-sensitive `event_name` 必须匹配 meter。
77. 后台 worker 约每 1 分钟处理新 usage，按 meter 聚合，用 `meter_units_per_credit` 转换，并按 FIFO 先消耗最旧未过期 grants。
78. 多个 meters 可以以不同 conversion rates 消耗同一个共享 credit pool。
79. 接受 usage event 不意味着紧接着读 balance 已包含该扣减。
80. 用 `usage-based-billing` 技能创建 meter、选择 `count`/`sum`/`max`/`last`、定义 filter、验证 event batching 和 metadata。
81. 端到端 AI token 配置：custom-unit entitlement `AI Token Credits` precision `0`。
82. 端到端配置：订阅产品每周期发放 credits。
83. 端到端配置：`sum` meter 的 case-sensitive event name 为 `ai.tokens`，key 为 `tokens`。
84. 端到端配置：该 meter 通过 `credit_entitlement_id` 和 `meter_units_per_credit` 链接。
85. 端到端配置：一次性产品 `pdt_ai_token_topup` 附带 credits。
86. 记录 token usage：用 `client.usageEvents.ingest({ events: [{ event_id: 'generation:${generationId}', customer_id, event_name: 'ai.tokens', timestamp: new Date().toISOString(), metadata: { tokens, prompt_tokens, completion_tokens, model } }] })`，其中 `tokens = promptTokens + completionTokens`；返回 `ingested_count`。
87. 读取 token balance：用 `client.creditEntitlements.balances.retrieve(customerId, { credit_entitlement_id })` 并返回 `balance`。
88. 创建 top-up checkout：用 `client.checkoutSessions.create({ product_cart: [{ product_id: 'pdt_ai_token_topup', quantity: 1 }], customer: { email: customerEmail }, return_url: 'https://app.example.com/credits' })`；在验证过的 `credit.balance_low` webhook 流程和客户操作后调用。
89. 端到端生命周期：模型返回实际 prompt/completion token counts。
90. 生命周期：应用 ingest 一个唯一标识的 `ai.tokens` event。
91. 生命周期：meter 聚合 `tokens` metadata。
92. 生命周期：worker 转换单位并按 FIFO 从未过期 grants 扣减。
93. 生命周期：Dodo 发出 `credit.deducted`；满足阈值条件时发出 `credit.balance_low`。
94. 生命周期：应用通知客户并提供附加 top-up product 的 checkout。
95. 不要每分钟轮询自行合成阈值事件；使用验证过的 webhook，轮询只用于 UI 新鲜度。
96. 处理 credit webhooks：按 `webhook-integration` 技能做签名验证、raw-body 处理、重试和事件去重。
97. 分发前用 `client.webhooks.unwrap()` 验证；绝不信任已解析未验证的 body。
98. 除 `credit.balance_low` 外，所有 credit events 使用 full ledger payload。
99. `credit.added`：刷新缓存 balance，关联 grant 或 purchase 与 ledger entry。
100. `credit.deducted`：刷新缓存 balance 和 usage 展示，对账 source usage/job。
101. `credit.expired`：刷新 balance，仅在产品政策承诺时通知。
102. `credit.rolled_over`：刷新 balance，并在账户历史展示新 rollover grant。
103. `credit.rollover_forfeited`：刷新 balance，并按配置 rollover 限制解释没收。
104. `credit.overage_charged`：对账 overage 收费与 billing 和客户可见历史。
105. `credit.overage_reset`：确认 ledger payload 后清除缓存 overage 状态。
106. `credit.manual_adjustment`：对账 adjustment 与内部 support/admin 操作。
107. `credit.balance_low`：去重、刷新权威 balance、通知客户并提供 upgrade 或 top-up。
108. low-balance payload 字段：`business_id`、`type`、`timestamp`、`data.payload_type`、`customer_id`、`subscription_id`、`credit_entitlement_id`、`credit_entitlement_name`、`available_balance`、`subscription_credits_amount`、`threshold_percent`、`threshold_amount`。
109. Low-balance 通知流程：验证 raw webhook 并按 `webhook-id` 去重。
110. 通知流程：确认 `type === 'credit.balance_low'` 并验证 dedicated payload。
111. 通知流程：把 `customer_id` 映射到已认证应用账号；不要接受浏览器提供的 customer ID。
112. 通知流程：用 `balances.retrieve(...)` 读当前 balance，因为 emit 后可能又发生 grant 或 deduction。
113. 通知流程：如果仍低于通知政策，用 webhook ID 或 threshold occurrence 作为 key 入队一条通知。
114. 通知流程：链接到 one-time top-up checkout 或 plan-upgrade 流程。
115. 通知流程：将通知投递记录与 Dodo ledger 分开记录；绝不为 email 制造 ledger entry。
116. Best-effort balance gate：precision `0` 时服务端可用 integer-safe parsing 粗检 `BigInt(response.balance) >= required`。
117. 该 gate 只用于 precision `0`；fractional credits 用保留配置 precision 的任意精度 decimal 实现。
118. 该读取不是 reservation；两个并发请求可能都看到足够 balance，自动 meter deductions 也可能尚未反映。
119. Strict request enforcement 模式：可预测固定成本时，服务前创建 idempotent manual debit，余额不足 `400` 视为拒绝；工作失败后若已 debit，发单独的 idempotent compensating credit 并关联 reason；不要同时对同一 usage 做 meter 扣减。
120. Strict request enforcement 模式：可变成本如 AI tokens 时，在自己的 datastore 原子预留估算容量，强制每客户并发限制，事后 ingest 实际 usage，并用 Dodo webhooks 和 ledger entries 对账本地 reservations。
121. Strict request enforcement 模式：overage product 时依据产品的 overage policy 和自己的风险限制授权，不要只看 `balance > 0`。
122. 授权失败时返回应用级 payment/credit-required 响应并提供 top-up 或 upgrade 路径；不要向客户端暴露 Dodo API 错误或 secrets。
123. 避免 check then act：远程 balance 读取后执行工作不是原子。
124. 避免 immediate post-event read：meter worker 可能未处理。
125. 避免 parallel workers：多个 jobs 在没有本地 reservation 或原子 debit 时消耗同一表面 balance。
126. 避免 retry with new IDs：timeout 后改 `event_id` 或 `idempotency_key` 会重复 usage/adjustments。
127. 避免 cache as authority：webhook 维护的 balances 适合展示，不用于严格授权。
128. 避免 mixed deduction paths：自动 meter deduction 加手动 debit 会重复计数。
129. 避免混淆两个资源：`creditEntitlements` 和 `entitlements` 不同；credit balances 不在 `client.entitlements.grants` 下。
130. 避免调用臆造 balance 方法：用 `balances.retrieve(customerId, { credit_entitlement_id })`，不是 `balances.get(creditId, customerId)`。
131. 避免 ledger 参数顺序错误：`createLedgerEntry` 第一个参数是 `customerId`；`credit_entitlement_id` 在 request object 中。
132. 避免 adjustments 字段错误：用 `entry_type` 和 `reason`，不要用 `type` 或 `description`。
133. 避免 grants 参数顺序错误：`creditEntitlements.balances.listGrants(customerID, params)` 存在，第一个参数是 customer id，entitlement 在 params object；返回 paginated page，要读 `.items` 而不是当数组；需要客户级摘要时用 `customers.listCreditEntitlements(customerID)`。
134. 避免把 `available_balance` 当 balance API 字段；balance API 用 `balance` 和 `overage`；`available_balance` 属于 dedicated low-balance webhook payload。
135. 避免随意选 precision：支持 0–10 且创建后不可改。
136. 避免用 JavaScript floating point 处理 credits：API amounts 是 decimal strings；保持字符串或用 decimal arithmetic。
137. 避免超出 adjustment bounds：ledger amounts 映射 `NUMERIC(38,28)`，整数部分必须小于 `10^10`。
138. 避免错述货币单位：currency amounts 使用最小货币单位；不要把 cents 标为 dollars。
139. 避免不稳定 idempotency keys：每次重试用 timestamp 或 random key 会破坏去重；从不可变业务操作派生。
140. 避免盲目重试 insufficient debit：手动 debits 可能因余额不足返回 `400`；引导客户 top-up 或走 overage policy。
141. 避免假设 event ingestion 是同步扣减：meter-to-credit processing 约每分钟一次。
142. 避免把 Dodo balance 当 per-request lock：文档警告不要用异步上报的 meter balances 做严格授权。
143. 避免 mismatch meter names：usage `event_name` 匹配大小写敏感。
144. 避免 batch 内重复 ID：同一 ingestion request 中重复 `event_id` 会拒绝整个请求；之前已 ingest 的 ID 在重试时会被忽略。
145. 避免臆造 deduplication window：当前文档要求唯一 event IDs 但未发布保留时长。
146. 避免弄反 conversion：`meter_units_per_credit` 是消耗一个 credit 所需的 usage units；设置 `credit_entitlement_id` 时必填。
147. 避免忽略 free threshold：低于 `free_threshold` 的 usage 在 credit deduction 前排除。
148. 避免只提供一个 rollover timeframe 字段：`rollover_timeframe_count` 和 `rollover_timeframe_interval` 必须一起提供。
149. 避免 rollover enum 大小写错误：确认值为 `Day`、`Week`、`Month`、`Year`。
150. 避免假设 expiry 先于 rollover：rollover 先应用，只有剩余部分 expires。
151. 避免臆造 overage enum values：只用 `forgive_at_reset`、`invoice_at_billing`、`carry_deficit`、`carry_deficit_auto_repay`。
152. 避免遗漏 overage pricing dependencies：启用 overage 需要 `price_per_unit`；有价格需要 `currency`。
153. 避免附加过多 credits：当前 product 限制为五个 credit entitlements。
154. 避免假设 checkout 能授予任意 credits：credits 必须已附加到购买的产品或 add-on。
155. 避免只处理常见 webhooks：包括 `credit.overage_reset` 和 `credit.rollover_forfeited`，不只是 added、deducted、low-balance。
156. 避免解析未验证 webhook：按 `webhook-integration` 用 `client.webhooks.unwrap()` 验证 raw body；绝不手写 HMAC 或信任重新序列化 JSON。
157. 避免臆造 historical snapshot APIs：用 ledger 的 `balance_before` 和 `balance_after` 做交易级历史。
158. 避免使用已废弃购买方法：新 checkout flows 用 `client.checkoutSessions.create(...)`，不是 `payments.create(...)` 或 `subscriptions.create(...)`。
159. 避免使用错误 host 或 key 格式：有效 host 是 `https://test.dodopayments.com` 和 `https://live.dodopayments.com`；keys 以 `dodo_test_` 或 `dodo_live_` 开头。

适用边界 · 注意事项

• 固定产品且无消耗跟踪时，用普通订阅或一次性支付，不需要信用余额。
• 纯按每个计量单位直接按金额计费时，用纯 usage-based billing，不需要预付池。
• 需要同步立即拒绝应用请求时，不能只依赖 Dodo 异步 meter 扣减余额作为唯一授权；需要应用侧原子预留或手动 debit。