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

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

Server-side language

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

Deactivate a billing meter

Deactivates a billing meter

Parameters

idstringRequired
Unique identifier for the object.

Returns

Returns a billing meter

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

Server-side language

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

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

List billing meters

Parameters

statusenum

More parametersExpand all

ending_beforestring

limitinteger

starting_afterstring

Returns

Deactivate a billing meter

Parameters

idstringRequired

Returns

More parameters