Migrating from WHMCS
Stacklane can import your clients, their users, credit, domains, hosting services and unpaid invoices from WHMCS. The import reads WHMCS through its API and writes directly into the Stacklane database.
How the import works#
You run the import from the command line on the Stacklane server:
sudo -u stacklane stacklane import whmcs \
--url https://billing.example.com/includes/api.php \
--identifier <identifier>
The command asks for the API secret. It then:
- Loads the panel servers and hosting plans you have set up in Stacklane.
- Reads all clients from WHMCS, 250 at a time.
- For each client, reads the client details and creates an organization, a user and the credit balance.
- For each client, reads the domains, the products and the unpaid invoices, and imports them.
- Prints a summary and a list of the items it skipped.
The import is not a transaction. If it stops halfway, for example because WHMCS is unreachable, the records that were already imported stay. You can run the command again and it continues where it stopped. See Running the import again.
Before you start#
1. Create a WHMCS API credential#
The import uses the WHMCS API with an API credential (an identifier and a secret). Create a credential in WHMCS for an administrator, with an API role that allows these actions:
| API action | Used for |
|---|---|
GetClients | List all clients |
GetClientsDetails | Name, company, address, VAT number, phone, email and credit |
GetClientsDomains | Domains of a client |
GetClientsProducts | Products and services of a client |
GetInvoices | Unpaid invoices of a client |
GetInvoice | Lines, VAT and balance of an invoice |
The import only reads from WHMCS. It does not need any action that changes data.
If your WHMCS installation only allows API access from known IP addresses, add the address of the Stacklane server.
The API URL is the includes/api.php file of your WHMCS installation, for example https://billing.example.com/includes/api.php. Stacklane requires https for this URL. Only localhost and 127.0.0.1 may use http.
2. Set up servers and plans in Stacklane#
Hosting services are only imported when Stacklane can match them to a server and a plan. Set these up first in the back office:
- Add each cPanel/WHM or DirectAdmin server under Administration → Panel servers.
- Add a hosting plan for each WHMCS product under Administration → Hosting plans.
See How services are matched for the exact rules.
3. Check the dunning settings#
Unpaid invoices are imported with their original due dates. Every five minutes, Stacklane suspends the services and stops the servers of customers with an open invoice that is overdue for more than the number of days in Administration → Billing settings → Suspend after (days overdue). The default is 14 days.
If you import invoices that are already overdue, those customers are suspended a few minutes after the import. To prevent this, set Suspend after to 0 (never suspend automatically) before the import, and set it back when you have checked the invoices.
Stacklane does not send payment reminders for imported invoices.
4. Make a backup#
Make a backup of the Stacklane database before the import:
sudo -u stacklane stacklane backup /var/lib/stacklane/backups/before-whmcs-import.db
Do a dry run#
Run the import with --dry-run first:
sudo -u stacklane stacklane import whmcs \
--url https://billing.example.com/includes/api.php \
--identifier <identifier> \
--dry-run
Dry run: 342 client(s) found, nothing was changed.
A dry run reads the client list and the details of every client. It counts the clients and changes nothing. It does not read domains, products or invoices, so it does not tell you which services will match a plan.
Use the dry run to check that:
- the URL, identifier and secret are correct
- the API role has the needed permissions
- the Stacklane server can reach WHMCS
Run the import#
sudo -u stacklane stacklane import whmcs \
--url https://billing.example.com/includes/api.php \
--identifier <identifier>
WHMCS API secret:
Imported 342 client(s), 340 user(s), 518 domain(s), 297 service(s) and 41 unpaid invoice(s); 1520.75 of credit.
skipped: user info@example.com already exists
skipped: service Reseller XL (web9.example.net) has no matching server and plan
Imported users sign in after choosing a new password via "Forgot password".
You can also give the secret in the environment variable STACKLANE_WHMCS_SECRET or with --secret. Do not use --secret on a shared server, because other users can see command lines.
Each request to WHMCS has a timeout of 60 seconds. If WHMCS returns an error, the import stops and prints it, for example error: WHMCS returned an error: Authentication Failed.
What is imported#
Clients#
Each WHMCS client becomes a Stacklane organization.
| Stacklane field | WHMCS source |
|---|---|
| Organization name | Company name, or first and last name if there is no company |
| Company name | companyname |
| VAT number | tax_id |
| Phone | phonenumberformatted, or phonenumber |
| Address lines | address1, address2 |
| City, postal code, state | city, postcode, state |
| Country | countrycode, or country |
| Billing email | email |
Users#
For each client with an email address, Stacklane creates one user:
- the email address in lower case
- the client's first and last name (or the organization name)
- the role
administratorin the new organization - English as the language and
Europe/Amsterdamas the time zone - the email address marked as verified
- a random password that nobody knows
Passwords are not imported. Tell your customers to choose a new password with Forgot password on the sign-in page. Make sure outgoing email works before you do. See Configuration.
If a Stacklane account with the same email address already exists, the organization is created without a user and the summary shows skipped: user ... already exists.
Additional WHMCS contacts and sub-accounts are not imported.
Credit#
A positive credit balance is added to the organization's balance, with the ledger entry Credit imported from WHMCS.
Domains#
Only domains with the status Active are imported. Other statuses, such as Cancelled or Expired, are skipped without a message.
For each domain, Stacklane stores:
- the domain name in lower case
- the expiry date
- the nameservers from
ns1andns2 - the registrar
manual, with no registrar ID - automatic renewal: on, unless the domain has Do not renew set in WHMCS
If the domain already exists in Stacklane, it is skipped with skipped: domain ... already exists.
Hosting services#
Only products with the status Active or Suspended are imported. A suspended product stays suspended in Stacklane.
Each imported service is linked to an existing account on the panel server by its user name. Stacklane does not create, change or provision anything on the panel. The account password is not imported.
How services are matched#
A WHMCS product is imported when all of these are true:
- The product's server host name (
serverhostnamein WHMCS) is the same as the host name in the API endpoint of a Stacklane panel server. The port is ignored. For example,web1.example.netmatches the endpointhttps://web1.example.net:2087. - That server has a hosting plan whose Package name is the same as the WHMCS product name. Upper and lower case do not matter.
- The product has a user name.
Otherwise the product is skipped with skipped: service <name> (<host>) has no matching server and plan.
Only cPanel/WHM and DirectAdmin plans have a package name. Pterodactyl game servers are not matched.
Unpaid invoices#
Only invoices with the status Unpaid are imported. Paid, cancelled and refunded invoices are not imported.
For each invoice, Stacklane stores:
| Stacklane field | WHMCS source |
|---|---|
| Invoice number | invoicenum, or WHMCS-<id> if the invoice has no number |
| Lines | Each invoice item with its description and amount, quantity 1 |
| VAT amount | tax plus tax2 |
| VAT rate | taxrate |
| Amount due | balance, or total |
| Currency | The invoice currency code, or EUR |
| Issue and due date | date, duedate |
| Customer details | Name, address, postal code, city, country, VAT number and email of the client |
Imported invoices keep their WHMCS number and do not use Stacklane's numbering. If an invoice with the same number already exists, it is skipped with skipped: invoice ... already exists.
What is not imported#
- passwords and two-factor settings
- contacts and sub-accounts
- domains that are not
Active - products that are not
ActiveorSuspended - products without a matching server and plan, and all Pterodactyl products
- paid, cancelled and refunded invoices
- transactions, payment methods and stored cards
- support tickets
- product and pricing configuration
Running the import again#
The import remembers every WHMCS client, domain, product and invoice it has imported, by its WHMCS ID. When you run it again:
- clients that were imported before are not created again
- for those clients, new domains, products and unpaid invoices are still imported
- records that were imported before are skipped without a message
This means you can:
- run the import again after it stopped because of an error
- add missing panel servers or plans and run it again to import the services that were skipped
- run it again shortly before you switch over, to pick up new clients and invoices
Changes in WHMCS to records that were already imported are not copied. For example, a new address of an imported client is not updated in Stacklane.
What to check afterwards#
- The summary. Read every
skipped:line. Add missing servers or plans and run the import again if needed. - Organizations. Open a few imported customers in the back office. Check the names, addresses and VAT numbers. Stacklane uses the VAT number and country to decide the VAT treatment of new invoices.
- Credit. Compare a few credit balances with WHMCS.
- Services. Check that each service is linked to the right plan and panel account. From the moment of import, Stacklane records usage for active and suspended services every hour and puts them on the next monthly invoice at the plan's price. Stop billing these services in WHMCS to avoid charging customers twice.
- Domains. Stacklane renews domains with automatic renewal on from the customer's credit when they get close to the expiry date (30 days before by default, set in Administration → Domains). Imported domains have no registrar ID in Stacklane. Decide before the first renewal is due which domains Stacklane should renew, and turn off automatic renewal for the others. Check that every extension has a renewal price.
- Invoices. Compare the open amounts with WHMCS. Set Suspend after back to the value you want.
- Email. Run
sudo -u stacklane stacklane checkand check that SMTP is configured. - Customers. Tell your customers to set a new password with Forgot password.