Billing

Whether billing needs attention (every member)

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.

get/billing/notice

Request

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

Response

Billing notice

role'owner' | 'admin' | 'member' | 'viewer' required
can_manageboolean required

Whether this member holds billing:manage (owners and admins).

configuredboolean required

Whether a workspace can subscribe on this deployment.

attentionboolean required

Billing needs an owner or admin: a trial or grace to act on, a failed payment, or a block.

restrictedboolean required

New domain connections are refused right now.

setup_requiredboolean

Owners and admins only: send them through the billing setup flow.

first_domain_freeboolean

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_domainsinteger

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.

reasonstring

Why a restricted workspace is restricted: setup_required, grace_ended, unpaid, comp_ended or canceled.

plan_idstring
plan_namestring
days_leftinteger

Whole days left in the trial or grace; -1 otherwise.

trial_ends_atstring date-time nullable
grace_ends_atstring date-time nullable
current_period_endstring date-time nullable
cancel_at_period_endboolean
payment_failedboolean

Changes

No recorded changes to this operation across all 1 revision of this API.