WHMCS module

If you already run WHMCS, this is the fastest way to resell Swarmz. WHMCS keeps the billing and the customer relationship; the module turns each service lifecycle event — create, suspend, terminate — into a single call to the Platform API. You write no code.

What you get

The download installs two modules in one step.

Before you start

You will need:

• WHMCS 8.x or newer, on PHP 8.1+ with the curl, json, and mbstring extensions enabled.
• An active Swarmz platform account. If yours is still draft, calls return 409 account_inactive — see Onboarding.
• Your API key (sk_live_…), issued once during onboarding. See Authentication.

Install and connect

The whole setup is: drop in the files, set your key once, create one server, then point a product at it.

<whmcs-root>/modules/servers/swarmz/   ← provisioning module
<whmcs-root>/modules/addons/swarmz/    ← Reseller Console

What each WHMCS action does

Once the product is live, WHMCS lifecycle events map straight onto Platform API calls. You never invoke these yourself — WHMCS does, on what your customers trigger through billing.

The module addresses each tenant by external_ref, set to whmcs:<serviceid> automatically, so you never track tenant UUIDs by hand.

Plan selection

The module ships one product option: the Plan dropdown. A product provisions purely from the named Swarmz plan you select — there are no per-option entitlement fields in WHMCS.

You build the plans themselves in your Swarmz dashboard (Platform → Settings → Plans): the credits a customer gets each cycle (Build / Cloud / AI lanes), a daily free allowance, rollover, and project / domain / compute limits. Each plan has a stable code, and WHMCS sends only that plan_code on platform-create and platform-plan — the platform resolves the full entitlement set server-side. See Platform plans for the plan model.

Every Swarmz product must have a plan selected. CreateAccount and ChangePackage fail with "select a Swarmz plan on the product's Module Settings tab" until you pick one — re-save any product migrated from an older module version (the old positional entitlement options and the initial-top-up option were removed in module v1.5.0).

Prompt Box — capture the first prompt on your own site

Since module v1.9.0, the Reseller Console ships an embeddable Prompt Box: one <script> tag on any page of your site — plain HTML, WordPress, any landing builder — renders a themeable prompt widget. A visitor types the app they want, optionally picks a plan inline, and lands in your WHMCS cart with the prompt riding along. When the order provisions, the module passes it to platform-create as initial_prompt — and your customer's first login opens the editor with that app already building.

<script src="https://YOUR-WHMCS/modules/addons/swarmz/promptbox.php?a=js"
        data-pid="12"
        data-button="Start building"
        data-placeholder="Describe the app you want to build…"
        data-theme="auto"
        data-accent="#4f46e5"
        async></script>

• Get the code from the console. The Prompt Box view (Reseller Console toolbar) has a snippet builder with a live preview and a log of recently captured prompts and their journey (Captured → Ordered → Provisioned).
• One product or many. data-pid targets one WHMCS product. To offer plans inline, add data-plans='[{"pid":12,"label":"Starter","price":"$9/mo"},{"pid":13,"label":"Pro","price":"$29/mo"}]' — each entry maps a label to one of your products.
• Free-instance flow. Point the widget at a $0.00 product with instant activation and the whole journey is: type a prompt → quick signup → workspace spins up already building it.
• Isolated and dependency-free. The widget renders in a Shadow DOM (your page's CSS can't break it), matches light/dark automatically (data-theme="auto"), and is unbranded — your accent color, your button label.
• Bounded by design. The capture endpoint is public but rate-limited per IP, capped at 10,000 characters, only accepts your Swarmz-module products, and prompts are retained for 30 days.

How the prompt-to-workspace mechanics work platform-side (consumption on first login, idempotency, the feature kill switch) is documented at Initial prompt.

Customer sign-in and usage

In the client area, the module adds an Open AI Editor button (rename it in the console). It calls platform-sso, mints a short-lived redirect, and drops the customer into their dashboard already logged in — a fresh token on every click, nothing cached. Since v1.9.0 the module retries transient network and gateway blips automatically, and any refusal (suspended, cancelled, still provisioning) renders as a plain-language, unbranded message with a next step instead of a raw error code.

The Reseller Console reads platform-usage and shows each customer's plan and live consumption in one table, so you can reconcile against your wholesale invoice. Its settings also control client-area presentation: the editor button label, what you call "credits", and whether to show AI and cloud spend to the customer. See Usage and Billing summary.

Troubleshooting

• Test Connection fails with 401 — the key is wrong, rotated, or not set. Paste the current sk_live_… key into the console's API Key (or the server's Password). See Authentication.
• Nothing provisions when an order is accepted — open the product's Module Settings and confirm Module Name is Swarmz and a Server Group is selected.
• Customer can't open the editor — the tenant is likely suspended; SSO returns 409 suspended until you unsuspend.
• Want to see what was sent — every call is recorded under Utilities → Logs → Module Log (the API key is redacted).

Prefer to build it yourself?

Not on WHMCS, or wiring provisioning into your own panel? Every action above is a plain REST call. Start at Authentication and Create a tenant.