メインコンテンツへスキップ

メーターイベント

メーターイベントは、特定のMeterに報告する使用状況の記録です。各イベントは、顧客によって実行された定量化可能なアクションを表し、使用量ベースまたはクレジット請求モデルで残高からクレジットを差し引くために使用できます。イベントを報告する前に、まずメーターを作成する必要があります。

メーターイベントは、特定のMeterに報告する使用状況の記録です。各イベントは、顧客によって実行された定量化可能なアクションを表し、使用量ベースまたはクレジット請求モデルで残高からクレジットを差し引くために使用できます。イベントを報告する前に、まずメーターを作成する必要があります。

このAPIを使用すると、メーターイベントの作成、取得、一覧表示、分析ができます。

メーターイベントオブジェクト

メーターイベントオブジェクトは、報告された単一の使用イベントを表します。展開された形式には、顧客やサブスクリプションなどの関連オブジェクトが含まれます。

AttributeTypeDescription
idstringメーターイベントの一意の識別子。
event_namestringイベントの名前。関連付けられたメーターのevent_nameに対応します。
payloadobject顧客IDや使用量などのイベントのコア詳細を含みます。
identifierstringべき等性を確保するために提供されるイベントの一意の識別子。同じ識別子を持つ後続のcreate呼び出しでは、新しいイベントは作成されません。
statusstringイベントの処理ステータス。pending、processed、failed、requires_action、またはrequires_captureのいずれかです。
livemodebooleanイベントがライブモードで作成された場合はtrue、テストモードの場合はfalse。
credit_consumedstring処理後にこのイベントによって消費されたクレジットの量。
credit_pendingstringこのイベントで消費が保留されているクレジットの量。
timestampnumberイベントが発生したときのUnixタイムスタンプ。
created_atstringシステムでイベントが作成されたときのタイムスタンプ。
metadataobjectイベントに添付できるキーと値のペアのセット。
customerobject(展開) このイベントに関連付けられた完全な顧客オブジェクト。
subscriptionobject(展開) イベントがリンクされている場合の完全なサブスクリプションオブジェクト。
meterobject(展開) このイベントに関連付けられた完全なメーターオブジェクト。

メーターイベントの作成

使用イベントをシステムに報告します。このアクションはべき等です。同じidentifierを持つイベントが既に存在する場合、システムは新しいイベントを作成しません。

メーターイベントの作成

javascript
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'
  }
});

パラメータ

NameTypeDescription
event_namestring必須。 イベントの名前。これはアクティブなMeterのevent_nameと一致する必要があります。
identifierstring必須。 このイベントを識別するための一意の文字列で、べき等性のために使用されます。最大255文字。
payloadobject必須。 イベントのコアデータを含むオブジェクト。詳細は以下を参照してください。
timestampnumberオプション。 イベントが発生した日時を表すUnixタイムスタンプ。指定しない場合、API呼び出し時の時刻がデフォルトになります。
metadataRecord<string, any>オプション。 イベントに関する追加情報を保存するためのキーと値のペアのセット。

ペイロードオブジェクトのプロパティ

NameTypeDescription
customer_idstring必須。 イベントをトリガーした顧客のID。
valuestring必須。 報告する使用量。これは文字列として表現される正の数である必要があります。
subscription_idstringオプション。 この使用量を関連付けるサブスクリプションのID。サブスクリプションはクレジットを消費するものである必要があります。

戻り値

作成されたメーターイベントオブジェクトを返します。作成時に、イベントは非同期処理のためにキューに入れられます。返されるオブジェクトには、キューに入れられた状態を示すprocessingフィールドが含まれます。

Response

json
{
  "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": "クレジット消費は非同期で処理されます"
  }
}

メーターイベントの取得

一意のIDによって特定のメーターイベントの詳細を取得します。

メーターイベントの取得

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

パラメータ

NameTypeDescription
idstring必須。 取得するメーターイベントの一意の識別子。

戻り値

メーターイベントオブジェクトを返します。利用可能な場合は、展開されたcustomer、subscription、meterの詳細が含まれます。

Response

json
{
  "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": { /* メーターオブジェクト */ }
}

メーターイベントの一覧表示

ページ分割されたメーターイベントのリストを返します。さまざまなパラメータを使用してリストをフィルタリングできます。

メーターイベントの一覧表示

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

パラメータ

NameTypeDescription
customer_idstringオプション。 特定の顧客IDでイベントをフィルタリングします。
meter_idstringオプション。 特定のメーターIDに関連付けられたイベントをフィルタリングします。
event_namestringオプション。 イベント名でフィルタリングします。
startnumberオプション。 この時刻以降に作成されたイベントをフィルタリングするためのUnixタイムスタンプ。
endnumberオプション。 この時刻以前に作成されたイベントをフィルタリングするためのUnixタイムスタンプ。
livemodebooleanオプション。 livemodeステータスでイベントをフィルタリングします。
qstringオプション。 一般的な検索クエリ文字列。
pagenumberオプション。 ページネーションのためのページ番号。1から始まります。
pageSizenumberオプション。 1ページあたりに返すイベントの数。デフォルトは20です。

戻り値

メーターイベントオブジェクトのリストを含むページ分割されたオブジェクトを返します。

Response

json
{
  "count": 15,
  "list": [
    {
      "id": "mevt_xxxxxxxxxxxxxx",
      "event_name": "api_calls",
      // ... その他のイベントプロパティ
    }
    // ... その他のイベント
  ],
  "paging": {
    "page": 1,
    "pageSize": 10
  }
}

メーターイベント統計の取得

指定された期間にわたる特定のメーターの集計統計を取得します。

メーターイベント統計の取得

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

パラメータ

NameTypeDescription
meter_idstring必須。 統計を取得するメーターのID。
startnumber必須。 期間の開始を示すUnixタイムスタンプ。
endnumber必須。 期間の終了を示すUnixタイムスタンプ。
customer_idstringオプション。 特定の顧客の統計をフィルタリングします。
granularitystringオプション。 統計の時間的粒度。'minute'、'hour'、または'day'が指定できます。デフォルトは'day'です。

戻り値

指定された粒度で集計された統計データポイントのリストを返します。

Response

json
{
  "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"
    }
    // ... その他のデータポイント
  ]
}

保留中の金額の取得

処理が保留中でアクションが必要な（例：まだクレジットを消費していない）メーターイベントの合計値を計算します。これは未処理の使用状況を把握するのに役立ちます。

保留中の金額の取得

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

パラメータ

NameTypeDescription
subscription_idstringオプション。 特定のサブスクリプションIDでフィルタリングします。
customer_idstringオプション。 特定の顧客IDでフィルタリングします。
currency_idstringオプション。 特定の通貨IDでフィルタリングします。

戻り値

通貨ごとにグループ化された、保留中の合計金額を要約したオブジェクトを返します。

Response

json
{
  "currency_id": "ccy_xxxxxxxxxxxxxx",
  "total_pending_amount": "12500",
  "currency": {
    "id": "ccy_xxxxxxxxxxxxxx",
    "name": "Credit",
    "decimal": 2
  }
}