How to Migrate WHMCS to a New Server With Minutes of Downtime

To migrate WHMCS to a new server, copy the files and the database, keep the original configuration.php with its encryption hash, reissue the license, update the system URL, set up the cron and switch DNS. Client-facing downtime can stay at minutes when the files are copied in advance and only the final database copy happens in maintenance mode.

I checked the steps and menu paths below against the WHMCS 9.0 documentation on 10 October 2026. They apply to self-hosted WHMCS. The official tutorial does not cover WHMCS Cloud.

How much downtime does a WHMCS server move need?

Minutes, not zero, when the database copies quickly and the new server is prepared first. Something has to stop new orders and payments while the last database copy is made, or they stay behind on the old server. Three things set the length of that pause.

• Database size. The export, the transfer and the import all happen inside the window. A rehearsal gives you the real figure.
• What you copied beforehand. Files, attachments and downloads can go across days earlier. Only what changed since needs a second pass.
• DNS. The official tutorial warns that DNS record changes can require several hours. Visitors whose resolver still holds the old address reach the old server, so it stays in maintenance mode. Lowering the TTL of the record beforehand shortens that tail.

I do not quote a number of minutes before a rehearsal, because the database decides it.

What do you copy when you move WHMCS?

You copy three things: the files, the database and the configuration file. WHMCS itself describes an installation as those three parts. The table splits them into what you will handle.

What changes in configuration.php on the new server?

Only the database settings and any absolute paths change. The configuration.php reference lists the variables.

• Change: $db_host, $db_username, $db_password and $db_name for the new database.
• Change if the directory structure differs: $templates_compiledir and $crons_dir, plus $attachments_dir and $downloads_dir where the file defines them.
• Never change: $cc_encryption_hash. WHMCS states that if you lose this value, the system cannot decrypt your data. That covers stored card details, passwords and security questions.
• Leave alone: $license, unless you are given a new key.

Attachment and download locations are also set in the admin area at Configuration > System Settings > Storage Settings. If the absolute path is different on the new server, add a Local Storage configuration with the new path and switch to it.

In what order do you move WHMCS with minutes of downtime?

Prepare outside the window, then follow the order of the official Move WHMCS to a New Server tutorial inside it. Before the window:

1. Build the new server to the WHMCS system requirements with the same PHP version, and keep the same WHMCS version. My guide on how to set up WHMCS covers the requirements.
2. Lower the TTL of the DNS record for the WHMCS hostname.
3. Copy the files, create the database and its user, and run a trial import to time it.
4. If you open the trial copy in a browser, treat it as a test installation. Keep it private, leave its cron off and set Disable Email Sending to ON on the Mail tab, so it cannot email real clients. WHMCS offers development licenses for test copies.

Inside the window:

1. Disable the WHMCS cron job on the old server. This is the first official step, and it stops automation from changing data.
2. Tick Maintenance Mode on the General tab at Configuration > System Settings > General Settings. The Maintenance Mode documentation says the admin area, the API and hooks keep working, so ask staff to stop too.
3. Export the database, import it on the new server and copy the attachments and downloads that changed since the first copy.
4. Edit configuration.php on the new server.
5. Point the DNS record at the new server.
6. Reissue the license.
7. Check WHMCS System URL on the General tab and update it if the address changed. It must match the address in the browser exactly.
8. Create the cron job on the new server. Copy the command from Configuration > System Settings > Automation Settings. The System Cron documentation recommends a run every five minutes.
9. Log in to the admin area on the new server, run the first four checks below, then untick Maintenance Mode. The imported database still has it ticked.

When and how do you reissue the WHMCS license?

Reissue the license during the cut-over, once the files and database are on the new server and DNS points to it. That is where the official tutorial places it. How you do it depends on where the license came from.

• Bought from WHMCS: log in to the WHMCS Member Area, go to Services > My Licenses, select the key and click Reissue.
• Bought from a hosting provider: ask them to reissue it. If you are leaving that provider, you will need a new license key.
• New key: enter it at Help > License Information with Change License Key. If the admin area shows License Invalid, the error page has a link to enter a new key.

The License Information page shows the valid domains and directories for the key, and has a Force License Update button.

Which permissions and paths break after a WHMCS move?

The three writeable directories and configuration.php cause most faults after a move.

• Writeable directories. PHP must be able to write to attachments, downloads and templates_c. The Secure Writeable Directories documentation gives 755 for servers that run suPHP or PHP suEXEC.
• Ownership. Files copied as root often end up owned by root, and then PHP cannot write to them. Set the owner to the account that runs PHP.
• The template cache. A blank client area with a working admin area points to templates_c: a wrong path in $templates_compiledir, or a folder that is not writeable.
• The configuration file. WHMCS recommends chmod 400 configuration.php, or 440 or 444 where 400 stops the site loading. The file has to be writeable while WHMCS saves a new license key.

What should you check after the DNS cut-over?

Check licensing, automation, outside connections, payments, email and stored files, in that order.

1. Log in to the admin area. There should be no license error.
2. Open Configuration > System Health and read any new warning, such as the permissions check or a cron PHP version mismatch.
3. Open Utilities > Automation Status after the cron has had time to run, and read the badge.
4. At Configuration > System Settings > Servers, open each server and click Test Connection. Firewalls, API tokens limited by IP address and registrar allowlists may still name the old address.
5. Place a test order as a client and pay it with each gateway you use, then read Billing > Gateway Log. Check gateway callbacks and the redirect addresses of any sign-in or mail provider integration.
6. Read the Email Message Log for that order, and send a message to your support address to prove that ticket email still arrives.
7. Open an old ticket attachment and a download.

What can go wrong, and when should you not move WHMCS this way?

The main risks are a lost encryption hash, two active crons and orders left on the old server. Do not plan a window of minutes when the database is large or the move is combined with other changes.

• A lost encryption hash. Keep a second copy of the original configuration.php somewhere safe before you start.
• Two crons. If the cron runs on both servers, both copies of the data act on the same clients. Disable the old one first.
• Orders left behind. Anything written to the old database after the final export is not on the new server.
• A large database. If the rehearsal import takes longer than you can accept, announce a longer window instead of rushing.
• Too many changes at once. I do not combine a move with a WHMCS upgrade, a PHP change or a new domain. Each is a separate job with its own rollback.

The official tutorial ends with deleting the WHMCS files from the old server. I leave the old server in maintenance mode with its cron off for some days first, because it is the rollback.

I do this as a scoped job under WHMCS migration, and I move whole servers under server migration and backup.

Last reviewed 10 October 2026. Disclosure: I am a freelance WHMCS developer and I sell WHMCS migration as a service, so I am not neutral. I am CTO at ElySpace, a freelance developer for Marmaids LLC, and founder of WHMCSPilot and MagizAI.