Dev.to WebDev πŸ›  Dev πŸ‘ 0 πŸ“– 3 min read

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 true on 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.

πŸ“° Read the original article on Dev.to WebDev

Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes β€” full credit and traffic to the original publisher.