Import client records into WHMCS using a supported workflow and a reviewed mapping of source identities. A successful upload is only the beginning: account ownership, duplicates, currency and communication settings must still be checked.
IN THIS ARTICLE
01 Choose the supported import method
ImportAssist supports database imports from documented applications and versions, and WHMCS 9.0 adds CSV support for client or customer data. Confirm that ImportAssist is available and installed for your deployment. Its CSV client workflow should not be treated as a general service, invoice or payment-token importer.
Download the current blank CSV template from the official ImportAssist documentation. Preserve its exact headers and format, and populate required fields from the authoritative customer record. Do not invent missing contact details or reuse one customer email merely to make validation pass.
02 Review identity and duplicate handling
Decide how source IDs map to destination clients before importing. A client ID that matches an existing record can merge imported data into that record. Matching email or UUID values also affect duplicate handling. An unrelated source database's number is not automatically a safe destination identifier.
Create a mapping sheet or internal record that links the source client to the intended destination. Include customers sharing a business contact address in the review, and distinguish user login identity from the billable client account.
03 Run a controlled import
- Back up the destination and create an isolated rehearsal environment. Disable outgoing messages and production actions during testing.
- Prepare a small representative
.client.csvfile using the current template. Include ordinary records, international addresses and cases that could collide with existing customers. - Open Addons and ImportAssist for WHMCS, then Select CSV Upload.
- Select the file and the supported client data type. Continue to the validation and preview screen.
- Review every reported validation error and the preview. Correct the source file instead of repeatedly importing uncertain rows.
- Continue only after the mapping is verified. Record the completion result and reconcile imported counts with the intended rows.
04 Validate the resulting accounts
Inspect representative client profiles, currencies, tax identifiers, language and account status. Check the associated user and owner relationship. Confirm that no unwanted welcome or billing messages were sent and that existing customer details were not overwritten unintentionally.
Keep a list of rejected or skipped rows with the exact reason. Reconcile those rows individually rather than treating a lower imported total as a successful complete migration. After the final import, protect and retire temporary files according to the data-retention plan.
Plan the first customer sign-in separately from the import. Confirm the supported invitation or password-recovery route for the resulting user record, then test it with an authorised sample account before sending a broader migration announcement.
05 Example: resolve a numeric client-ID collision before import
Suppose two independent systems each contain a client numbered 17. The matching number is an identifier collision, not evidence that the clients are the same business.
| Record | Illustrative identity | Decision |
|---|---|---|
| Source client 17 | Example Design Company | Identify the intended destination from the verified migration mapping. |
| Existing WHMCS client 17 | Example Garden Company | Do not merge the source record into this unrelated client. |
Keep this row out of the final import until its destination is resolved. Use the current template and importer rules to represent a new client or the verified existing client. Review email and UUID values as well, because removing an ID alone does not eliminate every duplicate-handling condition. Rehearse the resolved row privately and check the resulting account owner before continuing with the larger file.
Common questions
Can the importer process a file automatically?
The documented private import directory supports correctly named client CSV files processed by cron. Use the interactive validation workflow first and control who can place files there.
Should the same file be imported again after an uncertain result?
First inspect the destination and import result. Repeating an import can merge or duplicate data depending on its identifiers, so establish which rows completed before retrying.