WHMCS migration checklist
Prepare your move from WHMCS to LucidCP with a clear checklist for backups, supported records, connection settings and final checks. Test the migration in a separate staging environment before making changes to your live customer database.
Procedure
Migration planning checklist
-
01
Inventory the source and agree the scope
The migration module offers 17 selectable groups: currencies, customer groups, customers, product groups, servers, products, services, TLDs, domains, orders, invoices, transactions, support departments, tickets, coupons, knowledge base and announcements. Transactions also include credit-history rows; services may include hosting add-ons. The module targets WHMCS 7–9 database layouts, but a version label alone does not establish compatibility with your installation. Compare source counts, custom fields and authentication structures before approval.
-
02
Back up both systems and isolate the rehearsal
Make restorable backups of the WHMCS database and files, and the LucidCP database, application files and encryption configuration. Test restoring a copy before importing. Use a separate LucidCP staging installation and a copy of the source database. Keep scheduled billing, queue workers, real payment callbacks, outbound email/SMS and provider-side service actions disabled or isolated during rehearsal. Imported products can retain automatic-provisioning settings: importing data is not a substitute for operational isolation.
-
03
Configure the WHMCS connection
Sign in as a super administrator, open /admin/import in your LucidCP installation and expand WHMCS → LucidCP. Enter Db Host, Port (normally 3306), Db Name, Username and Password for the source copy. Create a dedicated source database user with read-only privileges; the migration module reads the source, but the form does not create or enforce database grants. Limit network access to the required application host. Connect and continue validates the source and creates a draft run in LucidCP; it is not the start of record transfer.
Step 3 of 11 · WHMCS connection settings with example staging database details. Use your own read-only database credentials. Click to view the full-size screenshot.Select the preview to inspect the full-resolution interface. -
04
Check password handling separately from account data
The optional cc_encryption_hash comes from the source WHMCS configuration.php and is used to decode service and server passwords. If it is absent, those passwords are not carried over. Enter secrets only in the private wizard, never in support screenshots. The customer mapping reads tblclients.password: recognized bcrypt hashes are retained and supported legacy MD5 formats are checked on first login. Login compatibility depends on your source authentication structure. Verify the authentication tables and test representative customers, including any separate users or contacts.
-
05
Review source counts and select dependent records
After connecting, review every count and any table error. The selection screen shows Source, Previously migrated and Requires. Dependencies are included automatically: invoices, for example, pull in customers, services, domains and their prerequisites. Select currencies explicitly when needed; not every operational dependency is automatically selected. Resolve missing-table errors before proceeding. The wizard requires confirmation that the LucidCP database has been backed up before Start migration.
-
06
Run a controlled batch and inspect all exceptions
The progress page offers chunk sizes of 25, 50, 100 or 200; start with 50 and keep the tab open. Browser requests drive the next batch, so closing the tab pauses further requests rather than starting a background worker. Pause stops requesting new batches; reopening a running run continues it. Review transferred, skipped and error counts plus the notes, not only the progress percentage. A run can finish despite skipped records or a failed data type, and the displayed notes retain only the latest 500 entries.
-
07
Understand resume and cancellation before retrying
Source-to-target mappings and the last processed source ID are retained for the same source identity. The current database source identity uses the importer, host and database name. Resuming can avoid re-adding mapped rows, but it is not an update/synchronization pass over older records. Skipped rows also advance the cursor and are not automatically repaired by a rerun. Keep the source identity stable and investigate exceptions in staging. Stop does not roll back transferred rows: it ends the run and removes its saved connection details. Restore the agreed backup for rollback; do not delete mappings and blindly run again.
-
08
Reconfigure servers, products and registrar settings
Test each imported server connection, then configure LucidCP’s module-specific product settings and package/template identifiers. WHMCS product module settings are not copied. Unknown server modules or registrars can fall back to manual, and a source server group maps to its first server rather than preserving placement policy. Review all billing cycles: triennial service amounts become annual amounts divided by three. Product pricing uses the source default-currency row (or a fallback row), and TLD mapping imports one-year prices. Reconcile currencies, additional renewal periods, configuration options and add-ons explicitly.
-
09
Reconcile money, ownership and customer access
Compare customer ownership, balances, invoice totals, tax, payment dates, due dates, credits, refunds and transaction references against the source copy. Existing customers matched by email are reused; their account fields and balances are not overwritten by the customer mapping. Imported invoice and order numbers use WH- prefixes. Test paid and unpaid invoices, a suspended service, an expiring domain and a legacy-password login. Verify customer-visible services, invoices and ticket history; internal staff notes must remain private. Do not mark invoices paid just to make totals match.
-
10
Account for unsupported or manual items
Payment tokens, saved cards, recurring gateway mandates, staff accounts, additional customer contacts, custom modules/hooks, templates, custom fields, configurable-option definitions and ticket attachments are not transferred automatically. Plan these items separately. Guest tickets without a mapped customer are skipped. Coupon mapping supports percentage and fixed-amount discounts, not every WHMCS promotion type. Reconfigure gateway and registrar credentials independently, and test recurring-payment ownership without charging real customers during rehearsal.
-
11
Approve the cutover and keep a rollback window
Freeze source-side writes for an agreed maintenance window, take final backups and record counts, then perform the approved migration procedure. A rerun does not synchronize changes to previously imported rows; reconcile those changes explicitly or repeat the rehearsal in a clean target restored from the agreed baseline. Check the renewal dry-run, provider mappings, customer access and gateway callbacks before enabling automation in one system only. Change DNS and announce the new panel only after acceptance. Retain the old system and protected backups for the agreed retention period; resolve any post-cutover payments before attempting a rollback.
Checklist
Best practices
- Compatibility depends on your WHMCS version, extensions and database structure. Complete a staging migration and verify the results before scheduling your live move.
- A completed progress bar is not proof of a complete migration. Resolve skipped rows and per-type errors against the original inventory.
- Run automated migration tests only in a disposable test environment: verification scripts can write records and clear application caches.
- Never reset or truncate a live customer database. Keep restorable backups of both systems and an agreed rollback plan before transferring records.
