A WHMCS Proxmox integration is a provisioning module that calls the Proxmox VE API to create, suspend, unsuspend and terminate virtual machines or containers as WHMCS orders, overdue invoices and cancellations require. WHMCS ships no Proxmox server module of its own, so you install one from the WHMCS Marketplace or have a custom module written against the API.
A WHMCS Proxmox integration is the layer that turns a billing event into a hypervisor action. WHMCS owns the order, the invoice and the service record; Proxmox VE owns the virtual machine. The module between them translates one into the other and remembers which machine belongs to which service.
In words: map each WHMCS event to its API call, scope a token with a narrow role and a renewable expiry, build one Cloud-Init template per operating system, decide how logins reach the customer, then judge a module against the eight checks below. Every version, price and date here comes from a page I read on 20 November 2026.
What does a WHMCS Proxmox integration have to do?
It has to turn each WHMCS service event into the matching Proxmox VE API call, and remember which virtual machine (VM) belongs to which service. The table pairs the WHMCS provisioning module functions with the calls and privileges in the Proxmox VE API viewer. Containers use /lxc/ in place of /qemu/.
| WHMCS side | Job on Proxmox VE | API calls | Privileges |
|---|---|---|---|
CreateAccount | Clone the template, set hardware and logins, start it. | GET /cluster/nextid, POST /nodes/{node}/qemu/{vmid}/clone, POST .../config, POST .../status/start | VM.Clone, VM.Allocate, Datastore.AllocateSpace, SDN.Use, the VM.Config group, VM.PowerMgmt |
SuspendAccount, UnsuspendAccount | Stop the VM, then start it again on payment. | POST .../status/stop, .../status/start | VM.PowerMgmt |
TerminateAccount | Destroy the VM and disks, release the IP. | DELETE /nodes/{node}/qemu/{vmid} | VM.Allocate |
ChangePackage | Apply the new plan: cores, memory, disk. | POST .../config, PUT .../resize | VM.Config.CPU, VM.Config.Memory, VM.Config.Disk |
ClientAreaCustomButtonArray | Client area power buttons. | POST .../status/start, .../shutdown, .../reboot | VM.PowerMgmt |
UsageUpdate, MetricProvider | Usage for overage or metric billing. | GET .../rrddata | VM.Audit |
| Console | Open a browser console to the VM. | POST .../vncproxy, GET .../vncwebsocket | VM.Console |
Three details catch people out.
- Proxmox "suspend" is not a billing suspension. The
status/suspendcall suspends a running VM, and itstodiskoption is documented as "Will be resumed on next VM start". An unpaid service needs a stop, with the client area start button blocked. - Calls return a task, not a result. Clone, start and destroy return a task ID called a UPID. Poll
GET /nodes/{node}/tasks/{upid}/statusuntil it stops, then read the exit status, or WHMCS emails logins for a VM still copying. - The module must store what it created. The service properties page gives the pattern:
$params['model']->serviceProperties->save(['VM ID' => $vmid]), then->get('VM ID'). Save creates the custom field if missing; ten reserved names write to core fields instead, among them Username, Password and Dedicated IP.
How should the module authenticate to the Proxmox VE API?
With its own Proxmox user and an API token, privilege separation left on, and a custom role holding only the privileges it uses. Do not give it the root password. The Proxmox VE API page gives the base address as https://your.server:8006/api2/json/ and the token header as Authorization: PVEAPIToken=USER@REALM!TOKENID=UUID. A login ticket lasts two hours and needs a CSRF prevention token on every write; a token needs neither, which suits code running from the WHMCS cron.
pveum role add WHMCSProvision --privs "VM.Allocate VM.Clone VM.Audit VM.PowerMgmt VM.Config.CPU VM.Config.Memory VM.Config.Disk VM.Config.Network VM.Config.Cloudinit VM.Config.Options Datastore.AllocateSpace SDN.Use"
Role names starting with PVE are reserved for built-in roles. The user management documentation says a privilege-separated token can "never have permissions on any given path that their associated user does not have", so assign the role to both, and on paths rather than the whole cluster: /pool/{poolname} for the customer pool, plus the storage and the bridge. The secret is shown once and cannot be read back.
The console is the exception. The same page says "endpoints that provide access to the virtual machine or system console" require user privileges and cannot be accessed via an API token, while the API viewer's schema still marks vncproxy and vncwebsocket as token-allowed. The sources disagree, so I plan for a second, console-only Proxmox user and test it on the version in use. I build this plumbing under WHMCS API integration and automation.
How do you keep the Proxmox API token from stopping the cron?
Give it an expiry, put the renewal date in a calendar, and rotate the secret with the regenerate option so the permissions survive. An expired token stops provisioning that day, and WHMCS reports only a failed module command.
Proxmox recommends an expire timestamp in Unix epoch seconds "so that abandoned automation does not silently keep working". A cluster can also carry a token policy, set at Datacenter > Options > API Token Policy or on the command line, where 7776000 seconds is 90 days:
pvesh set /cluster/options --token-policy max-lifetime=7776000
Three points matter for a module holding the token:
max-lifetimeimpliesrequire-expiry, so no new token can be made without an expiry.- With
disallow-expiry-extension, an expiry can only be shortened. You then delete, recreate and reassign permissions. - With
allow-extension-on-regenerate, the token rotates in place:pveum user token modify <userid> <tokenid> --expire <timestamp> --regenerate 1. The old secret dies at once, so paste the new one into WHMCS in the same window.
How do you build the templates WHMCS products point at?
Build one Proxmox template VM per operating system, then point each WHMCS product, or each value of an operating system configurable option, at that template's ID. The Proxmox Cloud-Init documentation gives the sequence: import a cloud image or install the cloud-init package inside the VM, attach a Cloud-Init drive with qm set 9000 --ide2 local-lvm:cloudinit, set the boot order, then run qm template 9000. Three details decide whether a module can use it.
- Proxmox passes Cloud-Init data as a generated ISO, so every Cloud-Init VM needs a CD-ROM drive. A template built without one fails like a module bug.
- Many cloud images expect a serial console as the display (
--serial0 socket --vga serial0), and Ubuntu images need thevirtio-scsi-pcicontroller. - Cloning gives a linked clone by default: fast, but the new disk depends on the template. Pass
fullfor an independent copy.
My WHMCS VPS provisioning guide covers option syntax, IP pools and the lifecycle test.
How do login details reach the customer?
Through Cloud-Init on the guest, saved on the WHMCS service, and sent in the welcome email. Proxmox recommends SSH key authentication, and says a password "is not as safe as using SSH key-based authentication because Proxmox VE needs to store an encrypted version of that password inside the Cloud-Init data".
- Virtual machines. After cloning, set
ciuser,sshkeysorcipassword, andipconfig0through the config call. Collect a public key at order time with a WHMCS custom field. - Containers. The create call,
POST /nodes/{node}/lxc, takespasswordandssh-public-keysdirectly. - Password changes later. WHMCS shows the option only when the module defines
ChangePasswordand the service is active. On a running VM that needs the QEMU guest agent and theVM.GuestAgent.Unrestrictedprivilege; without the agent, a rebuild or the console.
Which WHMCS Proxmox modules are on the Marketplace?
A search for "proxmox" on the WHMCS Marketplace returned 26 listings on 20 November 2026, five of them free and 21 commercial. The search matches the word anywhere, so it also catches themes, billing addons and modules for other hypervisors.
Twenty sit under Provisioning Modules, and some of those provision other platforms. I opened three listings; I have not tested the code.
| Listing | Developer | What the listing said on 20 November 2026 |
|---|---|---|
| Proxmox VE VPS & Cloud For WHMCS | ModulesGarden | Commercial, shown at $59.95. KVM and LXC, noVNC, SPICE and xterm.js consoles behind a proxy. Lists Proxmox VE 8.x and 9.x, PHP 8.2 to 8.4, WHMCS 8.10 to 9.1, ionCube 15 or later, and API token authentication. Updated 28 October 2026, marked WHMCS 9.1. |
| Proxmox VE for WHMCS | The Network Crew Pty Ltd | Free under GPLv3, source on GitHub. VMs and containers, IP pools, noVNC through a second Proxmox user restricted to VM.Console. Requirements name WHMCS 8.x over HTTPS, PHP 8.x and Proxmox VE 8.x. Its setup adds the host with the root user. Updated 13 May 2026, marked WHMCS 8.13. |
| PUQ Proxmox KVM provisioning module | PUQ Software | Commercial, shown at $22.00. KVM only, in two parts: a server module and an addon owning IP pools, DNS zones and cron tasks. Version 4.1.0, released 8 October 2026, adds SSH key storage and a queue that holds the welcome email until the VM runs. Marked WHMCS 9.0. |
Read the requirements tab, not the headline: the PUQ page states Proxmox VE 7.x and 8.x in its description table and 8.x and 9.x in the requirements box. I also sell one outside the Marketplace, the Proxmox VE VPS Provisioning Module; weigh it against the same checks. My roundup of WHMCS addons and modules covers the rest of the cart.
When is a custom WHMCS Proxmox module the better route?
When your setup differs from what a ready-made module assumes, or when you need to read and own the code. Typical reasons are an existing IP address system, one VLAN per customer, or an approval step before creation. The work is a WHMCS server module in /modules/servers/ implementing the functions in the first table, and the cost is the upkeep. I build these under WHMCS custom module development.
In words: owning the code, an existing IP address system, a VLAN per customer or an approval step all point to a build. Otherwise shortlist modules and keep one only if it passes all eight checks below.
What should you check before choosing a module or a custom build?
Check these eight points against your own cluster, where the options differ.
- Guest types: KVM only, or LXC containers too.
- Storage and nodes: shared or local storage, and how a node is picked.
- IP addresses: who owns the pool, and whether IPv6 is handled.
- Credentials: a scoped API token, or the root user.
- Console: how it is proxied, and whether port 8006 must be open to customers.
- Suspension: a real stop, with the start button blocked.
- Failure handling: a half-built VM after a failed clone, or an IP pool that runs dry.
- Source and updates: encoded or readable, the last update date, the versions listed.
What breaks when you upgrade the Proxmox VE cluster?
Mostly access control. Proxmox "tries to stay API compatible in a major release" and promises nothing across a major bump. The current release is Proxmox VE 9.2, published 21 May 2026, per the Proxmox VE roadmap read on 20 November 2026.
| Change | Release | What it means for a module |
|---|---|---|
VM.Monitor privilege removed | 9.0 | A custom role listing it needs rewriting. |
Privileged containers need Sys.Modify | 9.0 | An LXC module creating them needs it added. |
VM.Config.Cloudinit to dump the Cloud-Init password (PSA-2026-00017-1) | 9.2 | Needed to read the generated password back. |
VM.PowerMgmt to start a VM after creation, restore or rollback | 9.2 | Custom roles only; shipped roles bundle it. |
| VNC endpoint fixes, breaking for external clients (PSA-2026-00014-1) | 9.2 | A console on a raw vncproxy port must adapt. |
Every row is a role or endpoint change, not a code change, so a cluster upgrade can break provisioning while the module file is untouched. Test on staging first.
What are the limits of selling Proxmox VPS through WHMCS?
The main limit is that WHMCS only sends instructions. Capacity, IP pools, templates, backups and the network stay your work on the Proxmox side.
- WHMCS must reach port 8006 on a node. Restrict it to the WHMCS server's address unless your console needs customer browsers, and give the node a valid certificate. That is ordinary Linux administration, and hosting infrastructure consulting covers it.
- A leaked token controls every guest in its scope, so the pool, the narrow role and the expiry all matter.
- Browser consoles add constraints. The free module needs WHMCS and Proxmox on different subdomains of one domain for its anti-CSRF cookie, plus valid reverse DNS.
- Downgrades are not symmetric. The resize call is documented as "Extend volume size", so a smaller plan cannot shrink a disk, though WHMCS will still sell the downgrade.
What else do people ask about WHMCS Proxmox integration?
Does WHMCS have a built-in Proxmox module?
No. The WHMCS documentation lists no Proxmox server module of its own. You install a third-party module from the Marketplace, or have one written against the Proxmox VE API. Either way it goes in /modules/servers/ and the node is added under Configuration > System Settings > Servers.
Is there a free WHMCS Proxmox module?
Yes. Proxmox VE for WHMCS by The Network Crew Pty Ltd was listed as free under GPLv3 on 20 November 2026, with source on GitHub. I have not tested it. Its setup adds the host with the root user, so weigh that against the scoped token above.
Which Proxmox VE version do the WHMCS modules support?
It depends on the module, so read its requirements tab. Proxmox VE 9.2 is current, so anything stopping at 8.x needs a test on your version.
Which WHMCS versions should a Proxmox module support?
The ones still getting updates. The WHMCS development page, read on 20 November 2026, lists 9.1 as General Availability, ending 30 September 2027, and puts 9.0 and 8.13 in Long-Term Support, ending 31 December 2026 and 31 January 2027. A module marked only for 9.0 or 8.13 needs the vendor's word on 9.1.
If you want a second opinion on a module or a quote for a custom one, my scoping call is free and takes about 30 minutes.
Last reviewed 20 November 2026. Disclosure: I am a freelance WHMCS developer and I sell custom WHMCS modules, including provisioning modules like the one described here, so I am not neutral about the custom route. My own modules and services are final sale, so ask before you buy. I am CTO at ElySpace, a freelance developer for Marmaids LLC, and founder of WHMCSPilot and MagizAI.