Migration
Migrating from WHMCS without losing invoice history
The financial history is the part of a WHMCS migration you cannot re-create later. What to take, what to leave, and how to prove the numbers match.
15 min read · Reviewed 2026-09-21
In short
Run a preflight that reads the export and reports what it found without writing anything: how many records, which fields are missing, which currencies appear, which services point at things that no longer exist. Fix the findings, then import. A preflight costs an afternoon and routinely saves a weekend.
Blesta is a capable billing system with its own opinions, documented at docs.blesta.com, and those opinions show up in an export. Its client, service and transaction model does not map cleanly onto every other system, which means the interesting work in a Blesta migration is in the mapping rather than in the moving.
What a preflight should tell you
A preflight reads the export and writes nothing. It should answer, before you commit to anything:
- Counts by record type, so you can compare them against the source system's own reports.
- Fields present and absent. A required field missing on 3% of rows is a decision to make now, not a failure to hit at 2am.
- Currencies. More than one is a design question, not a detail.
- Orphans. Services pointing at deleted clients, invoices pointing at deleted services, payments with no invoice.
- Date ranges. The earliest and latest record of each type, which catches truncated exports immediately.
- Duplicates by the key you intend to match on — email address, usually — because that is the key that will collide.
A preflight that can write is not a preflight. The value comes from being able to run it repeatedly, on production data, with no possibility of a side effect.
The mappings that need a decision
| Blesta concept | The question you must answer |
|---|---|
| Client groups | Do these become customer tags, pricing tiers, or nothing? |
| Packages and pricing terms | Rebuild by hand, or map? Rebuilding is usually right |
| Service configurable options | Do they become product options, or are they folded into the price? |
| Transactions applied to several invoices | Your new system must support part-application, or the history will not reconcile |
| Credits and negative transactions | Are these credit notes, refunds, or account balance? They are not the same |
| Coupons | Historic discounts are part of the invoice, not a live rule to carry over |
The transaction row is the one that catches people. A payment applied across three invoices is one fact in Blesta and, in a system that models a payment as belonging to an invoice, three incompatible ones. Check this before you plan the migration, because it may decide which system you move to.
Reconciling afterwards
- Totals per year: invoiced, received, outstanding. These must match exactly.
- Per-customer balances for the twenty largest customers, checked by hand.
- Count of active services per product, compared against what the servers actually hold.
- Spot-check ten invoices end to end — line items, tax, payments applied, the resulting balance.
- Confirm no customer received an email during the import. This is the one that embarrasses you publicly.
Keep the import repeatable
The single most useful property of a migration is being able to throw the result away and do it again. That means: never hand-edit imported data, keep the raw export unchanged, and make every correction a change to the mapping rather than to the destination. Expect to run it more than once.
Where GENV is
GENV's migration workbench includes a preflight that checks a manifest and imports nothing, a mapping step that refuses unknown columns rather than dropping them silently, and a reconciliation view. Support threads and financial history are imported into their own tables as historical evidence — all of it, including invoices still owed, because none of it becomes a GENV invoice or takes an invoice number. The workbench handles staged waves so a large migration can be done in parts with each part reconciled before the next.
Questions
How long does a Blesta migration take?
Longer than the final import suggests, because the rehearsals are the work and the final run is comparatively quick. Plan by the reconciliation rather than by a number somebody else quoted: you are finished when the totals agree, and how many attempts that takes depends on how tidy the source data is.
Can I keep both systems running for a while?
For reading, yes and you should. For invoicing, no — pick a date after which only one system raises invoices, and disable it in the other.
What if the export is missing data I need?
Query the database directly if you have access, and keep that query alongside the export so the extraction is repeatable. An undocumented one-off extraction is a step nobody can repeat when the import needs re-running.
Sources
Official documentation, each requested on 21 September 2026. Provider behaviour changes; check the source before relying on a detail.