跳到主要內容

Meter 事件

Meter 事件是您回報給特定 Meter 的使用記錄。每個事件代表客戶執行的可量化操作，可用於在使用量計費或點數計費模型中從其餘額中扣除點數。在回報事件之前，您必須先建立一個 Meter。

此 API 可讓您建立、擷取、列出和分析 meter 事件。

Meter Event 物件

Meter Event 物件代表單一回報的使用事件。展開形式包括相關物件，如客戶和訂閱。

AttributeTypeDescription
idstringmeter 事件的唯一識別碼。
event_namestring事件的名稱，對應於相關 Meter 的 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（展開）與此事件關聯的完整 Customer 物件。
subscriptionobject（展開）如果事件連結到訂閱，則為完整的 Subscription 物件。
meterobject（展開）與此事件關聯的完整 Meter 物件。

建立 Meter Event

向系統回報使用事件。此操作是冪等的；如果已存在具有相同 identifier 的事件，系統將不會建立新事件。

建立 Meter Event

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' // Optional
  },
  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>選用。 用於儲存有關事件的額外資訊的一組鍵值對。

Payload 物件屬性

NameTypeDescription
customer_idstring必要。 觸發事件的客戶 ID。
valuestring必要。 要回報的使用量。應為以字串表示的正數。
subscription_idstring選用。 要與此使用量關聯的訂閱 ID。該訂閱必須消耗點數。

傳回值

傳回建立的 Meter Event 物件。建立後，事件會排入佇列進行非同步處理。傳回的物件包含一個 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": "Credit consumption will be processed asynchronously"
  }
}

擷取 Meter Event

依據其唯一 ID 擷取特定 meter 事件的詳細資訊。

擷取 Meter Event

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

參數

NameTypeDescription
idstring必要。 要擷取的 meter 事件的唯一識別碼。

傳回值

傳回 Meter Event 物件，如果可用，則包含展開的 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": { /* Customer object */ },
  "subscription": { /* Subscription object */ },
  "meter": { /* Meter object */ }
}

列出 Meter Event

傳回 meter 事件的分頁列表。您可以使用各種參數篩選列表。

列出 Meter Events

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

參數

NameTypeDescription
customer_idstring選用。 依特定客戶 ID 篩選事件。
meter_idstring選用。 篩選與特定 meter ID 關聯的事件。
event_namestring選用。 依事件名稱篩選。
startnumber選用。 用於篩選在此時間或之後建立的事件的 Unix 時間戳。
endnumber選用。 用於篩選在此時間或之前建立的事件的 Unix 時間戳。
livemodeboolean選用。 依 livemode 狀態篩選事件。
qstring選用。 一般搜尋查詢字串。
pagenumber選用。 分頁的頁碼，從 1 開始。
pageSizenumber選用。 每頁傳回的事件數。預設為 20。

傳回值

傳回包含 Meter Event 物件列表的分頁物件。

Response

json
{
  "count": 15,
  "list": [
    {
      "id": "mevt_xxxxxxxxxxxxxx",
      "event_name": "api_calls",
      // ... other event properties
    }
    // ... more events
  ],
  "paging": {
    "page": 1,
    "pageSize": 10
  }
}

取得 Meter Event 統計資料

擷取指定時間段內特定 meter 的彙總統計資料。

取得 Meter Event 統計資料

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

參數

NameTypeDescription
meter_idstring必要。 要擷取統計資料的 meter 的 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"
    }
    // ... more data points
  ]
}

取得待處理金額

計算待處理且需要採取行動（例如，尚未消耗點數）的 meter 事件總值。這有助於了解未結清的使用量。

取得待處理金額

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