The output is customer-facing on day one
The first bill run after cutover goes to real customers with real amounts. There is no soft launch, no percentage rollout, and no way to correct it without a conversation.
Guide · Chargebee Migration
Migration tooling moves records. It does not decide what a legacy plan should become.
Chargebee provides automated migration for several source systems, and that is the straightforward half. The project is deciding how each legacy plan maps to a new item price, what happens to mid-term amendments, and how you prove the new system bills the same customers the same amounts. This guide covers the planning, the data decisions and the cutover.
12+
500+
40+
250+
Trusted by 500+ organizations — including SaaS, subscription and usage-based businesses running their quote-to-revenue operations on Salesforce, HubSpot and Chargebee with Twopir Consulting.
Migration Experience
- Salesforce Partner
- HubSpot Partner
- Zuora
- Recurly
- Stripe Billing
- In-House Systems
- Parallel Run
- Invoice Reconciliation
What makes this different from any other data migration
A CRM migration that loses a field is an annoyance. A billing migration that gets a renewal date wrong sends the wrong invoice to a paying customer, and there is no silent fix for that.
Dates carry contractual meaning
Billing anniversaries, term end dates, notice periods and escalator dates are contractual. Shifting one by a day changes what a customer owes and when they can leave.
Legacy plans do not map one to one
Years of accumulated plans, grandfathered prices and one-off deals rarely fit the new catalog cleanly. Every mismatch is a decision, and there are usually hundreds.
Payment credentials are not simply copied
Cards are vaulted with a gateway and referenced by token. Whether those tokens can move depends on the gateways involved, and getting it wrong means asking your entire base to re-enter card details.
History has to survive intact
Historical invoices are accounting records. They must move with their original timestamps and amounts, and they must not be regenerated under the new catalog.
Revenue recognition spans the cutover
Contracts that started before the move and end after it need recognition schedules that are continuous across two systems, or the close after cutover will not balance.
The decisions to make before anyone exports anything
Migrations go wrong in planning and get discovered in reconciliation. These are the questions worth answering first.
A Chargebee migration is the work of moving customers, subscriptions, invoices, credit notes and payment methods from a legacy billing system into Chargebee, with the commercial model re-expressed in the new catalog and the result proven against the source before cutover.
Chargebee offers automated migration tooling for several source systems including Stripe, Zuora and Recurly, and imports historical data with its original timestamps so the new site becomes the single source of truth for current and past billing. The tooling handles movement; it does not make the modelling decisions below.
| Planning question | Why it is decided first | Common answer |
|---|---|---|
| Do we migrate the catalog as-is or redesign it? | Redesigning during migration doubles the risk but avoids carrying years of accumulated debt into a new system you will live with for a decade. | Redesign the structure, map legacy plans onto it, and grandfather prices rather than plan shapes. |
| How far back does history go? | Determines the volume, the reconciliation effort and how much of the audit trail lives in the new system versus the old one. | Full history for open and recently closed accounts; an agreed cut-off with the source system kept read-only for the rest. |
| Can payment tokens move? | If they cannot, every customer has to re-enter card details — which is a significant churn event, not a technical detail. | Confirm with both gateways early. It shapes the whole timeline and sometimes the choice of gateway. |
| Do billing dates stay or normalise? | Preserving anniversaries is contractually safe; normalising them simplifies operations but changes what customers are charged and when. | Preserve anniversaries. Normalise only with explicit commercial sign-off and customer communication. |
| What happens to mid-term amendments? | A subscription amended three times has a history the new system may not be able to represent in the same shape. | Migrate current state plus the amendment history as records; do not attempt to replay amendments through the new engine. |
| Who owns revenue recognition across the cutover? | Contracts spanning the move need continuous schedules or the first close after cutover will not reconcile. | Agree the split with the controller and auditors before the date is chosen. |
| What is the freeze window? | Changes made in the source system during the load will be lost unless captured, and a delta load is materially harder than a freeze. | A short, communicated freeze, timed against the billing cycle rather than the calendar month. |
What moves, and what has to be decided about each thing
The entity list is short. The decisions attached to each entity are where migrations actually spend their time.
| Entity | What moves | The decision attached to it |
|---|---|---|
| Customers | Identity, billing address, contact details, tax registration, currency and entity assignment. | How parent-child hierarchies map, and whether duplicates in the source are merged or carried across. |
| Product catalog | Plans, addons, charges and price points re-expressed as the new catalog. | Which legacy plans consolidate, which stay distinct, and how grandfathered prices are represented. |
| Subscriptions | Current state: plan, quantity, price, currency, term, billing anniversary, next billing date, status. | Whether to preserve or normalise dates, and how to represent a subscription the new catalog cannot express exactly. |
| Payment methods | Gateway tokens where portability allows, otherwise a re-collection campaign. | Confirmed with both gateways before the plan is fixed — this one can change the whole approach. |
| Invoices and credit notes | Historical documents with their original numbers, dates and amounts, immutable. | How far back, and whether the source system stays available read-only for anything older. |
| Payments and refunds | Transaction history linked to the invoices they settled. | Whether partial payments and unapplied credits carry across as balances or as opening adjustments. |
| Account credits and balances | Outstanding credit, unapplied payments and wallet balances. | Frequently missed entirely, and always noticed by the customer who had the credit. |
| Usage history | Consumption records for metered plans, at least for the open period. | How much history is needed for reporting versus what is required to bill the current period correctly. |
| Coupons and discounts | Active discounts, their remaining duration and redemption history. | Whether a perpetual legacy discount is recreated as a discount or as a grandfathered price point. |
Three strategies, and when each one is right
Chargebee's own guidance uses a dual-site approach — data reviewed thoroughly in a test site before it is imported to the live site, because changes made to a live site are irreversible. How you then move customers across is the strategy decision below.
Everyone moves at once
One freeze, one load, one cutover date. Operationally simplest and the only option when the old and new systems cannot both bill the same customer. It is also the highest-variance choice, which is why the parallel run beforehand is not optional.
- Simplest to operate and explain
- One freeze window, one reconciliation
- No period of dual operation
- Highest blast radius if something is wrong
- Right for most single-entity businesses
Cohort by cohort
Move a low-risk cohort first — monthly self-serve customers, one region, one entity — prove the process, then move the rest. Both systems bill simultaneously for a period, which means reporting has to span both.
- Small blast radius on the first wave
- Process proven on real customers
- Both systems live for weeks or months
- Reporting must consolidate two sources
- Right for large or multi-entity bases
Stop the bleeding, then backfill
All new customers go into Chargebee immediately; the existing base migrates later or runs off naturally. Fastest route to value when the legacy system is the constraint on selling, but it leaves two systems running indefinitely.
- Immediate benefit for new sales
- No migration risk on day one
- Existing base unaffected initially
- Two systems to operate, possibly for years
- Right when legacy blocks new pricing
| Cutover step | What happens | Exit condition |
|---|---|---|
| Parallel run | A full billing period is processed in both systems and compared invoice by invoice. | The variance report is empty, or every difference is explained and accepted. |
| Freeze | Changes in the source system stop, communicated in advance to every team that touches billing. | A confirmed freeze with a named owner on both sides. |
| Final delta load | Anything that changed since the last full load is applied. | Record counts and financial totals match the source exactly. |
| Verification | Spot checks on high-value accounts, edge cases and each customer archetype identified in planning. | Sign-off from finance, not just from the project team. |
| Go live | Chargebee becomes the system of record; the source goes read-only. | The rollback decision point has passed deliberately, not by default. |
| First bill run | The first real invoices go out, monitored closely. | Invoice count, total value and credit note volume all within expectation. |
| Hypercare | Two full billing cycles with elevated support. | Two clean bill runs and a period closed without manual intervention. |
Related Pages
The delivery engagement behind this guide is Chargebee implementation — Chargebee implementation, including migration and cutover Chargebee integration architecture guide — and the architecture the new stack should land on Chargebee consulting services — the wider Chargebee practice
What goes wrong, and what it costs
Every item here we have either seen or been called in to repair.
Skipping the parallel run
The single most expensive shortcut available. Without billing a full period in both systems and comparing invoice by invoice, the first real bill run is the first test — and it runs against paying customers.
Migrating the catalog unchanged
Carrying every legacy plan and one-off price point into the new system moves the debt rather than clearing it. Two years later the catalog is unmanageable and the opportunity to fix it cheaply has gone.
Assuming payment tokens will move
Token portability depends on the gateways involved and is not guaranteed. Discovering this late turns a technical migration into a re-collection campaign across the entire base, with the churn that implies.
Normalising billing dates without sign-off
Moving anniversaries to a common date simplifies operations and changes what customers are charged and when. Doing it quietly produces disputes; doing it deliberately with communication is fine.
Forgetting account credits
Outstanding credit, unapplied payments and wallet balances are easy to omit from a mapping document and impossible to hide from the customer who had them.
Regenerating historical invoices
Historical invoices are accounting records. Reissuing them under the new catalog produces documents with different numbers and sometimes different amounts, which is an audit problem and a customer-facing one.
Leaving recognition until after cutover
Contracts spanning the migration need continuous recognition schedules. Deciding how afterwards means the first close does not reconcile and nobody can say why.
Treating it as a finance-only project
Sales, CS and support all read billing data daily. If the CRM handover and the support view are not migrated alongside, those teams lose their operating picture at exactly the moment customers start asking questions.
Six phases with exit conditions, not dates
Discovery & Data Profiling
We profile the source data before promising anything: how many plans, how many exceptions, what state the customer records are in. Estimates before profiling are guesses.
Catalog & Mapping Design
Target catalog designed, every legacy plan mapped onto it, exception policy agreed, and the planning decisions above answered in writing.
Test Site Load
Data loads into a test site first, because changes to a live Chargebee site are irreversible. Nothing touches the live site until it has been proven here.
Reconciliation
Record by record against the source: counts, amounts, dates, statuses. Differences are explained rather than counted.
Parallel Run
A full billing period processed in both systems and compared invoice by invoice, with your finance team reviewing the variance report.
Cutover & Hypercare
Freeze, delta load, verify, go live — against a runbook with a rollback point — then two full billing cycles of elevated support.
Data and systems migration from the same practice
Moving commercial data between systems without losing the operating picture is long-standing Twopir work.
Accounting Seed & Salesforce Integration
Financial data brought onto one record with reconciliation designed into the process rather than performed after the fact.
- Financial data consolidation
- Bi-directional synchronisation
- Reconciliation at period end
- Reporting across ops and finance
Salesforce & HubSpot Integration
Two platforms reconciled record by record with ownership and conflict rules agreed before any data moved.
- Cross-platform record mapping
- Ownership and conflict resolution
- Lifecycle alignment across systems
- Consolidated reporting view
Salesforce CPQ & Multi-Tool Integration
Catalog and price book restructured alongside the systems that consume them, without disrupting live quoting.
- Catalog and price book redesign
- Multi-system data migration
- Quote and approval continuity
- Operational reporting preserved
We profile the data before we quote the project
We help growing and mid-market companies solve complex CRM, integration and business system challenges, and we run the same migrations for enterprise teams at larger record volumes and across more entities.
We profile before we estimate
How many plans, how many exceptions, what state the customer records are actually in. A migration estimate given before profiling is a guess, and the variance lands on you rather than on us.
The parallel run is not negotiable
Billing a full period in both systems and reconciling invoice by invoice is the only place a modelling error is cheap to find. We will push back in writing if a timeline tries to remove it.
We redesign the catalog rather than copying it
Migrating years of accumulated plans unchanged moves the debt into a system you will live with for a decade. We map legacy plans onto a clean structure and grandfather prices, not plan shapes.
We migrate the CRM side at the same time
Sales, CS and support read billing data daily. As a Salesforce Partner and HubSpot Partner we move the CRM handover alongside, so those teams do not lose their operating picture during cutover.
Every phase has an exit condition
Not a date. Proceeding because the calendar said so is how migrations arrive at cutover with unresolved design decisions, and it is the pattern behind most of the repair work we get called in for.
Migration questions answered properly
For a single-entity business with a manageable catalog, three to four months is typical from kickoff to a completed cutover. Multi-entity structures, usage-based pricing, large historical volumes or a complicated amendment history run five to eight months. The variable is catalog complexity and source-data quality, both of which we profile before giving an estimate rather than after.
Yes. Chargebee offers automated migration for several source systems including Stripe, Zuora and Recurly, provides templates and API documentation for the rest, and imports historical data with original timestamps so the new site becomes the single source of truth for current and past billing. The tooling moves records reliably. It does not decide how a legacy plan maps to a new item price, what happens to mid-term amendments, or whether your billing anniversaries should be preserved — and those decisions are the project.
It depends entirely on gateway token portability, which is why it is one of the first questions we ask. Cards are vaulted with the gateway or with Chargebee's vault partner and referenced by token; where the source and destination arrangement allows those tokens to transfer, customers notice nothing. Where it does not, you are running a re-collection campaign across the base, which is a churn event and changes the whole plan. Confirm it with both gateways before committing to a timeline.
Redesign, in almost every case. Copying years of accumulated plans, one-off price points and grandfathered rates moves the debt into a system you will operate for the next decade, and the opportunity to fix it cheaply never comes back. The safe approach is to design a clean target structure, map legacy plans onto it, and grandfather prices rather than plan shapes, so no customer's economics change.
Loading and reviewing everything in a Chargebee test site before importing anything to the live site. It matters because changes made to a live site are irreversible — so the test site is where mapping errors, duplicate records and date problems get found. It is Chargebee's own recommended approach and we have never run a migration any other way.
Yes, and for large or multi-entity bases it is often the better choice. Moving a low-risk cohort first — monthly self-serve customers, or a single region — proves the process on real customers with a small blast radius. The cost is a period where both systems are billing, which means reporting has to consolidate two sources and your team has to operate both. That trade-off is worth making above a certain size and not below it.
It has to be continuous, which means deciding before you pick a date rather than after. Contracts that started in the old system and end in the new one need recognition schedules that span both, and the split has to be agreed with your controller and, where relevant, your auditors. Leaving it until after cutover is reliably how the first close fails to reconcile.
Next Step
Profile the data first, and the timeline stops being a guess
We will profile your source system, map the catalog, answer the planning questions in writing and come back with a phased plan including the parallel run. Migration from Zuora, Recurly, Stripe Billing or an in-house system, with the CRM side moved alongside.
Guide last reviewed September 2026 — tooling and gateway rules change
