# WHMCS configurable options

Map WHMCS configurable options to GameCloud server parameters at provision and upgrade time.

## Overview

Configurable options let customers choose RAM tiers, Minecraft versions, or software types at order time. The server module reads selected options during `CreateAccount` and `ChangePackage`.

**Preferred approach:** Use addon product mappings for plan slugs; use configurable options for customer-visible upgrades that WHMCS invoices.

## Standard option layout

| Option name | Type | Maps to |
|-------------|------|---------|
| Plan | Dropdown | GameCloud plan slug (via mapping resolver) |
| Minecraft Version | Dropdown | `minecraftVersion` |
| Software | Dropdown | `softwareFamily` |
| Extra Backup Slot | Quantity | WHMCS addon product — see [addons](addons.md) |

Option order matters if using fallback config option indices in legacy setups. Mappings table overrides text fields when an active row exists.

## Dropdown values

### Software family

Values must match GameCloud enum exactly:

`VANILLA`, `PAPER`, `PURPUR`, `FABRIC`, `FORGE`, `NEOFORGE`, `QUILT`

### Minecraft version

Use semver strings present in GameCloud catalog. Invalid versions fail provisioning with module log error.

## Upgrade path

When a customer upgrades via WHMCS configurable option change:

1. WHMCS invokes `ChangePackage`
2. Module sends new `planSlug` to GameCloud
3. GameCloud resizes limits; may require server restart

Communicate restart requirement in WHMCS product description.

## Validation

The addon **Mappings** page validates plan slugs before save. Configurable option text is **not** validated until order time — typos cause provisioning failures.

## Pricing

WHMCS handles all pricing. GameCloud never stores invoice amounts in WHMCS mode (`BILLING_PROVIDER=whmcs`).

## Example: RAM upgrade option

1. WHMCS configurable option group "Upgrades"
2. Option "RAM Tier" with values mapping to plan slugs `starter`, `pro`, `enterprise`
3. Product mapping links WHMCS product + option combination to slug via `ProductMapping.php` resolver

For complex matrices, use separate WHMCS products instead of many conditional options.

## Related

- [Products](products.md)
- [Product mappings](../product-mappings.md)
- [Troubleshooting](troubleshooting.md)