信用交易

信用交易对象记录客户信用余额的每一次变动。这包括授予、消耗、调整和过期。您可以使用此 API 检索客户信用活动的详细历史记录。

每笔交易都提供了事件发生时信用余额的快照，使其成为审计和跟踪信用使用情况的可靠账本。有关信用管理的更高级别概述，请参阅基于信用的计费指南。

信用交易对象#

CreditTransaction 对象包含有关单个信用事件的详细信息。

Attribute

Type

Description

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

对象创建时的时间戳。

updated_at

string

对象最后更新的时间戳。

metadata

object

（可选）可以附加到对象的一组键值对。

检索信用交易#

通过其唯一 ID 检索特定信用交易的详细信息。

检索交易

const transaction = await payment.creditTransactions.retrieve(
  'ct_xxxxxxxxxxxxxx'
);

console.log(transaction);

参数

Name

Type

Description

id

string

必需。 要检索的信用交易的唯一标识符。

返回

如果提供了有效的 ID，则返回 TCreditTransactionExpanded 对象。否则，此调用将返回错误。

响应示例

{
  "id": "ct_123456789",
  "customer_id": "cus_abcdefgh",
  "credit_grant_id": "cg_ijklmnop",
  "meter_id": "mtr_qrstuvwx",
  "subscription_id": "sub_yz123456",
  "meter_event_id": "me_7890abcd",
  "type": "consumption",
  "amount": "-100.00",
  "running_balance": "900.00",
  "description": "API Call Usage",
  "livemode": true,
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "metadata": {},
  "customer": {
    "id": "cus_abcdefgh",
    "name": "John Doe",
    "email": "john.doe@example.com"
  },
  "meter": {
    "id": "mtr_qrstuvwx",
    "name": "API Calls"
  },
  "subscription": {

See all 8 lines

列出信用交易#

返回一个分页的信用交易列表。您可以根据各种参数筛选列表。

列出交易

const transactions = await payment.creditTransactions.list({
  customer_id: 'cus_xxxxxxxxxxxxxx',
  limit: 10,
});

console.log(transactions);

参数

Name

Type

Description

page

number

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

pageSize

number

可选。每页返回的项目数。默认为 20。

customer_id

string

可选。筛选特定客户的交易。

subscription_id

string

可选。筛选特定订阅的交易。

credit_grant_id

string

可选。筛选源自特定信用授予的交易。

meter_id

string

可选。筛选与特定计量器相关的交易。

source

string

可选。按交易来源筛选。

start

number

可选。一个 Unix 时间戳，用于筛选在此时间之后（含此时间）创建的交易。

end

number

可选。一个 Unix 时间戳，用于筛选在此时间之前（含此时间）创建的交易。

livemode

boolean

可选。指定是获取生产模式还是测试模式的交易。

q

string

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

返回

返回一个分页的 TCreditTransactionExpanded 对象列表。

响应示例

{
  "count": 15,
  "list": [
    {
      "id": "ct_123456789",
      "customer_id": "cus_abcdefgh",
      "credit_grant_id": "cg_ijklmnop",
      "type": "consumption",
      "amount": "-100.00",
      "running_balance": "900.00",
      "livemode": true,
      "created_at": "2023-10-27T10:00:00.000Z",
      // ... other fields and expanded objects
    }
    // ... more transactions
  ],
  "paging": {
    "page": 1,
    "pageSize": 10
  }
}

获取用量摘要#

检索客户、订阅或计量器在指定时间段内的信用消耗摘要。

获取用量摘要

const summary = await payment.creditTransactions.summary({
  customer_id: 'cus_xxxxxxxxxxxxxx',
  start: Math.floor(new Date('2023-01-01').getTime() / 1000),
  end: Math.floor(new Date('2023-12-31').getTime() / 1000),
});

console.log(summary);

参数

Name

Type

Description

customer_id

string

可选。要汇总用量的客户 ID。

subscription_id

string

可选。要汇总用量的订阅 ID。

currency_id

string

可选。按特定信用货币筛选摘要。

meter_id

string

可选。按特定计量器筛选摘要。

start

number

可选。报告期开始的 Unix 时间戳。

end

number

可选。报告期结束的 Unix 时间戳。

返回

返回一个 UsageSummary 对象，详细说明指定筛选条件内的总消耗量和交易计数。

响应示例

{
  "total_quantity": "1500",
  "total_credit_amount": "-1500.00",
  "transaction_count": 42,
  "filters": {
    "customer_id": "cus_xxxxxxxxxxxxxx",
    "start_time": "2023-01-01T00:00:00.000Z",
    "end_time": "2023-12-31T00:00:00.000Z"
  }
}
信用额度授予
客户