Pre-Migration Checklist

Before You Begin#

Complete every item on this checklist before importing any data. Skipping steps here causes problems that are much harder to fix after client records are in the system.

Environment Setup#

• Install Commerce on a staging subdomain (e.g., billing-new.example.com) — do not migrate directly to production without a staging test first
• Confirm the staging install can send and receive HTTPS traffic
• Point staging to a separate database from any future production database

Email Configuration#

• Configure SMTP settings in Admin → Settings → General → Email
• Set MAIL_FROM_ADDRESS and MAIL_FROM_NAME in .env
• Send a test email via Admin → Settings → General → Send Test Email and confirm delivery
• Verify the From address does not land in spam (check SPF/DKIM records for your sending domain)

Payment Gateways#

• Configure your payment gateways in Admin → Settings → Payment Gateways
• Test each gateway in sandbox/test mode with a test transaction
• Note the webhook URLs for each gateway — you will need to re-register them after DNS cutover
• Confirm that gateway webhook endpoints are excluded from CSRF protection (check VerifyCsrfToken middleware)

Product Catalog#

• Create product groups in Admin → Products → Groups (WHMCS "product groups" map directly)
• Create all products manually — products do not migrate automatically due to structural differences
• Set up pricing for each billing cycle on each product
• Configure configurable options or add-ons that were attached to WHMCS products

[!IMPORTANT] Products must exist before you import services. Services reference products by ID. If the product doesn't exist, the service import will fail or leave services without a product association.

Tax Configuration#

• Configure tax rules in Admin → Settings → Taxes to match your current WHMCS tax setup
• Verify that tax rates apply correctly by previewing an invoice for a test client

Staff Accounts#

• Create at least one staff account for yourself before importing clients (see Migrating Staff Accounts)
• Confirm that staff login works correctly on the staging install

WHMCS Backup#

• Take a full MySQL dump of your WHMCS database: mysqldump whmcs_db > whmcs_backup_$(date +%Y%m%d).sql
• Store the backup in a location outside the web root
• Note the highest invoice number in WHMCS: SELECT MAX(id) FROM tblinvoices;
• Note the highest client ID: SELECT MAX(id) FROM tblclients;
• Record these numbers — you will configure Commerce's sequences to start after them

Invoice Number Continuity#

• Determine what your last WHMCS invoice number was (e.g., INV-4821)
• Configure Commerce's invoice number sequence to continue from the next number
• This prevents duplicate invoice numbers which cause confusion for clients and accountants

[!TIP] Run the full checklist twice — once during your staging test, and again immediately before production cutover. Conditions can change between those two points (new payment gateway, new staff member, updated tax rules).