Migrate WHMCS to Blesta: end-to-end checklist

Moving a live billing platform is the part of switching panels nobody wants to own. Done badly, you lose invoice continuity, break recurring charges, or force every customer to reset their password on day one. Done correctly, the cutover is a DNS change and a config flag.

This checklist covers a WHMCS-to-Blesta migration end-to-end: staging install, character set repair, Import Manager run, the auth_legacy_passwords trick that keeps old WHMCS password hashes valid, and the modules you have to recreate by hand. It assumes Blesta 5.2+ importing from WHMCS 5.2 through 8.2. Want the business case first? Read Blesta vs WHMCS in 2026.

1. Install Blesta on a staging server

Do not migrate in place. Stand up a fresh Blesta on a separate host (or at minimum a separate database and document root) so the WHMCS instance keeps running until cutover. You will run the import multiple times before you trust the result.

# typical layout
/var/www/blesta-staging          # Blesta 5.x source
blesta_staging                   # empty target database

Activate the Blesta license against the staging hostname; you can move the license to the production hostname at cutover from the client area.

2. Repair the WHMCS character set

WHMCS installs from before 7.x default to latin1. Blesta's Import Manager reads the data, but anything beyond ASCII — accented client names, non-Latin domains, emoji in ticket replies — arrives mangled. Fix the source schema before importing, not after.

ALTER DATABASE whmcs CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Database-level alone is not enough; existing tables keep their old collation. Generate the per-table statements:

SELECT CONCAT('ALTER TABLE `', table_name,
       '` CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;') AS stmt
FROM information_schema.tables
WHERE table_schema = 'whmcs' AND table_type = 'BASE TABLE';

Pipe the output back through mysql. Take a dump first — a few TEXT columns can hit row-size limits and need their type adjusted.

3. Install the Import Manager plugin

In Blesta admin go to Settings → Company → Plugins → Available, find Import Manager, and install. It ships with the core distribution but is not enabled by default.

4. Run the import

Settings → Company → Plugins → Import Manager → Import. Choose WHMCS as the source, then enter the WHMCS database host, name, user, password, and the cc-encryption key from WHMCS configuration.php. Without the key, credit card data does not decrypt and clients with auto-pay break.

The importer walks: clients → contacts → packages → services → invoices → transactions → support tickets. Expect 10-15 minutes per 1,000 clients on a 2-vCPU VPS. Watch /var/www/blesta-staging/logs_blesta/ for plugin errors; a single malformed invoice can halt the run.

5. Enable legacy password compatibility

Out of the box, Blesta cannot validate WHMCS bcrypt hashes — the salts differ. Without the legacy flag every existing user has to reset their password at cutover. Avoid that by enabling backwards compatibility:

// /var/www/blesta-staging/config/blesta.php
Configure::set('Blesta.auth_legacy_passwords', true);

With this on, Blesta tries its native hash check first, then falls back to the WHMCS algorithm. On a successful legacy login the password is rehashed to Blesta's format silently. Leave the flag enabled for at least 90 days post-cutover, then audit and disable.

6. Sanity-check on a sample account

Pick five accounts that exercise the awkward paths: an annual prepayment, a monthly with a credit balance, a closed account, a reseller, and a domain-only client. Verify invoice totals match the WHMCS originals to the cent, next-due dates are unchanged, and the credit card token still charges (test with a $1 manual invoice on Stripe sandbox — see Blesta Stripe Payments setup).

7. Recreate modules and gateways

The Import Manager moves data, not configuration. Provisioning modules (cPanel, Plesk, Virtualmin), registrar modules (Enom, ResellerClub), and payment gateways do not migrate — Blesta and WHMCS use different module APIs. Reinstall each from Settings → Company → Modules / Gateways, configure with the same API credentials, then link existing services to the new module instance.

Email templates also do not transfer. Export the customer-facing templates from WHMCS, paste into Blesta's template editor, and adjust the {$client} style tags to Blesta's {client.first_name} syntax.

8. Cutover

Schedule a 30-minute maintenance window. Freeze WHMCS (disable cron, set the storefront to read-only), run a final delta import, change DNS for billing.example.com to the Blesta host, and swap the Blesta license to the production hostname. Keep WHMCS reachable on an internal hostname for 30 days for audit lookups, then archive the database and shut it down.

Next steps

• Configure your first gateway with Blesta Stripe Payments setup.
• Compare options before committing: Blesta vs WHMCS in 2026.
• Buy or transfer a Blesta license, or talk to sales via contact for volume pricing.