跳转到主要内容
事件是基于使用的计费的基础。当可计费操作发生时发送事件，计量器将其汇总为费用。

API 参考 - 事件摄取

完整的 API 文档，包括示例和响应代码。

​
事件结构

​
event_id
string
required
唯一标识符。使用 UUID 或组合客户 ID + 时间戳 + 操作。
​
customer_id
string
required
Dodo Payments 客户 ID。必须是有效的现有客户。
​
event_name
string
required
事件类型，必须与您的计量器的事件名称匹配（区分大小写）。示例： api.call, image.generated
​
timestamp
string
ISO 8601 时间戳。如果省略，则默认为服务器时间。对于延迟/批处理事件，包含以确保准确计费。
​
metadata
object
用于聚合和过滤的附加属性：
  • 数值： bytes, tokens, duration_ms
  • 过滤器： endpoint, method, quality
metadata: {
  endpoint: "/v1/orders",
  method: "POST",
  tokens: 1024
}

​
发送事件

await fetch('https://test.dodopayments.com/events/ingest', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.DODO_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    events: [{
      event_id: "api_call_1234",
      customer_id: "cus_abc123",
      event_name: "api.call",
      metadata: { endpoint: "/v1/orders" }
    }]
  })
});
每个请求批量处理最多 100 个事件以获得更好的性能。

​
摄取蓝图

适用于常见用例的现成事件模式。使用经过验证的蓝图开始，而不是从头开始构建。

LLM 蓝图

跟踪 OpenAI、Anthropic、Groq、Gemini 等的 AI 令牌使用情况。

API 网关蓝图

计量 API 请求，支持端点过滤和速率限制。

对象存储蓝图

跟踪文件上传和云存储服务的存储消耗。

流蓝图

测量视频、音频和实时数据的流带宽。

时间范围蓝图

按经过的时间对无服务器函数和计算实例进行计费。

查看所有蓝图

查看所有可用蓝图及其详细实施指南。

​
最佳实践

使用确定性 ID 以防止重复： ${customerId}_${action}_${timestamp}
在 5xx 错误时进行重试，使用指数退避。不要在 4xx 错误时重试。
实时事件可省略。对于延迟/批处理事件，包含以确保准确性。
跟踪成功率并将失败的事件排队以进行重试。

​
故障排除

  • 事件名称必须与计量器完全匹配（区分大小写）
  • 客户 ID 必须存在
  • 检查计量器过滤器是否未排除事件
  • 验证时间戳是否是最近的
验证 API 密钥是否正确，并使用格式： Bearer YOUR_API_KEY
确保所有必填字段均已存在： event_id, customer_id, event_name
  • 元数据键必须与计量器的 “Over Property” 完全匹配
  • 使用数字，而不是字符串： tokens: 150 而不是 tokens: "150"

​
下一步

创建计量器

定义您的事件如何通过过滤器和聚合函数聚合为可计费数量。

摄取蓝图

使用现成的蓝图处理常见用例，如 LLM 跟踪、API 网关和存储。

完整教程

从头开始构建一个完整的 AI 图像生成器，支持基于使用的计费。

API 参考

完整的 API 文档，包括所有参数、响应代码和交互式测试。