# Billing API

URL: https://docs.vaultpanel.net/guides/hosting-and-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.

The billing API lets a billing system manage [hosting accounts](https://docs.vaultpanel.net/guides/hosting-and-billing): 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](https://docs.vaultpanel.net/api-reference/billing). For WHMCS, the included [module](https://docs.vaultpanel.net/guides/hosting-and-billing/whmcs) makes these calls for you.

## API keys

Billing API keys start with `vpk_` and are different from the personal `vpt_` [API tokens](https://docs.vaultpanel.net/api-reference/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.

```bash
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](https://docs.vaultpanel.net/api-reference).
- 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](https://docs.vaultpanel.net/getting-started/panel-https-and-domain), so the key is never sent in the clear.

> **Warning:**
A billing key can set any customer's password and create sign-in links for them. Store it like a password, and revoke it when the billing system no longer needs it.

## 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 `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](https://docs.vaultpanel.net/guides/security/audit-log) with the API key as the actor. Accounts the API created show **Billing API** as **Added by** on the customer's page.
