Billing API
API reference for billing systems such as WHMCS and Blesta - plans, creating, suspending, upgrading and removing hosting accounts, passwords and single sign-on links.
The billing API lets a billing system (WHMCS, Blesta or your own) manage hosting accounts. It authenticates with a billing API key, not a user: create one under Hosting > Billing API in the panel, or with Create a billing API key. The key is shown once; the panel keeps only its hash. Every call is recorded in the audit log with the key as the actor.
The ready-made WHMCS module uses this API. For the concepts, see Billing API.
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/billing/plans | List plans |
| GET | /api/v1/billing/accounts | List accounts |
| POST | /api/v1/billing/accounts | Create an account |
| GET | /api/v1/billing/accounts/:ref | Get an account |
| POST | /api/v1/billing/accounts/:ref/suspend | Suspend an account |
| POST | /api/v1/billing/accounts/:ref/unsuspend | Unsuspend an account |
| POST | /api/v1/billing/accounts/:ref/plan | Change the plan |
| POST | /api/v1/billing/accounts/:ref/password | Set the password |
| POST | /api/v1/billing/accounts/:ref/login | Create a sign-in link |
| DELETE | /api/v1/billing/accounts/:ref | Remove an account |
Authentication
Send the key as a bearer token. No cookie or CSRF token is involved.
Authorization: Bearer vpk_…A missing, unknown or revoked key is refused with 401 UNAUTHENTICATED. Each address may make 120 calls a minute (429 RATE_LIMITED beyond that). The billing scope allows reading and managing customer accounts and nothing else.
:ref is the account's VaultPanel id (a UUID) or the externalId your billing system gave it when creating it, such as its WHMCS service id.
The PHP examples on this page use this small helper:
<?php
function vaultpanel(string $method, string $path, ?array $body = null)
{
$ch = curl_init('https://panel.example.com/api/v1/billing' . $path);
$headers = ['Authorization: Bearer ' . getenv('VAULTPANEL_BILLING_KEY'), 'Accept: application/json'];
if ($body !== null) {
$headers[] = 'Content-Type: application/json';
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
}
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => $method,
CURLOPT_HTTPHEADER => $headers,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
]);
$reply = json_decode((string) curl_exec($ch), true);
curl_close($ch);
if (!is_array($reply) || empty($reply['success'])) {
throw new RuntimeException($reply['error']['message'] ?? 'VaultPanel could not be reached');
}
return $reply['data'];
}List plans
/api/v1/billing/plansReturns the plans offered to new accounts (isActive plans), by name, with their price, limits and app caps. See the plan object.
Example request
curl https://panel.example.com/api/v1/billing/plans \
-H "Authorization: Bearer $VAULTPANEL_BILLING_KEY"$plans = vaultpanel('GET', '/plans')['items'];Response 200 OK
{
"success": true,
"data": {
"items": [
{
"id": "a0b1c2d3-…",
"name": "Starter",
"description": "",
"isActive": true,
"priceCents": 900,
"currency": "USD",
"billingCycle": "monthly",
"serverGroup": null,
"limits": { "websites": 5, "subdomains": 10, "applications": 2, "databases": 5, "databaseUsers": 5, "cronJobs": 10, "diskMb": 10240 },
"appCaps": { "appMemoryMb": 512, "appCpuPercent": 100 }
}
]
},
"message": "OK",
"requestId": "…"
}List accounts
/api/v1/billing/accountsReturns accounts a page at a time with their usage (counts, diskMb and the plan's limits), for usage syncs. Removed accounts are listed only with status=terminated.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
search | string | No | Part of the name, email, company or external id. |
status | string | No | active, suspended or terminated. |
planId, serverId | string (UUID) | No | Only accounts on this plan or server. |
page, pageSize | integer | No | Page from 1; 1 to 100 per page (default 25). |
sort, order | string | No | createdAt (default) or name; desc (default) or asc. |
Example request
curl "https://panel.example.com/api/v1/billing/accounts?pageSize=100&page=1" \
-H "Authorization: Bearer $VAULTPANEL_BILLING_KEY"$page = 1;
do {
$data = vaultpanel('GET', '/accounts?' . http_build_query(['page' => $page, 'pageSize' => 100]));
foreach ($data['items'] as $account) {
// $account['externalId'], $account['usage']['diskMb'], $account['usage']['limits']['diskMb']
}
$page++;
} while ($page <= $data['pagination']['totalPages']);Response 200 OK: { items, pagination } of customers.
Create an account
/api/v1/billing/accountsCreates the account and its sign-in, on a server the panel picks unless you give one. Without a password, the response carries an invite link for the customer to choose one.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Up to 120 characters. |
email | string | Yes | Unique among accounts. |
plan | string | Yes | A plan offered to new accounts, by id or exact name. |
company | string | No | Up to 120 characters. |
externalId | string | No | Your id for the account (letters, digits and . _ : -, up to 100), so you can use it as :ref. |
serverId | string (UUID) | No | A connected server. |
password | string | No | The account's password. |
Example request
curl https://panel.example.com/api/v1/billing/accounts \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_BILLING_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "Ada Customer", "email": "ada@example.org", "plan": "Starter", "externalId": "whmcs-1042" }'$created = vaultpanel('POST', '/accounts', [
'name' => 'Ada Customer',
'email' => 'ada@example.org',
'plan' => 'Starter',
'externalId' => 'whmcs-1042',
]);
$accountId = $created['customer']['id'];Response 201 Created: { customer, inviteUrl, inviteExpiresAt, email }, message Account created. inviteUrl is null when a password was given.
Errors
| Status | Code | When |
|---|---|---|
| 409 | EXTERNAL_ID_TAKEN | An account already has this external id; details.customerId is its id, so a retried create can find it. |
| 409 | NO_SERVER | No connected server to put the account on. |
| 422 | VALIDATION_ERROR | The email is taken, no plan has this id or name, the plan is not offered to new accounts, or another invalid field. |
Get an account
/api/v1/billing/accounts/:refReturns the account with its usage, planDetail, resources and app ports, as in Get a customer.
Example request
curl https://panel.example.com/api/v1/billing/accounts/whmcs-1042 \
-H "Authorization: Bearer $VAULTPANEL_BILLING_KEY"$account = vaultpanel('GET', '/accounts/' . rawurlencode('whmcs-1042'));
$diskMb = $account['usage']['diskMb'];Response 200 OK: the account. 404 NOT_FOUND when no account has this id or external id.
Suspend an account
/api/v1/billing/accounts/:ref/suspendSigns the account out and refuses its sign-in, turns its websites off, stops its apps and pauses its cron jobs.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
reason | string | No | Up to 300 characters. |
Example request
curl https://panel.example.com/api/v1/billing/accounts/whmcs-1042/suspend \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_BILLING_KEY" \
-H "Content-Type: application/json" \
-d '{ "reason": "Overdue on invoice 2291" }'vaultpanel('POST', '/accounts/whmcs-1042/suspend', ['reason' => 'Overdue on invoice 2291']);Response 200 OK: { customer, warnings }, message Account suspended.
Errors: 404 NOT_FOUND, 409 CUSTOMER_REMOVED.
Unsuspend an account
/api/v1/billing/accounts/:ref/unsuspendLets the account sign in again and turns back on exactly what suspending turned off.
Example request
curl https://panel.example.com/api/v1/billing/accounts/whmcs-1042/unsuspend \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_BILLING_KEY"vaultpanel('POST', '/accounts/whmcs-1042/unsuspend');Response 200 OK: { customer, warnings }, message Account unsuspended.
Errors: 404 NOT_FOUND, 409 NOT_SUSPENDED.
Change the plan
/api/v1/billing/accounts/:ref/planMoves the account to another plan (an upgrade or downgrade). Nothing is deleted when it is over the new plan's limits: over lists them and new things are refused until it is back under.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
plan | string | Yes | The new plan, by id or exact name. |
Example request
curl https://panel.example.com/api/v1/billing/accounts/whmcs-1042/plan \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_BILLING_KEY" \
-H "Content-Type: application/json" \
-d '{ "plan": "Business" }'$result = vaultpanel('POST', '/accounts/whmcs-1042/plan', ['plan' => 'Business']);Response 200 OK: { customer, over, appsCapped }, message Plan changed.
Errors: 404 NOT_FOUND, 409 CUSTOMER_REMOVED, 422 VALIDATION_ERROR when no plan has this id or name.
Set the password
/api/v1/billing/accounts/:ref/passwordSets the account's password and signs out its sessions. Without a password, it returns a link for the customer to choose one instead.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
password | string | No | The new password. |
Example request
curl https://panel.example.com/api/v1/billing/accounts/whmcs-1042/password \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_BILLING_KEY" \
-H "Content-Type: application/json" \
-d '{}'$link = vaultpanel('POST', '/accounts/whmcs-1042/password', []);
// $link['resetUrl'], $link['expiresAt']Response 200 OK: { resetUrl, expiresAt, email } (all null when a password was given), message Password changed or Reset link created.
Errors: 404 NOT_FOUND, 409 CUSTOMER_REMOVED, 422 VALIDATION_ERROR for a password that is too short or too long.
Create a sign-in link
/api/v1/billing/accounts/:ref/loginA one-time sign-in link for the account's owner, for a "Log in to VaultPanel" button in your client area. It works once, within two minutes, and signs in without the second factor (the key can already set the password). The link opens the panel's /sso page, which signs in with POST /api/v1/auth/sso.
Example request
curl https://panel.example.com/api/v1/billing/accounts/whmcs-1042/login \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_BILLING_KEY"$link = vaultpanel('POST', '/accounts/whmcs-1042/login');
header('Location: ' . $link['url']);Response 200 OK
{
"success": true,
"data": { "url": "https://panel.example.com/sso#token=…", "expiresAt": "2026-11-10T13:02:00.000Z" },
"message": "Sign-in link created",
"requestId": "…"
}Errors
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No such account. |
| 409 | ACCOUNT_SUSPENDED | The account is suspended, so its owner cannot sign in. |
| 409 | CUSTOMER_REMOVED | The account was removed. |
When the link is opened, POST /api/v1/auth/sso answers LOGIN_LINK_INVALID for a link that was used, expired or is unknown, and ACCOUNT_SUSPENDED when the account was suspended since. Invite and password reset links never accept a sign-in link's token.
Remove an account
/api/v1/billing/accounts/:refCloses the account's sign-in and deletes every website, app, database, database user, cron job and backup it owns. The account record is kept with status terminated. Calling it again retries anything left.
Example request
curl https://panel.example.com/api/v1/billing/accounts/whmcs-1042 \
-X DELETE \
-H "Authorization: Bearer $VAULTPANEL_BILLING_KEY"$result = vaultpanel('DELETE', '/accounts/whmcs-1042');
// $result['queued'], $result['warnings']Response 200 OK: { customer, queued, warnings } as in Remove an account, message Account removed.
Errors: 404 NOT_FOUND.
Hosting
API reference for hosting plans, customer accounts, quotas, suspending and removing accounts, the financial report, billing API keys and a customer's own account.
Plugins
API reference for installing, approving, updating and removing plugins, their event deliveries, their pages in the panel, and plugin directories.