WHMCS cPanel Integration: Setup, API Token and Common Errors

WHMCS cPanel integration means adding your cPanel & WHM server to WHMCS at Configuration > System Settings > Servers with the built-in cPanel module, a WHM username and an API token, then pointing each hosting product at a WHM package. WHMCS can then create, suspend, unsuspend and terminate accounts. Most failures come from token privileges, a firewall or a package name.

I checked the menu paths and privilege names below against the WHMCS 9.0 and cPanel documentation on 10 October 2026. The WHMCS 8.13 documentation shows the same Configuration menu.

What does the built-in WHMCS cPanel module do?

It lets WHMCS create, suspend, unsuspend and terminate cPanel accounts, change their package or password, update usage figures and show a login link in the client area. The WHMCS cPanel module documentation lists those eight features. The server needs a valid cPanel & WHM license.

It is not cPanel Extended For WHMCS, which people also search for. That is a paid third-party module from ModulesGarden that puts cPanel functions inside the WHMCS client area.

What must be in place before you connect WHMCS to cPanel?

You need three things: open ports, a WHM package and two-factor authentication that does not block API requests.

• Ports 2086 and 2087 are open for outbound connections from the WHMCS server. WHMCS uses 2087 with SSL and 2086 without it.
• WHM has at least one package, created at Packages > Add a Package.
• If two-factor authentication is on in WHM, it is switched off for API requests. Log in as root, open Security Center > Configure Security Policies and untick API requests.

How do you create the WHM API token for WHMCS?

You create it in WHM at Development > Manage API Tokens with the Generate Token button. WHMCS accepts a WHM password or an API token. I use a token, because it can be limited to chosen privileges and to the IP address of the WHMCS server, and it can be revoked without changing the root password.

1. Click Generate Token, enter a name and choose whether the token expires. An expired token stops working, so note the date or choose no expiry.
2. In the IPs box, enter the IP address of the WHMCS server. A blank box lets any address use the token.
3. Under Privileges, untick everything that is not in the table below.
4. Click Generate and copy the token at once. WHM does not show it again.

The cPanel documentation on API tokens adds two cautions. It calls privilege restrictions on tokens experimental. It also warns that Create User Session and Manage API Tokens let a token holder get around the restrictions you set, and WHMCS asks for both. Treat even a scoped token like a root password.

How do you add the cPanel server in WHMCS?

You add it at Configuration > System Settings > Servers with the Add New Server button.

1. Select cPanel for Module.
2. Enter the hostname or IP address, the WHM username and the API token.
3. Click Go to Advanced Mode for the other settings, such as the nameservers, Maximum No. of Accounts and the Secure checkbox.
4. Click Test Connection, wait for the success message, then click Save Changes.

WHMCS puts the nameservers in welcome emails and uses Maximum No. of Accounts to judge how full a server is. Secure turns on SSL. If this is your only cPanel server, click its name in the list and check that an asterisk appears. The asterisk marks the default server for the module.

How do WHM packages map to WHMCS products?

Each WHMCS product names one WHM package in its Module Settings tab. Open the product at Configuration > System Settings > Products/Services, choose Shared Hosting as the product type, set Module Name to cPanel and pick the plan in WHM Package Name. The name stored in WHMCS has to match WHM exactly, so a package renamed in WHM stops matching. The error is You do not have permission to use Selected Package.

• No package. Leave WHM Package Name empty, click Switch to Advanced Mode and type the limits. A blank field means unlimited.
• Reseller hosting. Choose Reseller Hosting as the product type, enter the limits in advanced mode and name an existing WHM ACL list in Reseller ACL List.

At the bottom of the tab, choose when WHMCS creates the account: when the order is placed, when the first payment is received, when you accept a pending order, or never automatically. For paid hosting I pick first payment.

How do server groups and fill rules work in WHMCS?

A server group is a set of servers that a product provisions onto, and its fill type decides which server gets the next account. Create one with Create New Group on the Servers page, then assign it to a product in the Module Settings tab. The server groups documentation gives two fill types.

• Add to the least full server, judged by the percentage of each server's Maximum No. of Accounts in use.
• Fill the default server until it reaches its account limit, then move to the next one.

Both rules count accounts, not disk space or load, so Maximum No. of Accounts is the only capacity figure WHMCS knows.

How does WHMCS sync disk and bandwidth usage from cPanel?

The daily cron run pulls disk space and bandwidth figures when Update Usage Statistics is ticked under Miscellaneous at Configuration > System Settings > Automation Settings. Utilities > Automation Status has a Server Usage Stats row that shows whether the last update succeeded. A server that is enabled in WHMCS but unreachable can make the update fail, so disable servers you have taken offline.

How does single sign-on from WHMCS to cPanel work?

Single sign-on lets a client or an admin open cPanel from WHMCS without typing the cPanel password. Three rules from the WHMCS single sign-on documentation explain most failures.

• A client user needs the View Products & Services and Perform Single Sign-On permissions.
• An admin can sign in to any account owned by the WHM user saved on the server. To limit that, edit the server and set Access Control to Restricted under SSO Access Control.
• A reseller WHM user must own the account. If it does not, the result is Action Failed Unable to auto-login. Please contact support. The same message appears when the username on the service is empty.

How do you import existing cPanel accounts into WHMCS?

You import them with the Sync Accounts button on the Servers page. WHMCS fetches the account list from the server and shows a report, with differences in red. What Import/Sync does depends on the row, according to the Sync Accounts documentation.

• On the server, not in WHMCS. WHMCS creates a service, using a matching product or creating a new one. It attaches the service to the client with the same email address, or creates a new client.
• Active in WHMCS, missing on the server. WHMCS sets the service to Terminated.
• In both, with different details. WHMCS changes its own record to match the server.

Which errors appear when the WHMCS cPanel connection fails?

The usual messages are a cURL connection error, Login Failed and Access Denied. WHMCS documents a cause for each one.

For anything else, open Utilities > Module Queue, which lists failed module actions with the error text. The Module Log at Configuration > System Logs records what WHMCS sent and what WHM answered, but only after you set Module Logging to On. Set it to Off when you finish.

What are the limits and risks of the WHMCS cPanel integration?

Four things can hurt you: the token, Sync Accounts, failures nobody retries and kept DNS zones.

• The token is powerful. Restrict it to the IP address of the WHMCS server and revoke it when you replace it.
• Sync Accounts changes data. It can mark services Terminated and create products and clients. Take a database backup and read every row before you tick it.
• Failures wait for you. WHMCS does not retry a failed module action. It sits in the Module Queue until someone clicks Retry.
• A kept DNS zone blocks re-creation. If you tick Keep DNS Zone when terminating, you cannot create a new account for that domain on the server until the zone is deleted.

How do you test the integration before taking orders?

Run one account through its whole life on a test client. Add an order from the admin area, run Create under Module Commands on the service, and confirm in WHM that the account has the right package. Then log in to cPanel from the service page, and suspend, unsuspend and terminate the account. Only then switch on automatic suspension.

I do this work as part of larger WHMCS and hosting projects; see WHMCS development and hosting infrastructure consulting. For the rest of a first configuration, read how to set up WHMCS.

Last reviewed 10 October 2026. Disclosure: I am a freelance WHMCS developer and I sell WHMCS and cPanel setup as a service, so I am not neutral. I am CTO at ElySpace, a freelance developer for Marmaids LLC, and founder of WHMCSPilot and MagizAI.