{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/converly-io/json-schema/converly-io-subscription-schema.json",
  "title": "Subscription",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/converly-io-openapi.yml#/components/schemas/Subscription",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Stripe-shaped id, prefixed `sub_`"
    },
    "plan_id": {
      "type": "string"
    },
    "plan_name": {
      "type": "string"
    },
    "price": {
      "type": "number",
      "description": "Cents USD"
    },
    "status": {
      "type": "string",
      "enum": [
        "trialing",
        "active",
        "past_due",
        "canceled",
        "trial_expired"
      ],
      "description": "Normalized Converly subscription status (NOT raw Stripe passthrough). Stripe statuses are mapped on sync: unpaid / incomplete_expired → canceled; incomplete / paused → no state change. `trial_expired` is Converly-internal — set by the cardless-trial expiry cron when a cardless trial lapses without a card. Mutations (publish/create flow, test-event) are gated to `trialing`/`active`; any other status returns 402 entitlement_required."
    },
    "cancel_at_period_end": {
      "type": "boolean",
      "description": "Always false in practice — /v1 does immediate cancel."
    },
    "trial_ends_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "trial_type": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "cardless",
        "carded",
        null
      ],
      "description": "`cardless` | `carded` | null. Cardless trials (plugin install-prep, or `/v1/signup` with start_cardless_trial) have NO Stripe subscription and expire via cron — plugin/extension surfaces should show an 'Add card' prompt during the trial and lock the UI once status is `trial_expired`. `carded` trials are Stripe-managed (no banner). null = legacy pre-column rows (treat as carded)."
    },
    "current_period_end": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "flows_limit": {
      "type": "number"
    },
    "conversions_limit": {
      "type": "number"
    },
    "flows_unlimited": {
      "type": "boolean",
      "description": "True when flows_limit is unlimited (mirrors -1) — read this rather than interpreting -1."
    },
    "conversions_unlimited": {
      "type": "boolean",
      "description": "True when conversions_limit is unlimited (mirrors -1)."
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    }
  },
  "required": [
    "id",
    "plan_id",
    "plan_name",
    "price",
    "status",
    "cancel_at_period_end",
    "trial_ends_at",
    "trial_type",
    "current_period_end",
    "flows_limit",
    "conversions_limit",
    "flows_unlimited",
    "conversions_unlimited",
    "created_at",
    "updated_at"
  ]
}