Meter Event Streams v2

You can send a higher-throughput of meter events using meter event streams. For this flow, you must first create a meter event session, which will provide you with a session token. You can then create meter events through the meter event stream endpoint, using the session token for authentication. The session tokens are short-lived and you will need to create a new meter event session when the token expires.

The MeterEventSession object 

Attributes

  • idstring

    The unique id of this auth session.

  • objectstring, value is "v2.billing.meter_event_session"

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

  • authentication_tokenstring

    The authentication token for this session. Use this token when calling the high-throughput meter event API.

  • createdtimestamp

    The creation time of this session.

  • expires_attimestamp

    The time at which this session will expire.

  • livemodeboolean

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

The MeterEventSession object
{
"id": "<AUTH_SESSION_ID>",
"livemode": "false",
"object": "v2.billing.meter_event_session",
"authentication_token": "token_12345678",
"created": "2024-06-01T12:00:00.000Z",
"expires_at": "2024-06-01T12:15:00.000Z"
}

Create billing meter event stream authentication session v2

Creates a meter event session to send usage on the high-throughput meter event stream. Authentication tokens are only valid for 15 minutes, so you will need to create a new meter event session when your token expires.

Learn more about calling API v2 endpoints.

Parameters

No parameters.

Returns

Response attributes

  • idstring

    The unique id of this auth session.

  • objectstring, value is "v2.billing.meter_event_session"

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

  • authentication_tokenstring

    The authentication token for this session. Use this token when calling the high-throughput meter event API.

  • createdtimestamp

    The creation time of this session.

  • expires_attimestamp

    The time at which this session will expire.

  • livemodeboolean

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

POST /v2/billing/meter_event_session
curl -X POST https://api.stripe.com/v2/billing/meter_event_session \
-H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
-H "Stripe-Version: 2025-07-30.preview"
Response
{
"id": "<AUTH_SESSION_ID>",
"livemode": "false",
"object": "v2.billing.meter_event_session",
"authentication_token": "token_12345678",
"created": "2024-06-01T12:00:00.000Z",
"expires_at": "2024-06-01T12:15:00.000Z"
}

Create a billing meter event with asynchronous validation v2

Creates meter events. Events are processed asynchronously, including validation. Requires a meter event session for authentication. Supports up to 10,000 requests per second in livemode. For even higher rate-limits, contact sales.

Learn more about calling API v2 endpoints.

Parameters

  • eventsarray of objectsRequired

    List of meter events to include in the request.

Returns

Response attributes

No response attributes.

Error Codes
401billing_meter_event_session_expired

The temporary session token has expired.

POST /v2/billing/meter_event_stream
curl -X POST https://meter-events.stripe.com/v2/billing/meter_event_stream \
-H "Authorization: Bearer {{SESSION AUTH TOKEN}}" \
-H "Stripe-Version: 2025-07-30.preview" \
--json '{
"events": [
{
"identifier": "idmp_12345678",
"event_name": "ai_search_api",
"timestamp": "2024-06-01T12:00:00.000Z",
"payload": {
"stripe_customer_id": "cus_12345678",
"value": "25"
}
}
]
}'
Response
{}

Meter Event Summary 

A billing meter event summary represents an aggregated view of a customer’s billing meter events within a specified timeframe. It indicates how much usage was accrued by a customer for that period.

Note: Meters events are aggregated asynchronously so the meter event summaries provide an eventually consistent view of the reported usage.