BillingStatus

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/customdomain-ai/json-schema/customdomain-ai-billing-status-schema.json",
  "title": "BillingStatus",
  "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/BillingStatus",
  "type": "object",
  "properties": {
    "tenant_id": {
      "type": "string"
    },
    "state": {
      "$ref": "#/$defs/BillingState"
    },
    "reason": {
      "type": "string"
    },
    "restricted": {
      "type": "boolean"
    },
    "first_domain_free": {
      "type": "boolean",
      "description": "Present only when true: a new workspace on the first domain free rule (see `GET /billing/notice`)."
    },
    "free_domains": {
      "type": "integer",
      "description": "Present with `first_domain_free`: how many domains the workspace may connect before it has a subscription."
    },
    "attention": {
      "type": "boolean"
    },
    "setup_required": {
      "type": "boolean"
    },
    "days_left": {
      "type": "integer"
    },
    "price_cents": {
      "type": "integer",
      "description": "What the workspace pays per month (the Stripe amount, else the catalog price)."
    },
    "currency": {
      "type": "string"
    },
    "trial_ends_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "grace_started_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"
    },
    "ended_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "comped": {
      "type": "boolean"
    },
    "comped_until": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "payment_failed": {
      "type": "boolean"
    },
    "payment_failed_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "has_billing_account": {
      "type": "boolean"
    },
    "portal_available": {
      "type": "boolean"
    },
    "can_change_plan": {
      "type": "boolean"
    },
    "mode": {
      "type": "string",
      "enum": [
        "test",
        "live",
        ""
      ]
    },
    "plan": {
      "type": "object",
      "properties": {
        "id": {
          "$ref": "#/$defs/PlanId"
        },
        "name": {
          "type": "string"
        },
        "price_cents": {
          "type": "integer"
        },
        "public_price": {
          "type": "boolean"
        },
        "domains_per_year": {
          "type": "integer"
        },
        "domains_per_month": {
          "type": "integer"
        },
        "hard_cap": {
          "type": "boolean"
        },
        "retired": {
          "type": "boolean"
        }
      }
    },
    "next_charge": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "at": {
          "type": "string",
          "format": "date-time"
        },
        "amount_cents": {
          "type": "integer"
        },
        "currency": {
          "type": "string"
        }
      }
    },
    "checkout": {
      "type": "object",
      "description": "What a checkout started now would give.",
      "properties": {
        "available": {
          "type": "boolean"
        },
        "trial_days": {
          "type": "integer"
        },
        "trial_end": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "first_charge_at": {
          "type": "string",
          "format": "date-time"
        },
        "default_plan": {
          "$ref": "#/$defs/PlanId"
        }
      }
    },
    "usage": {
      "type": "object",
      "properties": {
        "used": {
          "type": "integer"
        },
        "quota": {
          "type": "integer"
        },
        "period_start": {
          "type": "string",
          "format": "date-time"
        },
        "period_end": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "payment_method": {
      "type": [
        "object",
        "null"
      ],
      "description": "The payment method the workspace is charged on, or null when Stripe holds none. A card has its brand, last four digits and expiry, and names the wallet when it was paid through Apple Pay or Google Pay. A Link account has the email of the account (Stripe never shows the card behind it). Cash App Pay has only its type.",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "card",
            "link",
            "cashapp"
          ]
        },
        "brand": {
          "type": "string"
        },
        "last4": {
          "type": "string"
        },
        "exp_month": {
          "type": "integer"
        },
        "exp_year": {
          "type": "integer"
        },
        "wallet": {
          "type": "string",
          "enum": [
            "apple_pay",
            "google_pay"
          ],
          "description": "The wallet a card was paid through, when it was."
        },
        "email": {
          "type": "string",
          "description": "The email of the Link account (type link)."
        }
      }
    }
  },
  "$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"
      ]
    },
    "PlanId": {
      "type": "string",
      "description": "`free` is retired: legacy workspaces still carry it until they subscribe, and it cannot be bought or assigned.",
      "enum": [
        "starter",
        "startup",
        "growth",
        "premium",
        "enterprise",
        "free"
      ]
    }
  }
}