Meters specify how to aggregate meter events over a billing period. Meter events represent the actions that customers take in your system. Meters attach to prices and form the basis of the bill.
Related guide: Usage based billing
Attributes
- idstring
Unique identifier for the object.
- objectstring
String representing the object’s type. Objects of the same type share the same value.
- createdtimestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
- customer_
mappingobject Fields that specify how to map a meter event to a customer.
- display_
namestring The meter’s name.
- event_
namestring The name of the meter event to record usage for. Corresponds with the
event_
field on meter events.name - event_
time_ windownullable enum The time window to pre-aggregate meter events for, if any.
Possible enum valuesday
Events are pre-aggregated in daily buckets.
hour
Events are pre-aggregated in hourly buckets.
- livemodeboolean
Has the value
true
if the object exists in live mode or the valuefalse
if the object exists in test mode. - statusenum
The meter’s status.
Possible enum valuesactive
The meter is active.
inactive
The meter is inactive. No more events for this meter will be accepted. The meter cannot be attached to a price.
- status_
transitionsobject The timestamps at which the meter status changed.
- updatedtimestamp
Time at which the object was last updated. Measured in seconds since the Unix epoch.
- value_
settingsobject Fields that specify how to calculate a meter event’s value.
{ "id": "mtr_123", "object": "billing.meter", "created": 1704824589, "customer_mapping": { "type": "by_id", "event_payload_key": "stripe_customer_id" }, "default_aggregation": { "formula": "sum" }, "display_name": "Search API Calls", "event_name": "ai_search_api", "event_time_window": null, "livemode": false, "status": "active", "status_transitions": { "deactivated_at": null }, "updated": 1704898330, "value_settings": { "event_payload_key": "value" }}
Creates a billing meter.
Parameters
- 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_
field on meter events.name - customer_
mappingobject Fields that specify how to map a meter event to a customer.
- event_
time_ windowenum The time window to pre-aggregate meter events for, if any.
Possible enum valuesday
Events are pre-aggregated in daily buckets.
hour
Events are pre-aggregated in hourly buckets.
- value_
settingsobject Fields that specify how to calculate a meter event’s value.
Returns
Returns a billing meter.
{ "id": "mtr_123", "object": "billing.meter", "created": 1704824589, "customer_mapping": { "type": "by_id", "event_payload_key": "stripe_customer_id" }, "default_aggregation": { "formula": "sum" }, "display_name": "Search API Calls", "event_name": "ai_search_api", "event_time_window": null, "livemode": false, "status": "active", "status_transitions": { "deactivated_at": null }, "updated": 1704824589, "value_settings": { "event_payload_key": "value" }}
Updates a billing meter.
Parameters
- idstringRequired
Unique identifier for the object.
- display_
namestring The meter’s name. Not visible to the customer.
Returns
Returns a billing meter.
{ "id": "mtr_123", "object": "billing.meter", "created": 1704824589, "customer_mapping": { "type": "by_id", "event_payload_key": "stripe_customer_id" }, "default_aggregation": { "formula": "sum" }, "display_name": "Updated Display Name", "event_name": "ai_search_api", "event_time_window": null, "livemode": false, "status": "active", "status_transitions": { "deactivated_at": null }, "updated": 1704898330, "value_settings": { "event_payload_key": "value" }}
Retrieves a billing meter given an ID.
Parameters
- idstringRequired
Unique identifier for the object.
Returns
Returns a billing meter.
{ "id": "mtr_123", "object": "billing.meter", "created": 1704824589, "customer_mapping": { "type": "by_id", "event_payload_key": "stripe_customer_id" }, "default_aggregation": { "formula": "sum" }, "display_name": "Search API Calls", "event_name": "ai_search_api", "event_time_window": null, "livemode": false, "status": "active", "status_transitions": { "deactivated_at": null }, "updated": 1704898330, "value_settings": { "event_payload_key": "value" }}