WHMCS Configurable Options: Types, Pricing, Modules and Upgrades

WHMCS configurable options are choices a customer makes on a product, such as disk space, an operating system or a server location, that change the product's price. You build them in option groups at Configuration > System Settings > Configurable Options, assign each group to products, price every sub-option for each billing cycle, and the provisioning module receives the choices by option name.

What are WHMCS configurable options, and when should you use them?

Use them for a choice that belongs to one product and changes what that product costs. The Configurable Options page defines them as variables that alter the price of a product, kept in groups that you apply to one or more products.

The alternative is a product addon. The Product Configuration Options page draws the line this way:

• Configurable option: a choice for a single item, billed together with the product as one item, on the product's own billing cycle. The documentation's examples are disk space and the choice of an operating system.
• Product addon: billed separately, chosen independently, and able to run on its own cycle. The documentation's examples are SSL certificates and dedicated IP addresses.

How do you create a configurable option group and link it to products?

Create the group, choose its products, then add options inside it. Every option lives in a group.

1. Go to Configuration > System Settings > Configurable Options and click Create a New Group.
2. Enter a name and description. Only admins see them.
3. Select the products the group applies to and click Save Changes.
4. Click Add New Configurable Option, enter the option name, choose the type and enter the first sub-option. Save, and pricing fields appear.
5. Enter a price for every billing cycle the product has enabled. For Dropdown and Radio, click Add Option for each further sub-option and save after each one.
6. Set Sort Order to control the order on the form, then click Close Window.

The product side shows the same link on the Configurable Options tab of the product at Configuration > System Settings > Products/Services. One product setting blocks options entirely: if Allow Multiple Quantities is on, the documentation says the product cannot require additional configuration such as custom fields or configurable options.

Which configurable option types does WHMCS offer?

Four: Dropdown, Radio, Yes/No and Quantity. There is no free-text type, so typed answers belong in a custom field.

How does WHMCS configurable options pricing work?

Each sub-option carries its own price for each billing cycle the product offers, and WHMCS adds the chosen sub-option's price to the product price. Four details matter in practice.

• Quantity is a unit price. You enter it in the One Time/Monthly column and WHMCS multiplies it by the number the customer picks.
• Every enabled cycle needs a price. A product sold monthly and yearly needs both prices on every sub-option.
• Friendly names separate the label from the value. Write a sub-option as required value|display value, for example rbx01ssd|French Server - Solid State Drive. Customers see the text after the pipe on the order form, in emails and on invoices. The module receives the part before it.
• Price override hooks skip option costs. The shopping cart hook reference says OrderProductPricingOverride overrides product pricing "exclusive of configurable option cost". A discount written that way leaves the option prices untouched.

To retire a sub-option, tick Hidden instead of deleting it. The documentation says hiding removes it from the store without losing the selection for existing customers.

How does a provisioning module read configurable options?

It reads them from $params['configoptions'], keyed by option name. The Module Parameters page gives the example $params['configoptions']['Disk Space'], and product custom fields arrive the same way in $params['customfields'].

function mymodule_CreateAccount(array $params)
{
    $location = $params['configoptions']['Location'] ?? '';
    $extraIps = (int) ($params['configoptions']['Extra IPv4'] ?? 0);
    $sshKey   = $params['customfields']['SSH Public Key'] ?? '';

    // Call the platform's API with these values, then:
    return 'success';
}

Three points cause most confusion:

• Configurable options are not Config Options. $params['configoption1'] to configoption24 are the module's own settings from its ConfigOptions function, set per product by an admin. The documentation warns against mixing the two up.
• Upgrades call ChangePackage. The supported functions page says the same function runs for upgrades and downgrades of products and of configurable options, once the upgrade order is paid.
• The API uses a different format. The AddOrder API takes configoptions as base64-encoded, serialized arrays, and the documented example keys them by number, not by name. A script that places orders needs the IDs.

With the Configurable Package Addon, option names must follow the format your control panel expects. My WHMCS provisioning module guide covers the rest of $params.

What is the difference between configurable options and custom fields?

Configurable options change the price, and custom fields collect information. The table compares product custom fields, as described on the Custom Fields page, with configurable options.

My rule is simple. If the answer changes the price or the resources the server must allocate, it is a configurable option. If it is information you need to deliver the service, such as an SSH key or a project reference, it is a custom field. The Password type is encrypted by WHMCS, which makes it the right place for a credential the customer supplies.

How do customers upgrade or downgrade configurable options?

Tick Configurable Options on the Upgrades tab of the product at Configuration > System Settings > Products/Services. The customer then opens the service under Services > My Services and picks new values. Staff can do the same from the client's Products/Services tab with More > Upgrade/Downgrade.

The Upgrades and Downgrades page explains the billing. The customer is credited for the unused part of the current cycle at the old price and charged for the rest of the cycle at the new price. The Next Due Date does not move. If the upgrade order is still unpaid when the cron generates the renewal invoice, WHMCS cancels the upgrade order and renews on the current details.

Downgrades are where modules fail. Many platforms cannot shrink a disk, so ChangePackage must refuse what the platform cannot do and return a clear error for staff.

Can WHMCS configurable options show a city list that depends on the chosen country?

Not with the built-in types. Each option is independent, and the documentation describes no rule that shows, hides or filters one option based on another. That leaves four designs:

For the browser-filtered design, pair the script with the ShoppingCartValidateProductUpdate hook. It receives the request variables when a product is updated in the cart and can return error messages, so an invalid country and city pair never reaches checkout. My WHMCS hooks guide explains where the file goes. For a short list I use the combined option, because it needs nothing that can break on the next WHMCS update.

Which mistakes and limits should you plan for?

Most problems come from treating configurable options as more than a priced list of choices.

• Renaming an option. Modules look values up by name, so a renamed option arrives under a new key and the module reads nothing.
• An option the module ignores. WHMCS bills every option, but only the module turns it into a resource. Test each sub-option against the server, not only the invoice.
• A required Yes/No. It does not force a tick. Use a Dropdown with two choices if one answer must be chosen.
• No live availability. WHMCS does not know that a location is full. That check needs a module or a hook.

Before launch, I order every sub-option on a staging copy and check the price, the invoice line and what the module log shows the module received. My VPS provisioning guide shows how this applies to resources and operating systems. When a cart needs dependent options or live stock, I build it as WHMCS custom module development or WHMCS theme customization work.

Last reviewed 12 October 2026. Disclosure: I sell WHMCS and web development work, so I am not neutral. Menu paths and behavior are from the WHMCS 9.0 documentation and developers.whmcs.com as I read them on that date.