Skip to content
Shahid Malla

WHMCS Proxmox Integration: Modules, API Tokens and Checks

What a WHMCS Proxmox integration has to do, how a module authenticates to the Proxmox VE API with a scoped token, which modules the WHMCS Marketplace lists, and what to check before you choose one or build your own.

· Published · Updated · 11 min read · 10 steps

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.

Five-part workflow for a WHMCS Proxmox integration: map WHMCS functions to API calls, scope an API token, build Cloud-Init templates, plan logins, then choose a module or a custom build
The five parts of a WHMCS Proxmox integration, in the order this guide covers them. Source: shahidmalla.com.

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 sideJob on Proxmox VEAPI callsPrivileges
CreateAccountClone the template, set hardware and logins, start it.GET /cluster/nextid, POST /nodes/{node}/qemu/{vmid}/clone, POST .../config, POST .../status/startVM.Clone, VM.Allocate, Datastore.AllocateSpace, SDN.Use, the VM.Config group, VM.PowerMgmt
SuspendAccount, UnsuspendAccountStop the VM, then start it again on payment.POST .../status/stop, .../status/startVM.PowerMgmt
TerminateAccountDestroy the VM and disks, release the IP.DELETE /nodes/{node}/qemu/{vmid}VM.Allocate
ChangePackageApply the new plan: cores, memory, disk.POST .../config, PUT .../resizeVM.Config.CPU, VM.Config.Memory, VM.Config.Disk
ClientAreaCustomButtonArrayClient area power buttons.POST .../status/start, .../shutdown, .../rebootVM.PowerMgmt
UsageUpdate, MetricProviderUsage for overage or metric billing.GET .../rrddataVM.Audit
ConsoleOpen a browser console to the VM.POST .../vncproxy, GET .../vncwebsocketVM.Console

Three details catch people out.

  • Proxmox "suspend" is not a billing suspension. The status/suspend call suspends a running VM, and its todisk option 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}/status until 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-lifetime implies require-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 the virtio-scsi-pci controller.
  • Cloning gives a linked clone by default: fast, but the new disk depends on the template. Pass full for 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, sshkeys or cipassword, and ipconfig0 through the config call. Collect a public key at order time with a WHMCS custom field.
  • Containers. The create call, POST /nodes/{node}/lxc, takes password and ssh-public-keys directly.
  • Password changes later. WHMCS shows the option only when the module defines ChangePassword and the service is active. On a running VM that needs the QEMU guest agent and the VM.GuestAgent.Unrestricted privilege; 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.

Bar chart of 26 WHMCS Marketplace listings matching proxmox: 20 provisioning modules, 2 utilities, and one each in billing, security, themes and other
By Marketplace category: 20 Provisioning Modules, 2 Utilities, and one each under Billing & Invoicing, Performance & Security, Templates & Themes and Other. Source: WHMCS Marketplace search for "proxmox", read 20 November 2026.

Twenty sit under Provisioning Modules, and some of those provision other platforms. I opened three listings; I have not tested the code.

ListingDeveloperWhat the listing said on 20 November 2026
Proxmox VE VPS & Cloud For WHMCSModulesGardenCommercial, 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 WHMCSThe Network Crew Pty LtdFree 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 modulePUQ SoftwareCommercial, 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.

Decision flow: owning the code, an existing IP system, per-customer VLANs or an approval step point to a custom Proxmox module; otherwise use a Marketplace module that passes eight checks
How I decide between a Marketplace module and a custom build for Proxmox. Source: shahidmalla.com.

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.

  1. Guest types: KVM only, or LXC containers too.
  2. Storage and nodes: shared or local storage, and how a node is picked.
  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: a half-built VM after a failed clone, or an IP pool that runs dry.
  8. 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.

ChangeReleaseWhat it means for a module
VM.Monitor privilege removed9.0A custom role listing it needs rewriting.
Privileged containers need Sys.Modify9.0An LXC module creating them needs it added.
VM.Config.Cloudinit to dump the Cloud-Init password (PSA-2026-00017-1)9.2Needed to read the generated password back.
VM.PowerMgmt to start a VM after creation, restore or rollback9.2Custom roles only; shipped roles bundle it.
VNC endpoint fixes, breaking for external clients (PSA-2026-00014-1)9.2A 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.

Share this article

Shahid Malla

Written by

Shahid Malla

Freelance WHMCS developer and web designer with 13+ years of client work. CTO at ElySpace, freelance developer for Marmaids LLC, and founder of WHMCSPilot and MagizAI.

Got a project like this?

Tell me what you need and I will send a written quote within one business day.