Sample - Stripe API
POST/v1/billing/meters

Create a billing meter

Creates a billing meter that defines how usage events are aggregated for billing. Supply display_name, event_name, and default_aggregation, and configure customer mapping or value extraction when those settings are needed. The created meter includes its lifecycle status and aggregation configuration.

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

7 body fields

Form data defining the billing meter and its event aggregation settings.

customer_mappingobjectoptional
Fields that specify how to map a meter event to a customer.
default_aggregationobjectrequired
The default settings to aggregate a meter's events with.
display_namestringrequired
The meter’s name. Not visible to the customer.
event_namestringrequired
The name of the meter event to record usage for. Corresponds with the `event_name` field on meter events.
event_time_windowstringoptional
The time window which meter events have been pre-aggregated for, if any.
Allowed:dayhour
expandarray<string>optional
Specifies which fields in the response should be expanded.
value_settingsobjectoptional
Fields that specify how to calculate a meter event's value.

2 status codes
200Returns the created billing meter with its identifier, display name, event configuration, aggregation settings, lifecycle status, timestamps, and value settings.
createdintegerrequired
Time at which the object was created. Measured in seconds since the Unix epoch.
customer_mappingobjectrequired
default_aggregationobjectrequired
display_namestringrequired
The meter's name.
event_namestringrequired
The name of the meter event to record usage for. Corresponds with the `event_name` field on meter events.
event_time_windowstringoptional
The time window which meter events have been pre-aggregated for, if any.
Allowed:dayhour
idstringrequired
Unique identifier for the object.
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
statusstringrequired
The meter's status.
Allowed:activeinactive
status_transitionsobjectrequired
updatedintegerrequired
Time at which the object was last updated. Measured in seconds since the Unix epoch.
value_settingsobjectrequired
defaultError response.
errorobjectrequired

Error handling

display_name, event_name, and default_aggregation are required. default_aggregation.formula is required and must be count, last, or sum; customer_mapping.type must be by_id, and required nested event payload keys must be provided when those objects are supplied.