Usage-Based Billing Fresh

Charge customers based on what they actually consume. Usage-based billing works through meters and meter events.

How it works

1. Create a Meter — defines how to aggregate usage events
2. Create a Price attached to the meter
3. Subscribe customers to the metered price
4. Send Meter Events as customers use your product
5. At end of billing period, Stripe calculates usage and generates an invoice

Step 1: Create a meter

curl https://api.stripe.com/v1/billing/meters \
  -u "sk_test_YOUR_KEY:" \
  -d display_name="API Tokens" \
  -d event_name=api_tokens \
  -d "default_aggregation[formula]=sum" \
  -d "customer_mapping[event_payload_key]=stripe_customer_id" \
  -d "customer_mapping[type]=by_id" \
  -d "value_settings[event_payload_key]=value"

Aggregation formulas:

• sum — total value across all events
• count — number of events received
• last — last reported value in the period

Step 2: Create a metered price

curl https://api.stripe.com/v1/prices \
  -u "sk_test_YOUR_KEY:" \
  -d currency=usd \
  -d unit_amount=4 \
  -d billing_scheme=per_unit \
  -d "transform_quantity[divide_by]=100" \
  -d "transform_quantity[round]=up" \
  -d "recurring[usage_type]=metered" \
  -d "recurring[interval]=month" \
  -d "recurring[meter]=mtr_123" \
  -d "product_data[name]=API Tokens"

This example: $0.04 per 100 tokens, rounded up, billed monthly.

Step 3: Create a subscription

curl https://api.stripe.com/v1/subscriptions \
  -u "sk_test_YOUR_KEY:" \
  -d customer=cus_123 \
  -d "items[0][price]=price_456"

A single metered price can be attached to multiple subscriptions.

Note for billing_mode=flexible subscriptions: Stripe excludes metered line items from the first invoice since no prior usage exists. An invoice only generates if the subscription is backdated or pending invoice items exist.

Step 4: Report usage via meter events

curl https://api.stripe.com/v1/billing/meter_events \
  -u "sk_test_YOUR_KEY:" \
  -d event_name=api_tokens \
  -d "payload[stripe_customer_id]=cus_123" \
  -d "payload[value]=1500"

Send events as they occur. Stripe processes them asynchronously — upcoming invoice previews may not immediately reflect recent events.

Step 5: Preview an invoice

curl https://api.stripe.com/v1/invoices/create_preview \
  -u "sk_test_YOUR_KEY:" \
  -d subscription=sub_123

Retrieve usage for a custom time period

curl -G https://api.stripe.com/v1/billing/meters/mtr_123/event_summaries \
  -u "sk_test_YOUR_KEY:" \
  -d customer=cus_123 \
  -d start_time=1717249380 \
  -d end_time=1717249440

Returns aggregated usage for a specific meter, customer, and time window.

Pricing models for usage-based billing

Model	Description
Fixed fee + overage	Base charge includes N units. Usage above that billed per unit
Pay as you go	All usage billed at end of period. No base charge
Credit burndown	Customer prepays credits. Usage deducts from balance
Tiered	Different rates at different usage volumes

Alerts and thresholds

Configure subscriptions to generate invoices early when usage hits a threshold, rather than waiting for the billing period end. Useful for high-usage customers or preventing bill shock.

Cancellation with usage-based billing

When canceling a usage-based subscription:

• Pass prorate=true to credit for unused time
• Pass invoice_now=true to immediately generate a final invoice for outstanding usage
• Use clear_usage=true on the subscription item to discard accrued usage without billing