---
title: "Start a legacy Free workspace's grace period (owners and admins)"
method: POST
path: "/billing/grace:start"
tags: ["Billing"]
---

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

`POST /billing/grace:start`

## Request

- Base URL: `https://api.customdomain.ai/v1`
- URL: `https://api.customdomain.ai/v1/billing/grace:start`
- Auth: HTTP bearer

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`.

## Response `200`

The grace state

- object
  - `started` boolean: Whether this call started the grace.
  - `state` 'trialing' | 'active' | 'past_due' | 'grace' | 'blocked' | 'comped' | 'canceled' | 'legacy_free': 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, date-time, nullable
  - `days_left` integer

## Other responses

- `401`: Error envelope: {code, title, details}.
- `403`: Error envelope: {code, title, details}.
- `503`: Error envelope: {code, title, details}.

---

[API](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api.md) · [All operations](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api/llms.txt) · [OpenAPI document](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api/revisions/34d89cb7a7cd?raw)