Core Resources
Payment Methods
Products
Checkout
Payment Links
Billing
Capital
Connect
Reserves
Fraud
Issuing
Terminal
Treasury
Payment Records
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Webhooks

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.

  • default_aggregationobject

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

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

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

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

POST /v1/billing/meters
curl https://api.stripe.com/v1/billing/meters \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -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 

Updates a billing meter.

Parameters

  • display_namestring

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

    The maximum length is 250 characters.

Returns

Returns a billing meter.

POST /v1/billing/meters/:id
curl https://api.stripe.com/v1/billing/meters/mtr_test_61Q8nQMqIFK9fRQmr41CMAXJrFdZ5MnA \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -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 

Retrieves a billing meter given an ID.

Parameters

No parameters.

Returns

Returns a billing meter.

GET /v1/billing/meters/:id
curl https://api.stripe.com/v1/billing/meters/mtr_test_61Q8nQMqIFK9fRQmr41CMAXJrFdZ5MnA \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:"
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"
  }
}

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