# Hosting

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

> API reference for hosting plans, customer accounts, quotas, suspending and removing accounts, the financial report, billing API keys and a customer's own account.

Hosting plans set what a customer may have: websites, subdomains, apps, databases, database users, cron jobs, disk space, and caps on each app's CPU and memory. Customers sign in to a panel that shows only their own account. The staff endpoints under `/hosting` manage plans, customers and the API keys billing systems use; `/hosting/me` is for the signed-in customer.

Billing systems manage accounts through the separate [Billing API](https://docs.vaultpanel.net/api-reference/billing). For the concepts, see [Hosting plans and customers](https://docs.vaultpanel.net/guides/hosting-and-billing).

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/v1/hosting/me` | [Get your account](https://docs.vaultpanel.net/api-reference/hosting#get-your-account) |
| GET | `/api/v1/hosting/me/dns` | [Get your DNS](https://docs.vaultpanel.net/api-reference/hosting#get-your-dns) |
| POST | `/api/v1/hosting/me/dns/zones/:id/check` | [Check one of your zones](https://docs.vaultpanel.net/api-reference/hosting#check-one-of-your-zones) |
| GET | `/api/v1/hosting/plans` | [List plans](https://docs.vaultpanel.net/api-reference/hosting#list-plans) |
| POST | `/api/v1/hosting/plans` | [Create a plan](https://docs.vaultpanel.net/api-reference/hosting#create-a-plan) |
| GET | `/api/v1/hosting/plans/:id` | [Get a plan](https://docs.vaultpanel.net/api-reference/hosting#get-a-plan) |
| PATCH | `/api/v1/hosting/plans/:id` | [Update a plan](https://docs.vaultpanel.net/api-reference/hosting#update-a-plan) |
| DELETE | `/api/v1/hosting/plans/:id` | [Delete a plan](https://docs.vaultpanel.net/api-reference/hosting#delete-a-plan) |
| GET | `/api/v1/hosting/customers` | [List customers](https://docs.vaultpanel.net/api-reference/hosting#list-customers) |
| POST | `/api/v1/hosting/customers` | [Create a customer](https://docs.vaultpanel.net/api-reference/hosting#create-a-customer) |
| GET | `/api/v1/hosting/customers/:id` | [Get a customer](https://docs.vaultpanel.net/api-reference/hosting#get-a-customer) |
| PATCH | `/api/v1/hosting/customers/:id` | [Update a customer](https://docs.vaultpanel.net/api-reference/hosting#update-a-customer) |
| POST | `/api/v1/hosting/customers/:id/plan` | [Change the plan](https://docs.vaultpanel.net/api-reference/hosting#change-the-plan) |
| POST | `/api/v1/hosting/customers/:id/suspend` | [Suspend an account](https://docs.vaultpanel.net/api-reference/hosting#suspend-an-account) |
| POST | `/api/v1/hosting/customers/:id/unsuspend` | [Unsuspend an account](https://docs.vaultpanel.net/api-reference/hosting#unsuspend-an-account) |
| POST | `/api/v1/hosting/customers/:id/terminate` | [Remove an account](https://docs.vaultpanel.net/api-reference/hosting#remove-an-account) |
| POST | `/api/v1/hosting/customers/:id/password-reset` | [Create a password reset link](https://docs.vaultpanel.net/api-reference/hosting#create-a-password-reset-link) |
| POST | `/api/v1/hosting/customers/:id/resources` | [Move a resource to a customer](https://docs.vaultpanel.net/api-reference/hosting#move-a-resource-to-a-customer) |
| DELETE | `/api/v1/hosting/customers/:id/resources/:type/:resourceId` | [Take a resource back](https://docs.vaultpanel.net/api-reference/hosting#take-a-resource-back) |
| GET | `/api/v1/hosting/reports/financial` | [Get the financial report](https://docs.vaultpanel.net/api-reference/hosting#get-the-financial-report) |
| GET | `/api/v1/hosting/api-keys` | [List billing API keys](https://docs.vaultpanel.net/api-reference/hosting#list-billing-api-keys) |
| POST | `/api/v1/hosting/api-keys` | [Create a billing API key](https://docs.vaultpanel.net/api-reference/hosting#create-a-billing-api-key) |
| POST | `/api/v1/hosting/api-keys/:id/revoke` | [Revoke a billing API key](https://docs.vaultpanel.net/api-reference/hosting#revoke-a-billing-api-key) |

## Hosting customers and the API

A hosting customer (role `customer`) can reach only `/auth`, `/api-tokens`, `/hosting/me`, and the website, subdomain, domain, certificate, app, deployment, CMS, database, database user, backup, backup schedule, cron job and job routes; everything else answers `403 FORBIDDEN`. There they see and change only what their account owns (anything else is `404`). Their creates are checked against their plan:

| Status | Code | When |
| --- | --- | --- |
| 409 | `QUOTA_REACHED` | The plan's limit is reached (`details: { kind, limit, used }`), or the account is over its disk space. |
| 409 | `NO_SERVER` | The account has no server. |
| 403 | `ACCOUNT_SUSPENDED` | Signing in to a suspended or removed account. |

## Get your account

`GET /api/v1/hosting/me`

The signed-in customer's account: `customer`, `plan` (with its `limits` and `appCaps`), `usage`, `appCaps`, `ports` (the account's own app ports, each with the app on it or `null`) and `server` (its name, status, host name, addresses, time zone and installed software). Staff get `404`.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/hosting/me \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { customer, plan, usage, ports } = await panel.hosting.me();
```

**Response** `200 OK`

```json
{
  "success": true,
  "data": {
    "customer": { "id": "c1d2e3f4-…", "name": "Ada Customer", "company": "Example Ltd", "email": "ada@example.org", "status": "active", "createdAt": "2026-10-05T10:00:00.000Z" },
    "plan": {
      "id": "a0b1c2d3-…",
      "name": "Starter",
      "priceCents": 900,
      "currency": "USD",
      "billingCycle": "monthly",
      "limits": { "websites": 5, "subdomains": 10, "applications": 2, "databases": 5, "databaseUsers": 5, "cronJobs": 10, "diskMb": 10240 },
      "appCaps": { "appMemoryMb": 512, "appCpuPercent": 100 }
    },
    "usage": {
      "websites": 2,
      "subdomains": 1,
      "applications": 1,
      "databases": 2,
      "databaseUsers": 2,
      "cronJobs": 1,
      "diskMb": 812,
      "diskBytes": 851443712,
      "disk": { "websites": 402653184, "applications": 314572800, "databases": 134217728 },
      "limits": { "websites": 5, "subdomains": 10, "applications": 2, "databases": 5, "databaseUsers": 5, "cronJobs": 10, "diskMb": 10240 },
      "over": []
    },
    "appCaps": { "appMemoryMb": 512, "appCpuPercent": 100 },
    "ports": [{ "port": 3001, "serverId": "9b2e7c1a-…", "application": { "id": "3e4f5a6b-…", "name": "shop-api" } }],
    "server": { "id": "9b2e7c1a-…", "name": "web-1", "status": "online", "hostname": "web-1", "publicIp": "203.0.113.10" }
  },
  "message": "OK",
  "requestId": "…"
}
```

## Get your DNS

`GET /api/v1/hosting/me/dns`

The name servers to set at the registrar, whether new domains get a zone automatically, and the account's domains this panel answers for, with their name servers and last public DNS check. See [DNS](https://docs.vaultpanel.net/api-reference/dns) for the zone fields. Staff get `404`.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/hosting/me/dns \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { nameservers, autoZones, zones } = await panel.request('GET', '/hosting/me/dns');
```

**Response** `200 OK`

```json
{
  "success": true,
  "data": {
    "nameservers": ["ns1.example.net", "ns2.example.net"],
    "autoZones": true,
    "zones": [
      {
        "id": "4f0c2a8e-…",
        "domain": "example.org",
        "status": "active",
        "nameservers": [{ "host": "ns1.example.net", "inZone": false, "addresses": [] }],
        "delegation": { "status": "ok", "nameservers": ["ns1.example.net", "ns2.example.net"], "detail": null, "checkedAt": "2026-11-10T09:00:00.000Z" }
      }
    ]
  },
  "message": "OK",
  "requestId": "…"
}
```

## Check one of your zones

`POST /api/v1/hosting/me/dns/zones/:id/check`

Checks one of the account's zones against public DNS, like [Check name servers in public DNS](https://docs.vaultpanel.net/api-reference/dns#check-name-servers-in-public-dns), and returns `{ zone }` in the shape above.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/hosting/me/dns/zones/4f0c2a8e-5b1d-4c47-9a53-1c2f3b4d5e6f/check \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { zone } = await panel.request('POST', `/hosting/me/dns/zones/${zoneId}/check`);
```

**Response** `200 OK`: `{ zone }`.

**Errors**: `404 NOT_FOUND` for a zone that is not the account's.

## The plan object

| Field | Type | Description |
| --- | --- | --- |
| `id`, `name`, `description` | string | The plan. |
| `isActive` | boolean | Offered to new customers. |
| `priceCents`, `currency`, `billingCycle` | | The price per cycle (`monthly`, `quarterly`, `yearly` or `free`). VaultPanel stores it to show it and hand it to billing systems; it takes no payments. |
| `serverGroup` | object or null | New accounts go on a server of this group. |
| `limits` | object | `websites`, `subdomains`, `applications`, `databases`, `databaseUsers`, `cronJobs` and `diskMb`. `null` is unlimited. |
| `appCaps` | object | `appMemoryMb` (64 to 262144) and `appCpuPercent` (10 to 6400; 100 is one core) for each app. `null` is no cap. |
| `customerCount` | integer | Customers on the plan. |

## List plans

`GET /api/v1/hosting/plans` — Permission: customers.read — Token scope: read

Returns every plan, by name.

**Example request**

**cURL**

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

**JavaScript**

```js
const { items } = await panel.hosting.plans();
```

**Response** `200 OK`: `{ items }` of [plans](https://docs.vaultpanel.net/api-reference/hosting#the-plan-object).

## Create a plan

`POST /api/v1/hosting/plans` — Permission: plans.manage — Token scope: customers

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | Up to 60 letters, numbers, spaces and `. _ - + ( ) &`. Unique. |
| `description` | string | No | Up to 300 characters. |
| `isActive` | boolean | No | Offered to new customers. Default `true`. |
| `priceCents` | integer or null | No | 0 to 100000000. Default `null` (no price). |
| `currency` | string | No | A 3-letter code. Default `USD`. |
| `billingCycle` | string | No | `monthly` (default), `quarterly`, `yearly` or `free`. |
| `serverGroupId` | string (UUID) or null | No | Put new accounts on a server of this group. |
| `limits` | object | No | Any of the limits; 0 to 10000 (`diskMb` up to 100000000), or `null` for unlimited. |
| `appCaps` | object | No | `appMemoryMb` and `appCpuPercent`, or `null`. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/hosting/plans \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Starter",
    "priceCents": 900,
    "currency": "USD",
    "billingCycle": "monthly",
    "limits": { "websites": 5, "applications": 2, "databases": 5, "diskMb": 10240 },
    "appCaps": { "appMemoryMb": 512, "appCpuPercent": 100 }
  }'
```

**JavaScript**

```js
const plan = await panel.hosting.createPlan({
  name: 'Starter',
  priceCents: 900,
  limits: { websites: 5, applications: 2, databases: 5, diskMb: 10240 },
  appCaps: { appMemoryMb: 512, appCpuPercent: 100 },
});
```

**Response** `201 Created`: the plan, message `Plan created`.

**Errors**: `422 VALIDATION_ERROR` for a name another plan has, an unknown server group, or another invalid field.

## Get a plan

`GET /api/v1/hosting/plans/:id` — Permission: customers.read — Token scope: read

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/hosting/plans/a0b1c2d3-e4f5-4a6b-8c7d-8e9f0a1b2c3d \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const plan = await panel.request('GET', `/hosting/plans/${planId}`);
```

**Response** `200 OK`: the plan. `404 NOT_FOUND` when there is none.

## Update a plan

`PATCH /api/v1/hosting/plans/:id` — Permission: plans.manage — Token scope: customers

Changes any of the fields of [Create a plan](https://docs.vaultpanel.net/api-reference/hosting#create-a-plan) (send at least one). New app caps reach each of the plan's apps on its next deploy or apply; `appsCapped` says how many apps are affected.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/hosting/plans/a0b1c2d3-e4f5-4a6b-8c7d-8e9f0a1b2c3d \
  -X PATCH \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "limits": { "websites": 10 } }'
```

**JavaScript**

```js
const { plan, appsCapped } = await panel.hosting.updatePlan(planId, { limits: { websites: 10 } });
```

**Response** `200 OK`: `{ plan, appsCapped }`, message `Plan saved.` (plus how many apps get the new cap).

## Delete a plan

`DELETE /api/v1/hosting/plans/:id` — Permission: plans.manage — Token scope: customers

Deletes a plan no customer is on (removed accounts included). To stop offering a plan that has customers, set `isActive` to `false` instead.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/hosting/plans/a0b1c2d3-e4f5-4a6b-8c7d-8e9f0a1b2c3d \
  -X DELETE \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
await panel.hosting.removePlan(planId);
```

**Response** `200 OK`: `data` is `null`, message `Plan deleted`.

**Errors**: `404 NOT_FOUND`, and `409 PLAN_IN_USE` while customers are on it.

## The customer object

| Field | Type | Description |
| --- | --- | --- |
| `id`, `name`, `company`, `email` | string | The account. |
| `externalId` | string or null | The billing system's id for it (a WHMCS service id…). |
| `status` | string | `active`, `suspended` or `terminated` (removed; kept for the record). |
| `suspendReason`, `suspendedAt` | | Why and when it was suspended. |
| `suspendedResources` | object or null | How many `websites`, `applications` and `cronJobs` suspending turned off. |
| `terminatedAt`, `notes`, `createdVia` | | `createdVia` is `panel` or `api`. |
| `plan` | object | `{ id, name }`. |
| `server` | object or null | `{ id, name, status }`: where new websites and apps go. |
| `userId`, `user` | | The sign-in account: `{ id, email, isActive, twoFactorEnabled, lastLoginAt }` on single-customer responses. |
| `usage` | object | Counts, `diskBytes`, `diskMb`, `disk` per kind, the plan's `limits`, and `over`: the limits it is over (for example after moving to a smaller plan; nothing is deleted, new things are refused). |

## List customers

`GET /api/v1/hosting/customers` — Permission: customers.read — Token scope: read

Returns customers a page at a time, with their usage. 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 customers 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/hosting/customers?status=suspended" \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { items } = await panel.hosting.customers({ status: 'suspended' });
```

**Response** `200 OK`: `{ items, pagination }` of [customers](https://docs.vaultpanel.net/api-reference/hosting#the-customer-object).

## Create a customer

`POST /api/v1/hosting/customers` — Permission: customers.manage — Token scope: customers

Creates the account and its sign-in. Without a password, an invite link is returned (and emailed when [panel email](https://docs.vaultpanel.net/api-reference/settings) is set up) so the customer chooses one. Without a server, the panel picks one: a connected server of the plan's server group (or any server), online first, then the one with the fewest customers.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | Up to 120 characters. |
| `email` | string | Yes | Unique among accounts. |
| `planId` | string (UUID) | Yes | A plan offered to new customers. |
| `company` | string | No | Up to 120 characters. |
| `serverId` | string (UUID) or null | No | A connected server. |
| `externalId` | string | No | The billing system's id: letters, digits and `. _ : -`, up to 100. Unique. |
| `password` | string | No | The account's password. |
| `notes` | string | No | Up to 1000 characters, for staff. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/hosting/customers \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Ada Customer", "email": "ada@example.org", "planId": "a0b1c2d3-e4f5-4a6b-8c7d-8e9f0a1b2c3d" }'
```

**JavaScript**

```js
const { customer, inviteUrl } = await panel.hosting.createCustomer({
  name: 'Ada Customer',
  email: 'ada@example.org',
  planId: 'a0b1c2d3-e4f5-4a6b-8c7d-8e9f0a1b2c3d',
});
```

**Response** `201 Created`

```json
{
  "success": true,
  "data": {
    "customer": { "id": "c1d2e3f4-…", "name": "Ada Customer", "email": "ada@example.org", "status": "active", "plan": { "id": "a0b1c2d3-…", "name": "Starter" } },
    "inviteUrl": "https://panel.example.com/reset-password#token=…",
    "inviteExpiresAt": "2026-11-17T12:00:00.000Z",
    "email": { "sent": true, "to": "ada@example.org" }
  },
  "message": "Customer created. The invite link was emailed to ada@example.org.",
  "requestId": "…"
}
```

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 409 | `EXTERNAL_ID_TAKEN` | Another customer has this external id (`details.customerId`). |
| 409 | `NO_SERVER` | No connected server to put the account on. |
| 409 | `CONFLICT` | The email or external id was just taken. |
| 422 | `VALIDATION_ERROR` | The email is taken, the plan is not offered to new customers, the server is not connected, or another invalid field. |

## Get a customer

`GET /api/v1/hosting/customers/:id` — Permission: customers.read — Token scope: read

Returns the customer with `planDetail` (the full plan), `resources` (its `websites`, `applications`, `databases` and `databaseUsers`, up to 500 each) and `ports` (its app ports).

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/hosting/customers/c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const customer = await panel.hosting.customer(customerId);
```

**Response** `200 OK`: the customer with `planDetail`, `resources` and `ports`. `404 NOT_FOUND` when there is none.

## Update a customer

`PATCH /api/v1/hosting/customers/:id` — Permission: customers.manage — Token scope: customers

Changes any of `name`, `email`, `company`, `serverId`, `externalId` and `notes` (send at least one). The name and email also change on the sign-in account. Moving to another server moves the account's free app ports there. A removed account can change only its notes.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/hosting/customers/c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f \
  -X PATCH \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "company": "Example Holdings Ltd" }'
```

**JavaScript**

```js
await panel.hosting.updateCustomer(customerId, { company: 'Example Holdings Ltd' });
```

**Response** `200 OK`: the customer, message `Customer saved`.

**Errors**: `409 CUSTOMER_REMOVED`, `409 EXTERNAL_ID_TAKEN`, `422 VALIDATION_ERROR`.

## Change the plan

`POST /api/v1/hosting/customers/:id/plan` — Permission: customers.manage — Token scope: customers

Moves the account to another plan. Nothing is deleted when the account 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 |
| --- | --- | --- | --- |
| `planId` | string (UUID) | Yes | The new plan. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/hosting/customers/c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f/plan \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "planId": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e" }'
```

**JavaScript**

```js
const { customer, over, appsCapped } = await panel.hosting.changePlan(customerId, newPlanId);
```

**Response** `200 OK`: `{ customer, over, appsCapped }`, message `Plan changed`.

**Errors**: `409 CUSTOMER_REMOVED`, `422 VALIDATION_ERROR` for an unknown plan.

## Suspend an account

`POST /api/v1/hosting/customers/:id/suspend` — Permission: customers.manage — Token scope: customers

Signs the account out and refuses its sign-in, turns its websites off, stops its apps and pauses its cron jobs. Suspending again catches what was busy the first time. `warnings` lists anything that could not be turned off.

**Request body**

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

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/hosting/customers/c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f/suspend \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Invoice overdue" }'
```

**JavaScript**

```js
const { customer, warnings } = await panel.hosting.suspend(customerId, 'Invoice overdue');
```

**Response** `200 OK`: `{ customer, warnings }`, message `Account suspended`.

**Errors**: `409 CUSTOMER_REMOVED`.

## Unsuspend an account

`POST /api/v1/hosting/customers/:id/unsuspend` — Permission: customers.manage — Token scope: customers

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/hosting/customers/c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f/unsuspend \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { customer, warnings } = await panel.hosting.unsuspend(customerId);
```

**Response** `200 OK`: `{ customer, warnings }`, message `Account unsuspended`.

**Errors**: `409 NOT_SUSPENDED`.

## Remove an account

`POST /api/v1/hosting/customers/:id/terminate` — Permission: customers.manage — Token scope: customers

Closes the account's sign-in and deletes every cron job, app, website, database user, database and backup it owns (with their files), its backup schedules and the DNS zones added for it. 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/hosting/customers/c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f/terminate \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { queued, warnings } = await panel.hosting.terminate(customerId);
```

**Response** `200 OK`

```json
{
  "success": true,
  "data": {
    "customer": { "id": "c1d2e3f4-…", "status": "terminated", "terminatedAt": "2026-11-10T13:00:00.000Z" },
    "queued": { "cronJobs": 1, "applications": 1, "websites": 2, "databaseUsers": 2, "databases": 2, "backups": 6 },
    "warnings": []
  },
  "message": "Account removed. Its websites, apps and databases are being deleted.",
  "requestId": "…"
}
```

## Create a password reset link

`POST /api/v1/hosting/customers/:id/password-reset` — Permission: customers.manage — Token scope: customers

Creates a link for the customer to set a new password, emailed when panel email is set up.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/hosting/customers/c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f/password-reset \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { resetUrl, expiresAt } = await panel.request('POST', `/hosting/customers/${customerId}/password-reset`);
```

**Response** `200 OK`: `{ resetUrl, expiresAt, email }`.

**Errors**: `409 CUSTOMER_REMOVED`.

## Move a resource to a customer

`POST /api/v1/hosting/customers/:id/resources` — Permission: customers.manage — Token scope: customers

Gives an existing website, app, database or database user to the account, with what hangs off it (cron jobs, backups, schedules). Move an app rather than its website: the website goes with it.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string | Yes | `website`, `application`, `database` or `database_user`. |
| `resourceId` | string (UUID) | Yes | Its id. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/hosting/customers/c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f/resources \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "type": "website", "resourceId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d" }'
```

**JavaScript**

```js
await panel.request('POST', `/hosting/customers/${customerId}/resources`, {
  body: { type: 'website', resourceId: '1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d' },
});
```

**Response** `200 OK`: `{ customer }`, message `Moved to this customer`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No such resource. |
| 409 | `CUSTOMER_REMOVED` | The account was removed. |
| 409 | `RESOURCE_OWNED` | It belongs to another customer: take it from that account first. |
| 409 | `WEBSITE_OWNED_BY_APP` | The website serves an app: move the app instead. |
| 409 | `PANEL_WEBSITE` | The website puts VaultPanel itself on its domain. |
| 422 | `VALIDATION_ERROR` | A database user with access to another account's database, or an app on another customer's port. |

## Take a resource back

`DELETE /api/v1/hosting/customers/:id/resources/:type/:resourceId` — Permission: customers.manage — Token scope: customers

Takes a website, app, database or database user back from the account to staff.

**Example request**

**cURL**

```bash
curl -X DELETE \
  https://panel.example.com/api/v1/hosting/customers/c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f/resources/website/1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
await panel.request('DELETE', `/hosting/customers/${customerId}/resources/website/${websiteId}`);
```

**Response** `200 OK`: `{ customer }`, message `Taken back from this customer`.

**Errors**: `404 NOT_FOUND` when it is not this customer's, `409 WEBSITE_OWNED_BY_APP`.

## Get the financial report

`GET /api/v1/hosting/reports/financial` — Permission: customers.read — Token scope: read

What accounts are worth at their plans' prices: expected amounts, never payments (VaultPanel takes none). Currencies are never mixed. See [Financial report](https://docs.vaultpanel.net/guides/hosting-and-billing/financial-report).

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `months` | integer | No | 1 to 36. Default 12. |

**Example request**

**cURL**

```bash
curl "https://panel.example.com/api/v1/hosting/reports/financial?months=6" \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const report = await panel.request('GET', '/hosting/reports/financial', { query: { months: 6 } });
```

**Response** `200 OK`

```json
{
  "success": true,
  "data": {
    "generatedAt": "2026-11-10T13:00:00.000Z",
    "months": 6,
    "from": "2026-06-01T00:00:00.000Z",
    "summary": {
      "activeAccounts": 42,
      "suspendedAccounts": 3,
      "unpricedAccounts": 1,
      "newAccounts": 12,
      "removedAccounts": 2,
      "byCurrency": [{ "currency": "USD", "monthlyCents": 37800, "yearlyCents": 453600, "atRiskCents": 2700, "payingAccounts": 41 }]
    },
    "plans": [
      {
        "id": "a0b1c2d3-…",
        "name": "Starter",
        "isActive": true,
        "billingCycle": "monthly",
        "priceCents": 900,
        "currency": "USD",
        "monthlyCents": 900,
        "activeAccounts": 42,
        "suspendedAccounts": 3,
        "monthlyTotalCents": 37800,
        "atRiskCents": 2700
      }
    ],
    "history": [
      { "month": "2026-11", "newAccounts": 2, "removedAccounts": 0, "suspensions": 1, "accountsAtEnd": 45, "monthlyByCurrency": { "USD": 40500 } }
    ]
  },
  "message": "OK",
  "requestId": "…"
}
```

`monthlyCents` spreads a plan's price over one month (`0` for free plans, `null` without a price). `atRiskCents` is what suspended accounts would bring. `monthlyByCurrency` prices the accounts at the end of each month at their current plan.

## List billing API keys

`GET /api/v1/hosting/api-keys` — Permission: billing.manage — Token scope: full

Returns the `vpk_` keys billing systems use with the [Billing API](https://docs.vaultpanel.net/api-reference/billing), active ones first. The key itself is never returned again, only its `prefix`.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/hosting/api-keys \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { items } = await panel.request('GET', '/hosting/api-keys');
```

**Response** `200 OK`

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "e5f6a7b8-…",
        "name": "WHMCS",
        "prefix": "vpk_Xr8kQ2mN",
        "scopes": ["billing"],
        "createdBy": { "id": "3c4d5e6f-…", "email": "owner@example.com" },
        "lastUsedAt": "2026-11-10T12:58:00.000Z",
        "lastUsedIp": "198.51.100.20",
        "revokedAt": null,
        "createdAt": "2026-10-05T09:00:00.000Z"
      }
    ]
  },
  "message": "OK",
  "requestId": "…"
}
```

## Create a billing API key

`POST /api/v1/hosting/api-keys` — Permission: billing.manage — Token scope: full

Creates a key. The key (`vpk_…`) is in this response only; the panel keeps only its hash. Up to 50 active keys.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | Up to 100 characters. |
| `scopes` | string[] | No | `["billing"]` (the default and only scope): list plans, and create, suspend, unsuspend, change the plan of and remove customer accounts. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/hosting/api-keys \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "WHMCS" }'
```

**JavaScript**

```js
const { apiKey, key } = await panel.request('POST', '/hosting/api-keys', { body: { name: 'WHMCS' } });
```

**Response** `201 Created`: `{ apiKey, key }`, message `API key created. Copy it now: it is not shown again.`

**Errors**: `409 TOO_MANY_KEYS` with 50 active keys.

## Revoke a billing API key

`POST /api/v1/hosting/api-keys/:id/revoke` — Permission: billing.manage — Token scope: full

Revokes a key at once. Revoking a revoked key changes nothing.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/hosting/api-keys/e5f6a7b8-c9d0-4e1f-a2b3-c4d5e6f7a8b9/revoke \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const apiKey = await panel.request('POST', `/hosting/api-keys/${keyId}/revoke`);
```

**Response** `200 OK`: the key with `revokedAt`, message `API key revoked`.

**Errors**: `404 NOT_FOUND`.
