# Move a running subscription to another self-serve plan

> Move a running subscription to another self-serve plan: CustomDomain™ API reference in the billing group. Covers parameters, request body and responses.

Source: https://docs.customdomain.ai/docs/api-reference/billing/changeBillingPlan

## `POST https://api.customdomain.ai/v1/billing/change-plan`

Swaps the price of the workspace's running Stripe subscription (Stripe prorates the difference). Self-serve plans only; a workspace without a running subscription gets `409` and subscribes through `/billing/checkout`. Requires `billing:manage`.

### Authentication

`apiKey`

### Request body (JSON)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `plan` | `starter`, `startup`, `growth`, `premium`, `enterprise`, `free` | yes | `free` is retired: legacy workspaces still carry it until they subscribe, and it cannot be bought or assigned. |

### Responses

| Status | Description |
| --- | --- |
| `200` | The new billing status |
| `400` | Error envelope: {code, title, details}. |
| `403` | Error envelope: {code, title, details}. |
| `409` | Error envelope: {code, title, details}. |
| `503` | Error envelope: {code, title, details}. |

### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `tenant_id` | string | no |  |
| `state` | `trialing`, `active`, `past_due`, `grace`, `blocked`, `comped`, `canceled`, `legacy_free` | no | A workspace's billing state, evaluated from its record and the clock. `trialing` and `active` are a running Stripe subscription; `past_due` is a failed payment Stripe is still retrying (nothing is refused); `grace` is a legacy Free workspace (or an operator extension) inside its grace period; `legacy_free` is a Free workspace whose grace has not started; `comped` is an operator comp; `blocked` and `canceled` refuse new connections (`402 billing_required`) while live domains keep working. A new workspace (`blocked`, reason `setup_required`) is refused only once its first domain is connected: see `first_domain_free`. |
| `reason` | string | no |  |
| `restricted` | boolean | no |  |
| `first_domain_free` | boolean | no | Present only when true: a new workspace on the first domain free rule (see `GET /billing/notice`). |
| `free_domains` | integer | no | Present with `first_domain_free`: how many domains the workspace may connect before it has a subscription. |
| `attention` | boolean | no |  |
| `setup_required` | boolean | no |  |
| `days_left` | integer | no |  |
| `price_cents` | integer | no | What the workspace pays per month (the Stripe amount, else the catalog price). |
| `currency` | string | no |  |
| `trial_ends_at` | string or null | no |  |
| `grace_started_at` | string or null | no |  |
| `grace_ends_at` | string or null | no |  |
| `current_period_end` | string or null | no |  |
| `cancel_at_period_end` | boolean | no |  |
| `ended_at` | string or null | no |  |
| `comped` | boolean | no |  |
| `comped_until` | string or null | no |  |
| `payment_failed` | boolean | no |  |
| `payment_failed_at` | string or null | no |  |
| `has_billing_account` | boolean | no |  |
| `portal_available` | boolean | no |  |
| `can_change_plan` | boolean | no |  |
| `mode` | `test`, `live`, `""` | no |  |
| `plan` | object | no |  |
| `next_charge` | object or null | no |  |
| `checkout` | object | no | What a checkout started now would give. |
| `usage` | object | no | Usage over the plan's quota window: this calendar month, or the 12 months ending with it on `starter`. |
| `payment_method` | object or null | no | The payment method the workspace is charged on, or null when Stripe holds none. A card has its brand, last four digits and expiry, and names the wallet when it was paid through Apple Pay or Google Pay. A Link account has the email of the account (Stripe never shows the card behind it). Cash App Pay has only its type. |

The full specification is served at `GET https://api.customdomain.ai/v1/openapi.json`.
