Suspend the service via the WHMCS module hook
POST/services/:id/suspend
Calls WhmcsApiClient::moduleSuspend. WHMCS triggers its own virtualizor
module, and the queue cron turns it into a Virtualizor suspendvs job.
In our DB, mod_reseller_provisions.status='suspended'
notice='Suspended via API: <reason>'is set.
Idempotency-Key: OPTIONAL (if the header is sent, the middleware applies). Suspend is already idempotent (if already suspended, WHMCS is a no-op).
Rate limit: Default bucket (60 rpm) — lifecycle is not high-frequency.
vps_id null: 422 service_not_provisioned (a service that is not provisioned
cannot be suspended). For a management=basic service vps_id is not looked up;
the WHMCS module applies it.
Body: {"reason": "..."} optional (1-255 chars). Default:
"Suspended via Reseller API". So it can be in sync with the reason shown
in the reseller's WHMCS.
Side effect: A service.suspended event (status='skipped') is written to the
mod_reseller_webhooks_queue table. In the Phase 2 MVP there is NO delivery;
the v2 worker pushes these events to reseller webhook URLs.
Request
Responses
- 200
- 401
- 403
- 404
- 422
- 429
- 502
Service suspended
Response Headers
The per-minute limit defined for this key
Number of requests remaining in the current window
Unix epoch of the start of the next window (UTC seconds)
Authentication failed — missing header, wrong credential, outside the IP whitelist, or a revoked key. No detail is leaked; all cases return a single message.
Response Headers
RFC 7617 Basic Auth challenge
Insufficient authorization — the reseller tried to access another reseller's service_id, or has insufficient scope for an endpoint requiring admin scope. The message is kept generic (ServiceOwnershipMiddleware prevents leakage).
Service not found
VPS not yet provisioned
Per-minute limit exceeded
Response Headers
Seconds to wait before retrying after a 429 (RFC 7231 §7.1.3)
The per-minute limit defined for this key
Unix epoch of the start of the next window (UTC seconds)
WHMCS API upstream error (whmcs_upstream_error)