Stripe Meter Events v2 vs Legacy Usage Records — when and how should I migrate?
Choose whether to keep a Stripe legacy metered billing integration on an older API version or migrate to billing meters and Meter Events, where API-version compatibility, ingestion limits, and removed legacy features now drive the implementation cost.
Blockers
- capability/legacy-usage-records-billing — EOL 2025-03-31
- requires_version: capability/legacy-usage-records-billing → protocol/stripe-api
- breaking_change_in: capability/legacy-usage-records-billing → protocol/stripe-api
- Lock-in via protocol/stripe-api
- Lock-in via protocol/meter-events
Who this is for
- cost-sensitive
- high-scale
- enterprise
Candidates
Keep legacy usage records on an older Stripe API version
This keeps the existing `usage_records` integration and legacy metered prices running on an API version on or before `2025-02-24.acacia`. As of 2026-03-29, Stripe documents that the legacy usage records APIs were removed in `2025-03-31.basil`, so this path depends on not upgrading affected requests and webhook endpoints past the legacy-compatible version. Legacy usage records are tied to subscription items, use `action=increment` or `action=set`, and rely on the removed `aggregate_usage` price behavior. The legacy endpoint rate limit documented by Stripe is 100 calls per second per account, with 200 per second available on request.
When to choose
Use this when migration cost is the main constraint and the current integration is stable, low-volume, and already built around subscription-item usage records plus old `aggregate_usage` semantics. The decisive factor is whether you can safely stay pinned to an older Stripe API version and accept that newer API versions no longer support creating or attaching legacy metered prices.
Tradeoffs
Lowest short-term engineering effort if the integration already works, but it increases version pinning risk and blocks adoption of Stripe's current usage-based billing model. It also preserves lower throughput limits and older data semantics.
Cautions
As of 2026-03-29, this path is effectively a compatibility holdout, not Stripe's forward path. Stripe states that legacy usage-records billing is deprecated in favor of billing meters, and newer API versions remove `aggregate_usage`, remove the usage record endpoints, and reject metered prices without an attached meter. If you later upgrade account, request, or webhook API versions without a migration plan, billing behavior can break.
Migrate to billing meters and use Meter Events, with API v2 streams for high throughput
This moves usage reporting to Stripe billing meters and Meter Events, which Stripe positions as its only forward-looking usage-based billing solution. As of 2026-03-29, Stripe documents that standard Meter Events support 1,000 calls per second in live mode, while API v2 meter event streams support up to 10,000 events per second in live mode and up to 200,000 per second through sales-assisted limits. Meter events are asynchronous, use event identifiers for deduplication, accept timestamps up to 35 calendar days old and no more than 5 minutes in the future, and only accept whole-number usage values. Stripe's migration guide also notes that billing meters do not support the legacy `max` aggregation formula.
When to choose
Use this for any new Stripe usage-based billing work, for teams that want to upgrade beyond legacy-compatible API versions, or for systems that may outgrow usage-record rate limits. The decisive factor is whether you need a supported long-term integration and higher ingestion ceilings more than you need exact legacy `aggregate_usage` behavior.
Tradeoffs
Higher migration effort because you must create meters, meter-backed prices, and possibly dual-write during cutover, but it aligns with Stripe's supported model and unlocks much higher throughput. API v2 streams add extra auth-session handling because tokens expire after 15 minutes.
Cautions
Stripe says you must continue sending legacy usage records until migration is completed, because meter events do not affect invoices until subscriptions move to meter-backed prices. If your old design depends on `aggregate_usage=last_during_period`, `last_ever`, or especially `max`, verify the replacement carefully because the legacy aggregation model is not preserved one-for-one. Also account for asynchronous processing and the fact that meter event stream requests are not included in Workbench logs.
Try with your AI agent
$ npm install -g pocketlantern $ pocketlantern init # Restart Claude Code, Cursor, or your MCP client, then ask: # "Stripe Meter Events v2 vs Legacy Usage Records — when and how should I migrate?"