Meter Events

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.

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.

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

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.

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

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.

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

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.

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

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.

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