Retrieves aggregated meter usage data

Returns aggregated meter usage data for a customer within a specified time interval. The data can be grouped by various dimensions and can include multiple meters if specified.

Parameters

customerstringRequired
The customer id to fetch meter usage data for.

end_timetimestampRequired
The timestamp from when to stop aggregating meter events (exclusive). Must be aligned with minute boundaries.

start_timetimestampRequired
The timestamp from when to start aggregating meter events (inclusive). Must be aligned with minute boundaries.

metersarray of objects
An array of meter parameters to specify which meters to include in the usage data. If not specified, usage across all meters for the customer is included.

timezonestring
The timezone to use for the start and end times. Defaults to UTC if not specified.

value_grouping_windowenum
Specifies what granularity to use when aggregating meter usage events. If not specified, a single event would be returned for the specified time range.
Possible enum values
day
hour
month
week

Returns

Aggregated meter usage data for a customer in the specified time interval.

GET /v1/billing/analytics/meter_usage

Server-side language

curl -G https://api.stripe.com/v1/billing/analytics/meter_usage \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d start_time=1733097600 \
  -d end_time=1735689600 \
  -d customer=cus_123456789 \
  -d "meters[0][meter_id]"=mtr_test_61Q8nQMqIFK9fRQmr41CMAXJrFdZ5MnA \
  -d "meters[0][dimension_group_by_keys][0]"=model \
  -d "meters[0][dimension_filters][tier]"=premium \
  -d value_grouping_window=day \
  --data-urlencode timezone="America/New_York"

Response

{
  "object": "billing.analytics.meter_usage",
  "data_refreshed_at": 1735689000,
  "livemode": false,
  "data": [
    {
      "object": "billing.analytics.meter_usage_row",
      "bucket_start_time": 1733097600,
      "bucket_end_time": 1733184000,
      "meter_id": "mtr_test_61Q8nQMqIFK9fRQmr41CMAXJrFdZ5MnA",
      "bucket_value": 1500,
      "dimensions": {
        "model": "gpt-4"
      }
    },
    {
      "object": "billing.analytics.meter_usage_row",
      "bucket_start_time": 1733184000,
      "bucket_end_time": 1733270400,
      "meter_id": "mtr_test_61Q8nQMqIFK9fRQmr41CMAXJrFdZ5MnA",
      "bucket_value": 2250,
      "dimensions": {
        "model": "gpt-4"
      }
    },
    {
      "object": "billing.analytics.meter_usage_row",
      "bucket_start_time": 1733270400,
      "bucket_end_time": 1733356800,
      "meter_id": "mtr_test_61Q8nQMqIFK9fRQmr41CMAXJrFdZ5MnA",
      "bucket_value": 1875,
      "dimensions": {
        "model": "gpt-4"
      }
    }
  ]
}

Credit Grant

A credit grant is an API resource that documents the allocation of some billing credits to a customer.

Related guide: Billing credits

Endpoints

POST/v1/billing/credit_grants

POST/v1/billing/credit_grants/:id

GET/v1/billing/credit_grants/:id

GET/v1/billing/credit_grants

POST/v1/billing/credit_grants/:id/expire

POST/v1/billing/credit_grants/:id/void

Credit Balance Summary

Indicates the billing credit balance for billing credits granted to a customer.

Endpoints

GET/v1/billing/credit_balance_summary

Credit Balance Transaction

A credit balance transaction is a resource representing a transaction (either a credit or a debit) against an existing credit grant.

Endpoints

GET/v1/billing/credit_balance_transactions/:id

GET/v1/billing/credit_balance_transactions

Plans

You can now model subscriptions more flexibly using the Prices API. It replaces the Plans API and is backwards compatible to simplify your migration.

Plans define the base price, currency, and billing cycle for recurring purchases of products. Products help you track inventory or provisioning, and plans help you track pricing. Different physical goods or levels of service should be represented by products, and pricing options should be represented by plans. This approach lets you change prices without having to change your provisioning scheme.

For example, you might have a single “gold” product that has plans for $10/month, $100/year, €9/month, and €90/year.

Related guides: Set up a subscription and more about products and prices.

Endpoints