In this guide 6 sections
First reconcile the diverged copies into one codebase, then turn each customer’s custom changes into settings. Migrate data with record counts and totals checked, pilot with one friendly account, and cut over customers one at a time. Keep each old install running until its owner signs off.
Step 1: find out how far the copies have drifted
Take every customer’s installed version and compare it against your main branch. Count changed files, added tables, edited stored procedures and local patches. The diff shows you the real size of the job.
Some copies will be one patch behind. Others will have a developer’s fingerprints on login, invoice layout and the reports module. Sort customers into groups by distance from the core.
Start the plan with the closest group. Easy wins fund patience for the hard ones.
- Version and last update date per install
- Custom files and database objects found by diff
- Integrations unique to that customer
- Whether anyone still understands the changes
Step 2: turn customer changes into configuration
A custom invoice footer becomes a template setting. An extra approval step becomes a workflow toggle. A special discount rule becomes a pricing rule stored as data. The goal is one codebase and many configurations.
Some requests will not generalise. Decide for each: promote it to a product feature, offer it as a paid extension, or retire it. Write the decision against the customer’s name.
Review these with the account owner, because a customer may agree to drop a quirk that nobody remembers asking for.
Step 3: migrate data and prove it arrived
Script the move so it can run many times. Export from the old database, map IDs into the new tenant’s key space, load into a staging copy and compare. Never trust a first run.
Record checks matter more than the load itself. Compare row counts per table, totals of invoices and payments, and a sample of fifty records read side by side.
Files travel too. Attachments, logos and generated PDFs must land under the right tenant path, and the links in old records must still open.
- Row counts per table, old against new
- Sum of invoice, payment and stock values
- Orphan checks on foreign keys after the load
- Spot-read of a sample by the customer’s own staff
Step 4: pilot with one account
Choose a customer who is patient, close to the core version, and on friendly terms. Run their new tenant in parallel with the old install for a full billing cycle.
Ask their staff to log every difference they notice. Sort the list into bugs, missing configuration and habits that only need explaining.
Fix, re-run the migration script, and compare again. Move on only when the pilot customer stops finding gaps.
Step 5: cut over one customer at a time
Schedule each cutover outside the customer’s busy days. Freeze writes on the old install, run the final migration, check the totals, and switch the login address.
Keep the old copy read-only for an agreed period. If something is wrong, you compare against it instead of arguing from memory.
Close each move with a signed checklist, then archive the old install. Book the next customer before you finish the last one.
Customer cutover tracker
A one-page tracker with one row per customer. Columns cover version distance, custom changes and their decision, migration run date, record check result, pilot or cutover date, sign-off name, and the date the old install is archived. A header block holds the freeze time and the rollback contact.
Open a blank worksheet to printQuestions owners ask
How long should the old install stay available after cutover?
Keep it read-only until the customer has closed at least one full billing or month-end cycle on the new platform and confirmed their figures match.
What if a customer insists on keeping a custom feature?
Offer it as a configurable option or paid extension inside the shared codebase. Do not keep a forked copy, because it brings the original problem back.
Do all customers move at the same time?
No. Move them in groups ordered by distance from the core, starting with a pilot. A single big-bang move multiplies every risk.
How do I check that migrated data is complete?
Compare row counts, monetary totals and foreign-key integrity between old and new, then have the customer’s staff read a sample side by side.