Stripe Billing migration tool

Find the legacy Usage Records assumptions before Basil finds them for you

Inventory the removed resources and the semantics that need redesign before moving from Stripe Usage Records to Billing Meters.

Check the integration Read the migration guide

Basil removed the legacy path

UsageRecord endpoints
aggregate_usage
billing_thresholds
metered Prices without a Billing Meter

Legacy integration inventory

What does your Stripe integration still depend on?

Does your code call /subscription_items/:id/usage_records?

Do you have usage_type=metered Prices without recurring.meter?

Do you rely on legacy aggregate_usage?

Do you report authoritative totals with action=set?

Do you depend on legacy billing_thresholds?

Have you already upgraded this integration to 2025-03-31.basil or later?

Migration result

HIGH migration surface

Legacy dependencies to remove

Your code still calls the legacy UsageRecord endpoint, which is removed in 2025-03-31.basil.
You still have a metered Price without a Billing Meter attached.
Your integration still depends on legacy aggregate_usage configuration.

Safe migration sequence

Create a Billing Meter and a new metered Price attached to that meter.
During migration, keep reporting legacy Usage Records on 2025-02-24.acacia or earlier while also sending Billing Meter events.
Compare usage by customer, meter and billing period before moving subscriptions to the new price.
Use subscription schedules or another deliberate cutover plan so the new meter-backed price takes effect at the intended boundary.
Only upgrade the Stripe API/webhook version after no production path depends on removed legacy resources.

Read the full migration guide See Stripe + independent metering

This checker does not inspect your Stripe account and does not mutate Stripe objects. It is an architecture checklist based on Stripe's current public migration contract.

Dual-report before cutover

Stripe's migration guide says to keep sending legacy Usage Records while you begin sending Billing Meter events, until subscriptions have moved to meter-backed Prices.

`set` needs a semantics review

Current meters support sum/count/last plus raw or pre-aggregated ingestion. Choose the model that matches what your old authoritative total meant instead of blindly converting totals into additive events.

Grace period is configurable

Stripe's default invoice-finalization grace period is one hour, but it can be configured up to 72 hours. Treat it as billing configuration, not a fixed transport guarantee.