The Meter Event object

Attributes

objectstring
String representing the object’s type. Objects of the same type share the same value.

createdtimestamp
Time at which the object was created. Measured in seconds since the Unix epoch.

event_namestring
The name of the meter event. Corresponds with the event_name field on a meter.

identifierstring
A unique identifier for the event.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

payloadobject
The payload of the event. This contains the fields corresponding to a meter’s customer_mapping.event_payload_key (default is stripe_customer_id) and value_settings.event_payload_key (default is value). Read more about the payload.

timestamptimestamp
The timestamp passed in when creating the event. Measured in seconds since the Unix epoch.

The Meter Event object

{
  "object": "billing.meter_event",
  "created": 1704824589,
  "event_name": "ai_search_api",
  "identifier": "identifier_123",
  "livemode": true,
  "payload": {
    "value": "25",
    "stripe_customer_id": "cus_NciAYcXfLnqBoz"
  },
  "timestamp": 1680210639
}

Create a billing meter event

Creates a billing meter event.

Parameters

event_namestringRequired
The name of the meter event. Corresponds with the event_name field on a meter.

payloadobjectRequired
The payload of the event. This must contain the fields corresponding to a meter’s customer_mapping.event_payload_key (default is stripe_customer_id) and value_settings.event_payload_key (default is value). Read more about the payload.

identifierstring
A unique identifier for the event. If not provided, one is generated. We recommend using UUID-like identifiers. We will enforce uniqueness within a rolling period of at least 24 hours. The enforcement of uniqueness primarily addresses issues arising from accidental retries or other problems occurring within extremely brief time intervals. This approach helps prevent duplicate entries and ensures data integrity in high-frequency operations.

timestamptimestamp
The time of the event. Measured in seconds since the Unix epoch. Must be within the past 35 calendar days or up to 5 minutes in the future. Defaults to current timestamp if not specified.

Returns

Returns a billing meter event.

POST /v1/billing/meter_events

Server-side language

curl https://api.stripe.com/v1/billing/meter_events \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d event_name=ai_search_api \
  -d "payload[value]"=25 \
  -d "payload[stripe_customer_id]"=cus_NciAYcXfLnqBoz \
  -d identifier=identifier_123

Response

{
  "object": "billing.meter_event",
  "created": 1704824589,
  "event_name": "ai_search_api",
  "identifier": "identifier_123",
  "livemode": true,
  "payload": {
    "value": "25",
    "stripe_customer_id": "cus_NciAYcXfLnqBoz"
  },
  "timestamp": 1680210639
}

Meter Events v2

Meter events are used to report customer usage of your product or service. Meter events are associated with billing meters, which define the shape of the event’s payload and how those events are aggregated. Meter events are processed asynchronously, so they may not be immediately reflected in aggregates or on upcoming invoices.

Learn more about calling API v2 endpoints.

Endpoints

POST/v2/billing/meter_events

Meter Event Adjustment

A billing meter event adjustment is a resource that allows you to cancel a meter event. For example, you might create a billing meter event adjustment to cancel a meter event that was created in error or attached to the wrong customer.

Endpoints

POST/v1/billing/meter_event_adjustments