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_field on a meter.name - payloadmapRequired
The payload of the event. This must contain the fields corresponding to a meter’s
customer_(default ismapping. event_ payload_ key stripe_) andcustomer_ id value_(default issettings. event_ payload_ key 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_field on a meter.name - 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
trueif the object exists in live mode or the valuefalseif the object exists in test mode. - payloadmap
The payload of the event. This must contain the fields corresponding to a meter’s
customer_(default ismapping. event_ payload_ key stripe_) andcustomer_ id value_(default issettings. event_ payload_ key 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 meter must be Active to submit events.
A meter event with a duplicate identifier has already been submitted.
A meter must exist to submit events.
The value must be a positive integer.
The payload must have a reference to the customer.
The payload must have a value.
Cannot create multiple usage events for the same customer, meter concurrently.
{ "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" }}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.
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.
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.
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.