WHMCS Proxmox Integration: Modules, API Tokens and Checks

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. The WHMCS documentation lists no Proxmox server module of its own. You install a third-party module from the WHMCS Marketplace, or have a custom one written against the API.

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 module functions with the calls and privileges shown in the Proxmox VE API viewer. The paths are for KVM virtual machines. Containers use /lxc/ in place of /qemu/.

Three details catch people out.

• Proxmox "suspend" is not a billing suspension. The API's status/suspend call suspends a running VM, and its todisk option is described as "Will be resumed on next VM start". For an unpaid service the module should stop the VM and refuse the client area start button while WHMCS shows the service as suspended.
• Calls return a task, not a result. Clone, start and destroy return a task ID called a UPID. The module must poll GET /nodes/{node}/tasks/{upid}/status until the task has stopped, then read its exit status. Otherwise WHMCS emails login details for a VM that is still copying.
• The module must store what it created. WHMCS service properties do this. $params['model']->serviceProperties->save() writes the VM ID and node to custom fields, and the names Username, Password and Dedicated IP go to the core service fields.

The resize call is described as "Extend volume size", so a downgrade cannot shrink a disk.

How do login credentials get from Proxmox to the customer?

They are set on the guest through Cloud-Init, saved on the WHMCS service, and sent in the product's welcome email. Cloud-Init configures a cloud image on first boot.

• Virtual machines. The template carries a Cloud-Init drive. After cloning, the module sets ciuser, sshkeys or cipassword, and ipconfig0 through the config call. The API viewer says of cipassword: "Using this is generally not recommended. Use ssh keys instead." So collect a public SSH key at order time with a WHMCS custom field, and offer a password as the second choice.
• Containers. The create call, POST /nodes/{node}/lxc, takes password and ssh-public-keys directly.
• Password changes later. WHMCS shows clients a change-password option only when the module defines ChangePassword. On a running VM that needs the QEMU guest agent inside the guest and the VM.GuestAgent.Unrestricted privilege for the agent/set-user-password call. Without the agent, the honest answer is a rebuild or the console.

How do you map WHMCS products to Proxmox templates?

You point each WHMCS product, or each value of an operating system option, at the ID of a template VM on Proxmox.

• Build one template per operating system as the Proxmox Cloud-Init documentation describes: import a cloud image or install the cloud-init package, add the Cloud-Init drive, then run qm template on it.
• For templates the clone call tries a linked clone by default. That is fast, and the new disk depends on the template. Set full for an independent copy.
• The target parameter, which clones onto another node, is "only allowed if the original VM is on shared storage". With local storage, keep each template on every node or choose a module that migrates after cloning.
• Put customer guests in a resource pool. Permissions can then be granted on /pool/{poolname} instead of the whole cluster.

On the WHMCS side, plan sizes go in the product's Module Settings and the operating system is a configurable option whose stored value is the template ID. My WHMCS VPS provisioning guide covers the option syntax, IP pools, billing for extras and the full lifecycle test.

Which Proxmox API token and privileges should the module use?

Give the module a dedicated Proxmox user with an API token, leave privilege separation on, and assign a custom role that holds only the privileges the module uses. Do not hand 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 every write needs a CSRF prevention token. An API token needs neither, which suits a module running from 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 beginning with PVE are reserved for the built-in roles. Per the user management documentation, a privilege-separated token gets the intersection of its own permissions and its user's, so assign the role to both, on the customer pool, the templates, the storage and the bridge. The token secret is shown once. If you set an expiry date, put it in a calendar, because provisioning stops on that day.

The console is the exception. The same page says endpoints that give access to a VM console "require user privileges and cannot be accessed via an API token", while the API viewer's schema still flags vncproxy as allowed for tokens. I plan for a second, console-only Proxmox user and test on the exact version in use.

Which WHMCS Proxmox modules are on the Marketplace?

A search for "proxmox" on the WHMCS Marketplace returned 24 listings on 10 October 2026, 18 of them under Provisioning Modules. I opened three to confirm what they are. I have not tested them.

The other listings come from vendors whose pages I did not open, so I do not name them.

When is a custom WHMCS Proxmox module the better route?

A custom module is 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/ that implements the functions in the first table. The cost is that you own the upkeep. Proxmox says it tries to stay API compatible within a major release and makes no such promise across major versions, so a major Proxmox upgrade means a retest on staging. I build these under WHMCS custom module development.

What should you check before choosing a module or a custom build?

Check these eight points against your own cluster, because they are where the options differ.

1. Guest types: KVM only, or LXC containers too.
2. Storage and nodes: shared or local storage, and how the module picks a node.
3. IP addresses: who owns the pool, and whether IPv6 is handled.
4. Credentials: a scoped API token, or the root user.
5. Console: how it is proxied, and whether port 8006 must be open to customers.
6. Suspension: a real stop, with the start button blocked.
7. Failure handling: what happens to a half-built VM when a clone fails.
8. Source and updates: encoded or readable, the last update date, and the WHMCS, PHP and Proxmox versions listed.

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 remain your work on the Proxmox side.

• WHMCS must reach port 8006 on a node. Restrict that port to the WHMCS server's address unless your console design needs customers' browsers to reach it. Firewall rules and certificates on the node are ordinary Linux server setup work.
• A leaked token controls every guest in its scope, which is why the pool and the narrow role matter.
• If you do not want to run hypervisors at all, reselling a cloud provider's API is the simpler business.

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 10 October 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. I am CTO at ElySpace, a developer at Marmaids LLC, and founder of WHMCSPilot and MagizAI.