Hosting & Billing

Billing API

Connect WHMCS, Blesta or your own billing system to VaultPanel with a vpk_ API key that creates, suspends, upgrades and removes hosting accounts.

Last updated

The billing API lets a billing system manage hosting accounts: create one when an order is paid, suspend it when an invoice is overdue, change its plan on an upgrade and remove it when the service is cancelled. It lives under /api/v1/billing and authenticates with an API key that belongs to the panel rather than to a person.

This page explains how keys work and how the account lifecycle maps to API calls. Every endpoint, with its fields and responses, is in the billing API reference. For WHMCS, the included module makes these calls for you.

API keys

Billing API keys start with vpk_ and are different from the personal vpt_ API tokens people use for scripts:

Billing API key (vpk_)API token (vpt_)
Belongs toThe panelThe person who created it
Reaches/api/v1/billing onlyThe REST API, as its owner
Can doList plans, and create, suspend, unsuspend, change the plan of and remove customer accountsWhat its scopes and its owner's permissions allow
Managed underHosting > Billing APIUsers & Access > API Tokens

A key has one scope, Billing, which grants exactly customers.read and customers.manage, whoever created it. A panel can have up to 50 active keys.

Create a key

Open the Billing API page

In the panel, open Hosting > Billing API and click New API key. You need the billing.manage permission.

Name it after the system that uses it

For example WHMCS, so you know what breaks if you revoke it.

Copy the key

The key is shown once. Only a fingerprint of it (its SHA-256) is stored, so it cannot be shown again; make a new one if it is lost. Paste it into your billing system's VaultPanel settings.

Revoke or rotate a key

Click Revoke key next to a key on the Billing API page. A revoked key stops working at once and stays in the list for your records. To rotate, create a new key, put it in your billing system, then revoke the old one. The list shows when and from which address each key was last used.

Calling the API

Send the key as a Bearer token. No cookie or CSRF token is involved.

curl -X POST https://panel.example.com/api/v1/billing/accounts \
  -H "Authorization: Bearer $VAULTPANEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada Lovelace","email":"ada@example.com","plan":"Starter","externalId":"whmcs-1042"}'
  • Replies use the panel's usual envelope, { success, data, message, requestId }, and errors carry a code such as QUOTA_REACHED. See API overview.
  • The billing API allows 120 requests a minute per address.
  • Use an address with a certificate your billing system trusts, such as a panel domain, so the key is never sent in the clear.

Account references

Endpoints that act on one account take {ref}: the account's VaultPanel id, or the billing id (externalId) your billing system gave it when it created the account. Giving every account an externalId lets the billing system find it again with its own service id.

A plan can be given by its id or its exact name.

The account lifecycle

Billing eventCallResult
Order paidPOST /billing/accountsCreates the account on the plan, with a sign-in for the customer's email.
Invoice overduePOST /billing/accounts/{ref}/suspendSigns the customer out and blocks sign-in, turns websites off, stops apps and pauses cron jobs. Optional reason.
Invoice paidPOST /billing/accounts/{ref}/unsuspendTurns back on exactly what suspending turned off.
Upgrade or downgradePOST /billing/accounts/{ref}/planMoves the account to the new plan.
Password changePOST /billing/accounts/{ref}/passwordSets the password and signs the customer out elsewhere; without a password, returns a reset link.
"Log in" buttonPOST /billing/accounts/{ref}/loginA sign-in link that works once, for two minutes.
Usage syncGET /billing/accountsEvery account with its usage and limits, a page at a time.
CancellationDELETE /billing/accounts/{ref}Removes the account and deletes everything it owns.

Creating accounts safely

  • Retries never create two accounts. Creating an account with an externalId that already exists returns 409 EXTERNAL_ID_TAKEN with the existing account's id in details.customerId. Treat it as success after checking that account is not removed.
  • One account per email. An email address that already has an account is refused as a validation error on email.
  • Passwords are optional. With a password, the customer can sign in right away. Without one, the reply has a one-time inviteUrl (valid 72 hours) for the customer to choose a password.
  • Servers are picked for you. Without serverId, VaultPanel places the account on a server from the plan's server group (or any server): online servers first, then the one with the fewest customers. Only plans offered for new accounts can be used.

Plan changes

Moving to a smaller plan never deletes anything. The reply lists the limits the account is now over in over; new resources are refused with 409 QUOTA_REACHED until the account is back under its limits. Lower CPU and memory caps reach running apps on their next deploy.

Single sign-on

POST /billing/accounts/{ref}/login returns { url, expiresAt }, a link to the panel's /sso page that signs the customer in once within two minutes. It skips the customer's two-factor code, like the password the billing key can already set. Suspended accounts get 409 ACCOUNT_SUSPENDED instead. Invite and password-reset pages never accept a sign-in link's token.

Suspend, unsuspend and remove

These calls return the account and a list of warnings for anything that could not be changed, for example a resource busy with another change. Calling suspend or remove again retries what was left. Removal also deletes the account's backups and backup schedules and closes its sign-in; the account record stays, with status terminated.

Audit trail

Every billing API call is recorded in the audit log with the API key as the actor. Accounts the API created show Billing API as Added by on the customer's page.