事件摄取

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

API Reference — Events Ingestion

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

事件结构

Required Fields

string

必填

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

string

必填

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

string

必填

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

Optional Fields

string

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

object

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

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

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: "call_1", customer_id: "cus_abc", event_name: "api.call" },
      { event_id: "call_2", customer_id: "cus_abc", event_name: "api.call" },
      { event_id: "call_3", customer_id: "cus_abc", event_name: "api.call" }
    ]
  })
});

import os
import requests

requests.post(
    'https://test.dodopayments.com/events/ingest',
    headers={'Authorization': f"Bearer {os.environ['DODO_PAYMENTS_API_KEY']}", 'Content-Type': 'application/json'},
    json={'events': [{'event_id': 'call_1', 'customer_id': 'cus_abc', 'event_name': 'api.call'}]}
)

curl -X POST 'https://test.dodopayments.com/events/ingest' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"events": [{"event_id": "call_1", "customer_id": "cus_abc", "event_name": "api.call"}]}'

每个请求最多批量发送 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 文档，包含所有参数、响应代码和交互式测试。

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

API Reference — Events Ingestion

事件结构

发送事件

摄取蓝图

LLM Blueprint

API Gateway Blueprint

Object Storage Blueprint

Stream Blueprint

Time Range Blueprint

View All Blueprints

最佳实践

故障排除

下一步

Create Meters

Ingestion Blueprints

Complete Tutorial

API Reference

API Reference — Events Ingestion

​事件结构

​发送事件

​摄取蓝图

LLM Blueprint

API Gateway Blueprint

Object Storage Blueprint

Stream Blueprint

Time Range Blueprint

View All Blueprints

​最佳实践

​故障排除

​下一步

Create Meters

Ingestion Blueprints

Complete Tutorial

API Reference

事件结构

发送事件

摄取蓝图

最佳实践

故障排除

下一步