# Start a legacy Free workspace's grace period (owners and admins)

> Start a legacy Free workspace's grace period (owners and admins): CustomDomain™ API reference. Covers parameters, request body, responses and error codes.

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

## `POST https://api.customdomain.ai/v1/billing/grace:start`

Called by the console when an owner or admin opens it: a workspace still on the retired Free plan gets its 14 day grace period from now (and its owners and admins an email). Idempotent, and a no-op in any other state. A Free workspace that never signs in gets the same grace at its first connection attempt. Requires `billing:manage`.

### Authentication

`apiKey`

### Responses

| Status | Description |
| --- | --- |
| `200` | The grace state |
| `401` | Error envelope: {code, title, details}. |
| `403` | Error envelope: {code, title, details}. |
| `503` | Error envelope: {code, title, details}. |

### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `started` | boolean | no | Whether this call started the grace. |
| `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`. |
| `grace_ends_at` | string or null | no |  |
| `days_left` | integer | no |  |

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