BillingNotice

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/customdomain-ai/json-schema/customdomain-ai-billing-notice-schema.json",
  "title": "BillingNotice",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/customdomain-ai-billing-api-openapi.yml#/components/schemas/BillingNotice",
  "type": "object",
  "required": [
    "role",
    "can_manage",
    "configured",
    "attention",
    "restricted"
  ],
  "properties": {
    "role": {
      "$ref": "#/$defs/Role"
    },
    "can_manage": {
      "type": "boolean",
      "description": "Whether this member holds billing:manage (owners and admins)."
    },
    "configured": {
      "type": "boolean",
      "description": "Whether a workspace can subscribe on this deployment."
    },
    "attention": {
      "type": "boolean",
      "description": "Billing needs an owner or admin: a trial or grace to act on, a failed payment, or a block."
    },
    "restricted": {
      "type": "boolean",
      "description": "New domain connections are refused right now."
    },
    "setup_required": {
      "type": "boolean",
      "description": "Owners and admins only: send them through the billing setup flow."
    },
    "first_domain_free": {
      "type": "boolean",
      "description": "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": {
      "type": "integer",
      "description": "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": {
      "$ref": "#/$defs/BillingState"
    },
    "reason": {
      "type": "string",
      "description": "Why a restricted workspace is restricted: setup_required, grace_ended, unpaid, comp_ended or canceled."
    },
    "plan_id": {
      "type": "string"
    },
    "plan_name": {
      "type": "string"
    },
    "days_left": {
      "type": "integer",
      "description": "Whole days left in the trial or grace; -1 otherwise."
    },
    "trial_ends_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "grace_ends_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "current_period_end": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "cancel_at_period_end": {
      "type": "boolean"
    },
    "payment_failed": {
      "type": "boolean"
    }
  },
  "$defs": {
    "BillingState": {
      "type": "string",
      "description": "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`.",
      "enum": [
        "trialing",
        "active",
        "past_due",
        "grace",
        "blocked",
        "comped",
        "canceled",
        "legacy_free"
      ]
    },
    "Role": {
      "type": "string",
      "enum": [
        "owner",
        "admin",
        "member",
        "viewer"
      ]
    }
  }
}