事件摄取

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

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

API Reference - Events Ingestion

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

​

事件结构

Required Fields

event_id · string · 必填

唯一标识符。使用 UUID 或组合客户 ID + 时间戳 + 操作。

customer_id · string · 必填

Dodo Payments 客户 ID。必须为有效的现有客户。

event_name · string · 必填

与您的计量器事件名称相匹配的事件类型（区分大小写）。示例：api.call、image.generated

Optional Fields

timestamp · string

ISO 8601 时间戳。如省略则默认使用服务器时间。对于延迟/批量事件请务必包含，以确保计费准确。

metadata · object

用于聚合和过滤的附加属性：

• 数值：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" }
    }]
  })
});

每次请求最多批量处理 100 条事件，以提升性能。

​

摄取蓝图

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

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 错误时使用指数退避重试。不要对 4xx 错误重试。

Include Timestamps

实时事件可省略。对于延迟/批量事件请包含，以确保准确性。

Monitor Delivery

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

​

故障排除

Events not appearing

• 事件名称必须与计量器完全匹配（区分大小写）
• 客户 ID 必须存在
• 检查计量器过滤器是否排除了事件
• 确认时间戳是最近的

Authentication errors (401)

验证 API 密钥是否正确并使用格式：Bearer YOUR_API_KEY

Validation errors (400)

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

Metadata not aggregating

• 元数据键必须与计量器的“Over Property”完全一致
• 使用数字，而非字符串：tokens: 150，而不是 tokens: "150"

​

下一步

Create Meters

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

Ingestion Blueprints

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

Complete Tutorial

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

API Reference

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