點數交易 | ArcBlock

點數交易物件記錄了客戶點數餘額的每一次變動。這包括授予、消耗、調整和到期。您可以使用此 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": {
    "id": "sub_yz123456",
    "description": "Premium Plan"
  },
  "creditGrant": {
    "id": "cg_ijklmnop",
    "name": "Initial Grant"
  }
}

列出點數交易

回傳一個分頁的點數交易列表。您可以根據各種參數過濾列表。

列出交易

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"
  }
}