Meters

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

Was this section helpful? Yes No

Create a billing meter

POST / v1 / billing / meters

Update a billing meter

POST / v1 / billing / meters /:id

Retrieve a billing meter

GET / v1 / billing / meters /:id

List billing meters

GET / v1 / billing / meters

Deactivate a billing meter

POST / v1 / billing / meters /:id / deactivate

Reactivate a billing meter

POST / v1 / billing / meters /:id / reactivate

The Meter object

Attributes

• id string Unique identifier for the object.
• object string, value is "billing.meter" String representing the object’s type. Objects of the same type share the same value.
• created timestamp Time at which the object was created. Measured in seconds since the Unix epoch.
• customer _ mapping object Fields that specify how to map a meter event to a customer.
• default _ aggregation object The default settings to aggregate a meter’s events with.
• display _ name string The meter’s name.
• event _ name string The name of the meter event to record usage for. Corresponds with the event_name field on meter events.
• event _ time _ window nullable enum The time window which meter events have been pre-aggregated for, if any. Possible enum values day Events are pre-aggregated in daily buckets. hour Events are pre-aggregated in hourly buckets.
• livemode boolean If the object exists in live mode, the value is true. If the object exists in test mode, the value is false.
• status enum The meter’s status. Possible enum values active 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 _ transitions object The timestamps at which the meter status changed.
• updated timestamp Time at which the object was last updated. Measured in seconds since the Unix epoch.
• value _ settings object Fields that specify how to calculate a meter event’s value.

The Meter object

{ "id": "mtr_test_61Q8nQMqIFK9fRQmr41CMAXJrFdZ5MnA", "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" }}

Create a billing meter

POST / v1 / billing / meters

Creates a billing meter.

Parameters

• default _ aggregation object Required The default settings to aggregate a meter’s events with.
• display _ name string Required The meter’s name. Not visible to the customer. The maximum length is 250 characters.
• event _ name string Required The name of the meter event to record usage for. Corresponds with the event_name field on meter events. The maximum length is 100 characters.
• customer _ mapping object Fields that specify how to map a meter event to a customer.
• event _ time _ window enum The time window which meter events have been pre-aggregated for, if any. Possible enum values day Events are pre-aggregated in daily buckets. hour Events are pre-aggregated in hourly buckets.
• value _ settings object Fields that specify how to calculate a meter event’s value.

Returns

Returns a billing meter.

Response

{ "id": "mtr_test_61Q8nQMqIFK9fRQmr41CMAXJrFdZ5MnA", "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" }}