List billing meters 

Retrieve a list of billing meters.

Parameters

  • statusenum

    Filter results to only include meters with the given 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.

More parameters

  • ending_beforestring

  • limitinteger

  • starting_afterstring

Returns

Returns a list of billing meters.

GET /v1/billing/meters
curl https://api.stripe.com/v1/billing/meters \
-u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:"
Response
{
"object": "list",
"data": [
{
"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"
}
}
],
"has_more": true,
"url": "v1/billing/meters"
}

Deactivate a billing meter 

When a meter is deactivated, no more meter events will be accepted for this meter. You can’t attach a deactivated meter to a price.

Parameters

  • idstringRequired

    Unique identifier for the object.

Returns

Returns a billing meter.

POST /v1/billing/meters/:id/deactivate
curl -X POST https://api.stripe.com/v1/billing/meters/mtr_123/deactivate \
-u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:"
Response
{
"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": 1704898330
},
"updated": 1704898330,
"value_settings": {
"event_payload_key": "value"
}
}

Reactivate a billing meter 

When a meter is reactivated, events for this meter can be accepted and you can attach the meter to a price.

Parameters

  • idstringRequired

    Unique identifier for the object.

Returns

Returns a billing meter.

POST /v1/billing/meters/:id/reactivate
curl -X POST https://api.stripe.com/v1/billing/meters/mtr_123/reactivate \
-u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:"
Response
{
"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"
}
}

Meter Events 

Meter events represent actions that customers take in your system. You can use meter events to bill a customer based on their usage. Meter events are associated with billing meters, which define both the contents of the event’s payload and how to aggregate those events.

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.