クレジットトランザクション

クレジットトランザクションオブジェクトは、顧客のクレジット残高のすべての変更を記録します。これには、付与、消費、調整、失効が含まれます。この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コール使用量",
  "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コール"
  },
  "subscription": {
    "id": "sub_yz123456",
    "description": "プレミアムプラン"
  },
  "creditGrant": {
    "id": "cg_ijklmnop",
    "name": "初期付与"
  }
}

クレジットトランザクションの一覧表示

クレジットトランザクションのページ分割されたリストを返します。さまざまなパラメーターに基づいてリストをフィルタリングできます。

トランザクションの一覧表示

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",
      // ... その他のフィールドと展開されたオブジェクト
    }
    // ... その他のトランザクション
  ],
  "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"
  }
}