The WHMCS importer reads an existing WHMCS installation’s MySQL database directly and rebuilds its clients, catalogue, services, domains, invoices, credit balances and support tickets inside RackHelm. It lives at Import Data → WHMCS Data Import (/admin/import/whmcs) and is part of the import family described in Data Import Tools. If you are moving from Blesta or ClientExec instead, see Importing from Blesta or Importing from ClientExec.
Before you start #
Warning: Import into a fresh install, and take a database backup first. The importer writes directly into your live catalogue, users, orders, invoices and tickets. There is no undo.
You need read access to the WHMCS MySQL database — host, port, database name, username and password. A read-only account is sufficient, and importing from a restored copy of the database works just as well as the live one. In a default install only a Super Admin sees the Import Data menu; the permission details are in Data Import Tools.
What does not come across #
WHMCS encrypts service passwords, server passwords and stored card data with a key that never leaves that installation, so none of it is imported. Two things follow from that:
- Client passwords are not portable. Imported clients are created with a random password and use Forgot password the first time they log in.
- Saved payment methods do not transfer. Card tokens are encrypted with the old installation’s keys, so customers re-authorise their payment method once after the move.
Connection #
| Field | Notes |
|---|---|
| Database Host | Required. Pre-filled with 127.0.0.1 — but see the warning below. |
| Database Port | Required. Defaults to 3306. |
| Database Name | Required. Typically whmcs. An existing installation’s connection details are all in configuration.php in the WHMCS root. |
| Database Username | Required. A read-only account is sufficient. |
| Database Password | Required. |
The credentials are used once to run the import and are not saved to the system.
Warning: By default the database importers refuse private and reserved addresses, including
127.0.0.1and anything on your LAN — the host is resolved and pinned to a public IP before connecting, to stop the form being used to probe internal services. To import from a local or internal database, enable the importer’s allow-private override in.envfirst — see the private-address guard in Data Import Tools and The .env File Explained. Without it you get the same generic “Could not connect to the specified database” message as a genuine connection failure.
Import options and sync modes #
Six entity groups can be imported independently:
| Group | What it reads | Needs |
|---|---|---|
| Clients & Contacts | Client records (tblclients) and their login users (tblusers). Imported clients are given your default client role. |
— |
| Products & Pricing | Product groups, products, billing cycles and addons. | — |
| Services | Hosting services (tblhosting). |
Clients + Products |
| Domains | Registered domains (tbldomains). Unlike ClientExec and Blesta, WHMCS keeps domains in their own table, so they have their own toggle. |
Clients |
| Invoices & Credit | Invoices and each client’s credit balance. | Clients |
| Support Tickets | Departments, tickets and replies. | Clients |
The dependencies are enforced on the screen and again on the server: untick Clients and everything that needs it unticks and disables itself, so a group can never run without its prerequisites in the same run.
Each group has its own sync mode:
| Mode | Behaviour |
|---|---|
| Try Update Before Insert | Updates an existing record where one matches, otherwise creates it. The default and the right choice for a re-run. |
| Only Insert (Skip existing) | Creates new records and leaves anything already present untouched. |
| Only Update (Skip new) | Refreshes records that already exist and creates nothing. |
Tip: The modes make the import safely re-runnable. A common cutover plan: import everything early with Try Update Before Insert, keep trading in WHMCS, then run the importer again just before the switch to pick up the delta.
Pricing currency #
The Pricing Currency field controls the catalogue only. RackHelm stores one price per product and billing cycle and converts at display time, so only a single WHMCS currency can be imported as the catalogue. Leave it blank to use whichever currency WHMCS has marked as its default, or enter a three-letter code to pick another.
Your customers, their invoices and their credit are not limited to that currency: WHMCS’s currency list, tax rules, per-client currency and VAT numbers are all imported alongside, and historic invoices keep the currency they were issued in.
Running it #
- Fill in the connection details and choose your entity groups and modes.
- Start the import. RackHelm tests the connection first and refuses to start if it fails.
- The import runs in the background; the log panel on the page polls for progress every couple of seconds. You can navigate away — it keeps running.
Only one import runs at a time — a second attempt while one is in flight is refused as already running. The credentials are held briefly in the cache under a single-use key and cleared as soon as the background process picks them up; if they expire before it starts, just start the import again. The on-screen panel mirrors a log file under storage/logs/ on the server, and the run finishes with an Import Summary: block listing what was processed.
Tip: Do a first pass with Products & Pricing only and check the catalogue looks right before importing clients, services and invoices on top of it. Everything downstream inherits whatever the products pass produced.
After the import #
- Spot-check the catalogue, a few clients, their services and a handful of invoices against the WHMCS originals.
- Tell your customers to use Forgot password on first login, and to re-add their payment method.
- Check your queue workers are running so any jobs queued by the import are processed — see Maintenance, Logs and Health.
Troubleshooting #
| Symptom | Cause and fix |
|---|---|
| “Could not connect to the specified database” with details you know are correct | Almost always the private-address guard — the importer refuses internal hosts by default. See Data Import Tools for the .env override. The message is deliberately identical for every failure reason. |
| “Connection credentials expired” | The cached credentials are short-lived. Start the import again. |
| A group was skipped or cannot be ticked | Its prerequisites are not enabled in the same run. Services needs Clients and Products; Domains, Invoices and Tickets need Clients. |
| “already running” | Only one import runs at a time. Wait for the current run’s Import Summary: before starting another. |
| The log panel stops updating | Read the importer’s log file under storage/logs/ directly on the server; the panel only mirrors that file. |
| Catalogue prices are in the wrong currency | Only one WHMCS currency becomes the catalogue. Re-run the products group with the right code in Pricing Currency. |
