Subscription Structure

{
  "$schema": "https://json-structure.org/meta/core/v0/#",
  "$id": "https://raw.githubusercontent.com/api-evangelist/square/refs/heads/main/json-structure/subscription-structure.json",
  "name": "Square Subscription",
  "description": "Represents a subscription purchased by a customer. Subscriptions enable sellers to generate recurring revenue by offering scheduled fulfillment of products or services with configurable billing periods, pricing, and discounts.",
  "type": "object",
  "properties": {
    "id": {
      "description": "The Square-assigned ID of the subscription.",
      "maxLength": 255,
      "readOnly": true,
      "type": "string"
    },
    "location_id": {
      "description": "The ID of the location associated with the subscription.",
      "readOnly": true,
      "type": "string"
    },
    "plan_variation_id": {
      "description": "The ID of the subscribed-to subscription plan variation.",
      "readOnly": true,
      "type": "string"
    },
    "customer_id": {
      "description": "The ID of the subscribing customer profile.",
      "readOnly": true,
      "type": "string"
    },
    "start_date": {
      "description": "The YYYY-MM-DD-formatted date to start the subscription.",
      "readOnly": true,
      "type": "date"
    },
    "canceled_date": {
      "description": "The YYYY-MM-DD-formatted date to cancel the subscription, when the subscription status changes to CANCELED and the subscription billing stops.",
      "type": "date"
    },
    "charged_through_date": {
      "description": "The YYYY-MM-DD-formatted date up to when the subscriber is invoiced for the subscription.",
      "readOnly": true,
      "type": "date"
    },
    "status": {
      "description": "The current status of the subscription.",
      "enum": [
        "PENDING",
        "ACTIVE",
        "CANCELED",
        "DEACTIVATED",
        "PAUSED"
      ],
      "readOnly": true,
      "type": "string"
    },
    "tax_percentage": {
      "description": "The tax amount applied when billing the subscription. The percentage is expressed in decimal form, using a '.' as the decimal separator and without a '%' sign. For example, a value of 7.5 corresponds to 7.5%.",
      "type": "string"
    },
    "invoice_ids": {
      "items": {
        "type": "string"
      },
      "description": "The IDs of the invoices created for the subscription, listed in order when the invoices were created (newest invoices appear first).",
      "readOnly": true,
      "type": "array"
    },
    "price_override_money": {
      "$ref": "money.json",
      "description": "A custom price which overrides the cost of a subscription plan variation with STATIC pricing."
    },
    "version": {
      "description": "The version of the object. When updating an object, the version supplied must match the version in the database.",
      "type": "int64"
    },
    "created_at": {
      "description": "The timestamp when the subscription was created, in RFC 3339 format.",
      "readOnly": true,
      "type": "datetime"
    },
    "card_id": {
      "description": "The ID of the subscriber's card used to charge for the subscription.",
      "type": "string"
    },
    "timezone": {
      "description": "Timezone that will be used in date calculations for the subscription. Defaults to the timezone of the location based on location_id. Format: the IANA Timezone Database identifier.",
      "readOnly": true,
      "type": "string"
    },
    "source": {
      "description": "The origination details of the subscription.",
      "properties": {
        "name": {
          "description": "The name used to identify the place that created the subscription.",
          "type": "string"
        }
      },
      "type": "object"
    },
    "actions": {
      "items": {
        "properties": {
          "id": {
            "description": "The ID of the scheduled action.",
            "type": "string"
          },
          "type": {
            "description": "The type of the action.",
            "enum": [
              "CANCEL",
              "PAUSE",
              "RESUME",
              "SWAP_PLAN",
              "CHANGE_BILLING_ANCHOR_DATE"
            ],
            "type": "string"
          },
          "effective_date": {
            "description": "The YYYY-MM-DD-formatted date when the action will take effect.",
            "type": "date"
          }
        },
        "type": "object"
      },
      "description": "The list of scheduled actions on this subscription.",
      "type": "array"
    },
    "monthly_billing_anchor_date": {
      "description": "The day of the month on which the subscription will issue invoices and publish orders.",
      "minimum": 1,
      "maximum": 31,
      "type": "int32"
    },
    "phases": {
      "items": {
        "properties": {
          "uid": {
            "description": "The Square-assigned ID of the subscription phase.",
            "type": "string"
          },
          "cadence": {
            "description": "The billing cadence of the phase.",
            "enum": [
              "DAILY",
              "WEEKLY",
              "EVERY_TWO_WEEKS",
              "THIRTY_DAYS",
              "SIXTY_DAYS",
              "NINETY_DAYS",
              "MONTHLY",
              "EVERY_TWO_MONTHS",
              "QUARTERLY",
              "EVERY_FOUR_MONTHS",
              "EVERY_SIX_MONTHS",
              "ANNUAL",
              "EVERY_TWO_YEARS"
            ],
            "type": "string"
          },
          "periods": {
            "description": "The number of periods the phase lasts.",
            "type": "int32"
          },
          "recurring_price_money": {
            "$ref": "money.json",
            "description": "The amount billed per period during this phase."
          },
          "ordinal": {
            "description": "The position this phase appears in the sequence of phases.",
            "type": "int64"
          }
        },
        "type": "object"
      },
      "description": "The subscription phases that define the billing schedule.",
      "type": "array"
    }
  }
}