---
title: "Whether billing needs attention (every member)"
method: GET
path: "/billing/notice"
tags: ["Billing"]
---

# Whether billing needs attention (every member)

`GET /billing/notice`

## Request

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

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.

## Response `200`

Billing notice

- BillingNotice
  - `role` 'owner' | 'admin' | 'member' | 'viewer', required
  - `can_manage` boolean, required: Whether this member holds billing:manage (owners and admins).
  - `configured` boolean, required: Whether a workspace can subscribe on this deployment.
  - `attention` boolean, required: Billing needs an owner or admin: a trial or grace to act on, a failed payment, or a block.
  - `restricted` boolean, required: New domain connections are refused right now.
  - `setup_required` boolean: Owners and admins only: send them through the billing setup flow.
  - `first_domain_free` boolean: 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: 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': 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: Why a restricted workspace is restricted: setup_required, grace_ended, unpaid, comp_ended or canceled.
  - `plan_id` string
  - `plan_name` string
  - `days_left` integer: Whole days left in the trial or grace; -1 otherwise.
  - `trial_ends_at` string, date-time, nullable
  - `grace_ends_at` string, date-time, nullable
  - `current_period_end` string, date-time, nullable
  - `cancel_at_period_end` boolean
  - `payment_failed` boolean

## Other responses

- `401`: Error envelope: {code, title, details}.
- `403`: 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)