Meter 事件

Meter 事件是您向特定 Meter 报告的使用记录。每个事件代表客户执行的可量化操作，可用于在使用量计费或信用计费模型中从其余额中扣除信用。在报告事件之前，您必须首先创建一个 Meter。

此 API 允许您创建、检索、列出和分析 meter 事件。

Meter 事件对象#

Meter 事件对象表示单个报告的使用事件。展开形式包括相关对象，如客户和订阅。

属性

类型

描述

id

string

Meter 事件的唯一标识符。

event_name

string

事件的名称，与关联 Meter 的 event_name 相对应。

payload

object

包含事件的核心详细信息，例如客户 ID 和使用量值。

identifier

string

由您提供的事件唯一标识符，以确保幂等性。后续使用相同标识符的 create 调用不会创建新事件。

status

string

事件的处理状态。可以是 pending、processed、failed、requires_action 或 requires_capture。

livemode

boolean

如果在生产模式下创建事件，则为 true，在测试模式下则为 false。

credit_consumed

string

此事件处理后消耗的信用额度。

credit_pending

string

此事件待消耗的信用额度。

timestamp

number

事件发生时的 Unix 时间戳。

created_at

string

在系统中创建事件时的时间戳。

metadata

object

您可以附加到事件的一组键值对。

customer

object

（展开）与此事件关联的完整客户对象。

subscription

object

（展开）如果事件链接到订阅，则为完整的订阅对象。

meter

object

（展开）与此事件关联的完整 Meter 对象。

创建 Meter 事件#

向系统报告一个使用事件。此操作是幂等的；如果已存在具有相同 identifier 的事件，系统将不会创建新事件。

创建 Meter 事件

const event = await payment.meterEvents.create({
  event_name: 'api_calls',
  identifier: 'unique-event-id-12345',
  payload: {
    customer_id: 'cus_xxxxxxxxxxxxxx',
    value: '100',
    subscription_id: 'sub_xxxxxxxxxxxxxx' // 可选
  },
  timestamp: Math.floor(Date.now() / 1000),
  metadata: {
    region: 'us-west'
  }
});

参数#

名称

类型

描述

event_name

string

必需。 事件的名称。这必须与活动 Meter 的 event_name 匹配。

identifier

string

必需。 用于标识此事件的唯一字符串，用于幂等性。最多 255 个字符。

payload

object

必需。 包含事件核心数据的对象。详见下文。

timestamp

number

可选。 表示事件发生时间的 Unix 时间戳。如果未提供，则默认为 API 调用的时间。

metadata

Record<string, any>

可选。 用于存储有关事件的附加信息的一组键值对。

Payload 对象属性

名称

类型

描述

customer_id

string

必需。 触发事件的客户 ID。

value

string

必需。 要报告的使用量。这应该是一个表示为字符串的正数。

subscription_id

string

可选。 要与此使用量关联的订阅 ID。该订阅必须消耗信用。

返回值#

返回创建的 Meter 事件对象。创建后，事件将排队等待异步处理。返回的对象包含一个 processing 字段，用于指示其排队状态。

响应

{
  "id": "mevt_xxxxxxxxxxxxxx",
  "event_name": "api_calls",
  "payload": {
    "customer_id": "cus_xxxxxxxxxxxxxx",
    "value": "100",
    "subscription_id": "sub_xxxxxxxxxxxxxx"
  },
  "identifier": "unique-event-id-12345",
  "status": "pending",
  "livemode": false,
  "credit_consumed": "0",
  "credit_pending": "100",
  "timestamp": 1678886400,
  "created_at": "2023-03-15T12:00:00.000Z",
  "metadata": {
    "region": "us-west"
  },
  "processing": {
    "queued": true,
    "message": "Credit consumption will be processed asynchronously"
  }
}

检索 Meter 事件#

通过其唯一 ID 检索特定 meter 事件的详细信息。

检索 Meter 事件

const eventId = 'mevt_xxxxxxxxxxxxxx';
const event = await payment.meterEvents.retrieve(eventId);

参数#

名称

类型

描述

id

string

必需。 要检索的 meter 事件的唯一标识符。

返回值#

返回 Meter 事件对象，如果可用，则包括展开的 customer、subscription 和 meter 详细信息。

响应

{
  "id": "mevt_xxxxxxxxxxxxxx",
  "event_name": "api_calls",
  "payload": {
    "customer_id": "cus_xxxxxxxxxxxxxx",
    "value": "100"
  },
  "identifier": "unique-event-id-12345",
  "status": "processed",
  "livemode": false,
  "credit_consumed": "100",
  "credit_pending": "0",
  "timestamp": 1678886400,
  "created_at": "2023-03-15T12:00:00.000Z",
  "metadata": {},
  "customer": { /* 客户对象 */ },
  "subscription": { /* 订阅对象 */ },
  "meter": { /* Meter 对象 */ }
}

列出 Meter 事件#

返回分页的 meter 事件列表。您可以使用各种参数筛选列表。

列出 Meter 事件

const events = await payment.meterEvents.list({
  customer_id: 'cus_xxxxxxxxxxxxxx',
  start: 1672531200, // 2023年1月1日
  limit: 10
});

参数#

名称

类型

描述

customer_id

string

可选。 按特定客户 ID 筛选事件。

meter_id

string

可选。 筛选与特定 meter ID 关联的事件。

event_name

string

可选。 按事件名称筛选事件。

start

number

可选。 用于筛选在此时间或之后创建的事件的 Unix 时间戳。

end

number

可选。 用于筛选在此时间或之前创建的事件的 Unix 时间戳。

livemode

boolean

可选。 按 livemode 状态筛选事件。

q

string

可选。 通用搜索查询字符串。

page

number

可选。 分页的页码，从 1 开始。

pageSize

number

可选。 每页返回的事件数。默认为 20。

返回值#

返回一个包含 Meter 事件对象列表的分页对象。

响应

{
  "count": 15,
  "list": [
    {
      "id": "mevt_xxxxxxxxxxxxxx",
      "event_name": "api_calls",
      // ... 其他事件属性
    }
    // ... 更多事件
  ],
  "paging": {
    "page": 1,
    "pageSize": 10
  }
}

获取 Meter 事件统计信息#

检索给定 meter 在指定时间段内的聚合统计信息。

获取 Meter 事件统计信息

const stats = await payment.meterEvents.stats({
  meter_id: 'mtr_xxxxxxxxxxxxxx',
  start: 1672531200, // 2023年1月1日
  end: 1675209600,   // 2023年2月1日
  granularity: 'day'
});

参数#

名称

类型

描述

meter_id

string

必需。 要检索统计信息的 meter 的 ID。

start

number

必需。 时间范围开始的 Unix 时间戳。

end

number

必需。 时间范围结束的 Unix 时间戳。

customer_id

string

可选。 筛选特定客户的统计信息。

granularity

string

可选。 统计数据的时间粒度。可以是 'minute'、'hour' 或 'day'。默认为 'day'。

返回值#

返回按指定粒度聚合的统计数据点列表。

响应

{
  "count": 31,
  "list": [
    {
      "date": "2023-01-01",
      "timestamp": "2023-01-01T00:00:00.000Z",
      "event_count": 500,
      "total_value": "5000"
    },
    {
      "date": "2023-01-02",
      "timestamp": "2023-01-02T00:00:00.000Z",
      "event_count": 750,
      "total_value": "7500"
    }
    // ... 更多数据点
  ]
}

获取待处理金额#

计算待处理且需要操作（例如，尚未消耗信用）的 meter 事件的总价值。这对于了解未结清的使用量很有用。

获取待处理金额

const pending = await payment.meterEvents.pendingAmount({
  customer_id: 'cus_xxxxxxxxxxxxxx'
});

参数#

名称

类型

描述

subscription_id

string

可选。 按特定订阅 ID 筛选。

customer_id

string

可选。 按特定客户 ID 筛选。

currency_id

string

可选。 按特定货币 ID 筛选。

返回值#

返回一个按货币分组汇总的总待处理金额的对象。

响应

{
  "currency_id": "ccy_xxxxxxxxxxxxxx",
  "total_pending_amount": "12500",
  "currency": {
    "id": "ccy_xxxxxxxxxxxxxx",
    "name": "Credit",
    "decimal": 2
  }
}
发票
计量器