当按 API 调用、Token、存储等实际用量向客户计费时…

适用于需要按客户实际消耗（API 调用、AI token、存储、带宽等）直接计费，并可与订阅或一次性购买组合的场景。

适用场景

解决思路

1. 定义并发送用量事件：从你的应用向后端发送用量记录到 Dodo；每个事件通过 `customer_id` 归属客户，并通过 `event_name` 匹配到某个 meter。事件字段包括 `event_id`、`customer_id`、`event_name`、`timestamp`、`metadata`。
2. 创建 meter 时指定：`event_name`（要匹配的事件名，大小写敏感）、聚合类型（`count`、`sum`、`max`、`last`）、计量单位（如 calls、tokens、GB）以及可选 filters（事件必须满足的条件）。
3. 按计费指标选择聚合类型：`count` 统计总事件数（如 API calls、image generations）；`sum` 对某个 metadata 属性求和（如 tokens used、bytes transferred）；`max` 取周期内最高值（如 peak concurrent users）；`last` 取最近值（如 current storage used）。对 `sum`、`max`、`last` 必须指定要聚合的 metadata 属性。
4. 将 meter 附加到 product price 实现按单位计费：设置 `price_per_unit`（例如 $0.001 per API call），可选 `free_threshold`（例如每月 1,000 次免费调用）；费用公式为 `(usage − threshold) × price_per_unit`。例如 2,500 calls − 1,000 free = 1,500 × $0.02 = $30.00。
5. 用 SDK 创建 meter：调用 `client.meters.create({ name, event_name, aggregation, measurement_unit, description })`，例如 `aggregation: { type: 'count' }`；打印 `meter.id`（`mtr_...`）。若用 sum 聚合，指定 `aggregation: { type: 'sum', key: 'tokens' }`。
6. 列出和检索 meter：调用 `client.meters.list()` 列出所有 meter；调用 `client.meters.retrieve('mtr_abc123')` 检索指定 meter。
7. 归档和取消归档 meter：调用 `client.meters.archive('mtr_abc123')` 归档；调用 `client.meters.unarchive('mtr_abc123')` 取消归档。Meter 是归档而非删除；归档后停止接收新事件但保留历史数据。
8. 发送事件：调用 `client.usageEvents.ingest({ events: [{ event_id, customer_id, event_name, timestamp, metadata }] })`；例如 `event_id` 用 `api-call:${requestId}`，`requestId` 必须标识底层 API 操作并在重试间保持不变，不要在每次摄入尝试内部生成。
9. 遵守事件 schema：`event_id` 必填，用于幂等；`customer_id` 必填，Dodo Payments 客户 ID；`event_name` 必填，必须与 meter 的 event name 完全一致（大小写敏感）；`timestamp` 可选，ISO-8601，默认当前 UTC，必须在一小时前到五分钟未来之间；`metadata` 可选，值可为 string、integer、number、boolean，最多 50 对，key 长度 100，value 长度 500，不允许嵌套对象或数组。
10. 保证幂等和去重：每个不同操作使用一个全局唯一 `event_id`；从不可变的 request、job、generation 或 snapshot ID 派生，并在每次重试时复用同一个 ID；单个请求中重复 ID 会拒绝整个批次；之前已摄入的 ID 在后续请求中会被静默忽略，因此重试安全。
11. 批量摄入：每个请求最多发送 1,000 个事件；将每个事件的 `operationId` 映射为 `event_id: usage:${operationId}`，再调用 `client.usageEvents.ingest({ events: formattedEvents })`。示例批量跟踪多个 API calls：`req_101`、`req_102`、`req_103` 分别发给 `cus_abc`、`cus_abc`、`cus_xyz`，事件名 `api.call`，metadata 含 `endpoint`。
12. 查询事件：调用 `client.usageEvents.list({ customer_id: 'cus_abc123' })` 按客户列出事件；调用 `client.usageEvents.retrieve('evt_abc123')` 检索指定事件。
13. 使用按单位定价模型：目前唯一有文档且可操作的定价模型是 per-unit pricing；meter attachment 使用 `price_per_unit`（十进制字符串，最多 5 位整数、12 位小数）和可选 `free_threshold`（整数，低于此用量不收费）；费用公式 `(usage − threshold) × price_per_unit`。
14. 产品创建：以 `product-catalog-management` skill 为完整 product creation 请求的权威来源；它定义单个 `price` 对象，`type: 'usage_based_price'` 以及嵌套的 `meters` 数组；不要在此处定义并行的 product schema。
15. 注意定价模型限制：Dodo Payments API 当前没有文档化 tiered、graduated、volume、staircase 定价模型；当前请使用 per-unit pricing 加 free thresholds。
16. 跟踪 API calls 时，先持久化事件再报告操作完成，然后从带重试的 worker 摄入；outbox 或 queue 实现必须在 `persist` resolve 前持久保存 payload。定义 `PersistedUsageEvent` 类型和 `UsageOutbox` 接口：`persist(event)`、`nextBatch(limit)`、`markIngested(eventIds)`。
17. 在 `completeApiOperation` 中调用 `await outbox.persist({ event_id: 'api-call:' + operationId, customer_id, event_name: 'api.call', timestamp, metadata: { endpoint: '/v1/users', method: 'GET', status: 200 } })`；在 `ingestUsageOutbox` 中取 `nextBatch(1000)`，为空则返回，否则 `client.usageEvents.ingest({ events })`，成功后 `outbox.markIngested(events.map(event => event.event_id))`。
18. 如果 worker 在 Dodo 接受批次后、`markIngested` 前崩溃，用相同 `event_id` 重试相同的已持久化事件；Dodo 会忽略已摄入的 ID。
19. 跟踪 AI token 用量：调用 AI 完成后摄入事件，`event_id` 用 `generation:${generationId}`，`event_name: 'ai.tokens'`，metadata 包含 `tokens`、`prompt_tokens`、`completion_tokens`、`model`（值为字符串，如 `response.usage.total_tokens.toString()`）。
20. 跟踪存储用量：对基于 snapshot 的当前状态指标使用 `last` 聚合；摄入事件 `event_id: 'storage-snapshot:' + snapshotId`，`event_name: 'storage.snapshot'`，metadata 包含 `bytes` 和 `gb`（如 `(bytesUsed / 1024 / 1024 / 1024).toFixed(2)`）；定期或在存储变化后调用 `updateStorageUsage`，例如 `5GB` 对应 `5368709120`。
21. 查询展示用量：调用 `client.subscriptions.retrieveUsageHistory('sub_abc123', { page_size: 100 })`；返回订阅当前 billing period 内每个 meter 的聚合用量记录 `usage.items`。
22. 集成 credit-based billing：用量事件可以扣除客户 credit balance 而不是按单位收费；参见 `credit-based-billing` skill。将 meter 关联到 credits：1）创建 credit entitlement（如 'AI Credits'）；2）将 credit entitlement 附加到同一 product；3）在 meter 上启用 `Bill usage in Credits`；4）设置 `credit_entitlement_id` 和 `meter_units_per_credit`（如 1,000 tokens = 1 credit）。
23. Credit 集成行为：低于 free threshold 的用量不参与；大约每分钟，后台 worker 聚合新用量，按 meter-to-credit ratio 转换，并按 FIFO 消耗最早未过期的 credit grants；credits 用尽后应用已配置的 overage behavior。
24. 集成 webhook：用量事件会触发 webhooks 用于监控和对账；参见 `webhook-integration` skill 完成 webhook setup 和 verification。
25. 避免不稳定或复用 event IDs：从不可变业务操作生成一个 ID；给不同操作复用 ID 会丢用量，每次重试生成 timestamp 或 random ID 会把同一操作计费两次；错误示例 `api-call:${Date.now()}:${crypto.randomUUID()}`，正确示例为重试请求 `req_123` 时始终用 `api-call:req_123`；不要为不同请求复用 `api-call:req_123`；timeout 不是生成新 idempotency key 的许可。
26. 避免 fire-and-forget ingestion：不要在响应后才开始摄入而没有先持久化事件；进程可能在用户收到成功后、用量到达 Dodo 前崩溃。错误做法是在 `res.json(result)` 后 `void client.usageEvents.ingest(...)`；正确做法是在返回成功前 `await usageOutbox.persist(result.usageEvent)`，由 retrying worker 用原始 `event_id` 摄入已持久化 payload；如果持久化失败，返回错误以便操作重试，而不是静默少计费。
27. 避免 timestamp 时钟偏移：timestamp 必须在一小时前到五分钟未来之间；确保服务器时钟同步；不要用 2 小时前的 `new Date(Date.now() - 2 * 60 * 60 * 1000).toISOString()`；应使用 `new Date().toISOString()`。
28. 避免客户端摄入：绝不要从客户端代码发送事件；始终从后端摄入，避免暴露 API key。错误做法是在 client-side `fetch` 的 `Authorization` header 中放 `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`；正确做法是从 backend worker 用已持久化 payload 调用 `client.usageEvents.ingest({ events: [...] })`。
29. 避免 event name 不匹配：event names 大小写敏感，必须与 meter 的 event name 完全一致；如果 meter 期望 `api.call`，事件发送 `API.CALL` 不会匹配；应发送 `api.call`。

适用边界 · 注意事项

• 需要 tiered、graduated、volume 或 staircase 等阶梯/分级定价时暂不适用：Dodo Payments API 当前仅文档化并支持 per-unit pricing + free thresholds。
• 无法保证用量事件先持久化、再以稳定 event_id 重试摄入时不要用：会导致漏计费或重复计费。
• 不想依赖 Dodo Payments 这一特定计费服务/付费账号/API key，或必须完全自建计量计费时，不适用。