# Billing API

URL: https://docs.vaultpanel.net/api-reference/billing

> 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](https://docs.vaultpanel.net/api-reference/hosting#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](https://docs.vaultpanel.net/guides/hosting-and-billing/whmcs) uses this API. For the concepts, see [Billing API](https://docs.vaultpanel.net/guides/hosting-and-billing/billing-api).

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/v1/billing/plans` | [List plans](https://docs.vaultpanel.net/api-reference/billing#list-plans) |
| GET | `/api/v1/billing/accounts` | [List accounts](https://docs.vaultpanel.net/api-reference/billing#list-accounts) |
| POST | `/api/v1/billing/accounts` | [Create an account](https://docs.vaultpanel.net/api-reference/billing#create-an-account) |
| GET | `/api/v1/billing/accounts/:ref` | [Get an account](https://docs.vaultpanel.net/api-reference/billing#get-an-account) |
| POST | `/api/v1/billing/accounts/:ref/suspend` | [Suspend an account](https://docs.vaultpanel.net/api-reference/billing#suspend-an-account) |
| POST | `/api/v1/billing/accounts/:ref/unsuspend` | [Unsuspend an account](https://docs.vaultpanel.net/api-reference/billing#unsuspend-an-account) |
| POST | `/api/v1/billing/accounts/:ref/plan` | [Change the plan](https://docs.vaultpanel.net/api-reference/billing#change-the-plan) |
| POST | `/api/v1/billing/accounts/:ref/password` | [Set the password](https://docs.vaultpanel.net/api-reference/billing#set-the-password) |
| POST | `/api/v1/billing/accounts/:ref/login` | [Create a sign-in link](https://docs.vaultpanel.net/api-reference/billing#create-a-sign-in-link) |
| DELETE | `/api/v1/billing/accounts/:ref` | [Remove an account](https://docs.vaultpanel.net/api-reference/billing#remove-an-account) |

## Authentication

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

```http
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
<?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 — 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](https://docs.vaultpanel.net/api-reference/hosting#the-plan-object).

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/billing/plans \
  -H "Authorization: Bearer $VAULTPANEL_BILLING_KEY"
```

**PHP**

```php
$plans = vaultpanel('GET', '/plans')['items'];
```

**Response** `200 OK`

```json
{
  "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 — 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**

| 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**

```bash
curl "https://panel.example.com/api/v1/billing/accounts?pageSize=100&page=1" \
  -H "Authorization: Bearer $VAULTPANEL_BILLING_KEY"
```

**PHP**

```php
$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](https://docs.vaultpanel.net/api-reference/hosting#the-customer-object).

## Create an account

`POST /api/v1/billing/accounts` — Auth: billing — 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**

| 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**

```bash
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" }'
```

**PHP**

```php
$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

`GET /api/v1/billing/accounts/:ref` — Auth: billing — Permission: customers.read

Returns the account with its usage, `planDetail`, `resources` and app `ports`, as in [Get a customer](https://docs.vaultpanel.net/api-reference/hosting#get-a-customer).

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/billing/accounts/whmcs-1042 \
  -H "Authorization: Bearer $VAULTPANEL_BILLING_KEY"
```

**PHP**

```php
$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 — 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**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `reason` | string | No | Up to 300 characters. |

**Example request**

**cURL**

```bash
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" }'
```

**PHP**

```php
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 — Permission: customers.manage

Lets the account sign in again and turns back on exactly what suspending turned off.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/billing/accounts/whmcs-1042/unsuspend \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_BILLING_KEY"
```

**PHP**

```php
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 — 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**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `plan` | string | Yes | The new plan, by id or exact name. |

**Example request**

**cURL**

```bash
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" }'
```

**PHP**

```php
$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 — 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**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `password` | string | No | The new password. |

**Example request**

**cURL**

```bash
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 '{}'
```

**PHP**

```php
$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

`POST /api/v1/billing/accounts/:ref/login` — Auth: billing — 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**

```bash
curl https://panel.example.com/api/v1/billing/accounts/whmcs-1042/login \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_BILLING_KEY"
```

**PHP**

```php
$link = vaultpanel('POST', '/accounts/whmcs-1042/login');
header('Location: ' . $link['url']);
```

**Response** `200 OK`

```json
{
  "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

`DELETE /api/v1/billing/accounts/:ref` — Auth: billing — 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**

```bash
curl https://panel.example.com/api/v1/billing/accounts/whmcs-1042 \
  -X DELETE \
  -H "Authorization: Bearer $VAULTPANEL_BILLING_KEY"
```

**PHP**

```php
$result = vaultpanel('DELETE', '/accounts/whmcs-1042');
// $result['queued'], $result['warnings']
```

**Response** `200 OK`: `{ customer, queued, warnings }` as in [Remove an account](https://docs.vaultpanel.net/api-reference/hosting#remove-an-account), message `Account removed`.

**Errors**: `404 NOT_FOUND`.
