Sample - Stripe API
POST/v1/billing/meter_events

Create a billing meter event

Creates a billing meter event for recording customer usage. Supply event_name and a payload containing the customer mapping and measured value fields expected by the meter. You can provide an identifier for retry-safe uniqueness and a Unix timestamp within the permitted event window.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.
  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

5 body fields

Form data describing a customer usage event for a billing meter.

event_namestringrequired
The name of the meter event. Corresponds with the `event_name` field on a meter.
expandarray<string>optional
Specifies which fields in the response should be expanded.
identifierstringoptional
A unique identifier for the event. If not provided, one is generated. We recommend using UUID-like identifiers. Stripe enforces 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.
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](https://docs.stripe.com/billing/subscriptions/usage-based/meters/configure#meter-configuration-attributes).
timestampintegeroptional
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.

2 status codes
200Returns the billing meter event with its creation time, event name, identifier, live-mode flag, object type, payload, and event timestamp.
createdintegerrequired
Time at which the object was created. Measured in seconds since the Unix epoch.
event_namestringrequired
The name of the meter event. Corresponds with the `event_name` field on a meter.
identifierstringrequired
A unique identifier for the event.
livemodebooleanrequired
If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
objectstringrequired
String representing the object's type. Objects of the same type share the same value.
Allowed:billing.meter_event
payloadobjectrequired
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](https://docs.stripe.com/billing/subscriptions/usage-based/meters/configure#meter-configuration-attributes).
timestampintegerrequired
The timestamp passed in when creating the event. Measured in seconds since the Unix epoch.
defaultError response.
errorobjectrequired

Error handling

event_name and payload are required, and event_name must not exceed 100 characters. identifier must not exceed 100 characters when supplied, and timestamp must be a Unix timestamp within the past 35 calendar days or up to 5 minutes in the future.