Meter Events | ArcBlock

Meter Events are records of usage that you report to a specific Meter. Each event represents a quantifiable action performed by a customer, which can then be used to deduct credits from their balance in a usage-based or credit billing model. Before reporting events, you must first create a Meter.

This API allows you to create, retrieve, list, and analyze meter events.

The Meter Event Object

A Meter Event object represents a single reported usage event. The expanded form includes related objects like the customer and subscription.

Attribute	Type	Description
`id`	`string`	Unique identifier for the meter event.
`event_name`	`string`	The name of the event, which corresponds to the `event_name` of an associated Meter.
`payload`	`object`	Contains the core details of the event, such as the customer ID and usage value.
`identifier`	`string`	A unique identifier for the event provided by you to ensure idempotency. Subsequent `create` calls with the same identifier will not create a new event.
`status`	`string`	The processing status of the event. Can be `pending`, `processed`, `failed`, `requires_action`, or `requires_capture`.
`livemode`	`boolean`	`true` if the event was created in live mode, `false` for test mode.
`credit_consumed`	`string`	The amount of credit consumed by this event after processing.
`credit_pending`	`string`	The amount of credit that is pending consumption for this event.
`timestamp`	`number`	The Unix timestamp when the event occurred.
`created_at`	`string`	The timestamp when the event was created in the system.
`metadata`	`object`	A set of key-value pairs that you can attach to the event.
`customer`	`object`	(Expanded) The full Customer object associated with this event.
`subscription`	`object`	(Expanded) The full Subscription object if the event is linked to one.
`meter`	`object`	(Expanded) The full Meter object associated with this event.

Create a Meter Event

Reports a usage event to the system. This action is idempotent; if an event with the same identifier already exists, the system will not create a new one.

Create a Meter Event

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

Parameters

Name	Type	Description
`event_name`	`string`	Required. The name of the event. This must match the `event_name` of an active `Meter`.
`identifier`	`string`	Required. A unique string to identify this event, used for idempotency. Maximum 255 characters.
`payload`	`object`	Required. An object containing the event's core data. See details below.
`timestamp`	`number`	Optional. A Unix timestamp representing when the event occurred. If not provided, it defaults to the time of the API call.
`metadata`	`Record<string, any>`	Optional. A set of key-value pairs to store additional information about the event.

Payload Object Properties

Name	Type	Description
`customer_id`	`string`	Required. The ID of the customer who triggered the event.
`value`	`string`	Required. The amount of usage to report. This should be a positive number represented as a string.
`subscription_id`	`string`	Optional. The ID of the subscription to associate this usage with. The subscription must consume credits.

Returns

Returns the created Meter Event object. Upon creation, the event is queued for asynchronous processing. The returned object includes a processing field that indicates its queued status.

Response

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

Retrieve a Meter Event

Retrieves the details of a specific meter event by its unique ID.

Retrieve a Meter Event

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

Parameters

Name	Type	Description
`id`	`string`	Required. The unique identifier of the meter event to retrieve.

Returns

Returns the Meter Event object, including expanded customer, subscription, and meter details if available.

Response

{
  "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 */ }
}

List Meter Events

Returns a paginated list of meter events. You can filter the list using various parameters.

List Meter Events

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

Parameters

Name	Type	Description
`customer_id`	`string`	Optional. Filter events by a specific customer ID.
`meter_id`	`string`	Optional. Filter events associated with a specific meter ID.
`event_name`	`string`	Optional. Filter events by their name.
`start`	`number`	Optional. A Unix timestamp to filter events created on or after this time.
`end`	`number`	Optional. A Unix timestamp to filter events created on or before this time.
`livemode`	`boolean`	Optional. Filter events by their `livemode` status.
`q`	`string`	Optional. A general search query string.
`page`	`number`	Optional. The page number for pagination, starting from 1.
`pageSize`	`number`	Optional. The number of events to return per page. Defaults to 20.

Returns

Returns a paginated object containing a list of Meter Event objects.

Response

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

Get Meter Event Stats

Retrieves aggregated statistics for a given meter over a specified time period.

Get Meter Event Stats

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

Parameters

Name	Type	Description
`meter_id`	`string`	Required. The ID of the meter to retrieve statistics for.
`start`	`number`	Required. A Unix timestamp for the beginning of the time range.
`end`	`number`	Required. A Unix timestamp for the end of the time range.
`customer_id`	`string`	Optional. Filter statistics for a specific customer.
`granularity`	`string`	Optional. The temporal granularity of the statistics. Can be `'minute'`, `'hour'`, or `'day'`. Defaults to `'day'`.

Returns

Returns a list of statistical data points, aggregated by the specified granularity.

Response

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

Get Pending Amount

Calculates the total value of meter events that are pending processing and require action (e.g., have not yet consumed credit). This is useful for understanding outstanding usage.

Get Pending Amount

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

Parameters

Name	Type	Description
`subscription_id`	`string`	Optional. Filter by a specific subscription ID.
`customer_id`	`string`	Optional. Filter by a specific customer ID.
`currency_id`	`string`	Optional. Filter by a specific currency ID.

Returns

Returns an object summarizing the total pending amounts, grouped by currency.

Response

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