Stripe usage-based billing: meters, credits and Metronome

Setup, step by step

1. Step 1

   Decide whether you need Metronome

   Stripe recommends Metronome for new integrations and for prepaid credit burndown, commits or rates by model. The steps below set up basic pay-as-you-go billing on the Meters API, which Stripe keeps fully supported. Commands come from Stripe's implementation guide; replace the placeholders with your own values.

2. Step 2

   Create a meter

   A meter adds up the values in your usage events for each customer over the billing period. Set the event name you will send and the payload key that holds the Stripe customer ID.

   curl https://api.stripe.com/v1/billing/meters \
     -u "<<YOUR_SECRET_KEY>>:" \
     -d "display_name=Hypernian tokens" \
     -d event_name=hypernian_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"

3. Step 3

   Create a metered price

   This price charges $0.04 per 100 units each month and points at the meter's ID.

   curl https://api.stripe.com/v1/prices \
     -u "<<YOUR_SECRET_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]={{METER_ID}}" \
     -d "product_data[name]=Hypernian tokens"

4. Step 4

   Subscribe the customer

   Attach the metered price to a subscription for an existing customer.

   curl https://api.stripe.com/v1/subscriptions \
     -u "<<YOUR_SECRET_KEY>>:" \
     -d "customer={{CUSTOMER_ID}}" \
     -d "items[0][price]={{PRICE_ID}}"

5. Step 5

   Send meter events

   Send one event per use, or a pre-aggregated total. In live mode Stripe accepts 1,000 meter event calls a second per account and one concurrent call per customer per meter.

   curl https://api.stripe.com/v1/billing/meter_events \
     -u "<<YOUR_SECRET_KEY>>:" \
     -d event_name=hypernian_tokens \
     -d "payload[stripe_customer_id]={{CUSTOMER_ID}}" \
     -d "payload[value]=25"

6. Step 6

   Preview the invoice

   Stripe processes meter events asynchronously, so recent usage can take a moment to show on the preview.

   curl https://api.stripe.com/v1/invoices/create_preview \
     -u "<<YOUR_SECRET_KEY>>:" \
     -d "subscription={{SUBSCRIPTION_ID}}"

Should I use Stripe Meters or Metronome?

Stripe's docs now call Metronome its primary usage-based billing platform. Use the Meters API if you already bill with it and your pricing is simple pay-as-you-go. The comparison below follows Stripe's documentation, checked November 10, 2026.

How much does Stripe usage-based billing cost?

Stripe Billing pay-as-you-go costs 0.7% of billing volume. That includes Billing transactions processed off Stripe and excludes one-off invoices. Meters API usage is included up to 100 million events a month. Pay-monthly plans start at $620 a month for up to $100,000 of billing volume, with 0.67% above that. Metronome is sold separately; its own site lists Starter at 0.8% of billing volume plus $0.04 per 1,000 events. Prices checked November 10, 2026.

Card processing is extra, at 2.9% plus 30 cents per successful card charge. For $20,000 billed a month as 400 invoices of $50, Billing costs $140 and card fees cost $700. Fees total $840, or 4.2% of revenue.

Card fees are most of that cost. Collecting the same $20,000 as 100 charges of $200 cuts card fees to $610.

How do Stripe billing credits work?

Billing credits are prepaid or promotional amounts you give a customer through credit grants. They apply to subscription items with metered prices that report through Meters, after discounts and before taxes. They do not apply to one-off invoices, licensed prices or legacy usage records.

The catch for AI products: credits are applied only when an invoice finalizes. During the cycle a customer can use more than their balance, so basic credits do not stop spending in real time. Metronome burns credits down as usage arrives.

• A credit grant never expires unless you set an expiry date on it.
• A customer can hold up to 100 unused credit grants at a time.
• Issuing a credit note does not restore credits applied to an invoice; you create a new grant.
• Stripe bars using billing credits as gift cards or stored value, or to pay other businesses.

What limits apply to Stripe meter events?

Set an identifier on each meter event, or use an idempotency key, so a retry is not counted twice.

• Live mode: 1,000 meter event calls a second per account, outside the global rate limit, and one concurrent call per customer per meter.
• Meter event streams on API v2: up to 10,000 events a second, live mode only. Stripe sales can raise this to 200,000.
• Timestamps must fall within the past 35 days and no more than 5 minutes ahead.
• Per meter, up to 10,000 unique dimension combinations an hour; per customer on a meter, up to 100.
• Usage sent after an invoice finalizes can appear in summaries without being billed.
• Legacy usage records still work only if you pin an API version from before Basil.

Can Stripe bill LLM tokens with a markup?

Yes, through Metronome. Stripe’s billing for LLM tokens is in public preview for anyone with a Metronome account. Stripe syncs token prices for OpenAI, Anthropic and Google models, and you set your margin on top. Usage events carry the customer, model, token type and token count. It supports pay-as-you-go, a fixed fee with included tokens, and AI credit packs.

It bills the tokens you report. You still call the model providers yourself, under your own accounts, and pay them.

Where does Locus Pro fit next to Stripe?

Locus Pro covers a different job: the paid API and model calls your customers' agents make. Locus Pro Enterprise holds a credit balance for each customer, checks it before each call, and returns HTTP 402 when it is short. Each call is charged at the catalog base price plus your markup, with no meter events and no reconciliation at invoice time. Customers top up by card through Stripe-hosted checkout.

Example from the Locus catalog on November 10, 2026: Brave web search costs 30.3 credits, or $0.0303. With a 50% markup each customer search costs $0.04545, and $0.01515 of it is your margin.

Keep Stripe Billing for subscriptions and for usage of your own product. Use Locus Pro for third-party API calls billed per customer.

• Locus Pro for platforms
• Usage-based billing software compared

How do I choose between the Stripe options?

Pick by the pricing you need now and the Stripe products you already use.

• Simple pay-as-you-go already running on Meters: keep it. Stripe does not require a migration.
• New usage pricing, prepaid drawdown, commits, or rates by model: Metronome.
• A Stripe Connect platform billing on behalf of connected accounts: basic Meters, since Metronome does not support Connect.
• Reselling model tokens you buy yourself, with a margin: Stripe token billing on Metronome.
• Paid third-party APIs for your customers' agents, billed from prepaid balances: Locus Pro Enterprise.