Creates a billing meter

Parameters

  • default_aggregationobjectRequired

    The default settings to aggregate a meter’s events with.

  • 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.

  • 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 values
    day

    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

POST /v1/billing/meters
curl https://api.stripe.com/v1/billing/meters \
-u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
-d display_name="Search API Calls" \
-d event_name=ai_search_api \
-d "default_aggregation[formula]"=sum \
-d "value_settings[event_payload_key]"=tokens \
-d "customer_mapping[type]"=by_id \
-d "customer_mapping[event_payload_key]"=stripe_customer_id
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": 1704824589,
"value_settings": {
"event_payload_key": "tokens"
}
}

Updates a billing meter

Parameters

  • idstringRequired

    Unique identifier for the object.

  • display_namestring

    The meter’s name.

Returns

Returns a billing meter

POST /v1/billing/meters/:id
curl https://api.stripe.com/v1/billing/meters/mtr_123 \
-u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
-d display_name="Updated Display Name"
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": "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": "tokens"
}
}

Retrieves a billing meter given an ID

Parameters

  • idstringRequired

    Unique identifier for the object.

Returns

Returns a billing meter

GET /v1/billing/meters/:id
curl https://api.stripe.com/v1/billing/meters/mtr_123 \
-u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:"
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": "tokens"
}
}

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_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:"
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": "tokens"
}
}
],
"has_more": true,
"url": "v1/billing/meters"
}

Deactivates a billing meter

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_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:"
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": "tokens"
}
}