WHMCS setup walkthrough
From an empty WHMCS to selling Swarmz plans and credit packs — every click, in order, with nothing assumed. Follow it once, top to bottom, in about 30 minutes.
This is the guided version of the WHMCS setup: every step in the order you actually do them, with nothing assumed. The WHMCS module page is the full reference — this page is the path. Follow it once, top to bottom, and you end with plans selling, upgrades working, credit packs on sale, and a branded customer panel.
The mental model — where everything lives
One idea makes the whole setup make sense: Swarmz defines the products, WHMCS sells them. Each thing exists once on each side, and the module holds the link:
| On Swarmz (you define it) | In WHMCS (customers buy it) | Linked by |
|---|---|---|
| A plan (credits, limits, entitlements) | A product | The Plan dropdown on the product's Module Settings tab |
| A credit pack (top-up amount) | A Product Addon | The Credit Packs page in the Reseller Console — one click |
| — | The retail price | WHMCS only. Swarmz never sees or sets what you charge |
Swarmz is the source of truth for what the customer gets; WHMCS is the source of truth for what they pay. Change a plan's credits on Swarmz and every linked product follows; change a price in WHMCS and Swarmz doesn't care.
Before you start
The full requirements board has every line — the short version:
- WHMCS 8.x+ on PHP 8.1+ with
curl,json,mbstring(andzipif you want one-click updates — recommended). - Outbound HTTPS to
api.swarmz.net, plusgithub.com/api.github.comfor the auto-updater. - An active Swarmz platform account and your
sk_live_…API key. See Authentication. - No ionCube, no extra cron, no Composer, no shell access — if WHMCS runs, you're ready.
- 30 minutes.
Build your plans on Swarmz
In your Swarmz dashboard → Settings → Plans, create the plans you want to sell — say Starter, Pro, Business. For each: monthly credits, daily free allowance, rollover, and project/domain/compute limits. Give real thought to the ladder (each tier should be an obvious upgrade), because WHMCS will mirror this structure one product per plan.
If you want a free tier (great for the Prompt Box signup flow), make it a plan here too.
Define your credit packs on Swarmz
Still under Settings → Plans, scroll to Credit packs and add your top-ups — e.g. 500 Extra Credits one-time, 2,000 Extra Credits one-time, maybe a monthly booster. The pack decides the credits; you'll set the retail price in WHMCS later. This table is also where each pack's Sold count accumulates once you're live.
Install the module
Download the latest release and unzip it over your WHMCS root — it writes only modules/servers/swarmz/ and modules/addons/swarmz/. Then set the file ownership once so the in-console updater works forever after.
Activate the console and connect
Setup → Addon Modules → Swarmz Reseller Console → Activate, then open its settings and paste your sk_live_… key into API Key. That's the only place the key ever needs to go.
Create the server
Setup → Products/Services → Servers → Add New Server: name it Swarmz, hostname api.swarmz.net, module Swarmz, leave username/password blank, SSL on. Test Connection must come back green — if it doesn't, fix that before going further (it's always the key or the URL).
Then Create New Group, add this server to it. Products attach to the group.
One product per plan
For each Swarmz plan from step 1, create a product (Setup → Products/Services, type Other works): name it after the plan, set your retail price, and on Module Settings pick module Swarmz, your server group, and the matching plan in the Plan dropdown — the dropdown is filled live from your Swarmz plans.
Two settings worth getting right now:
- Payment-based setup for paid plans ("first payment received").
- For a $0.00 free plan: "Automatically setup the product as soon as an order is placed" — a zero-amount order has no payment event, so the payment option would leave it Pending forever.
Open the upgrade paths
On each product's Upgrades tab, tick the products a customer may move to (the tiers above; tick lower tiers too if you allow downgrades). Without this, customers have no self-serve upgrade path at all. Proration is handled on both sides automatically — details in Self-serve plan upgrades.
Put your packs on sale — one click each
Open Reseller Console → Credit Packs. Since module v1.20.0 this page is your Swarmz pack catalog: one row per pack, showing whether it's sold in WHMCS yet.
For each pack, click Create addon. The module creates the matching WHMCS Product Addon as a hidden draft — billing cycle taken from the pack, assigned to your Swarmz products, price prefilled, already linked. Then finish it in WHMCS (Setup → Products/Services → Product Addons): check the price is what you want to charge, and untick Hidden. Nothing can sell while it's hidden, so there's no wrong order of operations.
Already built an addon by hand? If it carries the pack's name, Create addon adopts and links it instead of duplicating; otherwise use the link existing picker on the row.
Make the panel yours
Reseller Console → Appearance: pick one of the six customer-panel layouts (with live previews), your accent color or brand hex, and the Checkout flow for pack purchases — Direct to invoice is the recommended default; pick Lagom only if you run Lagom's order form. Languages need no setup: the panel follows each customer's WHMCS language (EN/DE/FR/IT/ES).
Prove the money paths
Run the 8-step test checklist against a test client — order, pack purchase, double-payment (must not double-grant), upgrade, downgrade, admin SSO, forced cron. Fifteen minutes, and afterwards you know the billing chain end to end. Then check your Swarmz dashboard's Credit packs table: the pack you bought shows Sold 1×.
After launch
- Updates: one click in Console → Updates — checksummed, backed up, never touches your settings or data. No cron of your own is ever needed; the module rides WHMCS's standard automation (why).
- Changing a pack's credits: edit it on Swarmz — linked addons follow automatically (daily, or instantly when you open the Credit Packs page).
- Retiring a pack: archive it on Swarmz and hide the WHMCS addon. An archived pack never silently stops granting for customers mid-checkout — the console labels it and keeps the last amount until you unlink.
- Watching the business: per-customer usage and your wholesale cost live in the Reseller Console; per-pack sales counts live in the Swarmz dashboard next to the packs themselves.
Stuck on anything? The reference page's troubleshooting section covers the classic failure modes, and every API call the module makes is logged under Utilities → Logs → Module Log.
External references
Your own stable handle for a tenant — the idempotency key on create and an accepted fallback lookup afterward. The canonical address is the tenant_id returned by create.
WHMCS module
Resell Swarmz from WHMCS with no code. Install the module, set your API key once, create a server, and every WHMCS service lifecycle event provisions, signs in, suspends, and tears down a tenant for you.