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.
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.
{ "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" }}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.