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

The MeterEvent object

Attributes

objectstring, value is "v2.billing.meter_event"
String representing the object’s type. Objects of the same type share the same value of the object field.

createdtimestamp
The creation time of this meter event.

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

identifierstring
A unique identifier for the event. If not provided, one will be generated. We recommend using a globally unique identifier for this. We’ll enforce uniqueness within a rolling 24 hour period.

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

payloadmap
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.

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

The MeterEvent object

{
  "object": "v2.billing.meter_event",
  "created": "2024-06-01T12:10:00.000Z",
  "livemode": false,
  "identifier": "idmp_12345678",
  "event_name": "ai_search_api",
  "timestamp": "2024-06-01T12:00:00.000Z",
  "payload": {
    "stripe_customer_id": "cus_12345678",
    "value": "25"
  }
}

Create a billing meter event with synchronous validation v2

Creates a meter event. Events are validated synchronously, but are processed asynchronously. Supports up to 1,000 events per second in livemode. For higher rate-limits, please use meter event streams instead.

Learn more about calling API v2 endpoints.

Parameters

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

payloadmapRequired
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 will be generated. We recommend using a globally unique identifier for this. We’ll enforce uniqueness within a rolling 24 hour period.

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

Returns

Response attributes

objectstring, value is "v2.billing.meter_event"
String representing the object’s type. Objects of the same type share the same value of the object field.

createdtimestamp
The creation time of this meter event.

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

identifierstring
A unique identifier for the event. If not provided, one will be generated. We recommend using a globally unique identifier for this. We’ll enforce uniqueness within a rolling 24 hour period.

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

payloadmap
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.

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

Error Codes

400archived_meter

The meter must be Active to submit events.

400duplicate_meter_event

A meter event with a duplicate identifier has already been submitted.

400no_meter

A meter must exist to submit events.

400payload_invalid_value

The value must be a positive integer.

400payload_no_customer_defined

The payload must have a reference to the customer.

400payload_no_value_defined

The payload must have a value.

409too_many_concurrent_requests

Cannot create multiple usage events for the same customer, meter concurrently.

POST /v2/billing/meter_events

Server-side language

curl -X POST https://api.stripe.com/v2/billing/meter_events \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-07-30.preview" \
  --json '{
    "identifier": "idmp_12345678",
    "event_name": "ai_search_api",
    "timestamp": "2024-06-01T12:00:00.000Z",
    "payload": {
        "stripe_customer_id": "cus_12345678",
        "value": "25"
    }
  }'

Response

{
  "object": "v2.billing.meter_event",
  "created": "2024-06-01T12:10:00.000Z",
  "livemode": false,
  "identifier": "idmp_12345678",
  "event_name": "ai_search_api",
  "timestamp": "2024-06-01T12:00:00.000Z",
  "payload": {
    "stripe_customer_id": "cus_12345678",
    "value": "25"
  }
}

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