Exporting Clients from WHMCS
Export client data from the WHMCS tblclients table. You can do this via the WHMCS admin panel (Utilities → Export) or directly via SQL:
SELECT id, firstname, lastname, email, companyname,
address1, address2, city, state, postcode, country,
phonenumber, currency, status, password
FROM tblclients
WHERE status != 'Closed'
ORDER BY id;
Save the result as a CSV file.
Required CSV Format
The Commerce client import expects a CSV file with the following headers:
| Column | Required | Notes |
|---|---|---|
first_name |
Yes | |
last_name |
Yes | |
email |
Yes | Must be unique |
company |
No | |
phone |
No | |
address1 |
No | |
address2 |
No | |
city |
No | |
state |
No | |
postcode |
No | |
country |
No | Two-letter ISO code (e.g., US, GB) |
currency_code |
Yes | Three-letter ISO code (e.g., USD, EUR) |
status |
Yes | active, suspended, or closed |
password |
No | Bcrypt hash from WHMCS, or leave blank to force reset |
Map WHMCS column names to Commerce column names before importing:
| WHMCS Column | Commerce Column |
|---|---|
firstname |
first_name |
lastname |
last_name |
companyname |
company |
phonenumber |
phone |
Running the Import
- Go to Admin → Clients → Import CSV.
- Upload your prepared CSV file.
- Review the column mapping screen and confirm field assignments.
- Click Import.
- Review the import summary — any rows that failed will be listed with the reason.
[!TIP] Test with a small batch of 5–10 clients first before importing your full list. This catches column mapping issues before they affect hundreds of records.
Password Handling
You have two options for client passwords:
Option A — Migrate existing passwords. WHMCS stores passwords as bcrypt hashes. Commerce uses the same algorithm. If you include the password column with the hash value in the CSV (or perform a direct DB insert), clients can log in with their existing passwords immediately.
Option B — Force password reset. Leave the password column blank or exclude it. Commerce will create accounts without a password, and clients will need to use the "Forgot Password" flow on first login. This is the safer option if you cannot confirm the hash integrity.
[!IMPORTANT] If using Option A with direct DB insert, ensure the hash column is stored in the
passwordfield of theclientstable verbatim. Do not double-hash the value.
Client Groups
If you use WHMCS client groups, create the equivalent groups in Admin → Clients → Groups before importing. Add a client_group column to your CSV with the group name, and the importer will assign clients to the matching group.
Custom Fields
If you have WHMCS custom client fields:
- Create the equivalent custom fields first in Admin → Settings → Custom Fields → Clients.
- Add the field values as additional columns in your CSV using the field slug as the column header.
- Re-run the import with the extended CSV.
[!WARNING] Custom field values imported before the field definition exists will be silently dropped. Always create field definitions first.