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

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
        }
      }
    ]
  }'

基于使用量的计费分析

使用全面的分析仪表板监控和分析您的基于使用量的计费数据。跟踪客户消耗模式、计量器表现和计费趋势，以优化您的定价策略并理解使用行为。

概述分析

概述标签提供了您基于使用量的计费绩效的全面视图：

活动指标

跟踪不同时间段的关键使用统计数据：

metric

显示当前计费周期的使用活动，帮助您理解月度消耗模式。

metric

展示自开始跟踪以来的累计使用统计数据，提供长期增长见解。

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

计量器数量图表

计量器数量图表以以下功能可视化时间的使用趋势：

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

图表根据您的使用量和所选时间范围自动缩放，为细微波动和重大使用变化提供清晰的可见性。

事件分析

事件标签提供了个别使用事件的详细可见性：

事件信息显示

事件表提供个体使用事件的清晰视图，具有以下列：

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

此视图允许您跟踪和监控整个客户群的个体使用事件，为计费计算和使用模式提供透明度。

客户分析

客户标签提供详细的客户使用数据表视图，具有以下信息：

可用数据列

string

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

string

客户订阅的唯一标识符。

number

在开始收费之前，客户计划中包含的免费单元数。

currency

超出免费阈值的使用每单位成本。

timestamp

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

currency

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

number

客户已消费的总单元数。

number

已超出免费阈值并被收费的单元数。

表格功能

列过滤：使用“编辑列”功能显示/隐藏特定数据列
实时更新：使用数据反映最当前的消费指标

聚合示例

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

理解聚合类型

不同的聚合类型适用于不同的计费场景。根据您想如何度量和收取使用量来选择合适的类型。

实际实施示例

这些示例展示了每种聚合类型的实际应用场景，包含样本事件和预期结果。

Count Aggregation - API Calls

场景：跟踪 API 请求的总数计量器配置：

事件名称：api.call
聚合类型：计数
测量单位：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

场景：基于传输的字节总数进行计费计量器配置：

事件名称：data.transfer
聚合类型：求和
选择属性：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

场景：基于最高并发用户数进行计费计量器配置：

事件名称：concurrent.users
聚合类型：最大
选择属性：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

仅计算特定端点的 API 调用：过滤配置：

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

样本事件：

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

结果：符合过滤条件的事件将被计算。具有不同端点的事件将被忽略。

仅计算大文件上传：过滤配置：

属性：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"
  }
}

结果：将计算营业时间内的高级 API 调用（上午 9 点 - 下午 5 点）。

故障排除

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

常见问题

大多数基于使用量的计费问题可以归为以下几类：

事件交付和处理问题
计量器配置问题
数据类型和格式错误
客户 ID 和认证问题

调试步骤

在对基于使用量的计费进行故障排除时：

确认事件在事件分析标签中交付
检查计量器配置与您的事件结构是否匹配
验证客户 ID 和 API 认证
审查过滤条件和聚合设置

解决方案和修复

Events not showing in meter

常见原因：

事件名称与计量器配置不完全匹配
事件过滤条件排除了您的事件
客户 ID 不存在于您的 Dodo Payments 账户中
事件时间戳不在当前计费期间内

解决方案：

验证事件名称的拼写和大小写敏感性
审查并测试您的过滤条件
确认客户 ID 有效且活动
检查事件时间戳是否近期并正确格式化

Aggregation not working as expected

常见原因：

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

解决方案：

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

Filtering not working

常见原因：

过滤属性名称与事件元数据不匹配
错误的数据类型比较符（字符串 vs 数字）
字符串比较中的大小写敏感性

解决方案：

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

Create Meter

用于创建和配置使用计量器以跟踪客户消耗的 API 参考

Ingest Usage Events

用于将使用事件发送到已配置的计量器以进行计费计算的 API 参考

Integration Guides

Billing Deconstructions

Cookbooks

API Reference - Events Ingestion

API Reference - Meters Creation

创建计量器

逐步创建计量器

链接计量器到产品

产品配置过程

发送使用事件

事件结构

使用事件 API 示例

基于使用量的计费分析

概述分析

活动指标

计量器数量图表

事件分析

事件信息显示

客户分析

可用数据列

表格功能

聚合示例

理解聚合类型

实际实施示例

事件过滤示例

故障排除

常见问题

调试步骤

解决方案和修复

相关 API 参考

Create Meter

Ingest Usage Events

API Reference - Events Ingestion

API Reference - Meters Creation

​创建计量器

​逐步创建计量器

​链接计量器到产品

​产品配置过程

​发送使用事件

​事件结构

​使用事件 API 示例

​基于使用量的计费分析

​概述分析

​活动指标

​计量器数量图表

​事件分析

​事件信息显示

​客户分析

​可用数据列

​表格功能

​聚合示例

​理解聚合类型

​实际实施示例

​事件过滤示例

​故障排除

​常见问题

​调试步骤

​解决方案和修复

​相关 API 参考

Create Meter

Ingest Usage Events

创建计量器

逐步创建计量器

链接计量器到产品

产品配置过程

发送使用事件

事件结构

使用事件 API 示例

基于使用量的计费分析

概述分析

活动指标

计量器数量图表

事件分析

事件信息显示

客户分析

可用数据列

表格功能

聚合示例

理解聚合类型

实际实施示例

事件过滤示例

故障排除

常见问题

调试步骤

解决方案和修复

相关 API 参考