How to Build a Custom WHMCS Provisioning Module (Step by Step)
If you run a hosting business on a panel WHMCS doesn't support out of the box, a custom provisioning module is how you automate it. In this guide I'll walk through the structure I use for every module I build.
If you run a hosting business on a panel WHMCS doesn't support out of the box, a custom provisioning module is how you automate it. In this guide I'll walk through the structure I use for every module I build.
What a provisioning module does
A provisioning (server) module connects WHMCS to an external system. When a client orders, pays, gets suspended or cancels, WHMCS calls your module and your module talks to the panel API.
Modules live in:
/modules/servers/yourmodule/yourmodule.php
The folder name, file name and function prefix must all match.
Step 1: Metadata
<?php
if (!defined('WHMCS')) {
die('This file cannot be accessed directly');
}
function yourmodule_MetaData()
{
return [
'DisplayName' => 'Your Panel',
'APIVersion' => '1.1',
'RequiresServer' => true,
];
}
Step 2: Config options
These appear on the product's Module Settings tab. Use them for plan names, disk limits or package IDs.
function yourmodule_ConfigOptions()
{
return [
'Plan' => [
'Type' => 'text',
'Size' => '25',
'Description' => 'Plan ID on the panel',
],
'Disk (GB)' => [
'Type' => 'text',
'Size' => '5',
'Default' => '10',
],
];
}
Inside other functions you read them as $params['configoption1'], $params['configoption2'] and so on.
Step 3: A small API client
Keep HTTP logic out of the module functions. A tiny client class keeps things clean and testable.
class YourPanelClient
{
private $host;
private $token;
public function __construct($host, $token)
{
$this->host = rtrim($host, '/');
$this->token = $token;
}
public function call($method, $path, array $data = [])
{
$ch = curl_init("https://{$this->host}/api/{$path}");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => $method,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $this->token,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $data ? json_encode($data) : null,
]);
$body = curl_exec($ch);
$code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$result = json_decode($body, true);
if ($code >= 400) {
throw new Exception($result['message'] ?? "API error {$code}");
}
return $result;
}
}
Step 4: Core functions
function yourmodule_CreateAccount(array $params)
{
try {
$api = new YourPanelClient($params['serverhostname'], $params['serverpassword']);
$api->call('POST', 'users', [
'username' => $params['username'],
'password' => $params['password'],
'email' => $params['clientsdetails']['email'],
'plan' => $params['configoption1'],
]);
logModuleCall('yourmodule', __FUNCTION__, $params, 'created');
return 'success';
} catch (Exception $e) {
logModuleCall('yourmodule', __FUNCTION__, $params, $e->getMessage());
return $e->getMessage();
}
}
function yourmodule_SuspendAccount(array $params)
{
try {
$api = new YourPanelClient($params['serverhostname'], $params['serverpassword']);
$api->call('POST', "users/{$params['username']}/suspend");
return 'success';
} catch (Exception $e) {
return $e->getMessage();
}
}
Follow the same pattern for UnsuspendAccount, TerminateAccount, ChangePassword and ChangePackage.
Step 5: Test connection
Admins love this button on the server setup page.
function yourmodule_TestConnection(array $params)
{
try {
$api = new YourPanelClient($params['serverhostname'], $params['serverpassword']);
$api->call('GET', 'ping');
return ['success' => true, 'error' => ''];
} catch (Exception $e) {
return ['success' => false, 'error' => $e->getMessage()];
}
}
Step 6: Client area output
Give clients a login button or usage stats with ClientArea and a Smarty template, and add one-click SSO with ServiceSingleSignOn if the panel supports it.
Tips from real projects
- Always use
logModuleCall(). When something breaks you'll find it in Utilities > Logs > Module Log. - Never return
trueon failure. Return the real error string so admins know what went wrong. - Mask passwords and tokens in logs using the fifth parameter of
logModuleCall(). - Test every action on a staging WHMCS before going live.
Wrapping up
Once your module is solid, your hosting business runs on autopilot: orders provision instantly, unpaid services suspend on time and support tickets drop.
I'm Shahid Malla, a WHMCS developer from Kashmir with 12+ years in hosting. If you're stuck on a module, ask in the comments.
Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes β full credit and traffic to the original publisher.