B
Glossary
Billing System Migration
Billing system migration is the process of moving live subscriptions, usage meters, pricing configuration, and invoice history from one billing system onto another without breaking what customers get charged. The work runs in stages: export, pricing-model mapping, a parallel run against the incumbent, reconciliation, then cutover.
Key Takeaways
Billing counts as revenue-critical for parallel running, which published guidance puts at 8 to 16 weeks, not the 2 to 4 weeks non-critical systems get.
Set variance gates in currency before cycle one. On a $2.46M parallel window, 0.01% drift is $246 to investigate and 0.1% is $2,460 to pause.
Aggregate variance hides offsetting errors: invoices wrong by $1,900 and $1,880 in opposite directions net to $20 and clear a gate they should fail.
At Simplismart, a developer lost 20 to 30% of every working day to maintaining a billing engine the team had taken 1.5 to 2 months to build on Lago, before they migrated off it.
What are the stages of a billing system migration?
A migration moves through the same sequence every time, and each stage fails in its own way.
Stage | What breaks here
|
|---|---|
Export from the incumbent | Wallet balances arrive as a closing figure with no ledger behind them |
Pricing-model mapping | Overrides that were never plan objects, just spreadsheet rows |
Event replay | Meters that aggregate differently, a sum where the old one counted unique values |
Parallel run | Events reach one pipeline and not the other, so an ingestion gap reads as a pricing bug |
Reconciliation | Totals compared without line items, so offsetting errors cancel |
Cutover | Read access to the incumbent revoked before the first dispute lands |
The export is the easy part. Working out what a 2023 enterprise contract promised, and where that promise is written down, takes weeks, and the decision before all this sits in Build vs Buy (Billing).
Flexprice is enterprise-grade, open source usage based billing infrastructure for AI and SaaS companies. It can be deployed in your own VPC, on-prem, or on Flexprice's managed cloud. Simplismart, a GenAI and MLOps infrastructure company, moved onto it after 1.5 to 2 months building their own engine on Lago, and now books $145K+ in annual savings, iterates 6x faster on pricing, and runs 750+ pricing features. Plan migration and grandfathering at cutover live in Pricing Experiments. To walk the mapping against your plan list, book a demo.
How do you map the old pricing model onto the new one?
Map constructs, not plan names. A plan called Pro is a container for separate pricing decisions, and each needs its own home in the new system. Discount ordering matters as much as the rates: applying a coupon before a credit gives a different total than the reverse.
Incumbent construct | What it becomes | Where it goes wrong
|
|---|---|---|
Tiers hard-coded per SKU | A rule-based price, boundaries as data | One plan per SKU gets recreated, so the explosion survives |
A prepaid balance as one figure | A credit ledger with grants, expiries, priority | Expiry and rollover were enforced by hand, never stored |
An annual commitment with true-up | A commitment plus per-cycle overage terms | The true-up was a spreadsheet, so nothing imports |
A customer on a retired plan | A pinned plan version with an audit trail | It's rebuilt as "close enough" and the bill moves |
Write the mapping down before you touch the new system, and make whoever signs enterprise contracts read it. Disagreements caught there don't surface later inside a usage reconciliation report.
How long should a parallel run last?
Three consecutive full billing cycles, which for monthly billing lands inside the 8 to 16 week window published rollout guidance assigns to revenue-critical systems.
Three is the floor because each cycle exercises what the others can't:
Cycle one catches configuration errors: wrong meter, tier boundary, or currency.
Cycle two catches lifecycle events, which appear only once customers upgrade or cancel mid-cycle.
Cycle three catches period boundaries: backdated usage landing after a close, and the re-rating that follows.
Set tolerances in currency before cycle one, not after a diff appears. A worked example:
Inputs: 400 subscriptions, a 12-week window of three monthly cycles, average invoice $2,050.
Invoices compared: 400 x 3 = 1,200.
Incumbent total: 400 x $2,050 x 3 = $2,460,000.
Investigate at 0.01% drift: $2,460,000 x 0.0001 = $246.
Pause at 0.1% drift: $2,460,000 x 0.001 = $2,460.
Per-invoice gate at 0.5% of the average: $2,050 x 0.005 = $10.25, rounded to $10.
The per-invoice gate earns its keep. One invoice overstated by $1,900 and another understated by $1,880 net to $20, clearing the aggregate gate while both customers get billed wrong.
What makes a billing migration fail?
Migrations fail on what nobody scoped: corrections, contracts, and customers whose pricing was never really in the system.
Cutting over mid-cycle with no owner for the split. Both systems issue a partial invoice and support has no authoritative version.
No rollback condition. The cutover gets planned, the trigger for reversing it doesn't.
Changing the engine and the prices together. A mapping bug and an intended increase look identical.
Reconciling against the new system's own output. A draft invoice proves only that the new system agrees with itself.
Related terms
Terms worth reading alongside the execution:
Build vs Buy (Billing) covers the decision that comes first.
Billing Engine names the component you're replacing.
Usage Reconciliation is the discipline the variance report borrows from.
Re-Rating explains what happens when a migrated rate turns out wrong.
Backdated Usage is the event class most likely to split two systems.
Draft Invoice is the artifact you compare during parallel running.
FAQ
Can you migrate mid billing cycle?
You can, but one system has to own the cycle while the other sits idle. Cutting over on day one of a period gives every invoice one author, and staggered anniversaries are better handled in cohorts by renewal date.
Do you have to migrate historical invoices?
No, and most teams shouldn't. Move open and unpaid invoices, since the new system has to collect them, and leave closed ones in the incumbent as a read-only archive.
Is a billing system migration the same as changing your pricing model?
No. A system migration replaces the software that issues invoices while prices stay put, and a pricing-model change moves customers between commercial structures. Run both at once and you can't tell the two apart.
Back to glossary
