CreateSubscriptionRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/square/main/json-schema/square-create-subscription-request-schema.json",
  "title": "CreateSubscriptionRequest",
  "description": "Defines input parameters in a request to the \n[CreateSubscription](api-endpoint:Subscriptions-CreateSubscription) endpoint.",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/square-subscriptions-api-openapi.yml#/components/schemas/CreateSubscriptionRequest",
  "type": "object",
  "x-release-status": "PUBLIC",
  "required": [
    "location_id",
    "customer_id"
  ],
  "properties": {
    "idempotency_key": {
      "type": "string",
      "description": "A unique string that identifies this `CreateSubscription` request.\nIf you do not provide a unique string (or provide an empty string as the value),\nthe endpoint treats each request as independent.\n\nFor more information, see [Idempotency keys](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)."
    },
    "location_id": {
      "type": "string",
      "description": "The ID of the location the subscription is associated with.",
      "minLength": 1
    },
    "plan_variation_id": {
      "type": "string",
      "description": "The ID of the [subscription plan variation](https://developer.squareup.com/docs/subscriptions-api/plans-and-variations#plan-variations) created using the Catalog API."
    },
    "customer_id": {
      "type": "string",
      "description": "The ID of the [customer](entity:Customer) subscribing to the subscription plan variation.",
      "minLength": 1
    },
    "start_date": {
      "type": "string",
      "description": "The `YYYY-MM-DD`-formatted date to start the subscription. \nIf it is unspecified, the subscription starts immediately."
    },
    "canceled_date": {
      "type": "string",
      "description": "The `YYYY-MM-DD`-formatted date when the newly created subscription is scheduled for cancellation. \n\nThis date overrides the cancellation date set in the plan variation configuration.\nIf the cancellation date is earlier than the end date of a subscription cycle, the subscription stops\nat the canceled date and the subscriber is sent a prorated invoice at the beginning of the canceled cycle. \n\nWhen the subscription plan of the newly created subscription has a fixed number of cycles and the `canceled_date`\noccurs before the subscription plan expires, the specified `canceled_date` sets the date when the subscription \nstops through the end of the last cycle."
    },
    "tax_percentage": {
      "type": "string",
      "description": "The tax to add when billing the subscription.\nThe percentage is expressed in decimal form, using a `'.'` as the decimal\nseparator and without a `'%'` sign. For example, a value of 7.5\ncorresponds to 7.5%.",
      "maxLength": 10
    },
    "price_override_money": {
      "$ref": "#/$defs/Money",
      "description": "A custom price which overrides the cost of a subscription plan variation with `STATIC` pricing.\nThis field does not affect itemized subscriptions with `RELATIVE` pricing. Instead, \nyou should edit the Subscription's [order template](https://developer.squareup.com/docs/subscriptions-api/manage-subscriptions#phases-and-order-templates)."
    },
    "card_id": {
      "type": "string",
      "description": "The ID of the [subscriber's](entity:Customer) [card](entity:Card) to charge.\nIf it is not specified, the subscriber receives an invoice via email with a link to pay for their subscription."
    },
    "timezone": {
      "type": "string",
      "description": "The timezone that is used in date calculations for the subscription. If unset, defaults to\nthe location timezone. If a timezone is not configured for the location, defaults to \"America/New_York\".\nFormat: the IANA Timezone Database identifier for the location timezone. For\na list of time zones, see [List of tz database time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)."
    },
    "source": {
      "$ref": "#/$defs/SubscriptionSource",
      "description": "The origination details of the subscription.",
      "x-release-status": "BETA"
    },
    "monthly_billing_anchor_date": {
      "type": "integer",
      "description": "The day-of-the-month to change the billing date to.",
      "minimum": 1,
      "maximum": 31,
      "x-release-status": "BETA"
    },
    "phases": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Phase"
      },
      "description": "array of phases for this subscription"
    }
  },
  "$defs": {
    "Currency": {
      "type": "string",
      "enum": [
        "UNKNOWN_CURRENCY",
        "AED",
        "AFN",
        "ALL",
        "AMD",
        "ANG",
        "AOA",
        "ARS",
        "AUD",
        "AWG",
        "AZN",
        "BAM",
        "BBD",
        "BDT",
        "BGN",
        "BHD",
        "BIF",
        "BMD",
        "BND",
        "BOB",
        "BOV",
        "BRL",
        "BSD",
        "BTN",
        "BWP",
        "BYR",
        "BZD",
        "CAD",
        "CDF",
        "CHE",
        "CHF",
        "CHW",
        "CLF",
        "CLP",
        "CNY",
        "COP",
        "COU",
        "CRC",
        "CUC",
        "CUP",
        "CVE",
        "CZK",
        "DJF",
        "DKK",
        "DOP",
        "DZD",
        "EGP",
        "ERN",
        "ETB",
        "EUR",
        "FJD",
        "FKP",
        "GBP",
        "GEL",
        "GHS",
        "GIP",
        "GMD",
        "GNF",
        "GTQ",
        "GYD",
        "HKD",
        "HNL",
        "HRK",
        "HTG",
        "HUF",
        "IDR",
        "ILS",
        "INR",
        "IQD",
        "IRR",
        "ISK",
        "JMD",
        "JOD",
        "JPY",
        "KES",
        "KGS",
        "KHR",
        "KMF",
        "KPW",
        "KRW",
        "KWD",
        "KYD",
        "KZT",
        "LAK",
        "LBP",
        "LKR",
        "LRD",
        "LSL",
        "LTL",
        "LVL",
        "LYD",
        "MAD",
        "MDL",
        "MGA",
        "MKD",
        "MMK",
        "MNT",
        "MOP",
        "MRO",
        "MUR",
        "MVR",
        "MWK",
        "MXN",
        "MXV",
        "MYR",
        "MZN",
        "NAD",
        "NGN",
        "NIO",
        "NOK",
        "NPR",
        "NZD",
        "OMR",
        "PAB",
        "PEN",
        "PGK",
        "PHP",
        "PKR",
        "PLN",
        "PYG",
        "QAR",
        "RON",
        "RSD",
        "RUB",
        "RWF",
        "SAR",
        "SBD",
        "SCR",
        "SDG",
        "SEK",
        "SGD",
        "SHP",
        "SLL",
        "SLE",
        "SOS",
        "SRD",
        "SSP",
        "STD",
        "SVC",
        "SYP",
        "SZL",
        "THB",
        "TJS",
        "TMT",
        "TND",
        "TOP",
        "TRY",
        "TTD",
        "TWD",
        "TZS",
        "UAH",
        "UGX",
        "USD",
        "USN",
        "USS",
        "UYI",
        "UYU",
        "UZS",
        "VEF",
        "VND",
        "VUV",
        "WST",
        "XAF",
        "XAG",
        "XAU",
        "XBA",
        "XBB",
        "XBC",
        "XBD",
        "XCD",
        "XDR",
        "XOF",
        "XPD",
        "XPF",
        "XPT",
        "XTS",
        "XXX",
        "YER",
        "ZAR",
        "ZMK",
        "ZMW",
        "BTC",
        "XUS"
      ],
      "x-enum-elements": [
        {
          "name": "UNKNOWN_CURRENCY",
          "description": "Unknown currency"
        },
        {
          "name": "AED",
          "description": "United Arab Emirates dirham"
        },
        {
          "name": "AFN",
          "description": "Afghan afghani"
        },
        {
          "name": "ALL",
          "description": "Albanian lek"
        },
        {
          "name": "AMD",
          "description": "Armenian dram"
        },
        {
          "name": "ANG",
          "description": "Netherlands Antillean guilder"
        },
        {
          "name": "AOA",
          "description": "Angolan kwanza"
        },
        {
          "name": "ARS",
          "description": "Argentine peso"
        },
        {
          "name": "AUD",
          "description": "Australian dollar"
        },
        {
          "name": "AWG",
          "description": "Aruban florin"
        },
        {
          "name": "AZN",
          "description": "Azerbaijani manat"
        },
        {
          "name": "BAM",
          "description": "Bosnia and Herzegovina convertible mark"
        },
        {
          "name": "BBD",
          "description": "Barbados dollar"
        },
        {
          "name": "BDT",
          "description": "Bangladeshi taka"
        },
        {
          "name": "BGN",
          "description": "Bulgarian lev"
        },
        {
          "name": "BHD",
          "description": "Bahraini dinar"
        },
        {
          "name": "BIF",
          "description": "Burundian franc"
        },
        {
          "name": "BMD",
          "description": "Bermudian dollar"
        },
        {
          "name": "BND",
          "description": "Brunei dollar"
        },
        {
          "name": "BOB",
          "description": "Boliviano"
        },
        {
          "name": "BOV",
          "description": "Bolivian Mvdol"
        },
        {
          "name": "BRL",
          "description": "Brazilian real"
        },
        {
          "name": "BSD",
          "description": "Bahamian dollar"
        },
        {
          "name": "BTN",
          "description": "Bhutanese ngultrum"
        },
        {
          "name": "BWP",
          "description": "Botswana pula"
        },
        {
          "name": "BYR",
          "description": "Belarusian ruble"
        },
        {
          "name": "BZD",
          "description": "Belize dollar"
        },
        {
          "name": "CAD",
          "description": "Canadian dollar"
        },
        {
          "name": "CDF",
          "description": "Congolese franc"
        },
        {
          "name": "CHE",
          "description": "WIR Euro"
        },
        {
          "name": "CHF",
          "description": "Swiss franc"
        },
        {
          "name": "CHW",
          "description": "WIR Franc"
        },
        {
          "name": "CLF",
          "description": "Unidad de Fomento"
        },
        {
          "name": "CLP",
          "description": "Chilean peso"
        },
        {
          "name": "CNY",
          "description": "Chinese yuan"
        },
        {
          "name": "COP",
          "description": "Colombian peso"
        },
        {
          "name": "COU",
          "description": "Unidad de Valor Real"
        },
        {
          "name": "CRC",
          "description": "Costa Rican colon"
        },
        {
          "name": "CUC",
          "description": "Cuban convertible peso"
        },
        {
          "name": "CUP",
          "description": "Cuban peso"
        },
        {
          "name": "CVE",
          "description": "Cape Verdean escudo"
        },
        {
          "name": "CZK",
          "description": "Czech koruna"
        },
        {
          "name": "DJF",
          "description": "Djiboutian franc"
        },
        {
          "name": "DKK",
          "description": "Danish krone"
        },
        {
          "name": "DOP",
          "description": "Dominican peso"
        },
        {
          "name": "DZD",
          "description": "Algerian dinar"
        },
        {
          "name": "EGP",
          "description": "Egyptian pound"
        },
        {
          "name": "ERN",
          "description": "Eritrean nakfa"
        },
        {
          "name": "ETB",
          "description": "Ethiopian birr"
        },
        {
          "name": "EUR",
          "description": "Euro"
        },
        {
          "name": "FJD",
          "description": "Fiji dollar"
        },
        {
          "name": "FKP",
          "description": "Falkland Islands pound"
        },
        {
          "name": "GBP",
          "description": "Pound sterling"
        },
        {
          "name": "GEL",
          "description": "Georgian lari"
        },
        {
          "name": "GHS",
          "description": "Ghanaian cedi"
        },
        {
          "name": "GIP",
          "description": "Gibraltar pound"
        },
        {
          "name": "GMD",
          "description": "Gambian dalasi"
        },
        {
          "name": "GNF",
          "description": "Guinean franc"
        },
        {
          "name": "GTQ",
          "description": "Guatemalan quetzal"
        },
        {
          "name": "GYD",
          "description": "Guyanese dollar"
        },
        {
          "name": "HKD",
          "description": "Hong Kong dollar"
        },
        {
          "name": "HNL",
          "description": "Honduran lempira"
        },
        {
          "name": "HRK",
          "description": "Croatian kuna"
        },
        {
          "name": "HTG",
          "description": "Haitian gourde"
        },
        {
          "name": "HUF",
          "description": "Hungarian forint"
        },
        {
          "name": "IDR",
          "description": "Indonesian rupiah"
        },
        {
          "name": "ILS",
          "description": "Israeli new shekel"
        },
        {
          "name": "INR",
          "description": "Indian rupee"
        },
        {
          "name": "IQD",
          "description": "Iraqi dinar"
        },
        {
          "name": "IRR",
          "description": "Iranian rial"
        },
        {
          "name": "ISK",
          "description": "Icelandic króna"
        },
        {
          "name": "JMD",
          "description": "Jamaican dollar"
        },
        {
          "name": "JOD",
          "description": "Jordanian dinar"
        },
        {
          "name": "JPY",
          "description": "Japanese yen"
        },
        {
          "name": "KES",
          "description": "Kenyan shilling"
        },
        {
          "name": "KGS",
          "description": "Kyrgyzstani som"
        },
        {
          "name": "KHR",
          "description": "Cambodian riel"
        },
        {
          "name": "KMF",
          "description": "Comoro franc"
        },
        {
          "name": "KPW",
          "description": "North Korean won"
        },
        {
          "name": "KRW",
          "description": "South Korean won"
        },
        {
          "name": "KWD",
          "description": "Kuwaiti dinar"
        },
        {
          "name": "KYD",
          "description": "Cayman Islands dollar"
        },
        {
          "name": "KZT",
          "description": "Kazakhstani tenge"
        },
        {
          "name": "LAK",
          "description": "Lao kip"
        },
        {
          "name": "LBP",
          "description": "Lebanese pound"
        },
        {
          "name": "LKR",
          "description": "Sri Lankan rupee"
        },
        {
          "name": "LRD",
          "description": "Liberian dollar"
        },
        {
          "name": "LSL",
          "description": "Lesotho loti"
        },
        {
          "name": "LTL",
          "description": "Lithuanian litas"
        },
        {
          "name": "LVL",
          "description": "Latvian lats"
        },
        {
          "name": "LYD",
          "description": "Libyan dinar"
        },
        {
          "name": "MAD",
          "description": "Moroccan dirham"
        },
        {
          "name": "MDL",
          "description": "Moldovan leu"
        },
        {
          "name": "MGA",
          "description": "Malagasy ariary"
        },
        {
          "name": "MKD",
          "description": "Macedonian denar"
        },
        {
          "name": "MMK",
          "description": "Myanmar kyat"
        },
        {
          "name": "MNT",
          "description": "Mongolian tögrög"
        },
        {
          "name": "MOP",
          "description": "Macanese pataca"
        },
        {
          "name": "MRO",
          "description": "Mauritanian ouguiya"
        },
        {
          "name": "MUR",
          "description": "Mauritian rupee"
        },
        {
          "name": "MVR",
          "description": "Maldivian rufiyaa"
        },
        {
          "name": "MWK",
          "description": "Malawian kwacha"
        },
        {
          "name": "MXN",
          "description": "Mexican peso"
        },
        {
          "name": "MXV",
          "description": "Mexican Unidad de Inversion"
        },
        {
          "name": "MYR",
          "description": "Malaysian ringgit"
        },
        {
          "name": "MZN",
          "description": "Mozambican metical"
        },
        {
          "name": "NAD",
          "description": "Namibian dollar"
        },
        {
          "name": "NGN",
          "description": "Nigerian naira"
        },
        {
          "name": "NIO",
          "description": "Nicaraguan córdoba"
        },
        {
          "name": "NOK",
          "description": "Norwegian krone"
        },
        {
          "name": "NPR",
          "description": "Nepalese rupee"
        },
        {
          "name": "NZD",
          "description": "New Zealand dollar"
        },
        {
          "name": "OMR",
          "description": "Omani rial"
        },
        {
          "name": "PAB",
          "description": "Panamanian balboa"
        },
        {
          "name": "PEN",
          "description": "Peruvian sol"
        },
        {
          "name": "PGK",
          "description": "Papua New Guinean kina"
        },
        {
          "name": "PHP",
          "description": "Philippine peso"
        },
        {
          "name": "PKR",
          "description": "Pakistani rupee"
        },
        {
          "name": "PLN",
          "description": "Polish zBoty"
        },
        {
          "name": "PYG",
          "description": "Paraguayan guaraní"
        },
        {
          "name": "QAR",
          "description": "Qatari riyal"
        },
        {
          "name": "RON",
          "description": "Romanian leu"
        },
        {
          "name": "RSD",
          "description": "Serbian dinar"
        },
        {
          "name": "RUB",
          "description": "Russian ruble"
        },
        {
          "name": "RWF",
          "description": "Rwandan franc"
        },
        {
          "name": "SAR",
          "description": "Saudi riyal"
        },
        {
          "name": "SBD",
          "description": "Solomon Islands dollar"
        },
        {
          "name": "SCR",
          "description": "Seychelles rupee"
        },
        {
          "name": "SDG",
          "description": "Sudanese pound"
        },
        {
          "name": "SEK",
          "description": "Swedish krona"
        },
        {
          "name": "SGD",
          "description": "Singapore dollar"
        },
        {
          "name": "SHP",
          "description": "Saint Helena pound"
        },
        {
          "name": "SLL",
          "description": "Sierra Leonean first leone"
        },
        {
          "name": "SLE",
          "description": "Sierra Leonean second leone"
        },
        {
          "name": "SOS",
          "description": "Somali shilling"
        },
        {
          "name": "SRD",
          "description": "Surinamese dollar"
        },
        {
          "name": "SSP",
          "description": "South Sudanese pound"
        },
        {
          "name": "STD",
          "description": "São Tomé and Príncipe dobra"
        },
        {
          "name": "SVC",
          "description": "Salvadoran colón"
        },
        {
          "name": "SYP",
          "description": "Syrian pound"
        },
        {
          "name": "SZL",
          "description": "Swazi lilangeni"
        },
        {
          "name": "THB",
          "description": "Thai baht"
        },
        {
          "name": "TJS",
          "description": "Tajikstani somoni"
        },
        {
          "name": "TMT",
          "description": "Turkmenistan manat"
        },
        {
          "name": "TND",
          "description": "Tunisian dinar"
        },
        {
          "name": "TOP",
          "description": "Tongan pa'anga"
        },
        {
          "name": "TRY",
          "description": "Turkish lira"
        },
        {
          "name": "TTD",
          "description": "Trinidad and Tobago dollar"
        },
        {
          "name": "TWD",
          "description": "New Taiwan dollar"
        },
        {
          "name": "TZS",
          "description": "Tanzanian shilling"
        },
        {
          "name": "UAH",
          "description": "Ukrainian hryvnia"
        },
        {
          "name": "UGX",
          "description": "Ugandan shilling"
        },
        {
          "name": "USD",
          "description": "United States dollar"
        },
        {
          "name": "USN",
          "description": "United States dollar (next day)"
        },
        {
          "name": "USS",
          "description": "United States dollar (same day)"
        },
        {
          "name": "UYI",
          "description": "Uruguay Peso en Unidedades Indexadas"
        },
        {
          "name": "UYU",
          "description": "Uruguyan peso"
        },
        {
          "name": "UZS",
          "description": "Uzbekistan som"
        },
        {
          "name": "VEF",
          "description": "Venezuelan bolívar soberano"
        },
        {
          "name": "VND",
          "description": "Vietnamese ’Óng"
        },
        {
          "name": "VUV",
          "description": "Vanuatu vatu"
        },
        {
          "name": "WST",
          "description": "Samoan tala"
        },
        {
          "name": "XAF",
          "description": "CFA franc BEAC"
        },
        {
          "name": "XAG",
          "description": "Silver"
        },
        {
          "name": "XAU",
          "description": "Gold"
        },
        {
          "name": "XBA",
          "description": "European Composite Unit"
        },
        {
          "name": "XBB",
          "description": "European Monetary Unit"
        },
        {
          "name": "XBC",
          "description": "European Unit of Account 9"
        },
        {
          "name": "XBD",
          "description": "European Unit of Account 17"
        },
        {
          "name": "XCD",
          "description": "East Caribbean dollar"
        },
        {
          "name": "XDR",
          "description": "Special drawing rights (International Monetary Fund)"
        },
        {
          "name": "XOF",
          "description": "CFA franc BCEAO"
        },
        {
          "name": "XPD",
          "description": "Palladium"
        },
        {
          "name": "XPF",
          "description": "CFP franc"
        },
        {
          "name": "XPT",
          "description": "Platinum"
        },
        {
          "name": "XTS",
          "description": "Code reserved for testing"
        },
        {
          "name": "XXX",
          "description": "No currency"
        },
        {
          "name": "YER",
          "description": "Yemeni rial"
        },
        {
          "name": "ZAR",
          "description": "South African rand"
        },
        {
          "name": "ZMK",
          "description": "Zambian kwacha"
        },
        {
          "name": "ZMW",
          "description": "Zambian kwacha"
        },
        {
          "name": "BTC",
          "description": "Bitcoin"
        },
        {
          "name": "XUS",
          "description": "USD Coin"
        }
      ],
      "description": "Indicates the associated currency for an amount of money. Values correspond\nto [ISO 4217](https://wikipedia.org/wiki/ISO_4217).",
      "x-release-status": "PUBLIC"
    },
    "Money": {
      "type": "object",
      "description": "Represents an amount of money. `Money` fields can be signed or unsigned.\nFields that do not explicitly define whether they are signed or unsigned are\nconsidered unsigned and can only hold positive amounts. For signed fields, the\nsign of the value indicates the purpose of the money transfer. See\n[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts)\nfor more information.",
      "x-release-status": "PUBLIC",
      "properties": {
        "amount": {
          "type": [
            "integer",
            "null"
          ],
          "description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case.",
          "format": "int64"
        },
        "currency": {
          "$ref": "#/$defs/Currency",
          "description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\nSee [Currency](entity:Currency) for possible values.\nSee [Currency](#type-currency) for possible values"
        }
      }
    },
    "Phase": {
      "type": "object",
      "description": "Represents a phase, which can override subscription phases as defined by plan_id",
      "x-release-status": "PUBLIC",
      "properties": {
        "uid": {
          "type": [
            "string",
            "null"
          ],
          "description": "id of subscription phase"
        },
        "ordinal": {
          "type": [
            "integer",
            "null"
          ],
          "description": "index of phase in total subscription plan",
          "format": "int64"
        },
        "order_template_id": {
          "type": [
            "string",
            "null"
          ],
          "description": "id of order to be used in billing"
        },
        "plan_phase_uid": {
          "type": [
            "string",
            "null"
          ],
          "description": "the uid from the plan's phase in catalog"
        }
      }
    },
    "SubscriptionSource": {
      "type": "object",
      "description": "The origination details of the subscription.",
      "x-release-status": "BETA",
      "properties": {
        "name": {
          "type": [
            "string",
            "null"
          ],
          "description": "The name used to identify the place (physical or digital) that\na subscription originates. If unset, the name defaults to the name\nof the application that created the subscription.",
          "maxLength": 255
        }
      }
    }
  }
}