Core Resources
Payment Methods
Money Management
Products
Product Catalog
Commerce
Agentic Commerce
Checkout
Payment Links
Billing
Capital
Connect
Reserves
Fraud
Issuing
Terminal
Treasury for Platforms
Payment Records
Account Evaluation
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Tax Reporting
Forwarding
Privacy
Webhooks

Create a billing meter v1

POST /v1/billing/meters

Creates a billing meter.

Parameters

  • default_aggregationobjectRequired

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

  • display_namestringRequired

    The meter’s name. Not visible to the customer.

    The maximum length is 250 characters.

  • event_namestringRequired

    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_mappingobject

    Fields that specify how to map a meter event to a customer.

  • event_time_windowenum

    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_settingsobject

    Fields that specify how to calculate a meter event’s value.

Returns

Returns a billing meter.

curl https://api.stripe.com/v1/billing/meters \
  -u "sk_test_...sk_test_...:" \
  -H "Stripe-Version: 2026-10-28.endive" \
  -d "display_name=Search API Calls" \
  -d event_name=ai_search_api \
  -d "default_aggregation[formula]=sum" \
  -d "value_settings[event_payload_key]=value" \
  -d "customer_mapping[type]=by_id" \
  -d "customer_mapping[event_payload_key]=stripe_customer_id"
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"
  }
}

Update a billing meter v1

POST /v1/billing/meters/:id

Updates a billing meter.

Parameters

  • idstringRequired

    Unique identifier for the object.

  • display_namestring

    The meter’s name. Not visible to the customer.

    The maximum length is 250 characters.

Returns

Returns a billing meter.

curl https://api.stripe.com/v1/billing/meters/mtr_test_61Q8nQMqIFK9fRQmr41CMAXJrFdZ5MnA \
  -u "sk_test_...sk_test_...:" \
  -H "Stripe-Version: 2026-10-28.endive" \
  -d "display_name=Updated Display Name"
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": "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": "value"
  }
}

Retrieve a billing meter v1

GET /v1/billing/meters/:id

Retrieves a billing meter given an ID.

Parameters

  • idstringRequired

    Unique identifier for the object.

Returns

Returns a billing meter.

curl https://api.stripe.com/v1/billing/meters/mtr_test_61Q8nQMqIFK9fRQmr41CMAXJrFdZ5MnA \
  -u "sk_test_...sk_test_...:" \
  -H "Stripe-Version: 2026-10-28.endive"
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": 1704898330,
  "value_settings": {
    "event_payload_key": "value"
  }
}