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.
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 to | The panel | The person who created it |
| Reaches | /api/v1/billing only | The REST API, as its owner |
| Can do | List plans, and create, suspend, unsuspend, change the plan of and remove customer accounts | What its scopes and its owner's permissions allow |
| Managed under | Hosting > Billing API | Users & 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 acodesuch asQUOTA_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 event | Call | Result |
|---|---|---|
| Order paid | POST /billing/accounts | Creates the account on the plan, with a sign-in for the customer's email. |
| Invoice overdue | POST /billing/accounts/{ref}/suspend | Signs the customer out and blocks sign-in, turns websites off, stops apps and pauses cron jobs. Optional reason. |
| Invoice paid | POST /billing/accounts/{ref}/unsuspend | Turns back on exactly what suspending turned off. |
| Upgrade or downgrade | POST /billing/accounts/{ref}/plan | Moves the account to the new plan. |
| Password change | POST /billing/accounts/{ref}/password | Sets the password and signs the customer out elsewhere; without a password, returns a reset link. |
| "Log in" button | POST /billing/accounts/{ref}/login | A sign-in link that works once, for two minutes. |
| Usage sync | GET /billing/accounts | Every account with its usage and limits, a page at a time. |
| Cancellation | DELETE /billing/accounts/{ref} | Removes the account and deletes everything it owns. |
Creating accounts safely
- Retries never create two accounts. Creating an account with an
externalIdthat already exists returns409 EXTERNAL_ID_TAKENwith the existing account's id indetails.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-timeinviteUrl(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.
Hosting plans and customers
Sell hosting from VaultPanel with plans that cap what each customer may create, customer accounts that see only their own resources, suspension and removal.
WHMCS module
Install the VaultPanel provisioning module for WHMCS to create, suspend, upgrade and remove hosting accounts, with single sign-on and disk usage.