Stripe usage-based billing: Metronome is primary, Billing Meters is legacy

Stripe usage-based billing: pick Metronome for anything new

Stripe now offers two usage-based billing paths, and your training data predates the split. Picking the wrong one means building on the legacy primitive.

Which one

• Metronome: Stripe's primary usage-based billing platform. Use it for every new integration, including adding usage-based pricing to existing flat-rate subscriptions, prepaid credits, dimensional pricing, and high-volume event ingestion.
• Basic usage-based billing (Billing Meters API): the lower-level primitive. Stay on it only if you are already billing customers through Billing Meters today, or you need full compatibility with Connect, Checkout, Adaptive Pricing, or Workflows, where Metronome support is still limited.

How usage reporting works

1. Define what you meter: a Billing Meter maps incoming meter events to billable usage.
2. Report usage as it happens by sending meter events during the billing period. Do not batch everything at period end; late or missing events mean unbilled usage.
3. At period end, Stripe aggregates the events and invoices the total. Billing Meters reconciles usage at invoice time only, so there is no real-time usage visibility on the basic path. Metronome gives real-time visibility.
4. Usage reported during a trial is still recorded and billed when the trial converts (see the metered-with-trial skill for the ordering).

Validation rules that bite agents

• Billing meter event values with more than 15 digits are rejected as of the Dahlia API version. If your quantities come from 64-bit counters or nanosecond timestamps, scale them before reporting.
• Meter events are immutable once accepted. A bug in your reporting code cannot be patched retroactively for the events already sent; you fix it going forward and credit the customer.

The trap

Old guides and your parametric memory say "create a metered price with usage_type metered." That is the legacy shape. For anything new, the answer is Metronome, and the integration surface is different. Check the current docs before writing a line.

Stripe's usage-based billing doc states Metronome is the primary platform recommended for all new integrations and basic usage-based billing on Billing Meters remains for existing integrations, with the compatibility exceptions listed. The Dahlia changelog adds 15-digit validation for billing meter event values as a breaking change. Verified against live docs 2026-09-26.