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

API Reference - Events Ingestion

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

​
事件结构

​
event_id
string
必填
唯一标识符。使用 UUID 或组合客户 ID + 时间戳 + 操作。
​
customer_id
string
必填
Dodo Payments 客户 ID。必须为有效的现有客户。
​
event_name
string
必填
与您的计量器事件名称相匹配的事件类型（区分大小写）。示例：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_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" }
    }]
  })
});
每次请求最多批量处理 100 条事件，以提升性能。

​
摄取蓝图

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

LLM Blueprint

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

API Gateway Blueprint

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

Object Storage Blueprint

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

Stream Blueprint

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

Time Range Blueprint

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

View All Blueprints

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

​
最佳实践

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

​
故障排除

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

​
下一步

Create Meters

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

Ingestion Blueprints

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

Complete Tutorial

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

API Reference

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