SubscriptionSummary

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/fettle-sh/json-schema/fettle-sh-subscription-summary-schema.json",
  "title": "SubscriptionSummary",
  "description": "Current subscription state for the authenticated user.\n\n``status`` is ``null`` for accounts that never subscribed (free tier).\n``renews_at`` is set while the subscription auto-renews; ``expires_at`` is\nset instead once a cancellation is scheduled for period end.\n\n``plan`` is the effective plan (``max(paid_plan, active grants)``);\n``paid_plan`` is what the org is entitled to without grants. ``grant`` is\nthe highest active grant, ``last_ended_grant`` the latest grant that ended\nin the last 7 days and lowered the plan, and\n``checkout_trial_until_grant_end`` says whether a checkout for the\ngrant's tier opened now would start with a trial up to the grant's end.\n\nOverrides ``Base``'s ``use_enum_values``: this keeps ``billing_period`` as\nan actual ``BillingPeriod`` instance instead of a pre-coerced string, so\nthe declared response model stays the contract for what gets serialized.\nA ``StrEnum`` member serializes to the same JSON value either way.",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_original/fettle-sh-api-openapi.json#/components/schemas/SubscriptionSummary",
  "properties": {
    "plan": {
      "$ref": "#/$defs/PlanTier"
    },
    "status": {
      "anyOf": [
        {
          "$ref": "#/$defs/SubscriptionStatus"
        },
        {
          "type": "null"
        }
      ]
    },
    "cancel_at_period_end": {
      "type": "boolean",
      "title": "Cancel At Period End",
      "default": false
    },
    "renews_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Renews At"
    },
    "expires_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Expires At"
    },
    "trial_ends_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Trial Ends At"
    },
    "billing_period": {
      "anyOf": [
        {
          "$ref": "#/$defs/BillingPeriod"
        },
        {
          "type": "null"
        }
      ]
    },
    "amount": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Amount"
    },
    "currency": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Currency"
    },
    "paid_plan": {
      "$ref": "#/$defs/PlanTier"
    },
    "grant": {
      "anyOf": [
        {
          "$ref": "#/$defs/SummaryGrant"
        },
        {
          "type": "null"
        }
      ]
    },
    "last_ended_grant": {
      "anyOf": [
        {
          "$ref": "#/$defs/SummaryEndedGrant"
        },
        {
          "type": "null"
        }
      ]
    },
    "checkout_trial_until_grant_end": {
      "type": "boolean",
      "title": "Checkout Trial Until Grant End",
      "default": false
    }
  },
  "additionalProperties": false,
  "type": "object",
  "required": [
    "plan",
    "paid_plan"
  ],
  "$defs": {
    "BillingPeriod": {
      "type": "string",
      "enum": [
        "MONTH",
        "YEAR"
      ],
      "title": "BillingPeriod",
      "description": "How often a subscription renews.\n\nPolar models monthly and yearly billing as separate products, so the\nperiod is part of what a checkout selects. Member name == value to match\nthe project's enum convention and the persisted DB labels."
    },
    "GrantSource": {
      "type": "string",
      "enum": [
        "PROMO_CODE",
        "ADMIN",
        "CAMPAIGN"
      ],
      "title": "GrantSource",
      "description": "What created a plan grant."
    },
    "PlanTier": {
      "type": "string",
      "enum": [
        "FREE",
        "PLUS",
        "PRO",
        "MAX",
        "ENTERPRISE"
      ],
      "title": "PlanTier",
      "description": "Subscription tier of an organization; gates feature/usage limits."
    },
    "SubscriptionStatus": {
      "type": "string",
      "enum": [
        "ACTIVE",
        "TRIALING",
        "PAST_DUE",
        "CANCELED",
        "INCOMPLETE",
        "INCOMPLETE_EXPIRED",
        "UNPAID"
      ],
      "title": "SubscriptionStatus",
      "description": "Lifecycle state of a user's paid subscription.\n\nMember name == value (UPPER_SNAKE_CASE) to match the project's enum\nconvention and the persisted DB labels. Polar emits lowercase status\nstrings on the wire; that translation lives in ``SubscriptionService``."
    },
    "SummaryEndedGrant": {
      "properties": {
        "plan": {
          "$ref": "#/$defs/PlanTier"
        },
        "ended_at": {
          "type": "string",
          "format": "date-time",
          "title": "Ended At"
        },
        "paused_count": {
          "type": "integer",
          "title": "Paused Count"
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "plan",
        "ended_at",
        "paused_count"
      ],
      "title": "SummaryEndedGrant",
      "description": "A grant that ended within the last 7 days and lowered the plan."
    },
    "SummaryGrant": {
      "properties": {
        "plan": {
          "$ref": "#/$defs/PlanTier"
        },
        "ends_at": {
          "type": "string",
          "format": "date-time",
          "title": "Ends At"
        },
        "source": {
          "$ref": "#/$defs/GrantSource"
        },
        "code": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Code"
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "plan",
        "ends_at",
        "source",
        "code"
      ],
      "title": "SummaryGrant",
      "description": "The organization's highest active plan grant, as the billing page shows it.\n\nAlso the redeem answer (``src.promo.schemas.PromoGrantRead`` is this\nclass). Keeps real enum members for the reason ``SubscriptionSummary``\ngives."
    }
  }
}