{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/api-evangelist/square/main/json-schema/square-create-order-response-schema.json", "title": "CreateOrderResponse", "description": "Defines the fields that are included in the response body of\na request to the `CreateOrder` endpoint.\n\nEither `errors` or `order` is present in a given response, but never both.", "x-generated": "2026-10-12", "x-method": "derived", "x-generator": "derive-json-schema.py", "x-source": "openapi/square-orders-api-openapi.yml#/components/schemas/CreateOrderResponse", "type": "object", "x-release-status": "PUBLIC", "properties": { "order": { "$ref": "#/$defs/Order", "description": "The newly created order." }, "errors": { "type": "array", "items": { "$ref": "#/$defs/Error" }, "description": "Any errors that occurred during the request." } }, "$defs": { "AdditionalRecipient": { "type": "object", "description": "Represents an additional recipient (other than the merchant) receiving a portion of this tender.", "x-release-status": "DEPRECATED", "required": [ "location_id", "amount_money" ], "properties": { "location_id": { "type": "string", "description": "The location ID for a recipient (other than the merchant) receiving a portion of this tender.", "minLength": 1, "maxLength": 50 }, "description": { "type": [ "string", "null" ], "description": "The description of the additional recipient.", "maxLength": 100 }, "amount_money": { "$ref": "#/$defs/Money", "description": "The amount of money distributed to the recipient." }, "receivable_id": { "type": [ "string", "null" ], "description": "The unique ID for the RETIRED `AdditionalRecipientReceivable` object. This field should be empty for any `AdditionalRecipient` objects created after the retirement.", "maxLength": 192 } } }, "Address": { "type": "object", "description": "Represents a postal address in a country. \nFor more information, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "x-release-status": "PUBLIC", "properties": { "address_line_1": { "type": [ "string", "null" ], "description": "The first line of the address.\n\nFields that start with `address_line` provide the address's most specific\ndetails, like street number, street name, and building name. They do *not*\nprovide less specific details like city, state/province, or country (these\ndetails are provided in other fields)." }, "address_line_2": { "type": [ "string", "null" ], "description": "The second line of the address, if any." }, "address_line_3": { "type": [ "string", "null" ], "description": "The third line of the address, if any." }, "locality": { "type": [ "string", "null" ], "description": "The city or town of the address. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses)." }, "sublocality": { "type": [ "string", "null" ], "description": "A civil region within the address's `locality`, if any." }, "sublocality_2": { "type": [ "string", "null" ], "description": "A civil region within the address's `sublocality`, if any." }, "sublocality_3": { "type": [ "string", "null" ], "description": "A civil region within the address's `sublocality_2`, if any." }, "administrative_district_level_1": { "type": [ "string", "null" ], "description": "A civil entity within the address's country. In the US, this\nis the state. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses)." }, "administrative_district_level_2": { "type": [ "string", "null" ], "description": "A civil entity within the address's `administrative_district_level_1`.\nIn the US, this is the county." }, "administrative_district_level_3": { "type": [ "string", "null" ], "description": "A civil entity within the address's `administrative_district_level_2`,\nif any." }, "postal_code": { "type": [ "string", "null" ], "description": "The address's postal code. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses)." }, "country": { "$ref": "#/$defs/Country", "description": "The address's country, in the two-letter format of ISO 3166. For example, `US` or `FR`.\nSee [Country](#type-country) for possible values" }, "first_name": { "type": [ "string", "null" ], "description": "Optional first name when it's representing recipient." }, "last_name": { "type": [ "string", "null" ], "description": "Optional last name when it's representing recipient." } } }, "Card": { "type": "object", "description": "Represents the payment details of a card to be used for payments. These\ndetails are determined by the payment token generated by Web Payments SDK.", "x-release-status": "PUBLIC", "properties": { "id": { "type": "string", "description": "Unique ID for this card. Generated by Square.", "maxLength": 64, "readOnly": true }, "card_brand": { "$ref": "#/$defs/CardBrand", "description": "The card's brand.\nSee [CardBrand](#type-cardbrand) for possible values", "readOnly": true }, "last_4": { "type": "string", "description": "The last 4 digits of the card number.", "maxLength": 4, "readOnly": true }, "exp_month": { "type": [ "integer", "null" ], "description": "The expiration month of the associated card as an integer between 1 and 12.", "format": "int64" }, "exp_year": { "type": [ "integer", "null" ], "description": "The four-digit year of the card's expiration date.", "format": "int64" }, "cardholder_name": { "type": [ "string", "null" ], "description": "The name of the cardholder.", "maxLength": 96 }, "billing_address": { "$ref": "#/$defs/Address", "description": "The billing address for this card." }, "fingerprint": { "type": "string", "description": "Intended as a Square-assigned identifier, based\non the card number, to identify the card across multiple locations within a\nsingle application.", "maxLength": 255, "readOnly": true }, "customer_id": { "type": [ "string", "null" ], "description": "**Required** The ID of a customer created using the Customers API to be associated with the card." }, "merchant_id": { "type": "string", "description": "The ID of the merchant associated with the card.", "readOnly": true }, "reference_id": { "type": [ "string", "null" ], "description": "An optional user-defined reference ID that associates this card with\nanother entity in an external system. For example, a customer ID from an\nexternal customer management system.", "maxLength": 128 }, "enabled": { "type": "boolean", "description": "Indicates whether or not a card can be used for payments.", "readOnly": true }, "card_type": { "$ref": "#/$defs/CardType", "description": "The type of the card.\nThe Card object includes this field only in response to Payments API calls.\nSee [CardType](#type-cardtype) for possible values", "readOnly": true }, "prepaid_type": { "$ref": "#/$defs/CardPrepaidType", "description": "Indicates whether the Card is prepaid or not.\nThe Card object includes this field only in response to Payments API calls.\nSee [CardPrepaidType](#type-cardprepaidtype) for possible values", "readOnly": true }, "bin": { "type": "string", "description": "The first six digits of the card number, known as the Bank Identification Number (BIN). Only the Payments API\nreturns this field.", "maxLength": 6, "readOnly": true }, "version": { "type": "integer", "description": "Current version number of the card. Increments with each card update. Requests to update an\nexisting Card object will be rejected unless the version in the request matches the current\nversion for the Card.", "format": "int64" }, "card_co_brand": { "$ref": "#/$defs/CardCoBrand", "description": "The card's co-brand if available. For example, an Afterpay virtual card would have a\nco-brand of AFTERPAY.\nSee [CardCoBrand](#type-cardcobrand) for possible values", "readOnly": true } } }, "CardBrand": { "type": "string", "enum": [ "OTHER_BRAND", "VISA", "MASTERCARD", "AMERICAN_EXPRESS", "DISCOVER", "DISCOVER_DINERS", "JCB", "CHINA_UNIONPAY", "SQUARE_GIFT_CARD", "SQUARE_CAPITAL_CARD", "INTERAC", "EFTPOS", "FELICA", "EBT" ], "x-enum-elements": [ { "name": "OTHER_BRAND", "description": "" }, { "name": "VISA", "description": "" }, { "name": "MASTERCARD", "description": "" }, { "name": "AMERICAN_EXPRESS", "description": "" }, { "name": "DISCOVER", "description": "" }, { "name": "DISCOVER_DINERS", "description": "" }, { "name": "JCB", "description": "" }, { "name": "CHINA_UNIONPAY", "description": "" }, { "name": "SQUARE_GIFT_CARD", "description": "" }, { "name": "SQUARE_CAPITAL_CARD", "description": "" }, { "name": "INTERAC", "description": "" }, { "name": "EFTPOS", "description": "" }, { "name": "FELICA", "description": "" }, { "name": "EBT", "description": "" } ], "description": "Indicates a card's brand, such as `VISA` or `MASTERCARD`.", "x-release-status": "PUBLIC" }, "CardCoBrand": { "type": "string", "enum": [ "UNKNOWN", "AFTERPAY", "CLEARPAY" ], "x-enum-elements": [ { "name": "UNKNOWN", "description": "" }, { "name": "AFTERPAY", "description": "" }, { "name": "CLEARPAY", "description": "" } ], "description": "Indicates the brand for a co-branded card.", "x-release-status": "PUBLIC" }, "CardPrepaidType": { "type": "string", "enum": [ "UNKNOWN_PREPAID_TYPE", "NOT_PREPAID", "PREPAID" ], "x-enum-elements": [ { "name": "UNKNOWN_PREPAID_TYPE", "description": "" }, { "name": "NOT_PREPAID", "description": "" }, { "name": "PREPAID", "description": "" } ], "description": "Indicates a card's prepaid type, such as `NOT_PREPAID` or `PREPAID`.", "x-release-status": "PUBLIC" }, "CardType": { "type": "string", "enum": [ "UNKNOWN_CARD_TYPE", "CREDIT", "DEBIT" ], "x-enum-elements": [ { "name": "UNKNOWN_CARD_TYPE", "description": "" }, { "name": "CREDIT", "description": "" }, { "name": "DEBIT", "description": "" } ], "description": "Indicates a card's type, such as `CREDIT` or `DEBIT`.", "x-release-status": "PUBLIC" }, "Country": { "type": "string", "enum": [ "ZZ", "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW" ], "x-enum-elements": [ { "name": "ZZ", "description": "Unknown" }, { "name": "AD", "description": "Andorra" }, { "name": "AE", "description": "United Arab Emirates" }, { "name": "AF", "description": "Afghanistan" }, { "name": "AG", "description": "Antigua and Barbuda" }, { "name": "AI", "description": "Anguilla" }, { "name": "AL", "description": "Albania" }, { "name": "AM", "description": "Armenia" }, { "name": "AO", "description": "Angola" }, { "name": "AQ", "description": "Antartica" }, { "name": "AR", "description": "Argentina" }, { "name": "AS", "description": "American Samoa" }, { "name": "AT", "description": "Austria" }, { "name": "AU", "description": "Australia" }, { "name": "AW", "description": "Aruba" }, { "name": "AX", "description": "Åland Islands" }, { "name": "AZ", "description": "Azerbaijan" }, { "name": "BA", "description": "Bosnia and Herzegovina" }, { "name": "BB", "description": "Barbados" }, { "name": "BD", "description": "Bangladesh" }, { "name": "BE", "description": "Belgium" }, { "name": "BF", "description": "Burkina Faso" }, { "name": "BG", "description": "Bulgaria" }, { "name": "BH", "description": "Bahrain" }, { "name": "BI", "description": "Burundi" }, { "name": "BJ", "description": "Benin" }, { "name": "BL", "description": "Saint Barthélemy" }, { "name": "BM", "description": "Bermuda" }, { "name": "BN", "description": "Brunei" }, { "name": "BO", "description": "Bolivia" }, { "name": "BQ", "description": "Bonaire" }, { "name": "BR", "description": "Brazil" }, { "name": "BS", "description": "Bahamas" }, { "name": "BT", "description": "Bhutan" }, { "name": "BV", "description": "Bouvet Island" }, { "name": "BW", "description": "Botswana" }, { "name": "BY", "description": "Belarus" }, { "name": "BZ", "description": "Belize" }, { "name": "CA", "description": "Canada" }, { "name": "CC", "description": "Cocos Islands" }, { "name": "CD", "description": "Democratic Republic of the Congo" }, { "name": "CF", "description": "Central African Republic" }, { "name": "CG", "description": "Congo" }, { "name": "CH", "description": "Switzerland" }, { "name": "CI", "description": "Ivory Coast" }, { "name": "CK", "description": "Cook Islands" }, { "name": "CL", "description": "Chile" }, { "name": "CM", "description": "Cameroon" }, { "name": "CN", "description": "China" }, { "name": "CO", "description": "Colombia" }, { "name": "CR", "description": "Costa Rica" }, { "name": "CU", "description": "Cuba" }, { "name": "CV", "description": "Cabo Verde" }, { "name": "CW", "description": "Curaçao" }, { "name": "CX", "description": "Christmas Island" }, { "name": "CY", "description": "Cyprus" }, { "name": "CZ", "description": "Czechia" }, { "name": "DE", "description": "Germany" }, { "name": "DJ", "description": "Djibouti" }, { "name": "DK", "description": "Denmark" }, { "name": "DM", "description": "Dominica" }, { "name": "DO", "description": "Dominican Republic" }, { "name": "DZ", "description": "Algeria" }, { "name": "EC", "description": "Ecuador" }, { "name": "EE", "description": "Estonia" }, { "name": "EG", "description": "Egypt" }, { "name": "EH", "description": "Western Sahara" }, { "name": "ER", "description": "Eritrea" }, { "name": "ES", "description": "Spain" }, { "name": "ET", "description": "Ethiopia" }, { "name": "FI", "description": "Finland" }, { "name": "FJ", "description": "Fiji" }, { "name": "FK", "description": "Falkland Islands" }, { "name": "FM", "description": "Federated States of Micronesia" }, { "name": "FO", "description": "Faroe Islands" }, { "name": "FR", "description": "France" }, { "name": "GA", "description": "Gabon" }, { "name": "GB", "description": "United Kingdom" }, { "name": "GD", "description": "Grenada" }, { "name": "GE", "description": "Georgia" }, { "name": "GF", "description": "French Guiana" }, { "name": "GG", "description": "Guernsey" }, { "name": "GH", "description": "Ghana" }, { "name": "GI", "description": "Gibraltar" }, { "name": "GL", "description": "Greenland" }, { "name": "GM", "description": "Gambia" }, { "name": "GN", "description": "Guinea" }, { "name": "GP", "description": "Guadeloupe" }, { "name": "GQ", "description": "Equatorial Guinea" }, { "name": "GR", "description": "Greece" }, { "name": "GS", "description": "South Georgia and the South Sandwich Islands" }, { "name": "GT", "description": "Guatemala" }, { "name": "GU", "description": "Guam" }, { "name": "GW", "description": "Guinea-Bissau" }, { "name": "GY", "description": "Guyana" }, { "name": "HK", "description": "Hong Kong" }, { "name": "HM", "description": "Heard Island and McDonald Islands" }, { "name": "HN", "description": "Honduras" }, { "name": "HR", "description": "Croatia" }, { "name": "HT", "description": "Haiti" }, { "name": "HU", "description": "Hungary" }, { "name": "ID", "description": "Indonesia" }, { "name": "IE", "description": "Ireland" }, { "name": "IL", "description": "Israel" }, { "name": "IM", "description": "Isle of Man" }, { "name": "IN", "description": "India" }, { "name": "IO", "description": "British Indian Ocean Territory" }, { "name": "IQ", "description": "Iraq" }, { "name": "IR", "description": "Iran" }, { "name": "IS", "description": "Iceland" }, { "name": "IT", "description": "Italy" }, { "name": "JE", "description": "Jersey" }, { "name": "JM", "description": "Jamaica" }, { "name": "JO", "description": "Jordan" }, { "name": "JP", "description": "Japan" }, { "name": "KE", "description": "Kenya" }, { "name": "KG", "description": "Kyrgyzstan" }, { "name": "KH", "description": "Cambodia" }, { "name": "KI", "description": "Kiribati" }, { "name": "KM", "description": "Comoros" }, { "name": "KN", "description": "Saint Kitts and Nevis" }, { "name": "KP", "description": "Democratic People's Republic of Korea" }, { "name": "KR", "description": "Republic of Korea" }, { "name": "KW", "description": "Kuwait" }, { "name": "KY", "description": "Cayman Islands" }, { "name": "KZ", "description": "Kazakhstan" }, { "name": "LA", "description": "Lao People's Democratic Republic" }, { "name": "LB", "description": "Lebanon" }, { "name": "LC", "description": "Saint Lucia" }, { "name": "LI", "description": "Liechtenstein" }, { "name": "LK", "description": "Sri Lanka" }, { "name": "LR", "description": "Liberia" }, { "name": "LS", "description": "Lesotho" }, { "name": "LT", "description": "Lithuania" }, { "name": "LU", "description": "Luxembourg" }, { "name": "LV", "description": "Latvia" }, { "name": "LY", "description": "Libya" }, { "name": "MA", "description": "Morocco" }, { "name": "MC", "description": "Monaco" }, { "name": "MD", "description": "Moldova" }, { "name": "ME", "description": "Montenegro" }, { "name": "MF", "description": "Saint Martin" }, { "name": "MG", "description": "Madagascar" }, { "name": "MH", "description": "Marshall Islands" }, { "name": "MK", "description": "North Macedonia" }, { "name": "ML", "description": "Mali" }, { "name": "MM", "description": "Myanmar" }, { "name": "MN", "description": "Mongolia" }, { "name": "MO", "description": "Macao" }, { "name": "MP", "description": "Northern Mariana Islands" }, { "name": "MQ", "description": "Martinique" }, { "name": "MR", "description": "Mauritania" }, { "name": "MS", "description": "Montserrat" }, { "name": "MT", "description": "Malta" }, { "name": "MU", "description": "Mauritius" }, { "name": "MV", "description": "Maldives" }, { "name": "MW", "description": "Malawi" }, { "name": "MX", "description": "Mexico" }, { "name": "MY", "description": "Malaysia" }, { "name": "MZ", "description": "Mozambique" }, { "name": "NA", "description": "Namibia" }, { "name": "NC", "description": "New Caledonia" }, { "name": "NE", "description": "Niger" }, { "name": "NF", "description": "Norfolk Island" }, { "name": "NG", "description": "Nigeria" }, { "name": "NI", "description": "Nicaragua" }, { "name": "NL", "description": "Netherlands" }, { "name": "NO", "description": "Norway" }, { "name": "NP", "description": "Nepal" }, { "name": "NR", "description": "Nauru" }, { "name": "NU", "description": "Niue" }, { "name": "NZ", "description": "New Zealand" }, { "name": "OM", "description": "Oman" }, { "name": "PA", "description": "Panama" }, { "name": "PE", "description": "Peru" }, { "name": "PF", "description": "French Polynesia" }, { "name": "PG", "description": "Papua New Guinea" }, { "name": "PH", "description": "Philippines" }, { "name": "PK", "description": "Pakistan" }, { "name": "PL", "description": "Poland" }, { "name": "PM", "description": "Saint Pierre and Miquelon" }, { "name": "PN", "description": "Pitcairn" }, { "name": "PR", "description": "Puerto Rico" }, { "name": "PS", "description": "Palestine" }, { "name": "PT", "description": "Portugal" }, { "name": "PW", "description": "Palau" }, { "name": "PY", "description": "Paraguay" }, { "name": "QA", "description": "Qatar" }, { "name": "RE", "description": "Réunion" }, { "name": "RO", "description": "Romania" }, { "name": "RS", "description": "Serbia" }, { "name": "RU", "description": "Russia" }, { "name": "RW", "description": "Rwanda" }, { "name": "SA", "description": "Saudi Arabia" }, { "name": "SB", "description": "Solomon Islands" }, { "name": "SC", "description": "Seychelles" }, { "name": "SD", "description": "Sudan" }, { "name": "SE", "description": "Sweden" }, { "name": "SG", "description": "Singapore" }, { "name": "SH", "description": "Saint Helena, Ascension and Tristan da Cunha" }, { "name": "SI", "description": "Slovenia" }, { "name": "SJ", "description": "Svalbard and Jan Mayen" }, { "name": "SK", "description": "Slovakia" }, { "name": "SL", "description": "Sierra Leone" }, { "name": "SM", "description": "San Marino" }, { "name": "SN", "description": "Senegal" }, { "name": "SO", "description": "Somalia" }, { "name": "SR", "description": "Suriname" }, { "name": "SS", "description": "South Sudan" }, { "name": "ST", "description": "Sao Tome and Principe" }, { "name": "SV", "description": "El Salvador" }, { "name": "SX", "description": "Sint Maarten" }, { "name": "SY", "description": "Syrian Arab Republic" }, { "name": "SZ", "description": "Eswatini" }, { "name": "TC", "description": "Turks and Caicos Islands" }, { "name": "TD", "description": "Chad" }, { "name": "TF", "description": "French Southern Territories" }, { "name": "TG", "description": "Togo" }, { "name": "TH", "description": "Thailand" }, { "name": "TJ", "description": "Tajikistan" }, { "name": "TK", "description": "Tokelau" }, { "name": "TL", "description": "Timor-Leste" }, { "name": "TM", "description": "Turkmenistan" }, { "name": "TN", "description": "Tunisia" }, { "name": "TO", "description": "Tonga" }, { "name": "TR", "description": "Turkey" }, { "name": "TT", "description": "Trinidad and Tobago" }, { "name": "TV", "description": "Tuvalu" }, { "name": "TW", "description": "Taiwan" }, { "name": "TZ", "description": "Tanzania" }, { "name": "UA", "description": "Ukraine" }, { "name": "UG", "description": "Uganda" }, { "name": "UM", "description": "United States Minor Outlying Islands" }, { "name": "US", "description": "United States of America" }, { "name": "UY", "description": "Uruguay" }, { "name": "UZ", "description": "Uzbekistan" }, { "name": "VA", "description": "Vatican City" }, { "name": "VC", "description": "Saint Vincent and the Grenadines" }, { "name": "VE", "description": "Venezuela" }, { "name": "VG", "description": "British Virgin Islands" }, { "name": "VI", "description": "U.S. Virgin Islands" }, { "name": "VN", "description": "Vietnam" }, { "name": "VU", "description": "Vanuatu" }, { "name": "WF", "description": "Wallis and Futuna" }, { "name": "WS", "description": "Samoa" }, { "name": "YE", "description": "Yemen" }, { "name": "YT", "description": "Mayotte" }, { "name": "ZA", "description": "South Africa" }, { "name": "ZM", "description": "Zambia" }, { "name": "ZW", "description": "Zimbabwe" } ], "description": "Indicates the country associated with another entity, such as a business.\nValues are in [ISO 3166-1-alpha-2 format](http://www.iso.org/iso/home/standards/country_codes.htm).", "x-release-status": "PUBLIC" }, "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" }, "Error": { "type": "object", "description": "Represents an error encountered during a request to the Connect API.\n\nSee [Handling errors](https://developer.squareup.com/docs/build-basics/handling-errors) for more information.", "x-release-status": "PUBLIC", "required": [ "category", "code" ], "properties": { "category": { "$ref": "#/$defs/ErrorCategory", "description": "The high-level category for the error.\nSee [ErrorCategory](#type-errorcategory) for possible values" }, "code": { "$ref": "#/$defs/ErrorCode", "description": "The specific code of the error.\nSee [ErrorCode](#type-errorcode) for possible values" }, "detail": { "type": "string", "description": "A human-readable description of the error for debugging purposes." }, "field": { "type": "string", "description": "The name of the field provided in the original request (if any) that\nthe error pertains to." } } }, "ErrorCategory": { "type": "string", "enum": [ "API_ERROR", "AUTHENTICATION_ERROR", "INVALID_REQUEST_ERROR", "RATE_LIMIT_ERROR", "PAYMENT_METHOD_ERROR", "REFUND_ERROR", "MERCHANT_SUBSCRIPTION_ERROR", "EXTERNAL_VENDOR_ERROR" ], "x-enum-elements": [ { "name": "API_ERROR", "description": "An error occurred with the Connect API itself." }, { "name": "AUTHENTICATION_ERROR", "description": "An authentication error occurred. Most commonly, the request had\na missing, malformed, or otherwise invalid `Authorization` header." }, { "name": "INVALID_REQUEST_ERROR", "description": "The request was invalid. Most commonly, a required parameter was\nmissing, or a provided parameter had an invalid value." }, { "name": "RATE_LIMIT_ERROR", "description": "Your application reached the Square API rate limit. You might receive this error if your application sends a high number of requests\nto Square APIs in a short period of time.\n\nYour application should monitor responses for `429 RATE_LIMITED` errors and use a retry mechanism with an [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff)\nschedule to resend the requests at an increasingly slower rate. It is also a good practice to use a randomized delay (jitter) in your retry schedule." }, { "name": "PAYMENT_METHOD_ERROR", "description": "An error occurred while processing a payment method. Most commonly,\nthe details of the payment method were invalid (such as a card's CVV\nor expiration date)." }, { "name": "REFUND_ERROR", "description": "An error occurred while attempting to process a refund." }, { "name": "MERCHANT_SUBSCRIPTION_ERROR", "description": "An error occurred when checking a merchant subscription status" }, { "name": "EXTERNAL_VENDOR_ERROR", "description": "An error that is returned from an external vendor's API" } ], "description": "Indicates which high-level category of error has occurred during a\nrequest to the Connect API.", "x-release-status": "PUBLIC" }, "ErrorCode": { "type": "string", "enum": [ "INTERNAL_SERVER_ERROR", "UNAUTHORIZED", "ACCESS_TOKEN_EXPIRED", "ACCESS_TOKEN_REVOKED", "CLIENT_DISABLED", "FORBIDDEN", "INSUFFICIENT_SCOPES", "APPLICATION_DISABLED", "V1_APPLICATION", "V1_ACCESS_TOKEN", "CARD_PROCESSING_NOT_ENABLED", "MERCHANT_SUBSCRIPTION_NOT_FOUND", "BAD_REQUEST", "MISSING_REQUIRED_PARAMETER", "INCORRECT_TYPE", "INVALID_TIME", "INVALID_TIME_RANGE", "INVALID_VALUE", "INVALID_CURSOR", "UNKNOWN_QUERY_PARAMETER", "CONFLICTING_PARAMETERS", "EXPECTED_JSON_BODY", "INVALID_SORT_ORDER", "VALUE_REGEX_MISMATCH", "VALUE_TOO_SHORT", "VALUE_TOO_LONG", "VALUE_TOO_LOW", "VALUE_TOO_HIGH", "VALUE_EMPTY", "ARRAY_LENGTH_TOO_LONG", "ARRAY_LENGTH_TOO_SHORT", "ARRAY_EMPTY", "EXPECTED_BOOLEAN", "EXPECTED_INTEGER", "EXPECTED_FLOAT", "EXPECTED_STRING", "EXPECTED_OBJECT", "EXPECTED_ARRAY", "EXPECTED_MAP", "EXPECTED_BASE64_ENCODED_BYTE_ARRAY", "INVALID_ARRAY_VALUE", "INVALID_ENUM_VALUE", "INVALID_CONTENT_TYPE", "INVALID_FORM_VALUE", "CUSTOMER_NOT_FOUND", "ONE_INSTRUMENT_EXPECTED", "NO_FIELDS_SET", "TOO_MANY_MAP_ENTRIES", "MAP_KEY_LENGTH_TOO_SHORT", "MAP_KEY_LENGTH_TOO_LONG", "CUSTOMER_MISSING_NAME", "CUSTOMER_MISSING_EMAIL", "INVALID_PAUSE_LENGTH", "INVALID_DATE", "UNSUPPORTED_COUNTRY", "UNSUPPORTED_CURRENCY", "APPLE_TTP_PIN_TOKEN", "CARD_EXPIRED", "INVALID_EXPIRATION", "INVALID_EXPIRATION_YEAR", "INVALID_EXPIRATION_DATE", "UNSUPPORTED_CARD_BRAND", "UNSUPPORTED_ENTRY_METHOD", "INVALID_ENCRYPTED_CARD", "INVALID_CARD", "PAYMENT_AMOUNT_MISMATCH", "GENERIC_DECLINE", "CVV_FAILURE", "ADDRESS_VERIFICATION_FAILURE", "INVALID_ACCOUNT", "CURRENCY_MISMATCH", "INSUFFICIENT_FUNDS", "INSUFFICIENT_PERMISSIONS", "CARDHOLDER_INSUFFICIENT_PERMISSIONS", "INVALID_LOCATION", "TRANSACTION_LIMIT", "VOICE_FAILURE", "PAN_FAILURE", "EXPIRATION_FAILURE", "CARD_NOT_SUPPORTED", "INVALID_PIN", "MISSING_PIN", "MISSING_ACCOUNT_TYPE", "INVALID_POSTAL_CODE", "INVALID_FEES", "MANUALLY_ENTERED_PAYMENT_NOT_SUPPORTED", "PAYMENT_LIMIT_EXCEEDED", "GIFT_CARD_AVAILABLE_AMOUNT", "ACCOUNT_UNUSABLE", "BUYER_REFUSED_PAYMENT", "DELAYED_TRANSACTION_EXPIRED", "DELAYED_TRANSACTION_CANCELED", "DELAYED_TRANSACTION_CAPTURED", "DELAYED_TRANSACTION_FAILED", "CARD_TOKEN_EXPIRED", "CARD_TOKEN_USED", "AMOUNT_TOO_HIGH", "UNSUPPORTED_INSTRUMENT_TYPE", "REFUND_AMOUNT_INVALID", "REFUND_ALREADY_PENDING", "PAYMENT_NOT_REFUNDABLE", "PAYMENT_NOT_REFUNDABLE_DUE_TO_DISPUTE", "REFUND_DECLINED", "INSUFFICIENT_PERMISSIONS_FOR_REFUND", "INVALID_CARD_DATA", "SOURCE_USED", "SOURCE_EXPIRED", "UNSUPPORTED_LOYALTY_REWARD_TIER", "LOCATION_MISMATCH", "IDEMPOTENCY_KEY_REUSED", "UNEXPECTED_VALUE", "SANDBOX_NOT_SUPPORTED", "INVALID_EMAIL_ADDRESS", "INVALID_PHONE_NUMBER", "CHECKOUT_EXPIRED", "BAD_CERTIFICATE", "INVALID_SQUARE_VERSION_FORMAT", "API_VERSION_INCOMPATIBLE", "CARD_PRESENCE_REQUIRED", "UNSUPPORTED_SOURCE_TYPE", "CARD_MISMATCH", "PLAID_ERROR", "PLAID_ERROR_ITEM_LOGIN_REQUIRED", "PLAID_ERROR_RATE_LIMIT", "CARD_DECLINED", "VERIFY_CVV_FAILURE", "VERIFY_AVS_FAILURE", "CARD_DECLINED_CALL_ISSUER", "CARD_DECLINED_VERIFICATION_REQUIRED", "BAD_EXPIRATION", "CHIP_INSERTION_REQUIRED", "ALLOWABLE_PIN_TRIES_EXCEEDED", "RESERVATION_DECLINED", "UNKNOWN_BODY_PARAMETER", "NOT_FOUND", "APPLE_PAYMENT_PROCESSING_CERTIFICATE_HASH_NOT_FOUND", "METHOD_NOT_ALLOWED", "NOT_ACCEPTABLE", "REQUEST_TIMEOUT", "CONFLICT", "GONE", "REQUEST_ENTITY_TOO_LARGE", "UNSUPPORTED_MEDIA_TYPE", "UNPROCESSABLE_ENTITY", "RATE_LIMITED", "NOT_IMPLEMENTED", "BAD_GATEWAY", "SERVICE_UNAVAILABLE", "TEMPORARY_ERROR", "GATEWAY_TIMEOUT" ], "x-enum-elements": [ { "name": "INTERNAL_SERVER_ERROR", "description": "A general server error occurred.", "error-category": "API_ERROR" }, { "name": "UNAUTHORIZED", "description": "A general authorization error occurred.", "error-category": "AUTHENTICATION_ERROR" }, { "name": "ACCESS_TOKEN_EXPIRED", "description": "The provided access token has expired.", "error-category": "AUTHENTICATION_ERROR" }, { "name": "ACCESS_TOKEN_REVOKED", "description": "The provided access token has been revoked.", "error-category": "AUTHENTICATION_ERROR" }, { "name": "CLIENT_DISABLED", "description": "The provided client has been disabled.", "error-category": "AUTHENTICATION_ERROR" }, { "name": "FORBIDDEN", "description": "A general access error occurred.", "error-category": "AUTHENTICATION_ERROR" }, { "name": "INSUFFICIENT_SCOPES", "description": "The provided access token does not have permission\nto execute the requested action.", "error-category": "AUTHENTICATION_ERROR" }, { "name": "APPLICATION_DISABLED", "description": "The calling application was disabled.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "V1_APPLICATION", "description": "The calling application was created prior to\n2016-03-30 and is not compatible with v2 Square API calls.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "V1_ACCESS_TOKEN", "description": "The calling application is using an access token\ncreated prior to 2016-03-30 and is not compatible with v2 Square API\ncalls.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "CARD_PROCESSING_NOT_ENABLED", "description": "The location provided in the API call is not\nenabled for credit card processing.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "MERCHANT_SUBSCRIPTION_NOT_FOUND", "description": "A required subscription was not found for the merchant", "error-category": "MERCHANT_SUBSCRIPTION_ERROR" }, { "name": "BAD_REQUEST", "description": "A general error occurred with the request.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "MISSING_REQUIRED_PARAMETER", "description": "The request is missing a required path, query, or\nbody parameter.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INCORRECT_TYPE", "description": "The value provided in the request is the wrong\ntype. For example, a string instead of an integer.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_TIME", "description": "Formatting for the provided time value is\nincorrect.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_TIME_RANGE", "description": "The time range provided in the request is invalid.\nFor example, the end time is before the start time.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_VALUE", "description": "The provided value is invalid. For example,\nincluding `%` in a phone number.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_CURSOR", "description": "The pagination cursor included in the request is\ninvalid.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "UNKNOWN_QUERY_PARAMETER", "description": "The query parameters provided is invalid for the\nrequested endpoint.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "CONFLICTING_PARAMETERS", "description": "One or more of the request parameters conflict with\neach other.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "EXPECTED_JSON_BODY", "description": "The request body is not a JSON object.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_SORT_ORDER", "description": "The provided sort order is not a valid key.\nCurrently, sort order must be `ASC` or `DESC`.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "VALUE_REGEX_MISMATCH", "description": "The provided value does not match an expected\nregular expression.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "VALUE_TOO_SHORT", "description": "The provided string value is shorter than the\nminimum length allowed.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "VALUE_TOO_LONG", "description": "The provided string value is longer than the\nmaximum length allowed.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "VALUE_TOO_LOW", "description": "The provided value is less than the supported\nminimum.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "VALUE_TOO_HIGH", "description": "The provided value is greater than the supported\nmaximum.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "VALUE_EMPTY", "description": "The provided value has a default (empty) value\nsuch as a blank string.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "ARRAY_LENGTH_TOO_LONG", "description": "The provided array has too many elements.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "ARRAY_LENGTH_TOO_SHORT", "description": "The provided array has too few elements.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "ARRAY_EMPTY", "description": "The provided array is empty.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "EXPECTED_BOOLEAN", "description": "The endpoint expected the provided value to be a\nboolean.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "EXPECTED_INTEGER", "description": "The endpoint expected the provided value to be an\ninteger.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "EXPECTED_FLOAT", "description": "The endpoint expected the provided value to be a\nfloat.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "EXPECTED_STRING", "description": "The endpoint expected the provided value to be a\nstring.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "EXPECTED_OBJECT", "description": "The endpoint expected the provided value to be a\nJSON object.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "EXPECTED_ARRAY", "description": "The endpoint expected the provided value to be an\narray or list.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "EXPECTED_MAP", "description": "The endpoint expected the provided value to be a\nmap or associative array.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "EXPECTED_BASE64_ENCODED_BYTE_ARRAY", "description": "The endpoint expected the provided value to be an\narray encoded in base64.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_ARRAY_VALUE", "description": "One or more objects in the array does not match the\narray type.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_ENUM_VALUE", "description": "The provided static string is not valid for the\nfield.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_CONTENT_TYPE", "description": "Invalid content type header.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_FORM_VALUE", "description": "Only relevant for applications created prior to\n2016-03-30. Indicates there was an error while parsing form values.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "CUSTOMER_NOT_FOUND", "description": "The provided customer id can't be found in the merchant's customers list.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "ONE_INSTRUMENT_EXPECTED", "description": "A general error occurred.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "NO_FIELDS_SET", "description": "A general error occurred.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "TOO_MANY_MAP_ENTRIES", "description": "Too many entries in the map field.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "MAP_KEY_LENGTH_TOO_SHORT", "description": "The length of one of the provided keys in the map is too short.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "MAP_KEY_LENGTH_TOO_LONG", "description": "The length of one of the provided keys in the map is too long.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "CUSTOMER_MISSING_NAME", "description": "The provided customer does not have a recorded name.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "CUSTOMER_MISSING_EMAIL", "description": "The provided customer does not have a recorded email.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_PAUSE_LENGTH", "description": "The subscription cannot be paused longer than the duration of the current phase.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_DATE", "description": "The subscription cannot be paused/resumed on the given date.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "UNSUPPORTED_COUNTRY", "description": "The API request references an unsupported country.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "UNSUPPORTED_CURRENCY", "description": "The API request references an unsupported currency.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "APPLE_TTP_PIN_TOKEN", "description": "The payment was declined by the card issuer during an Apple Tap to Pay (TTP)\ntransaction with a request for the card's PIN. This code will be returned alongside\n`CARD_DECLINED_VERIFICATION_REQUIRED` as a supplemental error, and will include an\nissuer-provided token in the `details` field that is needed to initiate the PIN\ncollection flow on the iOS device.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "CARD_EXPIRED", "description": "The card issuer declined the request because the card is expired.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "INVALID_EXPIRATION", "description": "The expiration date for the payment card is invalid. For example,\nit indicates a date in the past.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "INVALID_EXPIRATION_YEAR", "description": "The expiration year for the payment card is invalid. For example,\nit indicates a year in the past or contains invalid characters.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_EXPIRATION_DATE", "description": "The expiration date for the payment card is invalid. For example,\nit contains invalid characters.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "UNSUPPORTED_CARD_BRAND", "description": "The credit card provided is not from a supported issuer.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "UNSUPPORTED_ENTRY_METHOD", "description": "The entry method for the credit card (swipe, dip, tap) is not supported.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "INVALID_ENCRYPTED_CARD", "description": "The encrypted card information is invalid.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "INVALID_CARD", "description": "The credit card cannot be validated based on the provided details.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "PAYMENT_AMOUNT_MISMATCH", "description": "The payment was declined because there was a payment amount mismatch.\nThe money amount Square was expecting does not match the amount provided.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "GENERIC_DECLINE", "description": "Square received a decline without any additional information.\nIf the payment information seems correct, the buyer can contact their\nissuer to ask for more information.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "CVV_FAILURE", "description": "The card issuer declined the request because the CVV value is invalid.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "ADDRESS_VERIFICATION_FAILURE", "description": "The card issuer declined the request because the postal code is invalid.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "INVALID_ACCOUNT", "description": "The issuer was not able to locate the account on record.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "CURRENCY_MISMATCH", "description": "The currency associated with the payment is not valid for the provided\nfunding source. For example, a gift card funded in USD cannot be used to process\npayments in GBP.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "INSUFFICIENT_FUNDS", "description": "The funding source has insufficient funds to cover the payment.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "INSUFFICIENT_PERMISSIONS", "description": "The Square account does not have the permissions to accept\nthis payment. For example, Square may limit which merchants are\nallowed to receive gift card payments.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "CARDHOLDER_INSUFFICIENT_PERMISSIONS", "description": "The card issuer has declined the transaction due to restrictions on where the card can be used.\nFor example, a gift card is limited to a single merchant.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "INVALID_LOCATION", "description": "The Square account cannot take payments in the specified region.\nA Square account can take payments only from the region where the account was created.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "TRANSACTION_LIMIT", "description": "The card issuer has determined the payment amount is either too high or too low.\nThe API returns the error code mostly for credit cards (for example, the card reached\nthe credit limit). However, sometimes the issuer bank can indicate the error for debit\nor prepaid cards (for example, card has insufficient funds).", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "VOICE_FAILURE", "description": "The card issuer declined the request because the issuer requires voice authorization from the cardholder. The seller should ask the customer to contact the card issuing bank to authorize the payment.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "PAN_FAILURE", "description": "The specified card number is invalid. For example, it is of\nincorrect length or is incorrectly formatted.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "EXPIRATION_FAILURE", "description": "The card expiration date is either invalid or indicates that the\ncard is expired.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "CARD_NOT_SUPPORTED", "description": "The card is not supported either in the geographic region or by\nthe [merchant category code](https://developer.squareup.com/docs/locations-api#initialize-a-merchant-category-code) (MCC).", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "INVALID_PIN", "description": "The card issuer declined the request because the PIN is invalid.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "MISSING_PIN", "description": "The payment is missing a required PIN.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "MISSING_ACCOUNT_TYPE", "description": "The payment is missing a required ACCOUNT_TYPE parameter.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "INVALID_POSTAL_CODE", "description": "The postal code is incorrectly formatted.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "INVALID_FEES", "description": "The app_fee_money on a payment is too high.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "MANUALLY_ENTERED_PAYMENT_NOT_SUPPORTED", "description": "The card must be swiped, tapped, or dipped. Payments attempted by manually entering the card number are declined.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "PAYMENT_LIMIT_EXCEEDED", "description": "Square declined the request because the payment amount exceeded the processing limit for this merchant.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "GIFT_CARD_AVAILABLE_AMOUNT", "description": "When a Gift Card is a payment source, you can allow taking a partial payment\nby adding the `accept_partial_authorization` parameter in the request.\nHowever, taking such a partial payment does not work if your request also includes\n`tip_money`, `app_fee_money`, or both. Square declines such payments and returns\nthe `GIFT_CARD_AVAILABLE_AMOUNT` error.\nFor more information, see\n[CreatePayment errors (additional information)](https://developer.squareup.com/docs/payments-api/error-codes#createpayment-errors-additional-information).", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "ACCOUNT_UNUSABLE", "description": "The account provided cannot carry out transactions.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "BUYER_REFUSED_PAYMENT", "description": "Bank account rejected or was not authorized for the payment.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "DELAYED_TRANSACTION_EXPIRED", "description": "The application tried to update a delayed-capture payment that has expired.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "DELAYED_TRANSACTION_CANCELED", "description": "The application tried to cancel a delayed-capture payment that was already cancelled.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "DELAYED_TRANSACTION_CAPTURED", "description": "The application tried to capture a delayed-capture payment that was already captured.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "DELAYED_TRANSACTION_FAILED", "description": "The application tried to update a delayed-capture payment that failed.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "CARD_TOKEN_EXPIRED", "description": "The provided card token (nonce) has expired.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "CARD_TOKEN_USED", "description": "The provided card token (nonce) was already used to process the payment or refund.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "AMOUNT_TOO_HIGH", "description": "The requested payment amount is too high for the provided payment source.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "UNSUPPORTED_INSTRUMENT_TYPE", "description": "The API request references an unsupported instrument type.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "REFUND_AMOUNT_INVALID", "description": "The requested refund amount exceeds the amount available to refund.", "error-category": "REFUND_ERROR" }, { "name": "REFUND_ALREADY_PENDING", "description": "The payment already has a pending refund.", "error-category": "REFUND_ERROR" }, { "name": "PAYMENT_NOT_REFUNDABLE", "description": "The payment is not refundable. For example, the payment is too old to be refunded.", "error-category": "REFUND_ERROR" }, { "name": "PAYMENT_NOT_REFUNDABLE_DUE_TO_DISPUTE", "description": "The payment is not refundable because it has been disputed.", "error-category": "REFUND_ERROR" }, { "name": "REFUND_DECLINED", "description": "Request failed - The card issuer declined the refund.", "error-category": "REFUND_ERROR" }, { "name": "INSUFFICIENT_PERMISSIONS_FOR_REFUND", "description": "The Square account does not have the permissions to process this refund.", "error-category": "REFUND_ERROR" }, { "name": "INVALID_CARD_DATA", "description": "Generic error - the provided card data is invalid.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "SOURCE_USED", "description": "The provided source id was already used to create a card.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "SOURCE_EXPIRED", "description": "The provided source id has expired.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "UNSUPPORTED_LOYALTY_REWARD_TIER", "description": "The referenced loyalty program reward tier is not supported.\nThis could happen if the reward tier created in a first party\napplication is incompatible with the Loyalty API.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "LOCATION_MISMATCH", "description": "Generic error - the given location does not matching what is expected.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "IDEMPOTENCY_KEY_REUSED", "description": "The provided idempotency key has already been used.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "UNEXPECTED_VALUE", "description": "General error - the value provided was unexpected.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "SANDBOX_NOT_SUPPORTED", "description": "The API request is not supported in sandbox.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_EMAIL_ADDRESS", "description": "The provided email address is invalid.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_PHONE_NUMBER", "description": "The provided phone number is invalid.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "CHECKOUT_EXPIRED", "description": "The provided checkout URL has expired.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "BAD_CERTIFICATE", "description": "Bad certificate.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_SQUARE_VERSION_FORMAT", "description": "The provided Square-Version is incorrectly formatted.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "API_VERSION_INCOMPATIBLE", "description": "The provided Square-Version is incompatible with the requested action.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "CARD_PRESENCE_REQUIRED", "description": "The transaction requires that a card be present.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "UNSUPPORTED_SOURCE_TYPE", "description": "The API request references an unsupported source type.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "CARD_MISMATCH", "description": "The provided card does not match what is expected.", "error-category": "REFUND_ERROR" }, { "name": "PLAID_ERROR", "description": "Generic plaid error", "error-category": "EXTERNAL_VENDOR_ERROR" }, { "name": "PLAID_ERROR_ITEM_LOGIN_REQUIRED", "description": "Plaid error - ITEM_LOGIN_REQUIRED", "error-category": "EXTERNAL_VENDOR_ERROR" }, { "name": "PLAID_ERROR_RATE_LIMIT", "description": "Plaid error - RATE_LIMIT", "error-category": "EXTERNAL_VENDOR_ERROR" }, { "name": "CARD_DECLINED", "description": "The card was declined.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "VERIFY_CVV_FAILURE", "description": "The CVV could not be verified.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "VERIFY_AVS_FAILURE", "description": "The AVS could not be verified.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "CARD_DECLINED_CALL_ISSUER", "description": "The payment card was declined with a request\nfor the card holder to call the issuer.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "CARD_DECLINED_VERIFICATION_REQUIRED", "description": "The payment card was declined with a request\nfor additional verification.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "BAD_EXPIRATION", "description": "The card expiration date is either missing or\nincorrectly formatted.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "CHIP_INSERTION_REQUIRED", "description": "The card issuer requires that the card be read\nusing a chip reader.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "ALLOWABLE_PIN_TRIES_EXCEEDED", "description": "The card has exhausted its available pin entry\nretries set by the card issuer. Resolving the error typically requires the\ncard holder to contact the card issuer.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "RESERVATION_DECLINED", "description": "The card issuer declined the refund.", "error-category": "REFUND_ERROR" }, { "name": "UNKNOWN_BODY_PARAMETER", "description": "The body parameter is not recognized by the requested endpoint.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "NOT_FOUND", "description": "Not Found - a general error occurred.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "APPLE_PAYMENT_PROCESSING_CERTIFICATE_HASH_NOT_FOUND", "description": "Square could not find the associated Apple Pay certificate.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "METHOD_NOT_ALLOWED", "description": "Method Not Allowed - a general error occurred.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "NOT_ACCEPTABLE", "description": "Not Acceptable - a general error occurred.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "REQUEST_TIMEOUT", "description": "Request Timeout - a general error occurred.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "CONFLICT", "description": "Conflict - a general error occurred.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "GONE", "description": "The target resource is no longer available and this\ncondition is likely to be permanent.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "REQUEST_ENTITY_TOO_LARGE", "description": "Request Entity Too Large - a general error occurred.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "UNSUPPORTED_MEDIA_TYPE", "description": "Unsupported Media Type - a general error occurred.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "UNPROCESSABLE_ENTITY", "description": "Unprocessable Entity - a general error occurred.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "RATE_LIMITED", "description": "Rate Limited - a general error occurred.", "error-category": "RATE_LIMIT_ERROR" }, { "name": "NOT_IMPLEMENTED", "description": "Not Implemented - a general error occurred.", "error-category": "API_ERROR" }, { "name": "BAD_GATEWAY", "description": "Bad Gateway - a general error occurred.", "error-category": "API_ERROR" }, { "name": "SERVICE_UNAVAILABLE", "description": "Service Unavailable - a general error occurred.", "error-category": "API_ERROR" }, { "name": "TEMPORARY_ERROR", "description": "A temporary internal error occurred. You can safely retry your call\nusing the same idempotency key.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "GATEWAY_TIMEOUT", "description": "Gateway Timeout - a general error occurred.", "error-category": "API_ERROR" } ], "description": "Indicates the specific error that occurred during a request to a\nSquare API.", "x-release-status": "PUBLIC" }, "Fulfillment": { "type": "object", "description": "Contains details about how to fulfill this order.\nOrders can only be created with at most one fulfillment using the API.\nHowever, orders returned by the Orders API might contain multiple fulfillments because sellers can create multiple fulfillments using Square products such as Square Online.", "x-release-status": "PUBLIC", "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID that identifies the fulfillment only within this order.", "maxLength": 60, "x-release-status": "BETA" }, "type": { "$ref": "#/$defs/FulfillmentType", "description": "The type of the fulfillment.\nSee [FulfillmentType](#type-fulfillmenttype) for possible values" }, "state": { "$ref": "#/$defs/FulfillmentState", "description": "The state of the fulfillment.\nSee [FulfillmentState](#type-fulfillmentstate) for possible values" }, "line_item_application": { "$ref": "#/$defs/FulfillmentFulfillmentLineItemApplication", "description": "Describes what order line items this fulfillment applies to.\nIt can be `ALL` or `ENTRY_LIST` with a supplied list of fulfillment entries.\nSee [FulfillmentFulfillmentLineItemApplication](#type-fulfillmentfulfillmentlineitemapplication) for possible values", "readOnly": true, "x-release-status": "BETA" }, "entries": { "type": "array", "items": { "$ref": "#/$defs/FulfillmentFulfillmentEntry" }, "description": "A list of entries pertaining to the fulfillment of an order. Each entry must reference\na valid `uid` for an order line item in the `line_item_uid` field, as well as a `quantity` to\nfulfill.\n\nMultiple entries can reference the same line item `uid`, as long as the total quantity among\nall fulfillment entries referencing a single line item does not exceed the quantity of the\norder's line item itself.\n\nAn order cannot be marked as `COMPLETED` before all fulfillments are `COMPLETED`,\n`CANCELED`, or `FAILED`. Fulfillments can be created and completed independently\nbefore order completion.", "readOnly": true, "x-release-status": "BETA" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Application-defined data attached to this fulfillment. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "x-release-status": "BETA" }, "pickup_details": { "$ref": "#/$defs/FulfillmentPickupDetails", "description": "Contains details for a pickup fulfillment. These details are required when the fulfillment\ntype is `PICKUP`." }, "shipment_details": { "$ref": "#/$defs/FulfillmentShipmentDetails", "description": "Contains details for a shipment fulfillment. These details are required when the fulfillment type\nis `SHIPMENT`.\n\nA shipment fulfillment's relationship to fulfillment `state`:\n`PROPOSED`: A shipment is requested.\n`RESERVED`: Fulfillment in progress. Shipment processing.\n`PREPARED`: Shipment packaged. Shipping label created.\n`COMPLETED`: Package has been shipped.\n`CANCELED`: Shipment has been canceled.\n`FAILED`: Shipment has failed.", "x-release-status": "BETA" }, "delivery_details": { "$ref": "#/$defs/FulfillmentDeliveryDetails", "description": "Describes delivery details of an order fulfillment.", "x-release-status": "BETA" } } }, "FulfillmentDeliveryDetails": { "type": "object", "description": "Describes delivery details of an order fulfillment.", "x-release-status": "BETA", "properties": { "recipient": { "$ref": "#/$defs/FulfillmentRecipient", "description": "The contact information for the person to receive the fulfillment." }, "schedule_type": { "$ref": "#/$defs/FulfillmentDeliveryDetailsOrderFulfillmentDeliveryDetailsScheduleType", "description": "Indicates the fulfillment delivery schedule type. If `SCHEDULED`, then\n`deliver_at` is required. If `ASAP`, then `prep_time_duration` is required. The default is `SCHEDULED`.\nSee [OrderFulfillmentDeliveryDetailsScheduleType](#type-orderfulfillmentdeliverydetailsscheduletype) for possible values" }, "placed_at": { "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was placed.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nMust be in RFC 3339 timestamp format, e.g., \"2016-09-04T23:59:33.123Z\".", "readOnly": true }, "deliver_at": { "type": [ "string", "null" ], "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nthat represents the start of the delivery period.\nWhen the fulfillment `schedule_type` is `ASAP`, the field is automatically\nset to the current time plus the `prep_time_duration`.\nOtherwise, the application can set this field while the fulfillment `state` is\n`PROPOSED`, `RESERVED`, or `PREPARED` (any time before the\nterminal state such as `COMPLETED`, `CANCELED`, and `FAILED`).\n\nThe timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\")." }, "prep_time_duration": { "type": [ "string", "null" ], "description": "The duration of time it takes to prepare and deliver this fulfillment.\nThe duration must be in RFC 3339 format (for example, \"P1W3D\")." }, "delivery_window_duration": { "type": [ "string", "null" ], "description": "The time period after `deliver_at` in which to deliver the order.\nApplications can set this field when the fulfillment `state` is\n`PROPOSED`, `RESERVED`, or `PREPARED` (any time before the terminal state\nsuch as `COMPLETED`, `CANCELED`, and `FAILED`).\n\nThe duration must be in RFC 3339 format (for example, \"P1W3D\")." }, "note": { "type": [ "string", "null" ], "description": "Provides additional instructions about the delivery fulfillment.\nIt is displayed in the Square Point of Sale application and set by the API.", "maxLength": 550 }, "completed_at": { "type": [ "string", "null" ], "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicates when the seller completed the fulfillment.\nThis field is automatically set when fulfillment `state` changes to `COMPLETED`.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\")." }, "in_progress_at": { "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicates when the seller started processing the fulfillment.\nThis field is automatically set when the fulfillment `state` changes to `RESERVED`.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "rejected_at": { "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was rejected. This field is\nautomatically set when the fulfillment `state` changes to `FAILED`.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "ready_at": { "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the seller marked the fulfillment as ready for\ncourier pickup. This field is automatically set when the fulfillment `state` changes\nto PREPARED.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "delivered_at": { "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was delivered to the recipient.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "canceled_at": { "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was canceled. This field is automatically\nset when the fulfillment `state` changes to `CANCELED`.\n\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "cancel_reason": { "type": [ "string", "null" ], "description": "The delivery cancellation reason. Max length: 100 characters.", "maxLength": 100 }, "courier_pickup_at": { "type": [ "string", "null" ], "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when an order can be picked up by the courier for delivery.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\")." }, "courier_pickup_window_duration": { "type": [ "string", "null" ], "description": "The time period after `courier_pickup_at` in which the courier should pick up the order.\nThe duration must be in RFC 3339 format (for example, \"P1W3D\")." }, "is_no_contact_delivery": { "type": [ "boolean", "null" ], "description": "Whether the delivery is preferred to be no contact." }, "dropoff_notes": { "type": [ "string", "null" ], "description": "A note to provide additional instructions about how to deliver the order.", "maxLength": 550 }, "courier_provider_name": { "type": [ "string", "null" ], "description": "The name of the courier provider.", "maxLength": 255 }, "courier_support_phone_number": { "type": [ "string", "null" ], "description": "The support phone number of the courier.", "maxLength": 17 }, "square_delivery_id": { "type": [ "string", "null" ], "description": "The identifier for the delivery created by Square.", "maxLength": 50 }, "external_delivery_id": { "type": [ "string", "null" ], "description": "The identifier for the delivery created by the third-party courier service.", "maxLength": 50 }, "managed_delivery": { "type": [ "boolean", "null" ], "description": "The flag to indicate the delivery is managed by a third party (ie DoorDash), which means\nwe may not receive all recipient information for PII purposes." } } }, "FulfillmentDeliveryDetailsOrderFulfillmentDeliveryDetailsScheduleType": { "type": "string", "enum": [ "SCHEDULED", "ASAP" ], "x-enum-elements": [ { "name": "SCHEDULED", "description": "Indicates the fulfillment to deliver at a scheduled deliver time." }, { "name": "ASAP", "description": "Indicates that the fulfillment to deliver as soon as possible and should be prepared\nimmediately." } ], "description": "The schedule type of the delivery fulfillment.", "x-release-status": "BETA" }, "FulfillmentFulfillmentEntry": { "type": "object", "description": "Links an order line item to a fulfillment. Each entry must reference\na valid `uid` for an order line item in the `line_item_uid` field, as well as a `quantity` to\nfulfill.", "x-release-status": "BETA", "required": [ "line_item_uid", "quantity" ], "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID that identifies the fulfillment entry only within this order.", "maxLength": 60 }, "line_item_uid": { "type": "string", "description": "The `uid` from the order line item.", "minLength": 1 }, "quantity": { "type": "string", "description": "The quantity of the line item being fulfilled, formatted as a decimal number.\nFor example, `\"3\"`.\n\nFulfillments for line items with a `quantity_unit` can have non-integer quantities.\nFor example, `\"1.70000\"`.", "minLength": 1, "maxLength": 12 }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Application-defined data attached to this fulfillment entry. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata)." } } }, "FulfillmentFulfillmentLineItemApplication": { "type": "string", "enum": [ "ALL", "ENTRY_LIST" ], "x-enum-elements": [ { "name": "ALL", "description": "If `ALL`, `entries` must be unset." }, { "name": "ENTRY_LIST", "description": "If `ENTRY_LIST`, supply a list of `entries`." } ], "description": "The `line_item_application` describes what order line items this fulfillment applies\nto. It can be `ALL` or `ENTRY_LIST` with a supplied list of fulfillment entries.", "x-release-status": "BETA" }, "FulfillmentPickupDetails": { "type": "object", "description": "Contains details necessary to fulfill a pickup order.", "x-release-status": "PUBLIC", "properties": { "recipient": { "$ref": "#/$defs/FulfillmentRecipient", "description": "Information about the person to pick up this fulfillment from a physical\nlocation." }, "expires_at": { "type": [ "string", "null" ], "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when this fulfillment expires if it is not marked in progress. The timestamp must be\nin RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\"). The expiration time can only be set\nup to 7 days in the future. If `expires_at` is not set, any new payments attached to the order\nare automatically completed." }, "auto_complete_duration": { "type": [ "string", "null" ], "description": "The duration of time after which an in progress pickup fulfillment is automatically moved\nto the `COMPLETED` state. The duration must be in RFC 3339 format (for example, \"P1W3D\").\n\nIf not set, this pickup fulfillment remains in progress until it is canceled or completed." }, "schedule_type": { "$ref": "#/$defs/FulfillmentPickupDetailsScheduleType", "description": "The schedule type of the pickup fulfillment. Defaults to `SCHEDULED`.\nSee [FulfillmentPickupDetailsScheduleType](#type-fulfillmentpickupdetailsscheduletype) for possible values" }, "pickup_at": { "type": [ "string", "null" ], "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nthat represents the start of the pickup window. Must be in RFC 3339 timestamp format, e.g.,\n\"2016-09-04T23:59:33.123Z\".\n\nFor fulfillments with the schedule type `ASAP`, this is automatically set\nto the current time plus the expected duration to prepare the fulfillment." }, "pickup_window_duration": { "type": [ "string", "null" ], "description": "The window of time in which the order should be picked up after the `pickup_at` timestamp.\nMust be in RFC 3339 duration format, e.g., \"P1W3D\". Can be used as an\ninformational guideline for merchants." }, "prep_time_duration": { "type": [ "string", "null" ], "description": "The duration of time it takes to prepare this fulfillment.\nThe duration must be in RFC 3339 format (for example, \"P1W3D\")." }, "note": { "type": [ "string", "null" ], "description": "A note to provide additional instructions about the pickup\nfulfillment displayed in the Square Point of Sale application and set by the API.", "maxLength": 500 }, "placed_at": { "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was placed. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "accepted_at": { "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was marked in progress. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "rejected_at": { "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was rejected. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "ready_at": { "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment is marked as ready for pickup. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "expired_at": { "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment expired. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "picked_up_at": { "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was picked up by the recipient. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "canceled_at": { "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was canceled. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "cancel_reason": { "type": [ "string", "null" ], "description": "A description of why the pickup was canceled. The maximum length: 100 characters.", "maxLength": 100 }, "is_curbside_pickup": { "type": [ "boolean", "null" ], "description": "If set to `true`, indicates that this pickup order is for curbside pickup, not in-store pickup.", "x-release-status": "BETA" }, "curbside_pickup_details": { "$ref": "#/$defs/FulfillmentPickupDetailsCurbsidePickupDetails", "description": "Specific details for curbside pickup. These details can only be populated if `is_curbside_pickup` is set to `true`.", "x-release-status": "BETA" } } }, "FulfillmentPickupDetailsCurbsidePickupDetails": { "type": "object", "description": "Specific details for curbside pickup.", "x-release-status": "BETA", "properties": { "curbside_details": { "type": [ "string", "null" ], "description": "Specific details for curbside pickup, such as parking number and vehicle model.", "maxLength": 250 }, "buyer_arrived_at": { "type": [ "string", "null" ], "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the buyer arrived and is waiting for pickup. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\")." } } }, "FulfillmentPickupDetailsScheduleType": { "type": "string", "enum": [ "SCHEDULED", "ASAP" ], "x-enum-elements": [ { "name": "SCHEDULED", "description": "Indicates that the fulfillment will be picked up at a scheduled pickup time." }, { "name": "ASAP", "description": "Indicates that the fulfillment will be picked up as soon as possible and\nshould be prepared immediately." } ], "description": "The schedule type of the pickup fulfillment.", "x-release-status": "PUBLIC" }, "FulfillmentRecipient": { "type": "object", "description": "Information about the fulfillment recipient.", "x-release-status": "PUBLIC", "properties": { "customer_id": { "type": [ "string", "null" ], "description": "The ID of the customer associated with the fulfillment.\n\nIf `customer_id` is provided, the fulfillment recipient's `display_name`,\n`email_address`, and `phone_number` are automatically populated from the\ntargeted customer profile. If these fields are set in the request, the request\nvalues override the information from the customer profile. If the\ntargeted customer profile does not contain the necessary information and\nthese fields are left unset, the request results in an error.", "maxLength": 191 }, "display_name": { "type": [ "string", "null" ], "description": "The display name of the fulfillment recipient. This field is required.\n\nIf provided, the display name overrides the corresponding customer profile value\nindicated by `customer_id`.", "maxLength": 255 }, "email_address": { "type": [ "string", "null" ], "description": "The email address of the fulfillment recipient.\n\nIf provided, the email address overrides the corresponding customer profile value\nindicated by `customer_id`.", "maxLength": 255 }, "phone_number": { "type": [ "string", "null" ], "description": "The phone number of the fulfillment recipient. This field is required.\n\nIf provided, the phone number overrides the corresponding customer profile value\nindicated by `customer_id`.", "maxLength": 17 }, "address": { "$ref": "#/$defs/Address", "description": "The address of the fulfillment recipient. This field is required.\n\nIf provided, the address overrides the corresponding customer profile value\nindicated by `customer_id`.", "x-release-status": "BETA" } } }, "FulfillmentShipmentDetails": { "type": "object", "description": "Contains the details necessary to fulfill a shipment order.", "x-release-status": "BETA", "properties": { "recipient": { "$ref": "#/$defs/FulfillmentRecipient", "description": "Information about the person to receive this shipment fulfillment." }, "carrier": { "type": [ "string", "null" ], "description": "The shipping carrier being used to ship this fulfillment (such as UPS, FedEx, or USPS).", "maxLength": 50 }, "shipping_note": { "type": [ "string", "null" ], "description": "A note with additional information for the shipping carrier.", "maxLength": 500 }, "shipping_type": { "type": [ "string", "null" ], "description": "A description of the type of shipping product purchased from the carrier\n(such as First Class, Priority, or Express).", "maxLength": 50 }, "tracking_number": { "type": [ "string", "null" ], "description": "The reference number provided by the carrier to track the shipment's progress.", "maxLength": 100 }, "tracking_url": { "type": [ "string", "null" ], "description": "A link to the tracking webpage on the carrier's website.", "maxLength": 2000 }, "placed_at": { "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the shipment was requested. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "in_progress_at": { "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when this fulfillment was moved to the `RESERVED` state, which indicates that preparation\nof this shipment has begun. The timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "packaged_at": { "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when this fulfillment was moved to the `PREPARED` state, which indicates that the\nfulfillment is packaged. The timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "expected_shipped_at": { "type": [ "string", "null" ], "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the shipment is expected to be delivered to the shipping carrier.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\")." }, "shipped_at": { "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when this fulfillment was moved to the `COMPLETED` state, which indicates that\nthe fulfillment has been given to the shipping carrier. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "canceled_at": { "type": [ "string", "null" ], "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating the shipment was canceled.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\")." }, "cancel_reason": { "type": [ "string", "null" ], "description": "A description of why the shipment was canceled.", "maxLength": 100 }, "failed_at": { "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the shipment failed to be completed. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "failure_reason": { "type": [ "string", "null" ], "description": "A description of why the shipment failed to be completed.", "maxLength": 100 } } }, "FulfillmentState": { "type": "string", "enum": [ "PROPOSED", "RESERVED", "PREPARED", "COMPLETED", "CANCELED", "FAILED" ], "x-enum-elements": [ { "name": "PROPOSED", "description": "Indicates that the fulfillment has been proposed." }, { "name": "RESERVED", "description": "Indicates that the fulfillment has been reserved." }, { "name": "PREPARED", "description": "Indicates that the fulfillment has been prepared." }, { "name": "COMPLETED", "description": "Indicates that the fulfillment was successfully completed." }, { "name": "CANCELED", "description": "Indicates that the fulfillment was canceled." }, { "name": "FAILED", "description": "Indicates that the fulfillment failed to be completed, but was not explicitly\ncanceled." } ], "description": "The current state of this fulfillment.", "x-release-status": "PUBLIC" }, "FulfillmentType": { "type": "string", "enum": [ "PICKUP", "SHIPMENT", "DELIVERY" ], "x-enum-elements": [ { "name": "PICKUP", "description": "A recipient to pick up the fulfillment from a physical [location](entity:Location)." }, { "name": "SHIPMENT", "description": "A shipping carrier to ship the fulfillment." }, { "name": "DELIVERY", "description": "A courier to deliver the fulfillment." } ], "description": "The type of fulfillment.", "x-release-status": "PUBLIC" }, "MeasurementUnit": { "type": "object", "description": "Represents a unit of measurement to use with a quantity, such as ounces\nor inches. Exactly one of the following fields are required: `custom_unit`,\n`area_unit`, `length_unit`, `volume_unit`, and `weight_unit`.", "x-release-status": "PUBLIC", "properties": { "custom_unit": { "$ref": "#/$defs/MeasurementUnitCustom", "description": "A custom unit of measurement defined by the seller using the Point of Sale\napp or ad-hoc as an order line item." }, "area_unit": { "$ref": "#/$defs/MeasurementUnitArea", "description": "Represents a standard area unit.\nSee [MeasurementUnitArea](#type-measurementunitarea) for possible values" }, "length_unit": { "$ref": "#/$defs/MeasurementUnitLength", "description": "Represents a standard length unit.\nSee [MeasurementUnitLength](#type-measurementunitlength) for possible values" }, "volume_unit": { "$ref": "#/$defs/MeasurementUnitVolume", "description": "Represents a standard volume unit.\nSee [MeasurementUnitVolume](#type-measurementunitvolume) for possible values" }, "weight_unit": { "$ref": "#/$defs/MeasurementUnitWeight", "description": "Represents a standard unit of weight or mass.\nSee [MeasurementUnitWeight](#type-measurementunitweight) for possible values" }, "generic_unit": { "$ref": "#/$defs/MeasurementUnitGeneric", "description": "Reserved for API integrations that lack the ability to specify a real measurement unit\nSee [MeasurementUnitGeneric](#type-measurementunitgeneric) for possible values" }, "time_unit": { "$ref": "#/$defs/MeasurementUnitTime", "description": "Represents a standard unit of time.\nSee [MeasurementUnitTime](#type-measurementunittime) for possible values" }, "type": { "$ref": "#/$defs/MeasurementUnitUnitType", "description": "Represents the type of the measurement unit.\nSee [MeasurementUnitUnitType](#type-measurementunitunittype) for possible values" } } }, "MeasurementUnitArea": { "type": "string", "enum": [ "IMPERIAL_ACRE", "IMPERIAL_SQUARE_INCH", "IMPERIAL_SQUARE_FOOT", "IMPERIAL_SQUARE_YARD", "IMPERIAL_SQUARE_MILE", "METRIC_SQUARE_CENTIMETER", "METRIC_SQUARE_METER", "METRIC_SQUARE_KILOMETER" ], "x-enum-elements": [ { "name": "IMPERIAL_ACRE", "description": "The area is measured in acres." }, { "name": "IMPERIAL_SQUARE_INCH", "description": "The area is measured in square inches." }, { "name": "IMPERIAL_SQUARE_FOOT", "description": "The area is measured in square feet." }, { "name": "IMPERIAL_SQUARE_YARD", "description": "The area is measured in square yards." }, { "name": "IMPERIAL_SQUARE_MILE", "description": "The area is measured in square miles." }, { "name": "METRIC_SQUARE_CENTIMETER", "description": "The area is measured in square centimeters." }, { "name": "METRIC_SQUARE_METER", "description": "The area is measured in square meters." }, { "name": "METRIC_SQUARE_KILOMETER", "description": "The area is measured in square kilometers." } ], "description": "Unit of area used to measure a quantity.", "x-release-status": "PUBLIC" }, "MeasurementUnitCustom": { "type": "object", "description": "The information needed to define a custom unit, provided by the seller.", "x-release-status": "PUBLIC", "required": [ "name", "abbreviation" ], "properties": { "name": { "type": "string", "description": "The name of the custom unit, for example \"bushel\"." }, "abbreviation": { "type": "string", "description": "The abbreviation of the custom unit, such as \"bsh\" (bushel). This appears\nin the cart for the Point of Sale app, and in reports." } } }, "MeasurementUnitGeneric": { "type": "string", "enum": [ "UNIT" ], "x-enum-elements": [ { "name": "UNIT", "description": "The generic unit." } ], "x-release-status": "PUBLIC" }, "MeasurementUnitLength": { "type": "string", "enum": [ "IMPERIAL_INCH", "IMPERIAL_FOOT", "IMPERIAL_YARD", "IMPERIAL_MILE", "METRIC_MILLIMETER", "METRIC_CENTIMETER", "METRIC_METER", "METRIC_KILOMETER" ], "x-enum-elements": [ { "name": "IMPERIAL_INCH", "description": "The length is measured in inches." }, { "name": "IMPERIAL_FOOT", "description": "The length is measured in feet." }, { "name": "IMPERIAL_YARD", "description": "The length is measured in yards." }, { "name": "IMPERIAL_MILE", "description": "The length is measured in miles." }, { "name": "METRIC_MILLIMETER", "description": "The length is measured in millimeters." }, { "name": "METRIC_CENTIMETER", "description": "The length is measured in centimeters." }, { "name": "METRIC_METER", "description": "The length is measured in meters." }, { "name": "METRIC_KILOMETER", "description": "The length is measured in kilometers." } ], "description": "The unit of length used to measure a quantity.", "x-release-status": "PUBLIC" }, "MeasurementUnitTime": { "type": "string", "enum": [ "GENERIC_MILLISECOND", "GENERIC_SECOND", "GENERIC_MINUTE", "GENERIC_HOUR", "GENERIC_DAY" ], "x-enum-elements": [ { "name": "GENERIC_MILLISECOND", "description": "The time is measured in milliseconds." }, { "name": "GENERIC_SECOND", "description": "The time is measured in seconds." }, { "name": "GENERIC_MINUTE", "description": "The time is measured in minutes." }, { "name": "GENERIC_HOUR", "description": "The time is measured in hours." }, { "name": "GENERIC_DAY", "description": "The time is measured in days." } ], "description": "Unit of time used to measure a quantity (a duration).", "x-release-status": "PUBLIC" }, "MeasurementUnitUnitType": { "type": "string", "enum": [ "TYPE_CUSTOM", "TYPE_AREA", "TYPE_LENGTH", "TYPE_VOLUME", "TYPE_WEIGHT", "TYPE_GENERIC" ], "x-enum-elements": [ { "name": "TYPE_CUSTOM", "description": "The unit details are contained in the custom_unit field." }, { "name": "TYPE_AREA", "description": "The unit details are contained in the area_unit field." }, { "name": "TYPE_LENGTH", "description": "The unit details are contained in the length_unit field." }, { "name": "TYPE_VOLUME", "description": "The unit details are contained in the volume_unit field." }, { "name": "TYPE_WEIGHT", "description": "The unit details are contained in the weight_unit field." }, { "name": "TYPE_GENERIC", "description": "The unit details are contained in the generic_unit field." } ], "description": "Describes the type of this unit and indicates which field contains the unit information. This is an ‘open’ enum.", "x-release-status": "PUBLIC" }, "MeasurementUnitVolume": { "type": "string", "enum": [ "GENERIC_FLUID_OUNCE", "GENERIC_SHOT", "GENERIC_CUP", "GENERIC_PINT", "GENERIC_QUART", "GENERIC_GALLON", "IMPERIAL_CUBIC_INCH", "IMPERIAL_CUBIC_FOOT", "IMPERIAL_CUBIC_YARD", "METRIC_MILLILITER", "METRIC_LITER" ], "x-enum-elements": [ { "name": "GENERIC_FLUID_OUNCE", "description": "The volume is measured in ounces." }, { "name": "GENERIC_SHOT", "description": "The volume is measured in shots." }, { "name": "GENERIC_CUP", "description": "The volume is measured in cups." }, { "name": "GENERIC_PINT", "description": "The volume is measured in pints." }, { "name": "GENERIC_QUART", "description": "The volume is measured in quarts." }, { "name": "GENERIC_GALLON", "description": "The volume is measured in gallons." }, { "name": "IMPERIAL_CUBIC_INCH", "description": "The volume is measured in cubic inches." }, { "name": "IMPERIAL_CUBIC_FOOT", "description": "The volume is measured in cubic feet." }, { "name": "IMPERIAL_CUBIC_YARD", "description": "The volume is measured in cubic yards." }, { "name": "METRIC_MILLILITER", "description": "The volume is measured in metric milliliters." }, { "name": "METRIC_LITER", "description": "The volume is measured in metric liters." } ], "description": "The unit of volume used to measure a quantity.", "x-release-status": "PUBLIC" }, "MeasurementUnitWeight": { "type": "string", "enum": [ "IMPERIAL_WEIGHT_OUNCE", "IMPERIAL_POUND", "IMPERIAL_STONE", "METRIC_MILLIGRAM", "METRIC_GRAM", "METRIC_KILOGRAM" ], "x-enum-elements": [ { "name": "IMPERIAL_WEIGHT_OUNCE", "description": "The weight is measured in ounces." }, { "name": "IMPERIAL_POUND", "description": "The weight is measured in pounds." }, { "name": "IMPERIAL_STONE", "description": "The weight is measured in stones." }, { "name": "METRIC_MILLIGRAM", "description": "The weight is measured in milligrams." }, { "name": "METRIC_GRAM", "description": "The weight is measured in grams." }, { "name": "METRIC_KILOGRAM", "description": "The weight is measured in kilograms." } ], "description": "Unit of weight used to measure a quantity.", "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" } } }, "Order": { "type": "object", "description": "Contains all information related to a single order to process with Square,\nincluding line items that specify the products to purchase. `Order` objects also\ninclude information about any associated tenders, refunds, and returns.\n\nAll Connect V2 Transactions have all been converted to Orders including all associated\nitemization data.", "x-release-status": "PUBLIC", "required": [ "location_id" ], "properties": { "id": { "type": "string", "description": "The order's unique ID.", "readOnly": true }, "location_id": { "type": "string", "description": "The ID of the seller location that this order is associated with.", "minLength": 1 }, "reference_id": { "type": [ "string", "null" ], "description": "A client-specified ID to associate an entity in another system\nwith this order.", "maxLength": 40 }, "source": { "$ref": "#/$defs/OrderSource", "description": "The origination details of the order." }, "customer_id": { "type": [ "string", "null" ], "description": "The ID of the [customer](entity:Customer) associated with the order.\n\nYou should specify a `customer_id` on the order (or the payment) to ensure that transactions\nare reliably linked to customers. Omitting this field might result in the creation of new\n[instant profiles](https://developer.squareup.com/docs/customers-api/what-it-does#instant-profiles).", "maxLength": 191, "x-release-status": "BETA" }, "line_items": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/OrderLineItem" }, "description": "The line items included in the order." }, "taxes": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/OrderLineItemTax" }, "description": "The list of all taxes associated with the order.\n\nTaxes can be scoped to either `ORDER` or `LINE_ITEM`. For taxes with `LINE_ITEM` scope, an\n`OrderLineItemAppliedTax` must be added to each line item that the tax applies to. For taxes\nwith `ORDER` scope, the server generates an `OrderLineItemAppliedTax` for every line item.\n\nOn reads, each tax in the list includes the total amount of that tax applied to the order.\n\n__IMPORTANT__: If `LINE_ITEM` scope is set on any taxes in this field, using the deprecated\n`line_items.taxes` field results in an error. Use `line_items.applied_taxes`\ninstead." }, "discounts": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/OrderLineItemDiscount" }, "description": "The list of all discounts associated with the order.\n\nDiscounts can be scoped to either `ORDER` or `LINE_ITEM`. For discounts scoped to `LINE_ITEM`,\nan `OrderLineItemAppliedDiscount` must be added to each line item that the discount applies to.\nFor discounts with `ORDER` scope, the server generates an `OrderLineItemAppliedDiscount`\nfor every line item.\n\n__IMPORTANT__: If `LINE_ITEM` scope is set on any discounts in this field, using the deprecated\n`line_items.discounts` field results in an error. Use `line_items.applied_discounts`\ninstead." }, "service_charges": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/OrderServiceCharge" }, "description": "A list of service charges applied to the order." }, "fulfillments": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/Fulfillment" }, "description": "Details about order fulfillment.\n\nOrders can only be created with at most one fulfillment. However, orders returned\nby the API might contain multiple fulfillments." }, "returns": { "type": "array", "items": { "$ref": "#/$defs/OrderReturn" }, "description": "A collection of items from sale orders being returned in this one. Normally part of an\nitemized return or exchange. There is exactly one `Return` object per sale `Order` being\nreferenced.", "readOnly": true, "x-release-status": "BETA" }, "return_amounts": { "$ref": "#/$defs/OrderMoneyAmounts", "description": "The rollup of the returned money amounts.", "readOnly": true, "x-release-status": "BETA" }, "net_amounts": { "$ref": "#/$defs/OrderMoneyAmounts", "description": "The net money amounts (sale money - return money).", "readOnly": true, "x-release-status": "BETA" }, "rounding_adjustment": { "$ref": "#/$defs/OrderRoundingAdjustment", "description": "A positive rounding adjustment to the total of the order. This adjustment is commonly\nused to apply cash rounding when the minimum unit of account is smaller than the lowest physical\ndenomination of the currency.", "readOnly": true, "x-release-status": "BETA" }, "tenders": { "type": "array", "items": { "$ref": "#/$defs/Tender" }, "description": "The tenders that were used to pay for the order.", "readOnly": true, "x-release-status": "BETA" }, "refunds": { "type": "array", "items": { "$ref": "#/$defs/Refund" }, "description": "The refunds that are part of this order.", "readOnly": true, "x-release-status": "BETA" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Application-defined data attached to this order. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "x-release-status": "BETA" }, "created_at": { "type": "string", "description": "The timestamp for when the order was created, at server side, in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "updated_at": { "type": "string", "description": "The timestamp for when the order was last updated, at server side, in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "closed_at": { "type": "string", "description": "The timestamp for when the order reached a terminal [state](entity:OrderState), in RFC 3339 format (for example \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "state": { "$ref": "#/$defs/OrderState", "description": "The current state of the order.\nSee [OrderState](#type-orderstate) for possible values" }, "version": { "type": "integer", "description": "The version number, which is incremented each time an update is committed to the order.\nOrders not created through the API do not include a version number and\ntherefore cannot be updated.\n\n[Read more about working with versions](https://developer.squareup.com/docs/orders-api/manage-orders/update-orders).", "x-release-status": "BETA" }, "total_money": { "$ref": "#/$defs/Money", "description": "The total amount of money to collect for the order.", "readOnly": true }, "total_tax_money": { "$ref": "#/$defs/Money", "description": "The total amount of tax money to collect for the order.", "readOnly": true }, "total_discount_money": { "$ref": "#/$defs/Money", "description": "The total amount of discount money to collect for the order.", "readOnly": true }, "total_tip_money": { "$ref": "#/$defs/Money", "description": "The total amount of tip money to collect for the order.", "readOnly": true }, "total_service_charge_money": { "$ref": "#/$defs/Money", "description": "The total amount of money collected in service charges for the order.\n\nNote: `total_service_charge_money` is the sum of `applied_money` fields for each individual\nservice charge. Therefore, `total_service_charge_money` only includes inclusive tax amounts,\nnot additive tax amounts.", "readOnly": true }, "ticket_name": { "type": [ "string", "null" ], "description": "A short-term identifier for the order (such as a customer first name,\ntable number, or auto-generated order number that resets daily).", "maxLength": 30, "x-release-status": "BETA" }, "pricing_options": { "$ref": "#/$defs/OrderPricingOptions", "description": "Pricing options for an order. The options affect how the order's price is calculated.\nThey can be used, for example, to apply automatic price adjustments that are based on\npreconfigured [pricing rules](entity:CatalogPricingRule)." }, "rewards": { "type": "array", "items": { "$ref": "#/$defs/OrderReward" }, "description": "A set-like list of Rewards that have been added to the Order.", "readOnly": true, "x-release-status": "BETA" }, "net_amount_due_money": { "$ref": "#/$defs/Money", "description": "The net amount of money due on the order.", "readOnly": true } } }, "OrderLineItem": { "type": "object", "description": "Represents a line item in an order. Each line item describes a different\nproduct to purchase, with its own quantity and price details.", "x-release-status": "PUBLIC", "required": [ "quantity" ], "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID that identifies the line item only within this order.", "maxLength": 60, "x-release-status": "BETA" }, "name": { "type": [ "string", "null" ], "description": "The name of the line item.", "maxLength": 512 }, "quantity": { "type": "string", "description": "The count, or measurement, of a line item being purchased:\n\nIf `quantity` is a whole number, and `quantity_unit` is not specified, then `quantity` denotes an item count. For example: `3` apples.\n\nIf `quantity` is a whole or decimal number, and `quantity_unit` is also specified, then `quantity` denotes a measurement. For example: `2.25` pounds of broccoli.\n\nFor more information, see [Specify item quantity and measurement unit](https://developer.squareup.com/docs/orders-api/create-orders#specify-item-quantity-and-measurement-unit).\n\nLine items with a quantity of `0` are automatically removed\nwhen paying for or otherwise completing the order.", "minLength": 1, "maxLength": 12 }, "quantity_unit": { "$ref": "#/$defs/OrderQuantityUnit", "description": "The measurement unit and decimal precision that this line item's quantity is measured in." }, "note": { "type": [ "string", "null" ], "description": "An optional note associated with the line item.", "maxLength": 2000 }, "catalog_object_id": { "type": [ "string", "null" ], "description": "The [CatalogItemVariation](entity:CatalogItemVariation) ID applied to this line item.", "maxLength": 192 }, "catalog_version": { "type": [ "integer", "null" ], "description": "The version of the catalog object that this line item references.", "format": "int64" }, "variation_name": { "type": [ "string", "null" ], "description": "The name of the variation applied to this line item.", "maxLength": 400 }, "item_type": { "$ref": "#/$defs/OrderLineItemItemType", "description": "The type of line item: an itemized sale, a non-itemized sale (custom amount), or the\nactivation or reloading of a gift card.\nSee [OrderLineItemItemType](#type-orderlineitemitemtype) for possible values" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Application-defined data attached to this line item. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "x-release-status": "BETA" }, "modifiers": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/OrderLineItemModifier" }, "description": "The [CatalogModifier](entity:CatalogModifier)s applied to this line item." }, "applied_taxes": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/OrderLineItemAppliedTax" }, "description": "The list of references to taxes applied to this line item. Each\n`OrderLineItemAppliedTax` has a `tax_uid` that references the `uid` of a\ntop-level `OrderLineItemTax` applied to the line item. On reads, the\namount applied is populated.\n\nAn `OrderLineItemAppliedTax` is automatically created on every line\nitem for all `ORDER` scoped taxes added to the order. `OrderLineItemAppliedTax`\nrecords for `LINE_ITEM` scoped taxes must be added in requests for the tax\nto apply to any line items.\n\nTo change the amount of a tax, modify the referenced top-level tax.", "x-release-status": "BETA" }, "applied_discounts": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/OrderLineItemAppliedDiscount" }, "description": "The list of references to discounts applied to this line item. Each\n`OrderLineItemAppliedDiscount` has a `discount_uid` that references the `uid` of a top-level\n`OrderLineItemDiscounts` applied to the line item. On reads, the amount\napplied is populated.\n\nAn `OrderLineItemAppliedDiscount` is automatically created on every line item for all\n`ORDER` scoped discounts that are added to the order. `OrderLineItemAppliedDiscount` records\nfor `LINE_ITEM` scoped discounts must be added in requests for the discount to apply to any\nline items.\n\nTo change the amount of a discount, modify the referenced top-level discount.", "x-release-status": "BETA" }, "applied_service_charges": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/OrderLineItemAppliedServiceCharge" }, "description": "The list of references to service charges applied to this line item. Each\n`OrderLineItemAppliedServiceCharge` has a `service_charge_id` that references the `uid` of a\ntop-level `OrderServiceCharge` applied to the line item. On reads, the amount applied is\npopulated.\n\nTo change the amount of a service charge, modify the referenced top-level service charge.", "x-release-status": "BETA" }, "base_price_money": { "$ref": "#/$defs/Money", "description": "The base price for a single unit of the line item." }, "variation_total_price_money": { "$ref": "#/$defs/Money", "description": "The total price of all item variations sold in this line item.\nThe price is calculated as `base_price_money` multiplied by `quantity`.\nIt does not include modifiers.", "readOnly": true }, "gross_sales_money": { "$ref": "#/$defs/Money", "description": "The amount of money made in gross sales for this line item.\nThe amount is calculated as the sum of the variation's total price and each modifier's total price.\nFor inclusive tax items in the US, Canada, and Japan, tax is deducted from `gross_sales_money`. For Europe and\nAustralia, inclusive tax remains as part of the gross sale calculation.", "readOnly": true }, "total_tax_money": { "$ref": "#/$defs/Money", "description": "The total amount of tax money to collect for the line item.", "readOnly": true }, "total_discount_money": { "$ref": "#/$defs/Money", "description": "The total amount of discount money to collect for the line item.", "readOnly": true }, "total_money": { "$ref": "#/$defs/Money", "description": "The total amount of money to collect for this line item.", "readOnly": true }, "pricing_blocklists": { "$ref": "#/$defs/OrderLineItemPricingBlocklists", "description": "Describes pricing adjustments that are blocked from automatic\napplication to a line item. For more information, see\n[Apply Taxes and Discounts](https://developer.squareup.com/docs/orders-api/apply-taxes-and-discounts).", "x-release-status": "BETA" }, "total_service_charge_money": { "$ref": "#/$defs/Money", "description": "The total amount of apportioned service charge money to collect for the line item.", "readOnly": true, "x-release-status": "BETA" } } }, "OrderLineItemAppliedDiscount": { "type": "object", "description": "Represents an applied portion of a discount to a line item in an order.\n\nOrder scoped discounts have automatically applied discounts present for each line item.\nLine-item scoped discounts must have applied discounts added manually for any applicable line\nitems. The corresponding applied money is automatically computed based on participating\nline items.", "x-release-status": "BETA", "required": [ "discount_uid" ], "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID that identifies the applied discount only within this order.", "maxLength": 60 }, "discount_uid": { "type": "string", "description": "The `uid` of the discount that the applied discount represents. It must\nreference a discount present in the `order.discounts` field.\n\nThis field is immutable. To change which discounts apply to a line item,\nyou must delete the discount and re-add it as a new `OrderLineItemAppliedDiscount`.", "minLength": 1, "maxLength": 60 }, "applied_money": { "$ref": "#/$defs/Money", "description": "The amount of money applied by the discount to the line item.", "readOnly": true } } }, "OrderLineItemAppliedServiceCharge": { "type": "object", "x-release-status": "BETA", "required": [ "service_charge_uid" ], "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID that identifies the applied service charge only within this order.", "maxLength": 60 }, "service_charge_uid": { "type": "string", "description": "The `uid` of the service charge that the applied service charge represents. It must\nreference a service charge present in the `order.service_charges` field.\n\nThis field is immutable. To change which service charges apply to a line item,\ndelete and add a new `OrderLineItemAppliedServiceCharge`.", "minLength": 1, "maxLength": 60 }, "applied_money": { "$ref": "#/$defs/Money", "description": "The amount of money applied by the service charge to the line item.", "readOnly": true } } }, "OrderLineItemAppliedTax": { "type": "object", "description": "Represents an applied portion of a tax to a line item in an order.\n\nOrder-scoped taxes automatically include the applied taxes in each line item.\nLine item taxes must be referenced from any applicable line items.\nThe corresponding applied money is automatically computed, based on the\nset of participating line items.", "x-release-status": "BETA", "required": [ "tax_uid" ], "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID that identifies the applied tax only within this order.", "maxLength": 60 }, "tax_uid": { "type": "string", "description": "The `uid` of the tax for which this applied tax represents. It must reference\na tax present in the `order.taxes` field.\n\nThis field is immutable. To change which taxes apply to a line item, delete and add a new\n`OrderLineItemAppliedTax`.", "minLength": 1, "maxLength": 60 }, "applied_money": { "$ref": "#/$defs/Money", "description": "The amount of money applied by the tax to the line item.", "readOnly": true } } }, "OrderLineItemDiscount": { "type": "object", "description": "Represents a discount that applies to one or more line items in an\norder.\n\nFixed-amount, order-scoped discounts are distributed across all non-zero line item totals.\nThe amount distributed to each line item is relative to the\namount contributed by the item to the order subtotal.", "x-release-status": "PUBLIC", "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID that identifies the discount only within this order.", "maxLength": 60, "x-release-status": "BETA" }, "catalog_object_id": { "type": [ "string", "null" ], "description": "The catalog object ID referencing [CatalogDiscount](entity:CatalogDiscount).", "maxLength": 192 }, "catalog_version": { "type": [ "integer", "null" ], "description": "The version of the catalog object that this discount references.", "format": "int64" }, "name": { "type": [ "string", "null" ], "description": "The discount's name.", "maxLength": 255 }, "type": { "$ref": "#/$defs/OrderLineItemDiscountType", "description": "The type of the discount.\n\nDiscounts that do not reference a catalog object ID must have a type of\n`FIXED_PERCENTAGE` or `FIXED_AMOUNT`.\nSee [OrderLineItemDiscountType](#type-orderlineitemdiscounttype) for possible values" }, "percentage": { "type": [ "string", "null" ], "description": "The percentage of the discount, as a string representation of a decimal number.\nA value of `7.25` corresponds to a percentage of 7.25%.\n\n`percentage` is not set for amount-based discounts.", "maxLength": 10 }, "amount_money": { "$ref": "#/$defs/Money", "description": "The total declared monetary amount of the discount.\n\n`amount_money` is not set for percentage-based discounts." }, "applied_money": { "$ref": "#/$defs/Money", "description": "The amount of discount actually applied to the line item.\n\nThe amount represents the amount of money applied as a line-item scoped discount.\nWhen an amount-based discount is scoped to the entire order, the value\nof `applied_money` is different than `amount_money` because the total\namount of the discount is distributed across all line items." }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Application-defined data attached to this discount. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "x-release-status": "BETA" }, "scope": { "$ref": "#/$defs/OrderLineItemDiscountScope", "description": "Indicates the level at which the discount applies. For `ORDER` scoped discounts,\nSquare generates references in `applied_discounts` on all order line items that do\nnot have them. For `LINE_ITEM` scoped discounts, the discount only applies to line items\nwith a discount reference in their `applied_discounts` field.\n\nThis field is immutable. To change the scope of a discount, you must delete\nthe discount and re-add it as a new discount.\nSee [OrderLineItemDiscountScope](#type-orderlineitemdiscountscope) for possible values" }, "reward_ids": { "type": "array", "items": { "type": "string" }, "description": "The reward IDs corresponding to this discount. The application and\nspecification of discounts that have `reward_ids` are completely controlled by the backing\ncriteria corresponding to the reward tiers of the rewards that are added to the order\nthrough the Loyalty API. To manually unapply discounts that are the result of added rewards,\nthe rewards must be removed from the order through the Loyalty API.", "readOnly": true, "x-release-status": "BETA" }, "pricing_rule_id": { "type": "string", "description": "The object ID of a [pricing rule](entity:CatalogPricingRule) to be applied\nautomatically to this discount. The specification and application of the discounts, to\nwhich a `pricing_rule_id` is assigned, are completely controlled by the corresponding\npricing rule.", "readOnly": true } } }, "OrderLineItemDiscountScope": { "type": "string", "enum": [ "OTHER_DISCOUNT_SCOPE", "LINE_ITEM", "ORDER" ], "x-enum-elements": [ { "name": "OTHER_DISCOUNT_SCOPE", "description": "Used for reporting only.\nThe original transaction discount scope is currently not supported by the API." }, { "name": "LINE_ITEM", "description": "The discount should be applied to only line items specified by\n`OrderLineItemAppliedDiscount` reference records." }, { "name": "ORDER", "description": "The discount should be applied to the entire order." } ], "description": "Indicates whether this is a line-item or order-level discount.", "x-release-status": "PUBLIC" }, "OrderLineItemDiscountType": { "type": "string", "enum": [ "UNKNOWN_DISCOUNT", "FIXED_PERCENTAGE", "FIXED_AMOUNT", "VARIABLE_PERCENTAGE", "VARIABLE_AMOUNT" ], "x-enum-elements": [ { "name": "UNKNOWN_DISCOUNT", "description": "Used for reporting only.\nThe original transaction discount type is currently not supported by the API." }, { "name": "FIXED_PERCENTAGE", "description": "Apply the discount as a fixed percentage (such as 5%) off the item price." }, { "name": "FIXED_AMOUNT", "description": "Apply the discount as a fixed monetary value (such as $1.00) off the item price." }, { "name": "VARIABLE_PERCENTAGE", "description": "Apply the discount as a variable percentage based on the item\nprice.\n\nThe specific discount percentage of a `VARIABLE_PERCENTAGE` discount\nis assigned at the time of the purchase." }, { "name": "VARIABLE_AMOUNT", "description": "Apply the discount as a variable amount based on the item price.\n\nThe specific discount amount of a `VARIABLE_AMOUNT` discount\nis assigned at the time of the purchase." } ], "description": "Indicates how the discount is applied to the associated line item or order.", "x-release-status": "PUBLIC" }, "OrderLineItemItemType": { "type": "string", "enum": [ "ITEM", "CUSTOM_AMOUNT", "GIFT_CARD" ], "x-enum-elements": [ { "name": "ITEM", "description": "Indicates that the line item is an itemized sale." }, { "name": "CUSTOM_AMOUNT", "description": "Indicates that the line item is a non-itemized sale." }, { "name": "GIFT_CARD", "description": "Indicates that the line item is a gift card sale. Gift cards sold through\nthe Orders API are sold in an unactivated state and can be activated through the\nGift Cards API using the line item `uid`." } ], "description": "Represents the line item type.", "x-release-status": "BETA" }, "OrderLineItemModifier": { "type": "object", "description": "A [CatalogModifier](entity:CatalogModifier).", "x-release-status": "PUBLIC", "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID that identifies the modifier only within this order.", "maxLength": 60, "x-release-status": "BETA" }, "catalog_object_id": { "type": [ "string", "null" ], "description": "The catalog object ID referencing [CatalogModifier](entity:CatalogModifier).", "maxLength": 192 }, "catalog_version": { "type": [ "integer", "null" ], "description": "The version of the catalog object that this modifier references.", "format": "int64" }, "name": { "type": [ "string", "null" ], "description": "The name of the item modifier.", "maxLength": 255 }, "quantity": { "type": [ "string", "null" ], "description": "The quantity of the line item modifier. The modifier quantity can be 0 or more.\nFor example, suppose a restaurant offers a cheeseburger on the menu. When a buyer orders\nthis item, the restaurant records the purchase by creating an `Order` object with a line item\nfor a burger. The line item includes a line item modifier: the name is cheese and the quantity\nis 1. The buyer has the option to order extra cheese (or no cheese). If the buyer chooses\nthe extra cheese option, the modifier quantity increases to 2. If the buyer does not want\nany cheese, the modifier quantity is set to 0." }, "base_price_money": { "$ref": "#/$defs/Money", "description": "The base price for the modifier.\n\n`base_price_money` is required for ad hoc modifiers.\nIf both `catalog_object_id` and `base_price_money` are set, `base_price_money` will\noverride the predefined [CatalogModifier](entity:CatalogModifier) price." }, "total_price_money": { "$ref": "#/$defs/Money", "description": "The total price of the item modifier for its line item.\nThis is the modifier's `base_price_money` multiplied by the line item's quantity.", "readOnly": true }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Application-defined data attached to this order. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "x-release-status": "BETA" } } }, "OrderLineItemPricingBlocklists": { "type": "object", "description": "Describes pricing adjustments that are blocked from automatic\napplication to a line item. For more information, see\n[Apply Taxes and Discounts](https://developer.squareup.com/docs/orders-api/apply-taxes-and-discounts).", "x-release-status": "BETA", "properties": { "blocked_discounts": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/OrderLineItemPricingBlocklistsBlockedDiscount" }, "description": "A list of discounts blocked from applying to the line item.\nDiscounts can be blocked by the `discount_uid` (for ad hoc discounts) or\nthe `discount_catalog_object_id` (for catalog discounts)." }, "blocked_taxes": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/OrderLineItemPricingBlocklistsBlockedTax" }, "description": "A list of taxes blocked from applying to the line item.\nTaxes can be blocked by the `tax_uid` (for ad hoc taxes) or\nthe `tax_catalog_object_id` (for catalog taxes)." } } }, "OrderLineItemPricingBlocklistsBlockedDiscount": { "type": "object", "description": "A discount to block from applying to a line item. The discount must be\nidentified by either `discount_uid` or `discount_catalog_object_id`, but not both.", "x-release-status": "BETA", "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID of the `BlockedDiscount` within the order.", "maxLength": 60 }, "discount_uid": { "type": [ "string", "null" ], "description": "The `uid` of the discount that should be blocked. Use this field to block\nad hoc discounts. For catalog discounts, use the `discount_catalog_object_id` field.", "maxLength": 60 }, "discount_catalog_object_id": { "type": [ "string", "null" ], "description": "The `catalog_object_id` of the discount that should be blocked.\nUse this field to block catalog discounts. For ad hoc discounts, use the\n`discount_uid` field.", "maxLength": 192 } } }, "OrderLineItemPricingBlocklistsBlockedTax": { "type": "object", "description": "A tax to block from applying to a line item. The tax must be\nidentified by either `tax_uid` or `tax_catalog_object_id`, but not both.", "x-release-status": "BETA", "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID of the `BlockedTax` within the order.", "maxLength": 60 }, "tax_uid": { "type": [ "string", "null" ], "description": "The `uid` of the tax that should be blocked. Use this field to block\nad hoc taxes. For catalog, taxes use the `tax_catalog_object_id` field.", "maxLength": 60 }, "tax_catalog_object_id": { "type": [ "string", "null" ], "description": "The `catalog_object_id` of the tax that should be blocked.\nUse this field to block catalog taxes. For ad hoc taxes, use the\n`tax_uid` field.", "maxLength": 192 } } }, "OrderLineItemTax": { "type": "object", "description": "Represents a tax that applies to one or more line item in the order.\n\nFixed-amount, order-scoped taxes are distributed across all non-zero line item totals.\nThe amount distributed to each line item is relative to the amount the item\ncontributes to the order subtotal.", "x-release-status": "PUBLIC", "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID that identifies the tax only within this order.", "maxLength": 60, "x-release-status": "BETA" }, "catalog_object_id": { "type": [ "string", "null" ], "description": "The catalog object ID referencing [CatalogTax](entity:CatalogTax).", "maxLength": 192 }, "catalog_version": { "type": [ "integer", "null" ], "description": "The version of the catalog object that this tax references.", "format": "int64" }, "name": { "type": [ "string", "null" ], "description": "The tax's name.", "maxLength": 255 }, "type": { "$ref": "#/$defs/OrderLineItemTaxType", "description": "Indicates the calculation method used to apply the tax.\nSee [OrderLineItemTaxType](#type-orderlineitemtaxtype) for possible values" }, "percentage": { "type": [ "string", "null" ], "description": "The percentage of the tax, as a string representation of a decimal\nnumber. For example, a value of `\"7.25\"` corresponds to a percentage of\n7.25%.", "maxLength": 10 }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Application-defined data attached to this tax. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "x-release-status": "BETA" }, "applied_money": { "$ref": "#/$defs/Money", "description": "The amount of money applied to the order by the tax.\n\n- For percentage-based taxes, `applied_money` is the money\ncalculated using the percentage." }, "scope": { "$ref": "#/$defs/OrderLineItemTaxScope", "description": "Indicates the level at which the tax applies. For `ORDER` scoped taxes,\nSquare generates references in `applied_taxes` on all order line items that do\nnot have them. For `LINE_ITEM` scoped taxes, the tax only applies to line items\nwith references in their `applied_taxes` field.\n\nThis field is immutable. To change the scope, you must delete the tax and\nre-add it as a new tax.\nSee [OrderLineItemTaxScope](#type-orderlineitemtaxscope) for possible values" }, "auto_applied": { "type": "boolean", "description": "Determines whether the tax was automatically applied to the order based on\nthe catalog configuration. For an example, see\n[Automatically Apply Taxes to an Order](https://developer.squareup.com/docs/orders-api/apply-taxes-and-discounts/auto-apply-taxes).", "readOnly": true, "x-release-status": "BETA" } } }, "OrderLineItemTaxScope": { "type": "string", "enum": [ "OTHER_TAX_SCOPE", "LINE_ITEM", "ORDER" ], "x-enum-elements": [ { "name": "OTHER_TAX_SCOPE", "description": "Used for reporting only.\nThe original transaction tax scope is currently not supported by the API." }, { "name": "LINE_ITEM", "description": "The tax should be applied only to line items specified by\nthe `OrderLineItemAppliedTax` reference records." }, { "name": "ORDER", "description": "The tax should be applied to the entire order." } ], "description": "Indicates whether this is a line-item or order-level tax.", "x-release-status": "PUBLIC" }, "OrderLineItemTaxType": { "type": "string", "enum": [ "UNKNOWN_TAX", "ADDITIVE", "INCLUSIVE" ], "x-enum-elements": [ { "name": "UNKNOWN_TAX", "description": "Used for reporting only.\nThe original transaction tax type is currently not supported by the API." }, { "name": "ADDITIVE", "description": "The tax is an additive tax. The tax amount is added on top of the price.\nFor example, an item with a cost of 1.00 USD and a 10% additive tax has a total\ncost to the buyer of 1.10 USD." }, { "name": "INCLUSIVE", "description": "The tax is an inclusive tax. Inclusive taxes are already included\nin the line item price or order total. For example, an item with a cost of\n1.00 USD and a 10% inclusive tax has a pretax cost of 0.91 USD\n(91 cents) and a 0.09 (9 cents) tax for a total cost of 1.00 USD to\nthe buyer." } ], "description": "Indicates how the tax is applied to the associated line item or order.", "x-release-status": "PUBLIC" }, "OrderMoneyAmounts": { "type": "object", "description": "A collection of various money amounts.", "x-release-status": "BETA", "properties": { "total_money": { "$ref": "#/$defs/Money", "description": "The total money." }, "tax_money": { "$ref": "#/$defs/Money", "description": "The money associated with taxes." }, "discount_money": { "$ref": "#/$defs/Money", "description": "The money associated with discounts." }, "tip_money": { "$ref": "#/$defs/Money", "description": "The money associated with tips." }, "service_charge_money": { "$ref": "#/$defs/Money", "description": "The money associated with service charges." } } }, "OrderPricingOptions": { "type": "object", "description": "Pricing options for an order. The options affect how the order's price is calculated.\nThey can be used, for example, to apply automatic price adjustments that are based on preconfigured\n[pricing rules](entity:CatalogPricingRule).", "x-release-status": "PUBLIC", "properties": { "auto_apply_discounts": { "type": [ "boolean", "null" ], "description": "The option to determine whether pricing rule-based\ndiscounts are automatically applied to an order." }, "auto_apply_taxes": { "type": [ "boolean", "null" ], "description": "The option to determine whether rule-based taxes are automatically\napplied to an order when the criteria of the corresponding rules are met.", "x-release-status": "BETA" } } }, "OrderQuantityUnit": { "type": "object", "description": "Contains the measurement unit for a quantity and a precision that\nspecifies the number of digits after the decimal point for decimal quantities.", "x-release-status": "PUBLIC", "properties": { "measurement_unit": { "$ref": "#/$defs/MeasurementUnit", "description": "A [MeasurementUnit](entity:MeasurementUnit) that represents the\nunit of measure for the quantity." }, "precision": { "type": [ "integer", "null" ], "description": "For non-integer quantities, represents the number of digits after the decimal point that are\nrecorded for this quantity.\n\nFor example, a precision of 1 allows quantities such as `\"1.0\"` and `\"1.1\"`, but not `\"1.01\"`.\n\nMin: 0. Max: 5." }, "catalog_object_id": { "type": [ "string", "null" ], "description": "The catalog object ID referencing the\n[CatalogMeasurementUnit](entity:CatalogMeasurementUnit).\n\nThis field is set when this is a catalog-backed measurement unit." }, "catalog_version": { "type": [ "integer", "null" ], "description": "The version of the catalog object that this measurement unit references.\n\nThis field is set when this is a catalog-backed measurement unit.", "format": "int64" } } }, "OrderReturn": { "type": "object", "description": "The set of line items, service charges, taxes, discounts, tips, and other items being returned in an order.", "x-release-status": "BETA", "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID that identifies the return only within this order.", "maxLength": 60 }, "source_order_id": { "type": [ "string", "null" ], "description": "An order that contains the original sale of these return line items. This is unset\nfor unlinked returns." }, "return_line_items": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/OrderReturnLineItem" }, "description": "A collection of line items that are being returned." }, "return_service_charges": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/OrderReturnServiceCharge" }, "description": "A collection of service charges that are being returned." }, "return_taxes": { "type": "array", "items": { "$ref": "#/$defs/OrderReturnTax" }, "description": "A collection of references to taxes being returned for an order, including the total\napplied tax amount to be returned. The taxes must reference a top-level tax ID from the source\norder.", "readOnly": true }, "return_discounts": { "type": "array", "items": { "$ref": "#/$defs/OrderReturnDiscount" }, "description": "A collection of references to discounts being returned for an order, including the total\napplied discount amount to be returned. The discounts must reference a top-level discount ID\nfrom the source order.", "readOnly": true }, "return_tips": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/OrderReturnTip" }, "description": "A collection of references to tips being returned for an order." }, "rounding_adjustment": { "$ref": "#/$defs/OrderRoundingAdjustment", "description": "A positive or negative rounding adjustment to the total value being returned. Adjustments are commonly\nused to apply cash rounding when the minimum unit of the account is smaller than the lowest\nphysical denomination of the currency." }, "return_amounts": { "$ref": "#/$defs/OrderMoneyAmounts", "description": "An aggregate monetary value being returned by this return entry." } } }, "OrderReturnDiscount": { "type": "object", "description": "Represents a discount being returned that applies to one or more return line items in an\norder.\n\nFixed-amount, order-scoped discounts are distributed across all non-zero return line item totals.\nThe amount distributed to each return line item is relative to that item’s contribution to the\norder subtotal.", "x-release-status": "BETA", "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID that identifies the returned discount only within this order.", "maxLength": 60 }, "source_discount_uid": { "type": [ "string", "null" ], "description": "The discount `uid` from the order that contains the original application of this discount.", "maxLength": 60 }, "catalog_object_id": { "type": [ "string", "null" ], "description": "The catalog object ID referencing [CatalogDiscount](entity:CatalogDiscount).", "maxLength": 192 }, "catalog_version": { "type": [ "integer", "null" ], "description": "The version of the catalog object that this discount references.", "format": "int64" }, "name": { "type": [ "string", "null" ], "description": "The discount's name.", "maxLength": 255 }, "type": { "$ref": "#/$defs/OrderLineItemDiscountType", "description": "The type of the discount. If it is created by the API, it is `FIXED_PERCENTAGE` or `FIXED_AMOUNT`.\n\nDiscounts that do not reference a catalog object ID must have a type of\n`FIXED_PERCENTAGE` or `FIXED_AMOUNT`.\nSee [OrderLineItemDiscountType](#type-orderlineitemdiscounttype) for possible values" }, "percentage": { "type": [ "string", "null" ], "description": "The percentage of the tax, as a string representation of a decimal number.\nA value of `\"7.25\"` corresponds to a percentage of 7.25%.\n\n`percentage` is not set for amount-based discounts.", "maxLength": 10 }, "amount_money": { "$ref": "#/$defs/Money", "description": "The total declared monetary amount of the discount.\n\n`amount_money` is not set for percentage-based discounts." }, "applied_money": { "$ref": "#/$defs/Money", "description": "The amount of discount actually applied to this line item. When an amount-based\ndiscount is at the order level, this value is different from `amount_money` because the discount\nis distributed across the line items.", "readOnly": true }, "scope": { "$ref": "#/$defs/OrderLineItemDiscountScope", "description": "Indicates the level at which the `OrderReturnDiscount` applies. For `ORDER` scoped\ndiscounts, the server generates references in `applied_discounts` on all\n`OrderReturnLineItem`s. For `LINE_ITEM` scoped discounts, the discount is only applied to\n`OrderReturnLineItem`s with references in their `applied_discounts` field.\nSee [OrderLineItemDiscountScope](#type-orderlineitemdiscountscope) for possible values" } } }, "OrderReturnLineItem": { "type": "object", "description": "The line item being returned in an order.", "x-release-status": "BETA", "required": [ "quantity" ], "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID for this return line-item entry.", "maxLength": 60 }, "source_line_item_uid": { "type": [ "string", "null" ], "description": "The `uid` of the line item in the original sale order.", "maxLength": 60 }, "name": { "type": [ "string", "null" ], "description": "The name of the line item.", "maxLength": 512 }, "quantity": { "type": "string", "description": "The quantity returned, formatted as a decimal number.\nFor example, `\"3\"`.\n\nLine items with a `quantity_unit` can have non-integer quantities.\nFor example, `\"1.70000\"`.", "minLength": 1, "maxLength": 12 }, "quantity_unit": { "$ref": "#/$defs/OrderQuantityUnit", "description": "The unit and precision that this return line item's quantity is measured in." }, "note": { "type": [ "string", "null" ], "description": "The note of the return line item.", "maxLength": 2000 }, "catalog_object_id": { "type": [ "string", "null" ], "description": "The [CatalogItemVariation](entity:CatalogItemVariation) ID applied to this return line item.", "maxLength": 192 }, "catalog_version": { "type": [ "integer", "null" ], "description": "The version of the catalog object that this line item references.", "format": "int64" }, "variation_name": { "type": [ "string", "null" ], "description": "The name of the variation applied to this return line item.", "maxLength": 400 }, "item_type": { "$ref": "#/$defs/OrderLineItemItemType", "description": "The type of line item: an itemized return, a non-itemized return (custom amount),\nor the return of an unactivated gift card sale.\nSee [OrderLineItemItemType](#type-orderlineitemitemtype) for possible values" }, "return_modifiers": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/OrderReturnLineItemModifier" }, "description": "The [CatalogModifier](entity:CatalogModifier)s applied to this line item." }, "applied_taxes": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/OrderLineItemAppliedTax" }, "description": "The list of references to `OrderReturnTax` entities applied to the return line item. Each\n`OrderLineItemAppliedTax` has a `tax_uid` that references the `uid` of a top-level\n`OrderReturnTax` applied to the return line item. On reads, the applied amount\nis populated." }, "applied_discounts": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/OrderLineItemAppliedDiscount" }, "description": "The list of references to `OrderReturnDiscount` entities applied to the return line item. Each\n`OrderLineItemAppliedDiscount` has a `discount_uid` that references the `uid` of a top-level\n`OrderReturnDiscount` applied to the return line item. On reads, the applied amount\nis populated." }, "base_price_money": { "$ref": "#/$defs/Money", "description": "The base price for a single unit of the line item." }, "variation_total_price_money": { "$ref": "#/$defs/Money", "description": "The total price of all item variations returned in this line item.\nThe price is calculated as `base_price_money` multiplied by `quantity` and\ndoes not include modifiers.", "readOnly": true }, "gross_return_money": { "$ref": "#/$defs/Money", "description": "The gross return amount of money calculated as (item base price + modifiers price) * quantity.", "readOnly": true }, "total_tax_money": { "$ref": "#/$defs/Money", "description": "The total amount of tax money to return for the line item.", "readOnly": true }, "total_discount_money": { "$ref": "#/$defs/Money", "description": "The total amount of discount money to return for the line item.", "readOnly": true }, "total_money": { "$ref": "#/$defs/Money", "description": "The total amount of money to return for this line item.", "readOnly": true }, "applied_service_charges": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/OrderLineItemAppliedServiceCharge" }, "description": "The list of references to `OrderReturnServiceCharge` entities applied to the return\nline item. Each `OrderLineItemAppliedServiceCharge` has a `service_charge_uid` that\nreferences the `uid` of a top-level `OrderReturnServiceCharge` applied to the return line\nitem. On reads, the applied amount is populated." }, "total_service_charge_money": { "$ref": "#/$defs/Money", "description": "The total amount of apportioned service charge money to return for the line item.", "readOnly": true } } }, "OrderReturnLineItemModifier": { "type": "object", "description": "A line item modifier being returned.", "x-release-status": "BETA", "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID that identifies the return modifier only within this order.", "maxLength": 60 }, "source_modifier_uid": { "type": [ "string", "null" ], "description": "The modifier `uid` from the order's line item that contains the\noriginal sale of this line item modifier.", "maxLength": 60 }, "catalog_object_id": { "type": [ "string", "null" ], "description": "The catalog object ID referencing [CatalogModifier](entity:CatalogModifier).", "maxLength": 192 }, "catalog_version": { "type": [ "integer", "null" ], "description": "The version of the catalog object that this line item modifier references.", "format": "int64" }, "name": { "type": [ "string", "null" ], "description": "The name of the item modifier.", "maxLength": 255 }, "base_price_money": { "$ref": "#/$defs/Money", "description": "The base price for the modifier.\n\n`base_price_money` is required for ad hoc modifiers.\nIf both `catalog_object_id` and `base_price_money` are set, `base_price_money` overrides the predefined [CatalogModifier](entity:CatalogModifier) price." }, "total_price_money": { "$ref": "#/$defs/Money", "description": "The total price of the item modifier for its line item.\nThis is the modifier's `base_price_money` multiplied by the line item's quantity.", "readOnly": true }, "quantity": { "type": [ "string", "null" ], "description": "The quantity of the line item modifier. The modifier quantity can be 0 or more.\nFor example, suppose a restaurant offers a cheeseburger on the menu. When a buyer orders\nthis item, the restaurant records the purchase by creating an `Order` object with a line item\nfor a burger. The line item includes a line item modifier: the name is cheese and the quantity\nis 1. The buyer has the option to order extra cheese (or no cheese). If the buyer chooses\nthe extra cheese option, the modifier quantity increases to 2. If the buyer does not want\nany cheese, the modifier quantity is set to 0." } } }, "OrderReturnServiceCharge": { "type": "object", "description": "Represents the service charge applied to the original order.", "x-release-status": "PUBLIC", "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID that identifies the return service charge only within this order.", "maxLength": 60, "x-release-status": "BETA" }, "source_service_charge_uid": { "type": [ "string", "null" ], "description": "The service charge `uid` from the order containing the original\nservice charge. `source_service_charge_uid` is `null` for\nunlinked returns.", "maxLength": 60 }, "name": { "type": [ "string", "null" ], "description": "The name of the service charge.", "maxLength": 255 }, "catalog_object_id": { "type": [ "string", "null" ], "description": "The catalog object ID of the associated [OrderServiceCharge](entity:OrderServiceCharge).", "maxLength": 192 }, "catalog_version": { "type": [ "integer", "null" ], "description": "The version of the catalog object that this service charge references.", "format": "int64" }, "percentage": { "type": [ "string", "null" ], "description": "The percentage of the service charge, as a string representation of\na decimal number. For example, a value of `\"7.25\"` corresponds to a\npercentage of 7.25%.\n\nEither `percentage` or `amount_money` should be set, but not both.", "maxLength": 10 }, "amount_money": { "$ref": "#/$defs/Money", "description": "The amount of a non-percentage-based service charge.\n\nEither `percentage` or `amount_money` should be set, but not both." }, "applied_money": { "$ref": "#/$defs/Money", "description": "The amount of money applied to the order by the service charge, including\nany inclusive tax amounts, as calculated by Square.\n\n- For fixed-amount service charges, `applied_money` is equal to `amount_money`.\n- For percentage-based service charges, `applied_money` is the money calculated using the percentage.", "readOnly": true }, "total_money": { "$ref": "#/$defs/Money", "description": "The total amount of money to collect for the service charge.\n\n__NOTE__: If an inclusive tax is applied to the service charge, `total_money`\ndoes not equal `applied_money` plus `total_tax_money` because the inclusive\ntax amount is already included in both `applied_money` and `total_tax_money`.", "readOnly": true }, "total_tax_money": { "$ref": "#/$defs/Money", "description": "The total amount of tax money to collect for the service charge.", "readOnly": true }, "calculation_phase": { "$ref": "#/$defs/OrderServiceChargeCalculationPhase", "description": "The calculation phase after which to apply the service charge.\nSee [OrderServiceChargeCalculationPhase](#type-orderservicechargecalculationphase) for possible values", "readOnly": true }, "taxable": { "type": [ "boolean", "null" ], "description": "Indicates whether the surcharge can be taxed. Service charges\ncalculated in the `TOTAL_PHASE` cannot be marked as taxable." }, "applied_taxes": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/OrderLineItemAppliedTax" }, "description": "The list of references to `OrderReturnTax` entities applied to the\n`OrderReturnServiceCharge`. Each `OrderLineItemAppliedTax` has a `tax_uid`\nthat references the `uid` of a top-level `OrderReturnTax` that is being\napplied to the `OrderReturnServiceCharge`. On reads, the applied amount is\npopulated.", "x-release-status": "BETA" }, "treatment_type": { "$ref": "#/$defs/OrderServiceChargeTreatmentType", "description": "The treatment type of the service charge.\nSee [OrderServiceChargeTreatmentType](#type-orderservicechargetreatmenttype) for possible values", "x-release-status": "BETA" }, "scope": { "$ref": "#/$defs/OrderServiceChargeScope", "description": "Indicates the level at which the apportioned service charge applies. For `ORDER`\nscoped service charges, Square generates references in `applied_service_charges` on\nall order line items that do not have them. For `LINE_ITEM` scoped service charges,\nthe service charge only applies to line items with a service charge reference in their\n`applied_service_charges` field.\n\nThis field is immutable. To change the scope of an apportioned service charge, you must delete\nthe apportioned service charge and re-add it as a new apportioned service charge.\nSee [OrderServiceChargeScope](#type-orderservicechargescope) for possible values", "x-release-status": "BETA" } } }, "OrderReturnTax": { "type": "object", "description": "Represents a tax being returned that applies to one or more return line items in an order.\n\nFixed-amount, order-scoped taxes are distributed across all non-zero return line item totals.\nThe amount distributed to each return line item is relative to that item’s contribution to the\norder subtotal.", "x-release-status": "BETA", "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID that identifies the returned tax only within this order.", "maxLength": 60 }, "source_tax_uid": { "type": [ "string", "null" ], "description": "The tax `uid` from the order that contains the original tax charge.", "maxLength": 60 }, "catalog_object_id": { "type": [ "string", "null" ], "description": "The catalog object ID referencing [CatalogTax](entity:CatalogTax).", "maxLength": 192 }, "catalog_version": { "type": [ "integer", "null" ], "description": "The version of the catalog object that this tax references.", "format": "int64" }, "name": { "type": [ "string", "null" ], "description": "The tax's name.", "maxLength": 255 }, "type": { "$ref": "#/$defs/OrderLineItemTaxType", "description": "Indicates the calculation method used to apply the tax.\nSee [OrderLineItemTaxType](#type-orderlineitemtaxtype) for possible values" }, "percentage": { "type": [ "string", "null" ], "description": "The percentage of the tax, as a string representation of a decimal number.\nFor example, a value of `\"7.25\"` corresponds to a percentage of 7.25%.", "maxLength": 10 }, "applied_money": { "$ref": "#/$defs/Money", "description": "The amount of money applied by the tax in an order.", "readOnly": true }, "scope": { "$ref": "#/$defs/OrderLineItemTaxScope", "description": "Indicates the level at which the `OrderReturnTax` applies. For `ORDER` scoped\ntaxes, Square generates references in `applied_taxes` on all\n`OrderReturnLineItem`s. For `LINE_ITEM` scoped taxes, the tax is only applied to\n`OrderReturnLineItem`s with references in their `applied_discounts` field.\nSee [OrderLineItemTaxScope](#type-orderlineitemtaxscope) for possible values" } } }, "OrderReturnTip": { "type": "object", "description": "A tip being returned.", "x-release-status": "BETA", "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID that identifies the tip only within this order.", "maxLength": 60 }, "applied_money": { "$ref": "#/$defs/Money", "description": "The amount of tip being returned\n--", "readOnly": true }, "source_tender_uid": { "type": [ "string", "null" ], "description": "The tender `uid` from the order that contains the original application of this tip.", "maxLength": 192 }, "source_tender_id": { "type": [ "string", "null" ], "description": "The tender `id` from the order that contains the original application of this tip.", "maxLength": 192 } } }, "OrderReward": { "type": "object", "description": "Represents a reward that can be applied to an order if the necessary\nreward tier criteria are met. Rewards are created through the Loyalty API.", "x-release-status": "BETA", "required": [ "id", "reward_tier_id" ], "properties": { "id": { "type": "string", "description": "The identifier of the reward.", "minLength": 1 }, "reward_tier_id": { "type": "string", "description": "The identifier of the reward tier corresponding to this reward.", "minLength": 1 } } }, "OrderRoundingAdjustment": { "type": "object", "description": "A rounding adjustment of the money being returned. Commonly used to apply cash rounding\nwhen the minimum unit of the account is smaller than the lowest physical denomination of the currency.", "x-release-status": "BETA", "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID that identifies the rounding adjustment only within this order.", "maxLength": 60 }, "name": { "type": [ "string", "null" ], "description": "The name of the rounding adjustment from the original sale order." }, "amount_money": { "$ref": "#/$defs/Money", "description": "The actual rounding adjustment amount." } } }, "OrderServiceCharge": { "type": "object", "description": "Represents a service charge applied to an order.", "x-release-status": "PUBLIC", "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID that identifies the service charge only within this order.", "maxLength": 60, "x-release-status": "BETA" }, "name": { "type": [ "string", "null" ], "description": "The name of the service charge.", "maxLength": 512 }, "catalog_object_id": { "type": [ "string", "null" ], "description": "The catalog object ID referencing the service charge [CatalogObject](entity:CatalogObject).", "maxLength": 192 }, "catalog_version": { "type": [ "integer", "null" ], "description": "The version of the catalog object that this service charge references.", "format": "int64" }, "percentage": { "type": [ "string", "null" ], "description": "The service charge percentage as a string representation of a\ndecimal number. For example, `\"7.25\"` indicates a service charge of 7.25%.\n\nExactly 1 of `percentage` or `amount_money` should be set.", "maxLength": 10 }, "amount_money": { "$ref": "#/$defs/Money", "description": "The amount of a non-percentage-based service charge.\n\nExactly one of `percentage` or `amount_money` should be set." }, "applied_money": { "$ref": "#/$defs/Money", "description": "The amount of money applied to the order by the service charge,\nincluding any inclusive tax amounts, as calculated by Square.\n\n- For fixed-amount service charges, `applied_money` is equal to `amount_money`.\n- For percentage-based service charges, `applied_money` is the money\ncalculated using the percentage.", "readOnly": true }, "total_money": { "$ref": "#/$defs/Money", "description": "The total amount of money to collect for the service charge.\n\n__Note__: If an inclusive tax is applied to the service charge,\n`total_money` does not equal `applied_money` plus `total_tax_money`\nbecause the inclusive tax amount is already included in both\n`applied_money` and `total_tax_money`.", "readOnly": true }, "total_tax_money": { "$ref": "#/$defs/Money", "description": "The total amount of tax money to collect for the service charge.", "readOnly": true }, "calculation_phase": { "$ref": "#/$defs/OrderServiceChargeCalculationPhase", "description": "The calculation phase at which to apply the service charge.\nSee [OrderServiceChargeCalculationPhase](#type-orderservicechargecalculationphase) for possible values" }, "taxable": { "type": [ "boolean", "null" ], "description": "Indicates whether the service charge can be taxed. If set to `true`,\norder-level taxes automatically apply to the service charge. Note that\nservice charges calculated in the `TOTAL_PHASE` cannot be marked as taxable." }, "applied_taxes": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/OrderLineItemAppliedTax" }, "description": "The list of references to the taxes applied to this service charge. Each\n`OrderLineItemAppliedTax` has a `tax_uid` that references the `uid` of a top-level\n`OrderLineItemTax` that is being applied to this service charge. On reads, the amount applied\nis populated.\n\nAn `OrderLineItemAppliedTax` is automatically created on every taxable service charge\nfor all `ORDER` scoped taxes that are added to the order. `OrderLineItemAppliedTax` records\nfor `LINE_ITEM` scoped taxes must be added in requests for the tax to apply to any taxable\nservice charge. Taxable service charges have the `taxable` field set to `true` and calculated\nin the `SUBTOTAL_PHASE`.\n\nTo change the amount of a tax, modify the referenced top-level tax.", "x-release-status": "BETA" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Application-defined data attached to this service charge. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "x-release-status": "BETA" }, "type": { "$ref": "#/$defs/OrderServiceChargeType", "description": "The type of the service charge.\nSee [OrderServiceChargeType](#type-orderservicechargetype) for possible values", "readOnly": true }, "treatment_type": { "$ref": "#/$defs/OrderServiceChargeTreatmentType", "description": "The treatment type of the service charge.\nSee [OrderServiceChargeTreatmentType](#type-orderservicechargetreatmenttype) for possible values", "x-release-status": "BETA" }, "scope": { "$ref": "#/$defs/OrderServiceChargeScope", "description": "Indicates the level at which the apportioned service charge applies. For `ORDER`\nscoped service charges, Square generates references in `applied_service_charges` on\nall order line items that do not have them. For `LINE_ITEM` scoped service charges,\nthe service charge only applies to line items with a service charge reference in their\n`applied_service_charges` field.\n\nThis field is immutable. To change the scope of an apportioned service charge, you must delete\nthe apportioned service charge and re-add it as a new apportioned service charge.\nSee [OrderServiceChargeScope](#type-orderservicechargescope) for possible values", "x-release-status": "BETA" } } }, "OrderServiceChargeCalculationPhase": { "type": "string", "enum": [ "SUBTOTAL_PHASE", "TOTAL_PHASE", "APPORTIONED_PERCENTAGE_PHASE", "APPORTIONED_AMOUNT_PHASE" ], "x-enum-elements": [ { "name": "SUBTOTAL_PHASE", "description": "The service charge is applied after discounts, but before\ntaxes." }, { "name": "TOTAL_PHASE", "description": "The service charge is applied after all discounts and taxes\nare applied." }, { "name": "APPORTIONED_PERCENTAGE_PHASE", "description": "The service charge is calculated as a compounding adjustment\nafter any discounts, but before amount based apportioned service charges\nand any tax considerations." }, { "name": "APPORTIONED_AMOUNT_PHASE", "description": "The service charge is calculated as a compounding adjustment\nafter any discounts and percentage based apportioned service charges,\nbut before any tax considerations." } ], "description": "Represents a phase in the process of calculating order totals.\nService charges are applied after the indicated phase.\n\n[Read more about how order totals are calculated.](https://developer.squareup.com/docs/orders-api/how-it-works#how-totals-are-calculated)", "x-release-status": "PUBLIC" }, "OrderServiceChargeScope": { "type": "string", "enum": [ "OTHER_SERVICE_CHARGE_SCOPE", "LINE_ITEM", "ORDER" ], "x-enum-elements": [ { "name": "OTHER_SERVICE_CHARGE_SCOPE", "description": "Used for reporting only.\nThe original transaction service charge scope is currently not supported by the API." }, { "name": "LINE_ITEM", "description": "The service charge should be applied to only line items specified by\n`OrderLineItemAppliedServiceCharge` reference records." }, { "name": "ORDER", "description": "The service charge should be applied to the entire order." } ], "description": "Indicates whether this is a line-item or order-level apportioned\nservice charge.", "x-release-status": "BETA" }, "OrderServiceChargeTreatmentType": { "type": "string", "enum": [ "LINE_ITEM_TREATMENT", "APPORTIONED_TREATMENT" ], "x-enum-elements": [ { "name": "LINE_ITEM_TREATMENT", "description": "" }, { "name": "APPORTIONED_TREATMENT", "description": "" } ], "description": "Indicates whether the service charge will be treated as a value-holding line item or\napportioned toward a line item.", "x-release-status": "BETA" }, "OrderServiceChargeType": { "type": "string", "enum": [ "AUTO_GRATUITY", "CUSTOM" ], "x-enum-elements": [ { "name": "AUTO_GRATUITY", "description": "" }, { "name": "CUSTOM", "description": "" } ], "x-release-status": "PUBLIC" }, "OrderSource": { "type": "object", "description": "Represents the origination details of an order.", "x-release-status": "PUBLIC", "properties": { "name": { "type": [ "string", "null" ], "description": "The name used to identify the place (physical or digital) that an order originates.\nIf unset, the name defaults to the name of the application that created the order." } } }, "OrderState": { "type": "string", "enum": [ "OPEN", "COMPLETED", "CANCELED", "DRAFT" ], "x-enum-elements": [ { "name": "OPEN", "description": "Indicates that the order is open. Open orders can be updated." }, { "name": "COMPLETED", "description": "Indicates that the order is completed. Completed orders are fully paid. This is a terminal state." }, { "name": "CANCELED", "description": "Indicates that the order is canceled. Canceled orders are not paid. This is a terminal state." }, { "name": "DRAFT", "description": "Indicates that the order is in a draft state. Draft orders can be updated,\nbut cannot be paid or fulfilled.\nFor more information, see [Create Orders](https://developer.squareup.com/docs/orders-api/create-orders)." } ], "description": "The state of the order.", "x-release-status": "PUBLIC" }, "Refund": { "type": "object", "description": "Represents a refund processed for a Square transaction.", "x-release-status": "PUBLIC", "required": [ "id", "location_id", "tender_id", "reason", "amount_money", "status" ], "properties": { "id": { "type": "string", "description": "The refund's unique ID.", "maxLength": 255 }, "location_id": { "type": "string", "description": "The ID of the refund's associated location.", "maxLength": 50 }, "transaction_id": { "type": [ "string", "null" ], "description": "The ID of the transaction that the refunded tender is part of.", "maxLength": 192 }, "tender_id": { "type": "string", "description": "The ID of the refunded tender.", "maxLength": 192 }, "created_at": { "type": "string", "description": "The timestamp for when the refund was created, in RFC 3339 format.", "maxLength": 32, "readOnly": true }, "reason": { "type": "string", "description": "The reason for the refund being issued.", "maxLength": 192 }, "amount_money": { "$ref": "#/$defs/Money", "description": "The amount of money refunded to the buyer." }, "status": { "$ref": "#/$defs/RefundStatus", "description": "The current status of the refund (`PENDING`, `APPROVED`, `REJECTED`,\nor `FAILED`).\nSee [RefundStatus](#type-refundstatus) for possible values" }, "processing_fee_money": { "$ref": "#/$defs/Money", "description": "The amount of Square processing fee money refunded to the *merchant*." }, "additional_recipients": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/AdditionalRecipient" }, "description": "Additional recipients (other than the merchant) receiving a portion of this refund.\nFor example, fees assessed on a refund of a purchase by a third party integration.", "x-release-status": "DEPRECATED" } } }, "RefundStatus": { "type": "string", "enum": [ "PENDING", "APPROVED", "REJECTED", "FAILED" ], "x-enum-elements": [ { "name": "PENDING", "description": "The refund is pending." }, { "name": "APPROVED", "description": "The refund has been approved by Square." }, { "name": "REJECTED", "description": "The refund has been rejected by Square." }, { "name": "FAILED", "description": "The refund failed." } ], "description": "Indicates a refund's current status.", "x-release-status": "PUBLIC" }, "Tender": { "type": "object", "description": "Represents a tender (i.e., a method of payment) used in a Square transaction.", "x-release-status": "PUBLIC", "required": [ "type" ], "properties": { "id": { "type": "string", "description": "The tender's unique ID. It is the associated payment ID.", "maxLength": 192 }, "location_id": { "type": [ "string", "null" ], "description": "The ID of the transaction's associated location.", "maxLength": 50 }, "transaction_id": { "type": [ "string", "null" ], "description": "The ID of the tender's associated transaction.", "maxLength": 192 }, "created_at": { "type": "string", "description": "The timestamp for when the tender was created, in RFC 3339 format.", "maxLength": 32, "readOnly": true }, "note": { "type": [ "string", "null" ], "description": "An optional note associated with the tender at the time of payment.", "maxLength": 500 }, "amount_money": { "$ref": "#/$defs/Money", "description": "The total amount of the tender, including `tip_money`. If the tender has a `payment_id`,\nthe `total_money` of the corresponding [Payment](entity:Payment) will be equal to the\n`amount_money` of the tender." }, "tip_money": { "$ref": "#/$defs/Money", "description": "The tip's amount of the tender." }, "processing_fee_money": { "$ref": "#/$defs/Money", "description": "The amount of any Square processing fees applied to the tender.\n\nThis field is not immediately populated when a new transaction is created.\nIt is usually available after about ten seconds." }, "customer_id": { "type": [ "string", "null" ], "description": "If the tender is associated with a customer or represents a customer's card on file,\nthis is the ID of the associated customer.", "maxLength": 191 }, "type": { "$ref": "#/$defs/TenderType", "description": "The type of tender, such as `CARD` or `CASH`.\nSee [TenderType](#type-tendertype) for possible values" }, "card_details": { "$ref": "#/$defs/TenderCardDetails", "description": "The details of the card tender.\n\nThis value is present only if the value of `type` is `CARD`." }, "cash_details": { "$ref": "#/$defs/TenderCashDetails", "description": "The details of the cash tender.\n\nThis value is present only if the value of `type` is `CASH`." }, "bank_account_details": { "$ref": "#/$defs/TenderBankAccountDetails", "description": "The details of the bank account tender.\n\nThis value is present only if the value of `type` is `BANK_ACCOUNT`." }, "buy_now_pay_later_details": { "$ref": "#/$defs/TenderBuyNowPayLaterDetails", "description": "The details of a Buy Now Pay Later tender.\n\nThis value is present only if the value of `type` is `BUY_NOW_PAY_LATER`." }, "square_account_details": { "$ref": "#/$defs/TenderSquareAccountDetails", "description": "The details of a Square Account tender.\n\nThis value is present only if the value of `type` is `SQUARE_ACCOUNT`." }, "additional_recipients": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/AdditionalRecipient" }, "description": "Additional recipients (other than the merchant) receiving a portion of this tender.\nFor example, fees assessed on the purchase by a third party integration.", "x-release-status": "DEPRECATED" }, "payment_id": { "type": [ "string", "null" ], "description": "The ID of the [Payment](entity:Payment) that corresponds to this tender.\nThis value is only present for payments created with the v2 Payments API.", "maxLength": 192 } } }, "TenderBankAccountDetails": { "type": "object", "description": "Represents the details of a tender with `type` `BANK_ACCOUNT`.\n\nSee [BankAccountPaymentDetails](entity:BankAccountPaymentDetails)\nfor more exposed details of a bank account payment.", "x-release-status": "PUBLIC", "properties": { "status": { "$ref": "#/$defs/TenderBankAccountDetailsStatus", "description": "The bank account payment's current state.\n\nSee [TenderBankAccountPaymentDetailsStatus](entity:TenderBankAccountDetailsStatus) for possible values.\nSee [TenderBankAccountDetailsStatus](#type-tenderbankaccountdetailsstatus) for possible values" } } }, "TenderBankAccountDetailsStatus": { "type": "string", "enum": [ "PENDING", "COMPLETED", "FAILED" ], "x-enum-elements": [ { "name": "PENDING", "description": "The bank account payment is in progress." }, { "name": "COMPLETED", "description": "The bank account payment has been completed." }, { "name": "FAILED", "description": "The bank account payment failed." } ], "description": "Indicates the bank account payment's current status.", "x-release-status": "PUBLIC" }, "TenderBuyNowPayLaterDetails": { "type": "object", "description": "Represents the details of a tender with `type` `BUY_NOW_PAY_LATER`.", "x-release-status": "PUBLIC", "properties": { "buy_now_pay_later_brand": { "$ref": "#/$defs/TenderBuyNowPayLaterDetailsBrand", "description": "The Buy Now Pay Later brand.\nSee [Brand](#type-brand) for possible values", "readOnly": true }, "status": { "$ref": "#/$defs/TenderBuyNowPayLaterDetailsStatus", "description": "The buy now pay later payment's current state (such as `AUTHORIZED` or\n`CAPTURED`). See [TenderBuyNowPayLaterDetailsStatus](entity:TenderBuyNowPayLaterDetailsStatus)\nfor possible values.\nSee [Status](#type-status) for possible values" } } }, "TenderBuyNowPayLaterDetailsBrand": { "type": "string", "enum": [ "OTHER_BRAND", "AFTERPAY" ], "x-enum-elements": [ { "name": "OTHER_BRAND", "description": "" }, { "name": "AFTERPAY", "description": "" } ], "x-release-status": "PUBLIC" }, "TenderBuyNowPayLaterDetailsStatus": { "type": "string", "enum": [ "AUTHORIZED", "CAPTURED", "VOIDED", "FAILED" ], "x-enum-elements": [ { "name": "AUTHORIZED", "description": "The buy now pay later payment has been authorized but not yet captured." }, { "name": "CAPTURED", "description": "The buy now pay later payment was authorized and subsequently captured (i.e., completed)." }, { "name": "VOIDED", "description": "The buy now pay later payment was authorized and subsequently voided (i.e., canceled)." }, { "name": "FAILED", "description": "The buy now pay later payment failed." } ], "x-release-status": "PUBLIC" }, "TenderCardDetails": { "type": "object", "description": "Represents additional details of a tender with `type` `CARD` or `SQUARE_GIFT_CARD`", "x-release-status": "PUBLIC", "properties": { "status": { "$ref": "#/$defs/TenderCardDetailsStatus", "description": "The credit card payment's current state (such as `AUTHORIZED` or\n`CAPTURED`). See [TenderCardDetailsStatus](entity:TenderCardDetailsStatus)\nfor possible values.\nSee [TenderCardDetailsStatus](#type-tendercarddetailsstatus) for possible values" }, "card": { "$ref": "#/$defs/Card", "description": "The credit card's non-confidential details." }, "entry_method": { "$ref": "#/$defs/TenderCardDetailsEntryMethod", "description": "The method used to enter the card's details for the transaction.\nSee [TenderCardDetailsEntryMethod](#type-tendercarddetailsentrymethod) for possible values" } } }, "TenderCardDetailsEntryMethod": { "type": "string", "enum": [ "SWIPED", "KEYED", "EMV", "ON_FILE", "CONTACTLESS" ], "x-enum-elements": [ { "name": "SWIPED", "description": "The card was swiped through a Square reader or Square stand." }, { "name": "KEYED", "description": "The card information was keyed manually into Square Point of Sale or a\nSquare-hosted web form." }, { "name": "EMV", "description": "The card was processed via EMV with a Square reader." }, { "name": "ON_FILE", "description": "The buyer's card details were already on file with Square." }, { "name": "CONTACTLESS", "description": "The card was processed via a contactless (i.e., NFC) transaction\nwith a Square reader." } ], "description": "Indicates the method used to enter the card's details.", "x-release-status": "PUBLIC" }, "TenderCardDetailsStatus": { "type": "string", "enum": [ "AUTHORIZED", "CAPTURED", "VOIDED", "FAILED" ], "x-enum-elements": [ { "name": "AUTHORIZED", "description": "The card transaction has been authorized but not yet captured." }, { "name": "CAPTURED", "description": "The card transaction was authorized and subsequently captured (i.e., completed)." }, { "name": "VOIDED", "description": "The card transaction was authorized and subsequently voided (i.e., canceled)." }, { "name": "FAILED", "description": "The card transaction failed." } ], "description": "Indicates the card transaction's current status.", "x-release-status": "PUBLIC" }, "TenderCashDetails": { "type": "object", "description": "Represents the details of a tender with `type` `CASH`.", "x-release-status": "PUBLIC", "properties": { "buyer_tendered_money": { "$ref": "#/$defs/Money", "description": "The total amount of cash provided by the buyer, before change is given." }, "change_back_money": { "$ref": "#/$defs/Money", "description": "The amount of change returned to the buyer." } } }, "TenderSquareAccountDetails": { "type": "object", "description": "Represents the details of a tender with `type` `SQUARE_ACCOUNT`.", "x-release-status": "PUBLIC", "properties": { "status": { "$ref": "#/$defs/TenderSquareAccountDetailsStatus", "description": "The Square Account payment's current state (such as `AUTHORIZED` or\n`CAPTURED`). See [TenderSquareAccountDetailsStatus](entity:TenderSquareAccountDetailsStatus)\nfor possible values.\nSee [Status](#type-status) for possible values" } } }, "TenderSquareAccountDetailsStatus": { "type": "string", "enum": [ "AUTHORIZED", "CAPTURED", "VOIDED", "FAILED" ], "x-enum-elements": [ { "name": "AUTHORIZED", "description": "The Square Account payment has been authorized but not yet captured." }, { "name": "CAPTURED", "description": "The Square Account payment was authorized and subsequently captured (i.e., completed)." }, { "name": "VOIDED", "description": "The Square Account payment was authorized and subsequently voided (i.e., canceled)." }, { "name": "FAILED", "description": "The Square Account payment failed." } ], "x-release-status": "PUBLIC" }, "TenderType": { "type": "string", "enum": [ "CARD", "CASH", "THIRD_PARTY_CARD", "SQUARE_GIFT_CARD", "NO_SALE", "BANK_ACCOUNT", "WALLET", "BUY_NOW_PAY_LATER", "SQUARE_ACCOUNT", "OTHER" ], "x-enum-elements": [ { "name": "CARD", "description": "A credit card." }, { "name": "CASH", "description": "Cash." }, { "name": "THIRD_PARTY_CARD", "description": "A credit card processed with a card processor other than Square.\n\nThis value applies only to merchants in countries where Square does not\nyet provide card processing." }, { "name": "SQUARE_GIFT_CARD", "description": "A Square gift card." }, { "name": "NO_SALE", "description": "This tender represents the register being opened for a \"no sale\" event." }, { "name": "BANK_ACCOUNT", "description": "A bank account payment." }, { "name": "WALLET", "description": "A payment from a digital wallet, e.g. Cash App, Paypay, Rakuten Pay,\nAu Pay, D Barai, Merpay, Wechat Pay, Alipay.\n\nNote: Some \"digital wallets\", including Google Pay and Apple Pay, facilitate\ncard payments. Those payments have the `CARD` type." }, { "name": "BUY_NOW_PAY_LATER", "description": "A Buy Now Pay Later payment." }, { "name": "SQUARE_ACCOUNT", "description": "A Square House Account payment." }, { "name": "OTHER", "description": "A form of tender that does not match any other value." } ], "description": "Indicates a tender's type.", "x-release-status": "PUBLIC" } } }