事件摄取

从您的应用程序发送使用事件，以跟踪客户消费并支持计费。

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

API Reference — Events Ingestion

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

​

事件结构

Required Fields

event_id · string · 必填

事件的唯一标识符，用于检测重试时的重复事件。请根据操作生成该标识符，例如使用 customer ID + 操作 + 时间戳，这样重试的事件会保持相同的 ID。每次重试都生成新的随机 UUID，会导致同一事件被计算两次。

customer_id · string · 必填

Dodo Payments customer ID。必须是有效且已存在的 customer。

event_name · string · 必填

与您的 meter event name 匹配的事件类型（区分大小写）。示例：api.call、image.generated。

Optional Fields

timestamp · string

ISO 8601 时间戳（UTC）。如果省略，则默认为当前服务器时间。对于延迟事件或批量事件，请提供该值以确保计费准确。早于 1 小时或未来超过 5 分钟的时间戳将被拒绝。

metadata · object

用于聚合和筛选的其他属性。最多可包含 50 个键；每个键最多 100 个字符，每个值最多 500 个字符。

• 数值：bytes、tokens、duration_ms
• 筛选器：endpoint、method、quality

metadata: {
  endpoint: "/v1/orders",
  method: "POST",
  tokens: 1024
}

​

发送事件

Single Event

await fetch('https://test.dodopayments.com/events/ingest', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.DODO_PAYMENTS_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" }
    }]
  })
});

每个请求最多批量发送 1,000 个事件，以获得更好的性能。API 对每个请求强制执行 1,000 个事件的上限。

​

摄取蓝图

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

LLM Blueprint

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

API Gateway Blueprint

通过端点过滤和速率限制支持对 API 请求进行计量。

Object Storage Blueprint

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

Stream Blueprint

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

Time Range Blueprint

按运行时间为无服务器函数和计算实例计费。

View All Blueprints

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

​

最佳实践

Use Unique Event IDs

使用确定性 ID 防止重复：${customerId}_${action}_${timestamp}。

Implement Retries

对于 5xx 和 429 错误，请使用指数退避进行重试。不要重试其他 4xx 错误。

Include Timestamps

对于实时事件，请省略时间戳。对于延迟事件或批量事件，请提供时间戳以确保准确性。

Monitor Delivery

跟踪成功率并将失败事件排队以便重试。

​

故障排除

Events not appearing

• 事件名称必须与 meter 完全匹配（区分大小写）
• Customer ID 必须存在于您的账户中
• 检查 meter filters 是否排除了事件
• 确认时间戳是近期的

Authentication errors (401)

确认 API key 正确，并使用以下格式：Bearer YOUR_API_KEY。

Validation errors (400)

确保所有必填字段均已提供：event_id、customer_id、event_name。

Metadata not aggregating

• Metadata keys 必须与 meter 的 “Over Property” 完全匹配
• 使用数字而非字符串：tokens: 150，而不是 tokens: "150"

​

下一步

Create Meters

使用过滤器和聚合函数定义事件如何汇总为可计费数量。

Ingestion Blueprints

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

Complete Tutorial

从零开始构建一个带有基于使用量计费的完整 AI 图像生成器。

API Reference

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