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

Create a billing meter 

Billing
Meters
Create a billing meter

Creates a billing meter.

Parameters

  • default_aggregationobjectRequired

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

    • default_aggregation.formulaenumRequired

      Specifies how events are aggregated. Allowed values are count to count the number of events and sum to sum each event’s value.

      Possible enum values
      count

      Count the number of events.

      sum

      Sum each event’s value.

  • display_namestringRequired

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

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

    • customer_mapping.event_payload_keystringRequired

      The key in the meter event payload to use for mapping the event to a customer.

    • customer_mapping.typeenumRequired

      The method for mapping a meter event to a customer. Must be by_id.

      Possible enum values
      by_id

      Map a meter event to a customer by passing a customer ID in the event’s payload.

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

    • value_settings.event_payload_keystringRequired

      The key in the usage event payload to use as the value for this meter. For example, if the event payload contains usage on a bytes_used field, then set the event_payload_key to “bytes_used”.

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_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": "value"
  }
}