基于使用量的计费集成指南

API Reference - Events Ingestion

访问完整的 API 文档，用于摄取使用事件，并以互动方式测试事件摄取请求和响应。

API Reference - Meters Creation

浏览创建计量器的完整 API 文档，并以互动方式测试计量器创建请求和响应。

创建计量器

计量器定义了您的使用事件如何被聚合和测量以用于计费。在创建计量器之前，请规划您的使用跟踪策略：

确定您想跟踪哪些使用事件
决定事件如何聚合（计数、求和等）
为特定用例定义任何过滤要求

逐步创建计量器

请遵循此综合指南以设置您的使用计量器：

Configure Basic Information

设置计量器的基本信息。

string

必填

选择一个清晰、描述性名称，以标识此计量器跟踪什么。示例：“代币”、“API 调用”、“存储使用量”、“计算小时”

string

提供一个详细的说明，说明此计量器测量的内容。示例：“计算每个客户发出的 POST /v1/orders 请求数”

string

必填

指定将触发此计量器的事件标识符。示例：“token”、“api.call”、“storage.usage”、“compute.session”

事件名称必须与您在使用事件中发送的内容完全匹配。事件名称区分大小写。

Configure Aggregation Settings

定义计量器如何从您的事件计算使用量。

string

必填

选择事件应如何聚合：

Count
Sum
Max
Last

仅计算接收到的事件数量。使用案例：API 调用、页面浏览、文件上传计算：事件总数

string

事件元数据中用于聚合的属性名称。

当使用 Sum、Max 或 Last 聚合类型时，该字段为必填字段。

string

必填

定义用于报告和计费显示的单位标签。示例：“calls”、“GB”、“hours”、“tokens”

Configure Event Filtering (Optional)

设置标准以控制哪些事件包含在计量器中。

事件过滤允许您创建复杂规则，以确定哪些事件有助于您的使用计算。这对于排除测试事件，根据用户等级进行过滤或专注于特定操作非常有用。

启用事件过滤切换 启用事件过滤 以激活条件事件处理。选择过滤逻辑选择如何评估多个条件：

AND Logic
OR Logic

所有条件必须为真才能计入事件。当您需要事件同时满足多个严格条件时使用此选项。示例： 计算 API 调用，其中 user_tier = "premium" AND endpoint = "/api/v2/users"

至少一个条件必须为真才能计入事件。当您希望包括满足任何多个条件的事件时使用此选项。示例： 计算事件，其中 method = "POST" OR method = "PUT" OR method = "DELETE"

设置过滤条件

Add Condition

点击 添加条件 来创建新过滤规则。

Configure Property Key

指定来自事件元数据的属性名称。

Select Comparator

选择可用的操作符：

equals - 精确匹配
not_equals - 排除过滤器
greater_than - 数字比较
greater_than_or_equals - 数字比较（包含）
less_than - 数字比较
less_than_or_equals - 数字比较（包含）
contains - 字符串包含子字符串
does_not_contain - 字符串排除过滤器

Set Comparison Value

设置比较的目标值。

Add Groups

使用 添加组 创建附加条件组，以实现复杂逻辑。

过滤属性必须包含在事件元数据中，以便条件正常工作。缺少所需属性的事件将被排除在计算之外。

Create Meter

检查您的计量器配置并点击 创建计量器。

您的计量器现已准备好接收和聚合使用事件。

链接计量器到产品

一旦您创建了计量器，您需要将其链接到产品以启用基于使用量的计费。此过程将计量器的使用数据与客户计费的定价规则连接起来。将计量器链接到产品建立了使用跟踪和计费之间的连接：

产品定义定价规则和计费行为
计量器提供用于计费计算的使用数据
多个计量器可以链接到单个产品以实现复杂的计费场景

产品配置过程

通过正确配置产品设置将您的使用数据转换为可计费费用：

Choose Usage-Based Billing Product Type

导航到您的产品创建或编辑页面并选择 基于使用量 作为产品类型。

Select Associated Meter

点击 关联计量器 以从侧面打开计量器选择面板。此面板允许您配置哪些计量器将跟踪此产品的使用情况。

Add Your Meter

在计量器选择面板中：

点击 添加计量器 以查看可用计量器
从下拉列表中选择您创建的计量器
已选择的计量器将出现在您的产品配置中

Configure Price Per Unit

为您的计量器跟踪的每个使用单位设置定价。

number

必填

定义为您的计量器测量的每个单位收费多少。示例：设置 $0.50 每单位意味着：

消费 1,000 单位 = 1,000 × $0.50 = 500.00 收取
消费 500 单位 = 500 × $0.50 = 250.00 收取
消费 100 单位 = 100 × $0.50 = 50.00 收取

Set Free Threshold (Optional)

配置免费使用额度后才开始计费。

number

在开始计算付费使用之前，消费者可以免费消费的单元数。工作原理：

免费阈值：100 个单位
每单位价格：$0.50
客户使用量：250 单位
计算： (250 - 100) × $0.50 = **$ 75.00** 收取

免费阈值非常适合于免费增值模式、试用期或为客户提供计划中包含的基本津贴。

免费阈值适用于每个计费周期，每月或根据您的计费计划为客户提供新的津贴。

Save Configuration

检查您的计量器和定价配置，然后点击 保存更改 以完成设置。

您的产品现已配置为基于使用量的计费，并将根据客户的实际消耗量自动收费。

接下来会发生什么：

发送到您的计量器的使用事件将被跟踪和聚合
计费计算将自动应用您的定价规则
客户将根据每个计费周期的实际消费量进行收费

请记住，每个产品最多可以添加 10 个计量器，从而实现复杂的使用跟踪跨多个维度，如 API 调用、存储、计算时间和自定义指标。

发送使用事件

配置计量器后，您可以开始从您的应用程序发送使用事件，以跟踪客户使用情况。

事件结构

每个使用事件必须包含以下必填字段：

string

必填

此特定事件的唯一标识符。必须在所有事件中唯一。

string

必填

该使用量应归属的 Dodo Payments 客户 ID。

string

必填

与您的计量器配置匹配的事件名称。事件名称触发适当的计量器。

string

事件发生时间的 ISO 8601 时间戳。如果未提供，默认为当前时间。

object

用于过滤和聚合的附加属性。包括计量器中 “Over Property” 或过滤条件中引用的任何值。

使用事件 API 示例

使用事件 API 将使用事件发送到已配置的计量器：

const response = 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_atXa1lklCRRzMicTqfiw2", 
        event_name: "api.call",
        timestamp: new Date().toISOString(),
        metadata: {
          endpoint: "/v1/orders",
          method: "POST",
          response_size: 1024
        }
      }
    ]
  })
});

import requests
from datetime import datetime

response = requests.post(
    'https://test.dodopayments.com/events/ingest',
    headers={
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json'
    },
    json={
        'events': [
            {
                'event_id': 'api_call_1234',
                'customer_id': 'cus_atXa1lklCRRzMicTqfiw2',
                'event_name': 'api.call',
                'timestamp': datetime.now().isoformat(),
                'metadata': {
                    'endpoint': '/v1/orders',
                    'method': 'POST',
                    'response_size': 1024
                }
            }
        ]
    }
)

curl -X POST 'https://test.dodopayments.com/events/ingest' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "events": [
      {
        "event_id": "api_call_1234",
        "customer_id": "cus_atXa1lklCRRzMicTqfiw2",
        "event_name": "api.call", 
        "timestamp": "2024-01-15T10:30:00Z",
        "metadata": {
          "endpoint": "/v1/orders",
          "method": "POST",
          "response_size": 1024
        }
      }
    ]
  }'

可靠摄取需要了解的关键事项

遵循以下实践，确保生产环境中的用量跟踪准确且具备弹性。

使用确定性且幂等的 event_id。 event_id 必须在所有事件中保持唯一，并作为幂等键使用——重复使用 event_id 会被视为重复事件，不会再次计数，因此重试不会导致重复计费。应根据操作生成 ID，而不是使用随机值，例如 `${customer_id}_${action}_${timestamp}`。

批量发送事件，每个请求最多 1,000 个。 /events/ingest endpoint 对每次调用强制执行 每次最多 1,000 个事件 的限制；超过该数量的批次会被拒绝，因此应将高用量拆分到多个调用中。对于高吞吐工作负载，应先缓冲事件并分批刷新，而不是每个事件发送一个请求。

重试 5xx 和 429，但不要重试 4xx。 对服务器错误（5xx）和速率限制（429）使用指数退避进行重试。不要重试 400/422 验证错误——负载格式不正确，每次都会失败；请修正后重新发送。将重试后仍然失败的事件加入队列，确保不会丢失任何事件。

有意设置时间戳。 对于实时事件，省略 timestamp，它将默认为摄取时间。在补录或发送延迟/批量事件时，应显式设置该值（ISO 8601），使用量归入正确的计费周期。

将聚合元数据作为数字而不是字符串发送。 Meter 的 Over Property（Sum、Max、Last）所引用的任何属性都必须是数字类型——{ "tokens": 150 }，而不是 { "tokens": "150" }。字符串值不会参与聚合。

基于用量的计费分析

通过全面的分析仪表板监控并分析基于用量的计费数据。跟踪客户消费模式、Meter 性能和计费趋势，以优化定价策略并了解用量行为。

概览分析

概览选项卡提供基于用量的计费性能的综合视图：

活动指标

跟踪不同时间段内的关键用量统计信息：

metric

显示当前计费周期内的用量活动，帮助你了解每月的消费模式。

metric

显示自开始跟踪以来的累计用量统计信息，提供长期增长洞察。

使用时间段选择器比较不同月份的用量，并识别季节性趋势或增长模式。

Meter 数量图表

Meter 数量图表通过以下功能可视化随时间变化的用量趋势：

时间序列可视化：跟踪按天、周或月划分的用量模式
支持多个 Meter：同时查看不同 Meter 的数据
趋势分析：识别用量峰值、模式和增长轨迹

图表会根据用量规模和所选时间范围自动调整比例，从而清晰呈现细微波动和重大用量变化。

事件分析

事件选项卡提供对单个用量事件的细粒度可见性：

事件信息显示

事件表通过以下列清晰展示单个用量事件：

事件名称：生成该用量事件的具体操作或触发器
事件 ID：每个事件实例的唯一标识符
客户 ID：与该事件关联的客户
时间戳：事件发生的时间

此视图可帮助你跟踪和监控客户群中的各个用量事件，从而透明了解计费计算和用量模式。

客户分析

Customers 选项卡以详细的表格形式展示客户用量数据，包括以下信息：

可用数据列

string

用于识别客户的电子邮件地址。

string

客户订阅的唯一标识符。

number

在开始收费前，客户套餐中包含的免费单位数量。

currency

超过免费阈值后每个用量单位的费用。

timestamp

客户最近一次用量事件的时间戳。

currency

向客户收取的基于用量的计费总金额。

number

客户已消耗的单位总数。

number

超过免费阈值并正在计费的单位数量。

表格功能

列筛选：使用“Edit Columns”功能显示或隐藏特定数据列
实时更新：用量数据反映最新的消费指标

聚合示例

以下是不同聚合类型工作方式的实际示例：

了解聚合类型

不同的聚合类型适用于不同的计费场景。应根据希望如何衡量和计费用量来选择正确的类型。

实际实现示例

这些示例通过示例事件和预期结果，展示了每种聚合类型在实际场景中的应用。

Count Aggregation - API Calls

场景：跟踪 API 请求总数Meter 配置：

事件名称：api.call
聚合类型：Count
计量单位：calls

示例事件：

{
  "events": [
    {"event_id": "call_1", "customer_id": "cus_123", "event_name": "api.call"},
    {"event_id": "call_2", "customer_id": "cus_123", "event_name": "api.call"},
    {"event_id": "call_3", "customer_id": "cus_123", "event_name": "api.call"}
  ]
}

结果：向客户计费 3 次调用

Sum Aggregation - Data Transfer

场景：根据传输的总字节数计费Meter 配置：

事件名称：data.transfer
聚合类型：Sum
Over Property：bytes
计量单位：GB

示例事件：

{
  "events": [
    {
      "event_id": "transfer_1",
      "customer_id": "cus_123", 
      "event_name": "data.transfer",
      "metadata": {"bytes": 1073741824}
    },
    {
      "event_id": "transfer_2",
      "customer_id": "cus_123",
      "event_name": "data.transfer", 
      "metadata": {"bytes": 536870912}
    }
  ]
}

结果：向客户计费的总传输量为 1.5 GB

Max Aggregation - Peak Concurrent Users

场景：根据并发用户数峰值计费Meter 配置：

事件名称：concurrent.users
聚合类型：Max
Over Property：count
计量单位：users

示例事件：

{
  "events": [
    {
      "event_id": "peak_1",
      "customer_id": "cus_123",
      "event_name": "concurrent.users", 
      "metadata": {"count": 15}
    },
    {
      "event_id": "peak_2",
      "customer_id": "cus_123",
      "event_name": "concurrent.users",
      "metadata": {"count": 23}
    },
    {
      "event_id": "peak_3",
      "customer_id": "cus_123",
      "event_name": "concurrent.users",
      "metadata": {"count": 18}
    }
  ]
}

结果：向客户计费的并发用户峰值为 23

事件筛选示例

Filter by API Endpoint
Filter by Value Range
Complex Multi-Condition Filters

仅统计对特定 endpoint 的 API 调用：筛选配置：

属性：endpoint
比较器：equals
值：/v1/orders

示例事件：

{
  "event_id": "call_1",
  "customer_id": "cus_123",
  "event_name": "api.call",
  "metadata": {
    "endpoint": "/v1/orders",
    "method": "POST"
  }
}

结果：符合筛选条件的事件会被计数。使用其他 endpoint 的事件将被忽略。

仅统计大型文件上传：筛选配置：

属性：file_size
比较器：greater_than
值：1048576（以字节为单位的 1MB）

示例事件：

{
  "event_id": "upload_1",
  "customer_id": "cus_123", 
  "event_name": "file.upload",
  "metadata": {
    "file_size": 5242880,
    "file_type": "image"
  }
}

结果：大于 1MB 的文件会被计数。较小的文件将被忽略。

统计营业时间内的高级 API 调用：使用 AND 逻辑的筛选配置：

属性：plan_type，比较器：equals，值：premium
属性：hour，比较器：greater_than_or_equals，值：9
属性：hour，比较器：less_than，值：17

示例事件：

{
  "event_id": "call_1",
  "customer_id": "cus_123",
  "event_name": "api.call",
  "metadata": {
    "plan_type": "premium",
    "hour": 14,
    "endpoint": "/v1/analytics"
  }
}

结果：营业时间（上午 9 点至下午 5 点）内的高级 API 调用会被计数。

故障排除

解决基于用量的计费实现中的常见问题，确保跟踪和计费准确无误。

常见问题

大多数基于用量的计费问题可归入以下类别：

事件传递和处理问题
Meter 配置问题
数据类型和格式错误
客户 ID 和身份验证问题

调试步骤

排查基于用量的计费问题时：

在事件分析选项卡中验证事件传递
检查 Meter 配置是否与事件结构匹配
验证客户 ID 和 API 身份验证
检查筛选条件和聚合设置

解决方案和修复

Events not showing in meter

常见原因：

事件名称与 Meter 配置不完全匹配
事件筛选条件排除了你的事件
客户 ID 不存在于你的 Dodo Payments 账户中
事件时间戳不在当前计费周期内

解决方案：

验证事件名称的拼写和大小写
检查并测试筛选条件
确认客户 ID 有效且处于活动状态
检查事件时间戳是否为近期时间并且格式正确

Aggregation not working as expected

常见原因：

Over Property 名称与事件元数据键不匹配
元数据值的数据类型错误（字符串而不是数字）
缺少必需的元数据属性

解决方案：

确保元数据键与 Over Property 设置完全匹配
在事件中将字符串数字转换为实际数字
在每个事件中包含所有必需属性

Filtering not working

常见原因：

筛选属性名称与事件元数据不匹配
数据类型使用了错误的比较器（字符串而不是数字）
字符串比较存在大小写敏感问题

解决方案：

仔细检查属性名称是否完全匹配
根据数据类型使用适当的比较器
筛选字符串时考虑大小写敏感性

Create Meter

用于创建和配置用量 Meter 以跟踪客户消费量的 API 参考

Ingest Usage Events

用于向已配置的 Meter 发送用量事件以进行计费计算的 API 参考

Integration Guides

Billing Deconstructions

Cookbooks

API Reference - Events Ingestion

API Reference - Meters Creation

创建计量器

逐步创建计量器

链接计量器到产品

产品配置过程

发送使用事件

事件结构

使用事件 API 示例

可靠摄取需要了解的关键事项

基于用量的计费分析

概览分析

活动指标

Meter 数量图表

事件分析

事件信息显示

客户分析

可用数据列

表格功能

聚合示例

了解聚合类型

实际实现示例

事件筛选示例

故障排除

常见问题

调试步骤

解决方案和修复

相关 API 参考

Create Meter

Ingest Usage Events

API Reference - Events Ingestion

API Reference - Meters Creation

​创建计量器

​逐步创建计量器

​链接计量器到产品

​产品配置过程

​发送使用事件

​事件结构

​使用事件 API 示例

​可靠摄取需要了解的关键事项

​基于用量的计费分析

​概览分析

​活动指标

​Meter 数量图表

​事件分析

​事件信息显示

​客户分析

​可用数据列

​表格功能

​聚合示例

​了解聚合类型

​实际实现示例

​事件筛选示例

​故障排除

​常见问题

​调试步骤

​解决方案和修复

​相关 API 参考

Create Meter

Ingest Usage Events

创建计量器

逐步创建计量器

链接计量器到产品

产品配置过程

发送使用事件

事件结构

使用事件 API 示例

可靠摄取需要了解的关键事项

基于用量的计费分析

概览分析

活动指标

Meter 数量图表

事件分析

事件信息显示

客户分析

可用数据列

表格功能

聚合示例

了解聚合类型

实际实现示例

事件筛选示例

故障排除

常见问题

调试步骤

解决方案和修复

相关 API 参考