Switch from cPanel to Koapanel Without Leaving WHMCS

26 September 2026 · read 9 min · Koapanel

If you bill with WHMCS, you can move off cPanel without rebuilding clients, invoices, products or automations: WHMCS drives control panels through server modules, and Koapanel has an official module that covers the same lifecycle as the cPanel one. The real work is installing the module, adding a server, setting up matching products, and then moving existing services over one at a time, with Koapanel's migration tool and a way back if something goes wrong.

Why this works: WHMCS server modules

WHMCS has no built-in knowledge of cPanel as such. Every hosting product is tied to a provisioning module (a server module) and to a server or server group. When an order is paid, an invoice goes overdue or a customer upgrades, WHMCS calls the module's functions: create, suspend, unsuspend, terminate, change package, change password. See the provisioning modules developer docs and the list of supported functions.

The practical consequence: clients, contracts, billing cycles, promotions, payment gateways, suspension rules and tickets stay exactly where they are. What changes is which module and which server each service points to.

What the Koapanel WHMCS module does

The koapanel module supports WHMCS 8.x and 9.x and Koapanel 0.21.0 or later. Here is what each WHMCS command does on the panel:

A few details that matter day to day:

• Idempotent creation: if WHMCS runs Create twice on the same service (say, after a timeout), you don't get duplicates.
• Passwords and usernames fixed automatically: if the WHMCS password is too weak for the panel (at least 12 characters, 5 distinct), the module generates a strong one and saves it to the service; an invalid username (3–32 characters, a-z 0-9 . _ -) is corrected and saved.
• Client-area quick links: the service page shows Panel, Files, WordPress, Email, Databases, each logging the customer straight into that section. Suspended accounts get no login links.
• Reseller products: set the account type to Reseller and the module creates a reseller on the panel; the product limits become its quota (accounts, disk, sites, mailboxes).
• Automatic packages: leave the package empty and the module creates a panel package with the product's limits (for example "WHMCS 3s-10g-5d-20m") and reuses it for identical services.
• Configurable options named Sites, Disk (GB), Databases, Mailboxes, Accounts let customers pick their limits.

The module authenticates with a panel API key, limited to 300 requests per minute per key. Every action appears in the panel's Activity log as "via API key WHMCS …", and WHMCS logs each call under Utilities › Logs › Module Log (keys and passwords are never logged). The Koapanel for WHMCS page and the manual chapter WHMCS and API keys sum it all up.

Step 1: create an API key in the panel

Log into Koapanel as an administrator and open API keys › Create key (name it "WHMCS", for instance). Copy the kpk_… key right away: it is shown only once.

A key acts as its account. A reseller's key can only create accounts among that reseller's clients, with its packages and within its quota; selling reseller products needs an administrator key.

Step 2: install the module in WHMCS

Download the zip and extract it into the WHMCS root (here /var/www/whmcs; adjust to your install):

cd /tmp
curl -fsSLO https://console.koapanel.app/updates/integrations/koapanel-whmcs-1.0.0.zip
unzip koapanel-whmcs-1.0.0.zip -d koapanel-whmcs
sudo cp -r koapanel-whmcs/modules/servers/koapanel /var/www/whmcs/modules/servers/
# only if you resell Koapanel licences:
sudo cp -r koapanel-whmcs/modules/servers/koapanel_license /var/www/whmcs/modules/servers/

That's it: WHMCS picks up the modules on its own. On the WHMCS side you need PHP 8.1 or later with curl, json and mbstring (WHMCS 9.0 requires PHP 8.2 or 8.3), and the WHMCS server must reach the panel on port 8443. The full guide also ships as README.en.md inside the zip.

Step 3: add the server

Go to System Settings › Servers › Add New Server:

Click Test Connection; it should succeed. Save the server and add it to a server group.

Step 4: create products (or duplicate your cPanel ones)

The quickest way to keep prices, billing cycles, welcome emails and options is to duplicate your existing cPanel products and change only the Module Settings tab: Module Koapanel, the new server group, and the module options. In the current release the option labels are in Italian, so here is what they mean:

A practical tip: first create panel packages that match the plans you sell today, then map products to them. Hide the old cPanel products from the order form once new orders should land on Koapanel.

From here on, new orders are provisioned on Koapanel. What's left is your existing customers.

Step 5: move existing customers, one service at a time

Each service involves two separate jobs: moving the data (sites, databases, mail) from the cPanel server to the Koapanel server, and pointing the WHMCS service at the new server. The order we suggest:

1. Point the service at the new server. In the client profile, Products/Services tab, change the Product/Service field to the matching Koapanel product and the Server field to the Koapanel server, then save. The module comes from the product, so the product change is what moves the service to the Koapanel module. Check that the recurring amount and next due date haven't changed.
2. Create the empty account. Under Module Commands, click Create. The module creates the panel account with the service's existing username (cPanel usernames usually already fit Koapanel's rules; if not, the module corrects the name and saves it to the service). If the stored password is too weak, the module generates a new one and saves it to the service, so keep that in mind when you email the customer.
3. Move the data. With Koapanel's migration from a backup file you import the full cPanel account backup, choosing the account you just created as the destination; with migration over SSH the panel connects to the cPanel server itself, as root if you like, and lists the accounts to bring over. It imports sites, files, databases (with new passwords, rewritten into wp-config.php), mailboxes with messages and original passwords when the mail service is on, and cron jobs paused for review.
4. Switch DNS after the final sync (available for 7 days with SSH migration), having lowered the TTL the day before.

These steps follow general WHMCS behaviour as described in the Products/Services tab documentation. Check the docs for your WHMCS version, and do a dry run on an internal service before touching real customers. Also make sure the product's package is large enough: migration respects the package limits and free disk space. For the cPanel side in depth, see Migrate from cPanel.

Testing checklist for each service

• "Login" from the admin area and the client area opens the panel; the Files, WordPress, Email and Databases quick links work.
• Sites respond from the new server (test with your hosts file before the DNS change) and the migration report shows no errors.
• Mailboxes send and receive, with MX, SPF and DKIM published.
• Suspend and Unsuspend from WHMCS work (try this on a test service, not a customer).
• Change Package applies the new limits; the next day WHMCS shows updated disk usage.
• The WHMCS Module Log shows no errors.

Rollback plan

The strength of this approach is that you can go back as long as the old server is untouched:

• Don't delete the cPanel account until the service has run cleanly for at least one cycle. After the switch WHMCS no longer manages it, so you'll remove it yourself in WHM at the end.
• Record each service's original product and server. To roll back, restore those values in the Products/Services tab and point DNS back at the old IP (with a low TTL this is quick).
• Never click Terminate on the service while testing: on Koapanel it deletes the account and its sites.

Telling your customers

A new control panel is a visible change, so announce it early. Give the date and window, what stays the same (invoices, price, WHMCS client area, email addresses) and what changes (the panel interface, no .htaccess because the server runs nginx, SFTP instead of plain FTP). Remind them they can log in with one click from the client area, and that database passwords change but WordPress sites are already updated.

Reselling licences? The koapanel_license module

If you're a partner provider and want to sell Koapanel licences to your own customers (say, VPS clients), the same zip includes the koapanel_license module. You need a kpp_… partner key issued by Koapanel to partners. Add a server with Hostname console.koapanel.app, Module Koapanel Licenze, Password = partner key, Secure, port 443; then a product of type "Other" with the Plan (Starter, Pro, Agency…). On Create the module issues the licence and stores the activation code in the service, where the customer sees it in the client area. Suspend, Unsuspend, Terminate and Change Package all work, and the Libera per un altro server button ("free for another server") unbinds the licence so it can be activated elsewhere. Terms and wholesale pricing are on the providers page.

The limits, stated plainly

• Koapanel runs only on Ubuntu 24.04 LTS with nginx: no Apache or .htaccess, no LiteSpeed, no CloudLinux. Customers relying on complex .htaccess rules need them translated to nginx.
• The module requires WHMCS 8.x or 9.x, PHP 8.1+ and Koapanel 0.21.0 or later.
• Account migration is done by Koapanel, not by WHMCS: repointing services in WHMCS is manual, service by service.

If you depend on Apache or CloudLinux, cPanel is still the better fit. If the reason you're moving is cPanel's pricing, it's worth running the numbers.

FAQ

Do I have to re-import customers into WHMCS?

No. Clients, invoices and services stay in WHMCS; you only change each service's product and server and create new products using the Koapanel module.

Can cPanel and Koapanel run side by side during the move?

Yes. They're two servers with two different modules in the same WHMCS, so you can move services gradually and send new orders to Koapanel.

What if WHMCS runs Create twice?

The module is idempotent: repeating Create on the same service won't make a second account.

Can I sell reseller hosting from WHMCS?

Yes, with the account type set to Reseller and an administrator API key. See resellers and our guide on starting a reseller hosting business.

Try it on a test server first

Install Koapanel for free on a fresh Ubuntu 24.04 server with curl -fsSL https://get.koapanel.app | sudo bash, connect it to a test copy of WHMCS and move one internal service. If you run several servers, check the terms for providers or get in touch to plan the switch.