# Whether billing needs attention (every member)

> Whether billing needs attention (every member): CustomDomain™ API reference in the billing group. Covers parameters, request body, responses and error codes.

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

## `GET https://api.customdomain.ai/v1/billing/notice`

What the console needs on every page to decide on a billing banner or the setup flow. Any member of the workspace may read it with their own tenant API key. Members and viewers get only `role`, `can_manage`, `configured`, `attention` and `restricted`: never the plan, dates or amounts. Owners and admins also get the billing state, and `first_domain_free` with `free_domains` (how many domains it may connect before a card) while a new workspace is on the first domain free rule. A delegated agent token needs `stats:read`.

### Authentication

`apiKey`, `agentToken`

### Responses

| Status | Description |
| --- | --- |
| `200` | Billing notice |
| `401` | Error envelope: {code, title, details}. |
| `403` | Error envelope: {code, title, details}. |

### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `role` | `owner`, `admin`, `member`, `viewer` | yes |  |
| `can_manage` | boolean | yes | Whether this member holds billing:manage (owners and admins). |
| `configured` | boolean | yes | Whether a workspace can subscribe on this deployment. |
| `attention` | boolean | yes | Billing needs an owner or admin: a trial or grace to act on, a failed payment, or a block. |
| `restricted` | boolean | yes | New domain connections are refused right now. |
| `setup_required` | boolean | no | Owners and admins only: send them through the billing setup flow. |
| `first_domain_free` | boolean | no | Owners and admins only, and present only when true: this is a new workspace on the first domain free rule. Its first domain connects without a subscription, so `restricted` is false until that domain is connected and true after, and the next one needs the trial. Credentials (an API key, an application) always need it. |
| `free_domains` | integer | no | Owners and admins only, present with `first_domain_free`: how many domains the workspace may connect before it has a subscription. One, unless the operator granted more. |
| `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 | Why a restricted workspace is restricted: setup_required, grace_ended, unpaid, comp_ended or canceled. |
| `plan_id` | string | no |  |
| `plan_name` | string | no |  |
| `days_left` | integer | no | Whole days left in the trial or grace; -1 otherwise. |
| `trial_ends_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 |  |
| `payment_failed` | boolean | no |  |

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