WHMCS Module Types: What Each Does and Which One You Need

WHMCS has four main module types, and each lives in its own folder under /modules/. Provisioning (server) modules create, suspend and terminate services on another system. Addon modules add admin pages, client area pages and hooks. Payment gateway modules take payments. Registrar modules register and manage domains. Two smaller types handle mail delivery and notifications. Choose the type by the job WHMCS must do.

Disclosure: I am Shahid Malla, a freelance WHMCS developer who sells custom WHMCS modules. I founded WHMCSPilot, which sells WHMCS modules and themes, and I am CTO at ElySpace, a hosting company. I am not affiliated with WHMCS. I checked the folders, function names and rules below against developers.whmcs.com and docs.whmcs.com on 20 October 2026.

What is a WHMCS module?

A WHMCS module is a PHP file, or a folder of files, that WHMCS loads from a fixed directory under /modules/ and calls by function name at set moments, such as when an order is paid. The module type decides the folder, the function names WHMCS looks for and the screens you get without writing them.

The official modules overview lists six types: provisioning, addon, registrar, gateway, mail provider and notification provider. Dashboard widgets are documented inside the addon and provisioning sections, not as a separate type. One limit applies to all of them: the Custom Modules page says custom modules are for self-hosted installs, because WHMCS Cloud does not currently support them.

Which folder and functions does each WHMCS module type use?

Each type has its own directory and function names, and every function starts with the module name and an underscore, such as mymodule_CreateAccount.

Naming rules differ by type, and a broken name is the first thing to check when a new module does not show up.

What does a provisioning module do, and which functions does it need?

A provisioning module ties a product to a service on another system and runs that service's lifecycle. Per the supported functions page:

• CreateAccount runs at checkout or payment of a new order, or when an admin runs it from the client's Products/Services tab.
• SuspendAccount runs when the cron finds the service overdue; UnsuspendAccount runs when the overdue invoice is paid.
• TerminateAccount runs for long-overdue services when automatic termination is enabled.
• Renew runs each time a renewal invoice is paid.
• ChangePackage runs on paid upgrades and downgrades, for products and configurable options alike.
• ChangePassword runs when a client changes the password; the option is hidden unless the function exists.

Those seven core module functions share one contract: return the string success, or an error message written for staff. On success WHMCS does the rest. CreateAccount sets the service to Active and sends the welcome email, SuspendAccount sets Suspended and TerminateAccount sets Terminated.

MetaData describes the module: DisplayName, APIVersion (the metadata page says to use 1.1) and RequiresServer, set to false when no server record is needed. ConfigOptions defines up to 24 per-product settings, which other functions read as configoption1, configoption2 and so on. Since ChangePackage also fires for option changes, see my configurable options guide before planning upgrades.

<?php
// Folder: modules/servers/mymodule/

if (!defined('WHMCS')) {
    die('This file cannot be accessed directly');
}

function mymodule_MetaData()
{
    return ['DisplayName' => 'My Module', 'APIVersion' => '1.1', 'RequiresServer' => false];
}

function mymodule_ConfigOptions()
{
    return ['plan' => ['FriendlyName' => 'Plan ID', 'Type' => 'text', 'Size' => '25']];
}

function mymodule_CreateAccount(array $params)
{
    try {
        $plan = $params['configoption1'];
        // call the remote API here
        return 'success';
    } catch (\Exception $e) {
        return $e->getMessage();
    }
}

Optional extras include ClientArea output on the service page, LoginLink for a control panel shortcut, custom buttons through ClientAreaCustomButtonArray, UsageUpdate for a daily disk and bandwidth import, and MetricProvider for usage billing. A Proxmox VE integration is a typical provisioning job, as my Proxmox integration guide shows, and the provisioning module guide covers parameters, logging and testing in depth.

What does an addon module do, and which functions does it need?

An addon module adds a feature to WHMCS as a whole instead of to one product. The addon module docs say it can be an admin page, hooks, or both. Once activated, it appears in the Addons menu, and full admins choose which admin roles may open it.

The main file is /modules/addons/your_module_name/your_module_name.php, per the addon getting started page. The official sample addon module marks every function except config as optional:

• config returns the name, description, version, author and settings fields. The configuration page lists six field types: text, password, yesno, textarea, dropdown and radio.
• activate and deactivate usually create and drop the module's tables and return a status of success, error or info, per the installation page.
• upgrade runs the first time the module is accessed after an update, with the previous version in $vars['version'].
• output prints the admin page; sidebar adds admin sidebar HTML.
• clientarea returns output parameters for a client page at index.php?m=your_module_name.

What does a payment gateway module do, and which functions does it need?

A payment gateway module connects WHMCS to a payment provider. The gateway getting started page names three kinds:

• Third party: the customer leaves your site to pay, then returns.
• Merchant: the customer enters card details in WHMCS and the payment runs in the background.
• Tokenized: a merchant variant that stores a token from the gateway instead of card details, or loads checkout in an iframe.

The layout differs from other types. The main file sits directly in /modules/gateways/, other files such as return pages go in /modules/gateways/yourgatewayname/, and the callback goes in /modules/gateways/callback/.

The sample gateway module says only _config is required; the optional _MetaData sets values such as DisplayName and TokenisedStorage. A third-party gateway adds _link, which returns the HTML shown on the invoice. A merchant gateway uses _capture instead, which per the merchant gateway page returns a status of success, pending or declined, plus transid and rawdata.

The callback file marks invoices paid, so follow the order on the callback files page:

1. Verify the request came from the provider, using settings from getGatewayVariables().
2. Validate the invoice with checkCbInvoiceID(), which stops on an invalid ID.
3. Reject a repeated transaction ID with checkCbTransID().
4. Log it with logTransaction().
5. Apply the payment with addInvoicePayment().

What does a registrar module do, and which functions does it need?

A registrar module connects WHMCS to a domain registrar's API. It lives in /modules/registrars/ and follows the provisioning naming rule, per the registrar getting started page.

The one required function is yourmodulename_getConfigArray, which defines settings with the same six field types, according to the registrar configuration page. An optional _config_validate can throw an InvalidConfiguration exception to block bad credentials. The rest come from the function index; define only what your registrar supports.

Do I need a module at all, or is a hook enough?

A hook is enough when you only react to something WHMCS already does, such as an invoice being paid. Hook files go in /includes/hooks/, and files starting with an underscore are skipped, per the hooks getting started page. There is nothing to activate.

Choose a module when WHMCS must call your code during a service's lifecycle, when staff need settings or pages, or when you take payments or sell domains. The two combine: a hooks.php in a module's root folder loads on every page, per the module hooks page. WHMCS detects it when a provisioning, registrar or addon module is activated. My WHMCS hooks guide covers hook points and examples.

Which module type does my job need?

Start from what has to happen and when.

A pattern I often undo is an addon that creates accounts on a remote panel. That is a provisioning module built by hand, and it must rebuild the suspension, termination and status handling WHMCS already provides.

What changed for module developers in WHMCS 9.0?

Three changes in the WHMCS 9.0 release notes touch every module type.

• PHP 8.2 or higher. 9.0 dropped PHP 7.2, 7.3, 7.4 and 8.1, requires PHP 8.2 at minimum and recommends PHP 8.3, and needs the matching ionCube Loader.
• Smarty 4. 9.0 moved to Smarty 4.0 and removed the {php}, {include_php}, {fetch} and {smarty_template.object} tags. Module templates using them must be fixed before upgrading.
• Immutable invoices. Invoices not in Draft status can no longer have items added or removed, or transactions edited. Code that changed unpaid invoices needs a new approach.

To change a module's template without editing the module, the Custom Modules page describes an override at /templates/yourtemplatename/modules/moduletype/modulename/, which updates do not overwrite.

What should I check before I pick a module type?

• Write the job as one sentence: trigger, outcome, outside system.
• Follows a service from order to termination: provisioning.
• Moves money: gateway, third party or merchant by where card details are entered.
• Registers or manages domains: registrar.
• Only reacts to an event: try a hook first.
• Pick a name that passes the type's naming rule and clashes with nothing installed.
• Confirm a self-hosted install on PHP 8.2 or higher for WHMCS 9.0 or later.

What do people ask about WHMCS module types?

Where are WHMCS modules stored?

Under /modules/ in your WHMCS install: provisioning modules in servers, addons in addons, gateways in gateways and registrars in registrars. Hooks are not modules. They live in /includes/hooks/ unless a module carries its own hooks.php.

What is the difference between a WHMCS addon module and a server module?

A server (provisioning) module is attached to a product and runs its lifecycle on another system: create, suspend, unsuspend, terminate, renew and change package. An addon module is not tied to any product. It adds admin pages, client pages, tables and hooks to WHMCS as a whole.

Can one module be both an addon and a provisioning module?

Not as one file, because each type has its own folder and WHMCS looks for different function names in each. You can ship a provisioning module and an addon in one package that share a library, and both can carry a hooks.php.

Why are the hooks in my module not running?

WHMCS detects a module's hooks.php at activation. If you added it later, the module hooks page says to save the product's Module Settings tab again for a provisioning module, or re-save the registrar or addon settings. Also check the file sits in the module's root folder.

Can I use custom modules on WHMCS Cloud?

Not at the moment. The WHMCS 9.0 Custom Modules page says WHMCS Cloud does not currently support custom modules, so a business that depends on one needs a self-hosted install.

What should I do once I know the type?

Download the official sample module for that type, rename it and its function prefix, and read that type's section of the developer docs before writing code. For budget or handing the build over, what a custom WHMCS module costs explains the price drivers and my custom WHMCS module development page covers the service.

Last reviewed 20 October 2026. Disclosure: I am a freelance WHMCS developer who sells custom WHMCS modules, the founder of WHMCSPilot, which sells WHMCS modules and themes, and CTO at ElySpace, a hosting company. I am not affiliated with WHMCS.