Meters

A billing meter is a resource that allows you to track usage of a particular event. For example, you might create a billing meter to track the number of API calls made by a particular user. You can then attach the billing meter to a price and attach the price to a subscription to charge the user for the number of API calls they make.

Endpoints

POST/v1/billing/meters

POST/v1/billing/meters/:id

GET/v1/billing/meters/:id

GET/v1/billing/meters

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

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

The Meter object

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_name field on meter events.

event_time_windownullable enum
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.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

statusenum
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_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.

The Meter object

{
  "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"
  }
}

Create a billing meter

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

Server-side language

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"
  }
}

Update a billing meter

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

Server-side language

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"
  }
}

Retrieve a billing meter

Retrieves a billing meter given an ID

Parameters

idstringRequired
Unique identifier for the object.

Returns

Returns a billing meter

GET /v1/billing/meters/:id

Server-side language

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"
  }
}

Meters

The Meter object

Attributes

idstring

objectstring

createdtimestamp

customer_mappingobject

display_namestring

event_namestring

event_time_windownullable enum

livemodeboolean

statusenum

status_transitionsobject

updatedtimestamp

value_settingsobject

Create a billing meter

Parameters

default_aggregationobjectRequired

display_namestringRequired

event_namestringRequired

customer_mappingobject

event_time_windowenum

value_settingsobject

Returns

Update a billing meter

Parameters

idstringRequired

display_namestring

Returns

Retrieve a billing meter

Parameters

idstringRequired

Returns