Core Resources
Payment Methods
Products
Checkout
Payment Links
Billing
Capital
Connect
Reserves
Fraud
Issuing
Terminal
Treasury
Payment Records
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Webhooks

Create a billing meter event with synchronous validation v2

Billing
Meter Events
Create a billing meter event with synchronous validation

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
curl -X POST https://api.stripe.com/v2/billing/meter_events \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: {{STRIPE_API_VERSION}}" \
  --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"
  }
}