Building Custom WHMCS Provisioning Modules: Developer Guide

When commercial modules don't exist for your server platform or control panel, custom development is the answer. WHMCS provisioning modules follow a defined structure that, once understood, enables integration with virtually any service that has an API. This guide walks through building provisioning modules from scratch, covering structure, required functions, and best practices for reliable automation.

Module Structure Overview

Provisioning modules (also called server modules) live in the modules/servers/ directory. Each module is a folder containing at minimum a main PHP file matching the folder name.

Basic File Structure

A minimal module structure includes a folder at modules/servers/yourmodule/ containing yourmodule.php as the main module file. Additional files can include helper classes, templates, and configuration files as needed. The main file contains all the function definitions WHMCS calls during various lifecycle events.

Naming Conventions

The folder name becomes the module identifier. Use lowercase letters and underscores only. The main PHP file must match the folder name exactly. Function names follow the pattern yourmodule_FunctionName. Consistent naming prevents loading issues and confusion.

Required Functions

MetaData Function

The metadata function provides module information to WHMCS. It defines display name, API version, and whether the module requires a server connection.

function yourmodule_MetaData() {
    return array(
        'DisplayName' => 'Your Module Name',
        'APIVersion' => '1.1',
        'RequiresServer' => true,
    );
}

ConfigOptions Function

ConfigOptions defines fields that appear in product configuration. These settings are specific to each product using the module.

function yourmodule_ConfigOptions() {
    return array(
        'Plan ID' => array(
            'Type' => 'text',
            'Size' => '25',
            'Description' => 'Plan identifier from provider',
        ),
        'Server Type' => array(
            'Type' => 'dropdown',
            'Options' => 'Linux,Windows',
        ),
    );
}

Support various field types including text, password, dropdown, textarea, and yesno. Each configuration option becomes available when configuring products that use this module.

CreateAccount Function

The most critical function—CreateAccount provisions the service when an order is accepted. This is where you call your target platform's API to create the account or service.

function yourmodule_CreateAccount(array $params) {
    try {
        // Get server configuration
        $server = $params['serverhostname'];
        $username = $params['serverusername'];
        $password = $params['serverpassword'];
        
        // Get product configuration
        $planId = $params['configoption1'];
        
        // Get client details
        $clientEmail = $params['clientsdetails']['email'];
        $domain = $params['domain'];
        
        // Call your platform API
        $result = callProviderAPI($server, $username, $password, [
            'action' => 'create',
            'plan' => $planId,
            'domain' => $domain,
            'email' => $clientEmail,
        ]);
        
        if ($result['success']) {
            return 'success';
        } else {
            return $result['error'];
        }
    } catch (Exception $e) {
        return 'Error: ' . $e->getMessage();
    }
}

SuspendAccount and UnsuspendAccount

These functions handle service suspension for non-payment and reactivation upon payment. Similar structure to CreateAccount but calling appropriate API endpoints.

TerminateAccount

Called when an account is cancelled. Permanently removes the service from the target platform. Be careful—this is usually irreversible.

ChangePassword

Allows customers to change their service password through the client area. Not all platforms support this, so implementation is optional.

Working with Parameters

Server Parameters

Access server connection details through the params array including serverhostname for the server address, serverusername and serverpassword for API credentials, serversecure for SSL flag, and serverport if non-standard port is used.

Product Parameters

Product settings from ConfigOptions are available as configoption1, configoption2, and so on in order defined. Custom fields appear by name in the customfields array.

Client Parameters

Customer details are nested in clientsdetails including email and name, address fields, phone number, custom field values. Use these for account creation that requires customer information.

Client Area Integration

ClientArea Function

Provide customer self-service through the ClientArea function. Return HTML that displays in the client area service details page.

function yourmodule_ClientArea(array $params) {
    $serverData = getServiceData($params);
    
    return array(
        'templatefile' => 'clientarea',
        'vars' => array(
            'serviceData' => $serverData,
        ),
    );
}

Create template files in the module's templates folder for the client area interface. Include service status, management actions, and relevant information customers need.

Custom Buttons

Add action buttons to the client area that trigger module functions. Define buttons that call specific module functions for actions like restart, reinstall, or accessing console.

Admin Area Integration

AdminCustomButtonArray

Add custom buttons to the admin service view. Support staff can trigger actions like manual sync, password reset, or server migration directly from the admin panel.

AdminServicesTabFields

Display custom information on the admin service view. Show relevant service details, connection status, or management shortcuts for support staff.

Error Handling

Return Values

Functions return 'success' as a string for successful operations or an error message string for failures. WHMCS displays error messages in the admin area and logs them for troubleshooting.

Logging

Use WHMCS logging functions for debugging. Log API calls and responses with logModuleCall for the module debug log. This creates audit trail for troubleshooting provisioning issues.

logModuleCall(
    'yourmodule',
    'CreateAccount',
    $requestParams,
    $responseData,
    $processedResult,
    array('password', 'apikey')  // Fields to mask in logs
);

Best Practices

API Wrapper Classes

Create a separate class for API communication. Keep the main module file focused on WHMCS integration. The API class handles authentication, request formatting, and response parsing. This separation makes testing and maintenance easier.

Configuration Validation

Validate server connection during test connection function. Verify API credentials work before provisioning attempts. Clear error messages help administrators fix configuration issues quickly.

Idempotency

Handle duplicate calls gracefully. WHMCS might call CreateAccount multiple times for the same service due to retries. Check if service already exists before attempting creation to avoid errors or duplicates.

Timeout Handling

Set appropriate timeouts for API calls. Remote services might be slow or unresponsive. Handle timeouts gracefully with clear error messages. Consider async processing for long operations.

Testing and Deployment

Development Environment

Test on a WHMCS development installation with test accounts. Never develop against production data or services. Create test products and clients for thorough testing scenarios.

Testing Checklist

Verify all functions work correctly for CreateAccount with various configurations, suspend and unsuspend operations, termination process, client area display and actions, and error handling for API failures. Test edge cases like invalid credentials, network timeouts, and duplicate operations.

Deployment

Move tested module to production by copying the folder. Configure server connection with production credentials. Create products using the module. Test with a real order before broadly enabling.

Conclusion

Custom provisioning modules extend WHMCS to automate any service with an API. The structured approach using standard functions ensures your module works with WHMCS automation, admin tools, and client area. Invest time in proper error handling and logging—these save countless hours during production troubleshooting. With custom modules, your hosting business can offer unique services with full automation, differentiating from competitors limited to commercial module availability.