API Reference

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.

Last updated

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.

MethodPathDescription
GET/api/v1/billing/plansList plans
GET/api/v1/billing/accountsList accounts
POST/api/v1/billing/accountsCreate an account
GET/api/v1/billing/accounts/:refGet an account
POST/api/v1/billing/accounts/:ref/suspendSuspend an account
POST/api/v1/billing/accounts/:ref/unsuspendUnsuspend an account
POST/api/v1/billing/accounts/:ref/planChange the plan
POST/api/v1/billing/accounts/:ref/passwordSet the password
POST/api/v1/billing/accounts/:ref/loginCreate a sign-in link
DELETE/api/v1/billing/accounts/:refRemove 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:

vaultpanel.php
<?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

GET/api/v1/billing/plans
Auth
Billing API key (vpk_…)
Permission
customers.read

Returns 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

GET/api/v1/billing/accounts
Auth
Billing API key (vpk_…)
Permission
customers.read

Returns 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

NameTypeRequiredDescription
searchstringNoPart of the name, email, company or external id.
statusstringNoactive, suspended or terminated.
planId, serverIdstring (UUID)NoOnly accounts on this plan or server.
page, pageSizeintegerNoPage from 1; 1 to 100 per page (default 25).
sort, orderstringNocreatedAt (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

POST/api/v1/billing/accounts
Auth
Billing API key (vpk_…)
Permission
customers.manage

Creates 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

FieldTypeRequiredDescription
namestringYesUp to 120 characters.
emailstringYesUnique among accounts.
planstringYesA plan offered to new accounts, by id or exact name.
companystringNoUp to 120 characters.
externalIdstringNoYour id for the account (letters, digits and . _ : -, up to 100), so you can use it as :ref.
serverIdstring (UUID)NoA connected server.
passwordstringNoThe 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

StatusCodeWhen
409EXTERNAL_ID_TAKENAn account already has this external id; details.customerId is its id, so a retried create can find it.
409NO_SERVERNo connected server to put the account on.
422VALIDATION_ERRORThe 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

GET/api/v1/billing/accounts/:ref
Auth
Billing API key (vpk_…)
Permission
customers.read

Returns 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

POST/api/v1/billing/accounts/:ref/suspend
Auth
Billing API key (vpk_…)
Permission
customers.manage

Signs the account out and refuses its sign-in, turns its websites off, stops its apps and pauses its cron jobs.

Request body

FieldTypeRequiredDescription
reasonstringNoUp 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

POST/api/v1/billing/accounts/:ref/unsuspend
Auth
Billing API key (vpk_…)
Permission
customers.manage

Lets 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

POST/api/v1/billing/accounts/:ref/plan
Auth
Billing API key (vpk_…)
Permission
customers.manage

Moves 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

FieldTypeRequiredDescription
planstringYesThe 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

POST/api/v1/billing/accounts/:ref/password
Auth
Billing API key (vpk_…)
Permission
customers.manage

Sets 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

FieldTypeRequiredDescription
passwordstringNoThe 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.

POST/api/v1/billing/accounts/:ref/login
Auth
Billing API key (vpk_…)
Permission
customers.manage

A 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

StatusCodeWhen
404NOT_FOUNDNo such account.
409ACCOUNT_SUSPENDEDThe account is suspended, so its owner cannot sign in.
409CUSTOMER_REMOVEDThe 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

DELETE/api/v1/billing/accounts/:ref
Auth
Billing API key (vpk_…)
Permission
customers.manage

Closes 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.