Square Subscription

{
  "$id": "https://github.com/api-evangelist/square/blob/main/json-schema/subscription.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "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": {
      "type": "string",
      "description": "The Square-assigned ID of the subscription.",
      "maxLength": 255,
      "readOnly": true
    },
    "location_id": {
      "type": "string",
      "description": "The ID of the location associated with the subscription.",
      "readOnly": true
    },
    "plan_variation_id": {
      "type": "string",
      "description": "The ID of the subscribed-to subscription plan variation.",
      "readOnly": true
    },
    "customer_id": {
      "type": "string",
      "description": "The ID of the subscribing customer profile.",
      "readOnly": true
    },
    "start_date": {
      "type": "string",
      "format": "date",
      "description": "The YYYY-MM-DD-formatted date to start the subscription.",
      "readOnly": true
    },
    "canceled_date": {
      "type": "string",
      "format": "date",
      "description": "The YYYY-MM-DD-formatted date to cancel the subscription, when the subscription status changes to CANCELED and the subscription billing stops."
    },
    "charged_through_date": {
      "type": "string",
      "format": "date",
      "description": "The YYYY-MM-DD-formatted date up to when the subscriber is invoiced for the subscription.",
      "readOnly": true
    },
    "status": {
      "type": "string",
      "description": "The current status of the subscription.",
      "enum": ["PENDING", "ACTIVE", "CANCELED", "DEACTIVATED", "PAUSED"],
      "readOnly": true
    },
    "tax_percentage": {
      "type": "string",
      "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%."
    },
    "invoice_ids": {
      "type": "array",
      "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
    },
    "price_override_money": {
      "$ref": "money.json",
      "description": "A custom price which overrides the cost of a subscription plan variation with STATIC pricing."
    },
    "version": {
      "type": "integer",
      "format": "int64",
      "description": "The version of the object. When updating an object, the version supplied must match the version in the database."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "The timestamp when the subscription was created, in RFC 3339 format.",
      "readOnly": true
    },
    "card_id": {
      "type": "string",
      "description": "The ID of the subscriber's card used to charge for the subscription."
    },
    "timezone": {
      "type": "string",
      "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
    },
    "source": {
      "type": "object",
      "description": "The origination details of the subscription.",
      "properties": {
        "name": {
          "type": "string",
          "description": "The name used to identify the place that created the subscription."
        }
      }
    },
    "actions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The ID of the scheduled action."
          },
          "type": {
            "type": "string",
            "description": "The type of the action.",
            "enum": ["CANCEL", "PAUSE", "RESUME", "SWAP_PLAN", "CHANGE_BILLING_ANCHOR_DATE"]
          },
          "effective_date": {
            "type": "string",
            "format": "date",
            "description": "The YYYY-MM-DD-formatted date when the action will take effect."
          }
        }
      },
      "description": "The list of scheduled actions on this subscription."
    },
    "monthly_billing_anchor_date": {
      "type": "integer",
      "description": "The day of the month on which the subscription will issue invoices and publish orders.",
      "minimum": 1,
      "maximum": 31
    },
    "phases": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "uid": {
            "type": "string",
            "description": "The Square-assigned ID of the subscription phase."
          },
          "cadence": {
            "type": "string",
            "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"]
          },
          "periods": {
            "type": "integer",
            "description": "The number of periods the phase lasts."
          },
          "recurring_price_money": {
            "$ref": "money.json",
            "description": "The amount billed per period during this phase."
          },
          "ordinal": {
            "type": "integer",
            "format": "int64",
            "description": "The position this phase appears in the sequence of phases."
          }
        }
      },
      "description": "The subscription phases that define the billing schedule."
    }
  }
}