API 参考

积分交易

积分交易是不可变的记录，用于跟踪积分的授予、消耗、调整和到期。它们为每个客户提供了所有积分相关活动的详细账本，这对于审计和理解使用模式至关重要。
每笔交易都与一个 customer 和一个 credit_grant 相关联。有关如何发放积分的更多信息，请参阅 Credit Grants 文档。要了解如何跟踪使用情况，请参阅 Meters 和 Meter Events。
积分交易对象#一个积分交易对象包含单次积分事件的详细信息。
属性
类型
描述
id
string
积分交易的唯一标识符。
customer_id
string
与此交易关联的客户 ID。
credit_grant_id
string
此交易所源自的积分授予 ID。
meter_id
string
（可选）触发消耗交易的计量器 ID。
subscription_id
string
（可选）与此交易相关的订阅 ID。
meter_event_id
string
（可选）导致此消耗的计量器事件 ID。
type
string
交易类型。可以是 grant、consumption、adjustment 或 expiration。
amount
string
交易的积分数量。对于增加积分的授予和调整，此值为正；对于消耗和到期，此值为负。
running_balance
string
此交易发生后，该积分授予的实时余额。
description
string
（可选）交易的内部描述。
livemode
boolean
如果交易在实时模式下创建，则为 true；对于测试模式，则为 false。
created_at
string
交易创建时的时间戳（ISO 8601 格式）。
updated_at
string
上次更新的时间戳（ISO 8601 格式）。
metadata
object
（可选）可以附加到对象上的一组键值对。
检索交易#通过唯一 ID 获取特定积分交易的详细信息。
参数
名称
类型
描述
id
string
要检索的积分交易的唯一标识符。
返回
一个 TCreditTransactionExpanded 对象，包含交易的完整详细信息。
示例
async function getCreditTransaction(transactionId) {
  try {
    const transaction = await payment.creditTransactions.retrieve(transactionId);
    console.log('Retrieved Transaction:', transaction);
  } catch (error) {
    console.error('Error retrieving transaction:', error.message);
  }
}

// 将 'crtrx_xxxxxxxx' 替换为有效的交易 ID
getCreditTransaction('crtrx_xxxxxxxx');响应示例
{
  "id": "crtrx_xxxxxxxxxxxxxx",
  "customer_id": "cust_xxxxxxxxxxxxxx",
  "credit_grant_id": "crg_xxxxxxxxxxxxxx",
  "meter_id": "mtr_xxxxxxxxxxxxxx",
  "subscription_id": "sub_xxxxxxxxxxxxxx",
  "meter_event_id": "mevt_xxxxxxxxxxxxxx",
  "type": "consumption",
  "amount": "-100",
  "running_balance": "900",
  "description": "API Call Usage",
  "livemode": false,
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "metadata": {}
}列出交易#返回积分交易的分页列表。您可以根据各种参数筛选列表。
参数
名称
类型
描述
customer_id
string
（可选）按特定客户 ID 筛选交易。
subscription_id
string
（可选）按特定订阅 ID 筛选交易。
credit_grant_id
string
（可选）按特定积分授予 ID 筛选交易。
start
number
（可选）一个 Unix 时间戳，用于筛选在此时间之后创建的交易。
end
number
（可选）一个 Unix 时间戳，用于筛选在此时间之前创建的交易。
livemode
boolean
（可选）设置为 true 仅返回实时模式对象，或设置为 false 仅返回测试模式对象。
q
string
（可选）用于在相关字段上进行自由文本搜索的搜索查询字符串。
page
number
（可选）用于分页的页码，从 1 开始。
pageSize
number
（可选）每页返回的项目数。默认为 20。
order
string[] or string
（可选）对结果进行排序的顺序（例如，['created_at', 'DESC']）。
返回
一个包含积分交易对象列表的分页对象。
名称
类型
描述
count
number
与查询匹配的交易总数。
list
TCreditTransactionExpanded[]
当前页面的积分交易对象数组。
示例
async function listCustomerTransactions(customerId) {
  try {
    const transactions = await payment.creditTransactions.list({
      customer_id: customerId,
      pageSize: 5
    });
    console.log(`Found ${transactions.count} transactions.`);
    transactions.list.forEach(tx => {
      console.log(`- ID: ${tx.id}, Type: ${tx.type}, Amount: ${tx.amount}`);
    });
  } catch (error) {
    console.error('Error listing transactions:', error.message);
  }
}

// 将 'cust_xxxxxxxx' 替换为有效的客户 ID
listCustomerTransactions('cust_xxxxxxxx');响应示例
{
  "count": 25,
  "list": [
    {
      "id": "crtrx_xxxxxxxxxxxxxx",
      "customer_id": "cust_xxxxxxxx",
      "credit_grant_id": "crg_xxxxxxxxxxxxxx",
      "type": "consumption",
      "amount": "-50",
      "running_balance": "850",
      "livemode": false,
      "created_at": "2023-10-27T11:00:00.000Z",
      "updated_at": "2023-10-27T11:00:00.000Z"
    },
    {
      "id": "crtrx_yyyyyyyyyyyyyy",
      "customer_id": "cust_xxxxxxxx",
      "credit_grant_id": "crg_xxxxxxxxxxxxxx",
      "type": "grant",
      "amount": "1000",
      "running_balance": "1000",
      "livemode": false,
      "created_at": "2023-10-01T09:00:00.000Z",
      "updated_at": "2023-10-01T09:00:00.000Z"
    }
  ]
}获取使用摘要#为客户或订阅提供指定时期内积分使用情况的摘要视图。
参数
名称
类型
描述
customer_id
string
（可选）要为其生成摘要的客户 ID。
subscription_id
string
（可选）要为其生成摘要的订阅 ID。
currency_id
string
（可选）按特定货币 ID 筛选摘要。
start
number
（可选）定义摘要周期开始的 Unix 时间戳。
end
number
（可选）定义摘要周期结束的 Unix 时间戳。
返回
一个 UsageSummary 对象，包含汇总的积分数据。
名称
类型
描述
total_consumption
string
该时期内消耗的积分总额。
total_grants
string
该时期内授予的积分总额。
net_balance
string
积分余额的净变化（total_grants - total_consumption）。
transaction_count
number
该时期内的交易总数。
breakdown
object
一个提供更详细使用明细的对象。
breakdown.by_type
object
按交易类型（grant、consumption 等）分列的使用明细。
breakdown.by_meter
object
（可选）按计量器分列的使用明细（如果适用）。
示例
async function getCreditSummary(customerId) {
  try {
    const summary = await payment.creditTransactions.summary({
      customer_id: customerId
    });
    console.log('Usage Summary:', summary);
  } catch (error) {
    console.error('Error getting usage summary:', error.message);
  }
}

// 将 'cust_xxxxxxxx' 替换为有效的客户 ID
getCreditSummary('cust_xxxxxxxx');响应示例
{
  "customer_id": "cust_xxxxxxxx",
  "total_consumption": "150",
  "total_grants": "1000",
  "net_balance": "850",
  "transaction_count": 12,
  "breakdown": {
    "by_type": {
      "grant": {
        "amount": "1000",
        "count": 1
      },
      "consumption": {
        "amount": "150",
        "count": 11
      }
    },
    "by_meter": {
      "mtr_xxxxxxxxxxxxxx": {
        "amount": "100",
        "count": 8,
        "meter_name": "API Calls"
      },
      "mtr_yyyyyyyyyyyyyy": {
        "amount": "50",
        "count": 3,
        "meter_name": "Data Storage"
      }
    }
  }
}
借助这些工具，您可以有效地监控和分析应用程序中的积分活动。关于实现基于积分的系统的更高级别概述，请参阅我们的积分计费指南。

属性	类型	描述
`id`	`string`	积分交易的唯一标识符。
`customer_id`	`string`	与此交易关联的客户 ID。
`credit_grant_id`	`string`	此交易所源自的积分授予 ID。
`meter_id`	`string`	（可选）触发消耗交易的计量器 ID。
`subscription_id`	`string`	（可选）与此交易相关的订阅 ID。
`meter_event_id`	`string`	（可选）导致此消耗的计量器事件 ID。
`type`	`string`	交易类型。可以是 `grant`、`consumption`、`adjustment` 或 `expiration`。
`amount`	`string`	交易的积分数量。对于增加积分的授予和调整，此值为正；对于消耗和到期，此值为负。
`running_balance`	`string`	此交易发生后，该积分授予的实时余额。
`description`	`string`	（可选）交易的内部描述。
`livemode`	`boolean`	如果交易在实时模式下创建，则为 `true`；对于测试模式，则为 `false`。
`created_at`	`string`	交易创建时的时间戳（ISO 8601 格式）。
`updated_at`	`string`	上次更新的时间戳（ISO 8601 格式）。
`metadata`	`object`	（可选）可以附加到对象上的一组键值对。

名称	类型	描述
`customer_id`	`string`	（可选）按特定客户 ID 筛选交易。
`subscription_id`	`string`	（可选）按特定订阅 ID 筛选交易。
`credit_grant_id`	`string`	（可选）按特定积分授予 ID 筛选交易。
`start`	`number`	（可选）一个 Unix 时间戳，用于筛选在此时间之后创建的交易。
`end`	`number`	（可选）一个 Unix 时间戳，用于筛选在此时间之前创建的交易。
`livemode`	`boolean`	（可选）设置为 `true` 仅返回实时模式对象，或设置为 `false` 仅返回测试模式对象。
`q`	`string`	（可选）用于在相关字段上进行自由文本搜索的搜索查询字符串。
`page`	`number`	（可选）用于分页的页码，从 1 开始。
`pageSize`	`number`	（可选）每页返回的项目数。默认为 20。
`order`	`string[]` or `string`	（可选）对结果进行排序的顺序（例如，`['created_at', 'DESC']`）。

名称	类型	描述
`customer_id`	`string`	（可选）要为其生成摘要的客户 ID。
`subscription_id`	`string`	（可选）要为其生成摘要的订阅 ID。
`currency_id`	`string`	（可选）按特定货币 ID 筛选摘要。
`start`	`number`	（可选）定义摘要周期开始的 Unix 时间戳。
`end`	`number`	（可选）定义摘要周期结束的 Unix 时间戳。

名称	类型	描述
`total_consumption`	`string`	该时期内消耗的积分总额。
`total_grants`	`string`	该时期内授予的积分总额。
`net_balance`	`string`	积分余额的净变化（`total_grants` - `total_consumption`）。
`transaction_count`	`number`	该时期内的交易总数。
`breakdown`	`object`	一个提供更详细使用明细的对象。
`breakdown.by_type`	`object`	按交易类型（`grant`、`consumption` 等）分列的使用明细。
`breakdown.by_meter`	`object`	（可选）按计量器分列的使用明细（如果适用）。

概述

快速入门

核心概念

使用指南

API 参考

TypeScript 支持

积分交易

积分交易对象#

检索交易#

列出交易#

获取使用摘要#

信用额度授予

TypeScript 支持

名称	类型	描述
`count`	`number`	与查询匹配的交易总数。
`list`	`TCreditTransactionExpanded[]`	当前页面的积分交易对象数组。