Settle a pending payment from credit (InvoicePaid)
POST/orders/:id/settle
Attempts to pay the WHMCS invoice of a pending (pending_payment / payment_failed)
order from the reseller balance. Triggered when the customer pays the invoice in the
reseller's WHMCS (InvoicePaid hook). If the balance was insufficient at order time,
the charge is collected here after the reseller tops up the balance → VPS setup is
queued (pending_provision).
Idempotent: For an order that is already paid (payment_applied=true), WHMCS is
not touched at all; the current state is returned with already_applied=true.
The Idempotency-Key header is optional; if sent, the same key returns the same response.
Concurrent settlement: If another settlement for the same order is in progress,
409 settle_in_progress (Retry-After 5) is returned. A record whose ApplyCredit
result is uncertain (transport error) is resolved after 5 minutes using the WHMCS
invoice status: if Paid it is treated as paid, if Unpaid it is retried.
Result states (status):
pending_provision— credit applied, VPS setup pendingpending_payment— balance still insufficient (notice=insufficient_credit), can be retried immediatelypayment_failed— temporary WHMCS error (5xx); retry after 5 minutesunknown_state/provision_failed— no charge is made,already_applied=false
Isolation: Another reseller's order id returns 404 order_not_found.
Request
Responses
- 200
- 401
- 404
- 429
Result of the settlement attempt (success, insufficient, or already paid)
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
Order not found (another reseller's record also returns 404)
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)