Connecting a billing panel

A billing panel (WHMCS, Blesta, HostBill or your own) runs the server lifecycle through the API: create when an order is paid, suspend when an invoice is overdue, unsuspend when it’s paid, terminate when it’s cancelled, and upgrades and add-ons in between. /admin/api in the panel lists these calls.

1. Create a token

• Your own billing: as staff, create a token with the Billing module preset (servers:read, servers:create, servers:resize, servers:suspend, servers:terminate, servers:power, servers:reinstall, customers:read, customers:write).
• A reseller’s billing: the reseller creates a token with their Billing module preset (reseller:read, reseller:customers, reseller:servers, servers:read, servers:power, servers:reinstall).

Limit it to your billing server’s address with the IP allowlist. See Authentication and tokens.

2. Map your products

Put each package’s ID into the matching billing product. GET /admin/packages (staff) or GET /reseller/account (resellers) lists the packages and locations with their IDs. Packages and backup plans also have a Billing product ID field you can fill in with your billing’s product ID, e.g. whmcs:12.

3. The lifecycle

Send an Idempotency-Key on every POST, such as the order or invoice number, so a retry after a timeout never creates a second server or suspends twice.

Creating a server

POST /api/v1/admin/servers
Authorization: Bearer pnl_…
Content-Type: application/json
Idempotency-Key: order-10482

{
  "ownerId": "usr_…",
  "packageId": "pkg_vps2",
  "nodeGroupId": "grp_fra",
  "nodeId": null,
  "imageId": "debian-12",
  "hostname": "web-01.example.com",
  "access": { "mode": "password" }
}

POST /reseller/servers takes the same fields without nodeId; the owner must be the reseller or one of its customers.

The answer comes straight away:

{
  "jobId": "job_…",
  "serverId": "srv_abc123",
  "ipv4": "203.0.113.10",
  "rootPassword": "…"
}

rootPassword is only there for password access, and only this once. Follow GET /jobs/{jobId} until state is succeeded, or wait for the server.provisioned webhook.

Waiting for setup

Without an imageId the server is created with the status pending_setup: its node, disk space and addresses are held, but nothing is installed and jobId is null. Until it has a hostname of its own it’s called server<number>. The customer is notified and sees a setup page in place of the server’s tabs; you can do the same from the admin side.

To build it, call POST /servers/{id}/actions/setup with { imageId, hostname, name?, access, scriptId? } (permission servers:reinstall). Custom images and saved startup scripts work as they do for a reinstall, and SSH keys can be the owner’s or those of whoever sets it up. The answer is { jobId, rootPassword? }, followed by server.provisioned as usual.

Until then power, console, reinstall, backups, disk and hardware changes are refused with not_set_up. Moving it to another node (POST /admin/servers/{id}/actions/move) happens at once and answers with jobId: null, since nothing is copied. It can be suspended (unsuspending brings it back to waiting), and terminating it only frees what it held: there’s nothing on the node to destroy.

Why an order can be refused

GPU instances

GPU containers are sold the same way, with a GPU offer in place of a package. Put each offer’s ID (from GET /admin/gpu-offers) into the matching billing product, or fill in the offer’s Billing product ID. The same staff token works: the GPU calls use the server scopes.

Usage answers, for a period (ISO times; this calendar month in UTC up to now when left out), how many seconds the instance existed (allocatedSeconds: its cards, ports and address are held whether it runs or not) and how many of those it was running, stopped or suspended, with each spell in intervals and the offer’s billingProductId. Suspension counts from the moment it’s asked for. A deleted instance’s usage stays readable by staff for 400 days, so the last period can still be invoiced, and the billing run includes instances deleted during the period. The panel doesn’t price anything: charge running hours, allocated hours, or both, as your products say.

For GPU instances, the useful webhooks are gpu_instance.created, ready, started, stopped (with reason requested or crashed, and for a crash the exitCode and whether it ran out of memory), failed, image_changed, suspended, unsuspended and deleted. An instance whose container stops on its own and stays down is marked stopped within a minute or so of its host noticing.

Leave out imageId and it runs the offer’s first available image; the customer can change it in the panel. Leave out sshKeyIds and root’s SSH login takes every key on the owner’s account; the customer can change which with PUT /gpu-instances/{id}/ssh-keys { sshKeyIds }. Send an Idempotency-Key here too. An order is refused with 409 no_capacity when no GPU container host in the location has the cards or room, and no_addresses when an own-IPv4 offer’s host has no address left. Check locations[].available and free in GET /admin/gpu-offers before selling.

4. Listen for webhooks

Add a webhook so billing hears about changes made elsewhere, such as staff suspending a server or a reseller’s customer being created. See Webhooks. Useful events for billing are server.provisioned, server.suspended, server.terminated, server.resized, floating_ip.created and floating_ip.released.

Usage reports

Operations → Usage reports (staff) and Reseller → Usage show each account’s servers, server-days per package, and traffic for the current month and the two before, with the billing ID. Download CSV gives one line per server, for checking against billing or for a reseller’s invoice run. Billing can fetch it with GET /reports/usage?month= (staff tokens need customers:read).