{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/api-evangelist/square/main/json-schema/square-cancel-invoice-response-schema.json", "title": "CancelInvoiceResponse", "description": "The response returned by the `CancelInvoice` request.", "x-generated": "2026-10-12", "x-method": "derived", "x-generator": "derive-json-schema.py", "x-source": "openapi/square-invoices-api-openapi.yml#/components/schemas/CancelInvoiceResponse", "type": "object", "x-release-status": "PUBLIC", "properties": { "invoice": { "$ref": "#/$defs/Invoice", "description": "The canceled invoice." }, "errors": { "type": "array", "items": { "$ref": "#/$defs/Error" }, "description": "Information about errors encountered during the request." } }, "$defs": { "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." } } }, "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" }, "Invoice": { "type": "object", "description": "Stores information about an invoice. You use the Invoices API to create and manage\ninvoices. For more information, see [Invoices API Overview](https://developer.squareup.com/docs/invoices-api/overview).", "x-release-status": "PUBLIC", "properties": { "id": { "type": "string", "description": "The Square-assigned ID of the invoice.", "readOnly": true }, "version": { "type": "integer", "description": "The Square-assigned version number, which is incremented each time an update is committed to the invoice." }, "location_id": { "type": [ "string", "null" ], "description": "The ID of the location that this invoice is associated with. \n\nIf specified in a `CreateInvoice` request, the value must match the `location_id` of the associated order.", "minLength": 1, "maxLength": 255 }, "order_id": { "type": [ "string", "null" ], "description": "The ID of the [order](entity:Order) for which the invoice is created. \nThis field is required when creating an invoice, and the order must be in the `OPEN` state.\n\nTo view the line items and other information for the associated order, call the \n[RetrieveOrder](api-endpoint:Orders-RetrieveOrder) endpoint using the order ID.", "minLength": 1, "maxLength": 255 }, "primary_recipient": { "$ref": "#/$defs/InvoiceRecipient", "description": "The customer who receives the invoice. This customer data is displayed on the invoice and used by Square to deliver the invoice. \n\nThis field is required to publish an invoice, and it must specify the `customer_id`." }, "payment_requests": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/InvoicePaymentRequest" }, "description": "The payment schedule for the invoice, represented by one or more payment requests that\ndefine payment settings, such as amount due and due date. An invoice supports the following payment request combinations:\n- One balance\n- One deposit with one balance\n- 2–12 installments \n- One deposit with 2–12 installments\n\nThis field is required when creating an invoice. It must contain at least one payment request. \nAll payment requests for the invoice must equal the total order amount. For more information, see \n[Configuring payment requests](https://developer.squareup.com/docs/invoices-api/create-publish-invoices#payment-requests).\n\nAdding `INSTALLMENT` payment requests to an invoice requires an \n[Invoices Plus subscription](https://developer.squareup.com/docs/invoices-api/overview#invoices-plus-subscription)." }, "delivery_method": { "$ref": "#/$defs/InvoiceDeliveryMethod", "description": "The delivery method that Square uses to send the invoice, reminders, and receipts to\nthe customer. After the invoice is published, Square processes the invoice based on the delivery\nmethod and payment request settings, either immediately or on the `scheduled_at` date, if specified.\nFor example, Square might send the invoice or receipt for an automatic payment. For invoices with\nautomatic payments, this field must be set to `EMAIL`.\n\nOne of the following is required when creating an invoice:\n- (Recommended) This `delivery_method` field. To configure an automatic payment, the\n`automatic_payment_source` field of the payment request is also required.\n- The deprecated `request_method` field of the payment request. Note that `invoice`\nobjects returned in responses do not include `request_method`.\nSee [InvoiceDeliveryMethod](#type-invoicedeliverymethod) for possible values" }, "invoice_number": { "type": [ "string", "null" ], "description": "A user-friendly invoice number that is displayed on the invoice. The value is unique within a location.\nIf not provided when creating an invoice, Square assigns a value.\nIt increments from 1 and is padded with zeros making it 7 characters long\n(for example, 0000001 and 0000002).", "minLength": 1, "maxLength": 191 }, "title": { "type": [ "string", "null" ], "description": "The title of the invoice, which is displayed on the invoice.", "minLength": 1, "maxLength": 255 }, "description": { "type": [ "string", "null" ], "description": "The description of the invoice, which is displayed on the invoice.", "minLength": 1, "maxLength": 65536 }, "scheduled_at": { "type": [ "string", "null" ], "description": "The timestamp when the invoice is scheduled for processing, in RFC 3339 format.\nAfter the invoice is published, Square processes the invoice on the specified date,\naccording to the delivery method and payment request settings.\n\nIf the field is not set, Square processes the invoice immediately after it is published." }, "public_url": { "type": "string", "description": "The URL of the Square-hosted invoice page.\nAfter you publish the invoice using the `PublishInvoice` endpoint, Square hosts the invoice\npage and returns the page URL in the response.", "readOnly": true }, "next_payment_amount_money": { "$ref": "#/$defs/Money", "description": "The current amount due for the invoice. In addition to the\namount due on the next payment request, this includes any overdue payment amounts.", "readOnly": true }, "status": { "$ref": "#/$defs/InvoiceStatus", "description": "The status of the invoice.\nSee [InvoiceStatus](#type-invoicestatus) for possible values", "readOnly": true }, "timezone": { "type": "string", "description": "The time zone used to interpret calendar dates on the invoice, such as `due_date`.\nWhen an invoice is created, this field is set to the `timezone` specified for the seller\nlocation. The value cannot be changed.\n\nFor example, a payment `due_date` of 2021-03-09 with a `timezone` of America/Los\\_Angeles\nbecomes overdue at midnight on March 9 in America/Los\\_Angeles (which equals a UTC timestamp\nof 2021-03-10T08:00:00Z).", "readOnly": true }, "created_at": { "type": "string", "description": "The timestamp when the invoice was created, in RFC 3339 format.", "readOnly": true }, "updated_at": { "type": "string", "description": "The timestamp when the invoice was last updated, in RFC 3339 format.", "readOnly": true }, "accepted_payment_methods": { "$ref": "#/$defs/InvoiceAcceptedPaymentMethods", "description": "The payment methods that customers can use to pay the invoice on the Square-hosted\ninvoice page. This setting is independent of any automatic payment requests for the invoice.\n\nThis field is required when creating an invoice and must set at least one payment method to `true`." }, "custom_fields": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/InvoiceCustomField" }, "description": "Additional seller-defined fields that are displayed on the invoice. For more information, see\n[Custom fields](https://developer.squareup.com/docs/invoices-api/overview#custom-fields).\n\nAdding custom fields to an invoice requires an \n[Invoices Plus subscription](https://developer.squareup.com/docs/invoices-api/overview#invoices-plus-subscription).\n\nMax: 2 custom fields" }, "subscription_id": { "type": "string", "description": "The ID of the [subscription](entity:Subscription) associated with the invoice.\nThis field is present only on subscription billing invoices.", "readOnly": true }, "sale_or_service_date": { "type": [ "string", "null" ], "description": "The date of the sale or the date that the service is rendered, in `YYYY-MM-DD` format.\nThis field can be used to specify a past or future date which is displayed on the invoice." }, "payment_conditions": { "type": [ "string", "null" ], "description": "**France only.** The payment terms and conditions that are displayed on the invoice. For more information, \nsee [Payment conditions](https://developer.squareup.com/docs/invoices-api/overview#payment-conditions).\n\nFor countries other than France, Square returns an `INVALID_REQUEST_ERROR` with a `BAD_REQUEST` code and \n\"Payment conditions are not supported for this location's country\" detail if this field is included in `CreateInvoice` or `UpdateInvoice` requests.", "minLength": 1, "maxLength": 2000 }, "store_payment_method_enabled": { "type": [ "boolean", "null" ], "description": "Indicates whether to allow a customer to save a credit or debit card as a card on file or a bank transfer as a\nbank account on file. If `true`, Square displays a __Save my card on file__ or __Save my bank on file__ checkbox on the\ninvoice payment page. Stored payment information can be used for future automatic payments. The default value is `false`." }, "attachments": { "type": "array", "items": { "$ref": "#/$defs/InvoiceAttachment" }, "description": "Metadata about the attachments on the invoice. Invoice attachments are managed using the\n[CreateInvoiceAttachment](api-endpoint:Invoices-CreateInvoiceAttachment) and [DeleteInvoiceAttachment](api-endpoint:Invoices-DeleteInvoiceAttachment) endpoints.", "readOnly": true } } }, "InvoiceAcceptedPaymentMethods": { "type": "object", "description": "The payment methods that customers can use to pay an [invoice](entity:Invoice) on the Square-hosted invoice payment page.", "x-release-status": "PUBLIC", "properties": { "card": { "type": [ "boolean", "null" ], "description": "Indicates whether credit card or debit card payments are accepted. The default value is `false`." }, "square_gift_card": { "type": [ "boolean", "null" ], "description": "Indicates whether Square gift card payments are accepted. The default value is `false`." }, "bank_account": { "type": [ "boolean", "null" ], "description": "Indicates whether ACH bank transfer payments are accepted. The default value is `false`." }, "buy_now_pay_later": { "type": [ "boolean", "null" ], "description": "Indicates whether Afterpay (also known as Clearpay) payments are accepted. The default value is `false`.\n\nThis option is allowed only for invoices that have a single payment request of the `BALANCE` type. This payment method is\nsupported if the seller account accepts Afterpay payments and the seller location is in a country where Afterpay\ninvoice payments are supported. As a best practice, consider enabling an additional payment method when allowing\n`buy_now_pay_later` payments. For more information, including detailed requirements and processing limits, see\n[Buy Now Pay Later payments with Afterpay](https://developer.squareup.com/docs/invoices-api/overview#buy-now-pay-later)." }, "cash_app_pay": { "type": [ "boolean", "null" ], "description": "Indicates whether Cash App payments are accepted. The default value is `false`.\n\nThis payment method is supported only for seller [locations](entity:Location) in the United States." } } }, "InvoiceAttachment": { "type": "object", "description": "Represents a file attached to an [invoice](entity:Invoice).", "x-release-status": "PUBLIC", "properties": { "id": { "type": "string", "description": "The Square-assigned ID of the attachment.", "readOnly": true }, "filename": { "type": "string", "description": "The file name of the attachment, which is displayed on the invoice.", "readOnly": true }, "description": { "type": "string", "description": "The description of the attachment, which is displayed on the invoice.\nThis field maps to the seller-defined **Message** field.", "readOnly": true }, "filesize": { "type": "integer", "description": "The file size of the attachment in bytes.", "readOnly": true }, "hash": { "type": "string", "description": "The MD5 hash that was generated from the file contents.", "readOnly": true }, "mime_type": { "type": "string", "description": "The mime type of the attachment.\nThe following mime types are supported: \nimage/gif, image/jpeg, image/png, image/tiff, image/bmp, application/pdf.", "readOnly": true }, "uploaded_at": { "type": "string", "description": "The timestamp when the attachment was uploaded, in RFC 3339 format.", "readOnly": true } } }, "InvoiceAutomaticPaymentSource": { "type": "string", "enum": [ "NONE", "CARD_ON_FILE", "BANK_ON_FILE" ], "x-enum-elements": [ { "name": "NONE", "description": "An automatic payment is not configured for the payment request." }, { "name": "CARD_ON_FILE", "description": "Use a card on file as the automatic payment method. On the due date, Square charges the card\nfor the amount of the payment request.\n\nFor `CARD_ON_FILE` payments, the invoice delivery method must be `EMAIL` and `card_id` must be\nspecified for the payment request before the invoice can be published." }, { "name": "BANK_ON_FILE", "description": "Use a bank account on file as the automatic payment method. On the due date, Square charges the bank\naccount for the amount of the payment request if the buyer has approved the payment. The buyer receives a\nrequest to approve the payment when the invoice is sent or the invoice is updated.\n\nThis payment method applies only to invoices that sellers create in the Seller Dashboard or other\nSquare product. The bank account is provided by the customer during the payment flow. \n\nYou cannot set `BANK_ON_FILE` as a payment method using the Invoices API, but you can change a `BANK_ON_FILE`\npayment method to `NONE` or `CARD_ON_FILE`. For `BANK_ON_FILE` payments, the invoice delivery method must be `EMAIL`." } ], "description": "Indicates the automatic payment method for an [invoice payment request](entity:InvoicePaymentRequest).", "x-release-status": "PUBLIC" }, "InvoiceCustomField": { "type": "object", "description": "An additional seller-defined and customer-facing field to include on the invoice. For more information, \nsee [Custom fields](https://developer.squareup.com/docs/invoices-api/overview#custom-fields).\n\nAdding custom fields to an invoice requires an \n[Invoices Plus subscription](https://developer.squareup.com/docs/invoices-api/overview#invoices-plus-subscription).", "x-release-status": "PUBLIC", "properties": { "label": { "type": [ "string", "null" ], "description": "The label or title of the custom field. This field is required for a custom field.", "maxLength": 30 }, "value": { "type": [ "string", "null" ], "description": "The text of the custom field. If omitted, only the label is rendered.", "maxLength": 2000 }, "placement": { "$ref": "#/$defs/InvoiceCustomFieldPlacement", "description": "The location of the custom field on the invoice. This field is required for a custom field.\nSee [InvoiceCustomFieldPlacement](#type-invoicecustomfieldplacement) for possible values" } } }, "InvoiceCustomFieldPlacement": { "type": "string", "enum": [ "ABOVE_LINE_ITEMS", "BELOW_LINE_ITEMS" ], "x-enum-elements": [ { "name": "ABOVE_LINE_ITEMS", "description": "Render the custom field above the invoice line items." }, { "name": "BELOW_LINE_ITEMS", "description": "Render the custom field below the invoice line items." } ], "description": "Indicates where to render a custom field on the Square-hosted invoice page and in emailed or PDF \ncopies of the invoice.", "x-release-status": "PUBLIC" }, "InvoiceDeliveryMethod": { "type": "string", "enum": [ "EMAIL", "SHARE_MANUALLY", "SMS" ], "x-enum-elements": [ { "name": "EMAIL", "description": "Directs Square to send invoices, reminders, and receipts to the customer using email." }, { "name": "SHARE_MANUALLY", "description": "Directs Square to take no action on the invoice. In this case, the seller\nor application developer follows up with the customer for payment. For example,\na seller might collect a payment in the Seller Dashboard or Point of Sale (POS) application.\nThe seller might also share the URL of the Square-hosted invoice page (`public_url`) with the customer to request payment." }, { "name": "SMS", "description": "Directs Square to send invoices and receipts to the customer using SMS (text message).\n\nYou cannot set `SMS` as a delivery method using the Invoices API, but you can change an `SMS` delivery method to `EMAIL` or `SHARE_MANUALLY`." } ], "description": "Indicates how Square delivers the [invoice](entity:Invoice) to the customer.", "x-release-status": "PUBLIC" }, "InvoicePaymentReminder": { "type": "object", "description": "Describes a payment request reminder (automatic notification) that Square sends\nto the customer. You configure a reminder relative to the payment request\n`due_date`.", "x-release-status": "PUBLIC", "properties": { "uid": { "type": "string", "description": "A Square-assigned ID that uniquely identifies the reminder within the\n`InvoicePaymentRequest`.", "readOnly": true }, "relative_scheduled_days": { "type": [ "integer", "null" ], "description": "The number of days before (a negative number) or after (a positive number)\nthe payment request `due_date` when the reminder is sent. For example, -3 indicates that\nthe reminder should be sent 3 days before the payment request `due_date`.", "minimum": -32767, "maximum": 32767 }, "message": { "type": [ "string", "null" ], "description": "The reminder message.", "minLength": 1, "maxLength": 1000 }, "status": { "$ref": "#/$defs/InvoicePaymentReminderStatus", "description": "The status of the reminder.\nSee [InvoicePaymentReminderStatus](#type-invoicepaymentreminderstatus) for possible values", "readOnly": true }, "sent_at": { "type": "string", "description": "If sent, the timestamp when the reminder was sent, in RFC 3339 format.", "readOnly": true } } }, "InvoicePaymentReminderStatus": { "type": "string", "enum": [ "PENDING", "NOT_APPLICABLE", "SENT" ], "x-enum-elements": [ { "name": "PENDING", "description": "The reminder will be sent on the `relative_scheduled_date` (if the invoice is published)." }, { "name": "NOT_APPLICABLE", "description": "The reminder is not applicable and is not sent. The following are examples\nof when reminders are not applicable and are not sent:\n- You schedule a reminder to be sent before the invoice is published.\n- The invoice is configured with multiple payment requests and a payment request reminder\nis configured to be sent after the next payment request `due_date`.\n- Two reminders (for different payment requests) are configured to be sent on the\nsame date. Therefore, only one reminder is sent.\n- You configure a reminder to be sent on the date that the invoice is scheduled to be sent.\n- The payment request is already paid.\n- The invoice status is `CANCELED` or `FAILED`." }, { "name": "SENT", "description": "The reminder is sent." } ], "description": "The status of a payment request reminder.", "x-release-status": "PUBLIC" }, "InvoicePaymentRequest": { "type": "object", "description": "Represents a payment request for an [invoice](entity:Invoice). Invoices can specify a maximum\nof 13 payment requests, with up to 12 `INSTALLMENT` request types. For more information, \nsee [Configuring payment requests](https://developer.squareup.com/docs/invoices-api/create-publish-invoices#payment-requests).\n\nAdding `INSTALLMENT` payment requests to an invoice requires an \n[Invoices Plus subscription](https://developer.squareup.com/docs/invoices-api/overview#invoices-plus-subscription).", "x-release-status": "PUBLIC", "properties": { "uid": { "type": [ "string", "null" ], "description": "The Square-generated ID of the payment request in an [invoice](entity:Invoice).", "minLength": 1, "maxLength": 255 }, "request_method": { "$ref": "#/$defs/InvoiceRequestMethod", "description": "Indicates how Square processes the payment request. DEPRECATED at version 2021-01-21. Replaced by the\n`Invoice.delivery_method` and `InvoicePaymentRequest.automatic_payment_source` fields.\n\nOne of the following is required when creating an invoice:\n- (Recommended) The `delivery_method` field of the invoice. To configure an automatic payment, the\n`automatic_payment_source` field of the payment request is also required.\n- This `request_method` field. Note that `invoice` objects returned in responses do not include `request_method`.\nSee [InvoiceRequestMethod](#type-invoicerequestmethod) for possible values", "x-release-status": "DEPRECATED" }, "request_type": { "$ref": "#/$defs/InvoiceRequestType", "description": "Identifies the payment request type. This type defines how the payment request amount is determined. \nThis field is required to create a payment request.\nSee [InvoiceRequestType](#type-invoicerequesttype) for possible values" }, "due_date": { "type": [ "string", "null" ], "description": "The due date (in the invoice's time zone) for the payment request, in `YYYY-MM-DD` format. This field\nis required to create a payment request. If an `automatic_payment_source` is defined for the request, Square\ncharges the payment source on this date.\n\nAfter this date, the invoice becomes overdue. For example, a payment `due_date` of 2021-03-09 with a `timezone`\nof America/Los\\_Angeles becomes overdue at midnight on March 9 in America/Los\\_Angeles (which equals a UTC\ntimestamp of 2021-03-10T08:00:00Z)." }, "fixed_amount_requested_money": { "$ref": "#/$defs/Money", "description": "If the payment request specifies `DEPOSIT` or `INSTALLMENT` as the `request_type`, \nthis indicates the request amount.\nYou cannot specify this when `request_type` is `BALANCE` or when the \npayment request includes the `percentage_requested` field." }, "percentage_requested": { "type": [ "string", "null" ], "description": "Specifies the amount for the payment request in percentage:\n\n- When the payment `request_type` is `DEPOSIT`, it is the percentage of the order's total amount.\n- When the payment `request_type` is `INSTALLMENT`, it is the percentage of the order's total less \nthe deposit, if requested. The sum of the `percentage_requested` in all installment \npayment requests must be equal to 100.\n\nYou cannot specify this when the payment `request_type` is `BALANCE` or when the \npayment request specifies the `fixed_amount_requested_money` field." }, "tipping_enabled": { "type": [ "boolean", "null" ], "description": "If set to true, the Square-hosted invoice page (the `public_url` field of the invoice) \nprovides a place for the customer to pay a tip. \n\nThis field is allowed only on the final payment request \nand the payment `request_type` must be `BALANCE` or `INSTALLMENT`." }, "automatic_payment_source": { "$ref": "#/$defs/InvoiceAutomaticPaymentSource", "description": "The payment method for an automatic payment.\n\nThe default value is `NONE`.\nSee [InvoiceAutomaticPaymentSource](#type-invoiceautomaticpaymentsource) for possible values" }, "card_id": { "type": [ "string", "null" ], "description": "The ID of the credit or debit card on file to charge for the payment request. To get the cards on file for a customer,\ncall [ListCards](api-endpoint:Cards-ListCards) and include the `customer_id` of the invoice recipient.", "minLength": 1, "maxLength": 255 }, "reminders": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/InvoicePaymentReminder" }, "description": "A list of one or more reminders to send for the payment request." }, "computed_amount_money": { "$ref": "#/$defs/Money", "description": "The amount of the payment request, computed using the order amount and information from the various payment\nrequest fields (`request_type`, `fixed_amount_requested_money`, and `percentage_requested`).", "readOnly": true }, "total_completed_amount_money": { "$ref": "#/$defs/Money", "description": "The amount of money already paid for the specific payment request. \nThis amount might include a rounding adjustment if the most recent invoice payment \nwas in cash in a currency that rounds cash payments (such as, `CAD` or `AUD`).", "readOnly": true }, "rounding_adjustment_included_money": { "$ref": "#/$defs/Money", "description": "If the most recent payment was a cash payment \nin a currency that rounds cash payments (such as, `CAD` or `AUD`) and the payment \nis rounded from `computed_amount_money` in the payment request, then this \nfield specifies the rounding adjustment applied. This amount \nmight be negative.", "readOnly": true } } }, "InvoiceRecipient": { "type": "object", "description": "Represents a snapshot of customer data. This object stores customer data that is displayed on the invoice \nand that Square uses to deliver the invoice.\n\nWhen you provide a customer ID for a draft invoice, Square retrieves the associated customer profile and populates \nthe remaining `InvoiceRecipient` fields. You cannot update these fields after the invoice is published. \nSquare updates the customer ID in response to a merge operation, but does not update other fields.", "x-release-status": "PUBLIC", "properties": { "customer_id": { "type": [ "string", "null" ], "description": "The ID of the customer. This is the customer profile ID that \nyou provide when creating a draft invoice.", "minLength": 1, "maxLength": 255 }, "given_name": { "type": "string", "description": "The recipient's given (that is, first) name.", "readOnly": true }, "family_name": { "type": "string", "description": "The recipient's family (that is, last) name.", "readOnly": true }, "email_address": { "type": "string", "description": "The recipient's email address.", "readOnly": true }, "address": { "$ref": "#/$defs/Address", "description": "The recipient's physical address.", "readOnly": true }, "phone_number": { "type": "string", "description": "The recipient's phone number.", "readOnly": true }, "company_name": { "type": "string", "description": "The name of the recipient's company.", "readOnly": true }, "tax_ids": { "$ref": "#/$defs/InvoiceRecipientTaxIds", "description": "The recipient's tax IDs. The country of the seller account determines whether this field \nis available for the customer. For more information, see [Invoice recipient tax IDs](https://developer.squareup.com/docs/invoices-api/overview#recipient-tax-ids).", "readOnly": true } } }, "InvoiceRecipientTaxIds": { "type": "object", "description": "Represents the tax IDs for an invoice recipient. The country of the seller account determines \nwhether the corresponding `tax_ids` field is available for the customer. For more information, \nsee [Invoice recipient tax IDs](https://developer.squareup.com/docs/invoices-api/overview#recipient-tax-ids).", "x-release-status": "PUBLIC", "properties": { "eu_vat": { "type": "string", "description": "The EU VAT identification number for the invoice recipient. For example, `IE3426675K`.", "readOnly": true } } }, "InvoiceRequestMethod": { "type": "string", "enum": [ "EMAIL", "CHARGE_CARD_ON_FILE", "SHARE_MANUALLY", "CHARGE_BANK_ON_FILE", "SMS", "SMS_CHARGE_CARD_ON_FILE", "SMS_CHARGE_BANK_ON_FILE" ], "x-enum-elements": [ { "name": "EMAIL", "description": "Directs Square to send invoices, reminders, and receipts to the customer using email.\nSquare sends the invoice after it is published (either immediately or at the `scheduled_at`\ntime, if specified in the [invoice](entity:Invoice))." }, { "name": "CHARGE_CARD_ON_FILE", "description": "Directs Square to charge the card on file on the `due_date` specified in the payment request\nand to use email to send invoices, reminders, and receipts." }, { "name": "SHARE_MANUALLY", "description": "Directs Square to take no specific action on the invoice. In this case, the seller \n(or the application developer) follows up with the customer for payment. For example, \na seller might collect a payment in the Seller Dashboard or use the Point of Sale (POS) application. \nThe seller might also share the URL of the Square-hosted invoice page (`public_url`) with the customer requesting payment." }, { "name": "CHARGE_BANK_ON_FILE", "description": "Directs Square to charge the customer's bank account on file and to use email to send invoices, reminders, and receipts.\nThe customer must approve the payment.\n\nThe bank on file payment method applies only to invoices that sellers create in the Seller Dashboard or other\nSquare product. The bank account is provided by the customer during the payment flow. You \ncannot set `CHARGE_BANK_ON_FILE` as a request method using the Invoices API." }, { "name": "SMS", "description": "Directs Square to send invoices and receipts to the customer using SMS (text message). Square sends the invoice\nafter it is published (either immediately or at the `scheduled_at` time, if specified in the [invoice](entity:Invoice)). \n\nYou cannot set `SMS` as a request method using the Invoices API." }, { "name": "SMS_CHARGE_CARD_ON_FILE", "description": "Directs Square to charge the card on file on the `due_date` specified in the payment request and to\nuse SMS (text message) to send invoices and receipts. \n\nYou cannot set `SMS_CHARGE_CARD_ON_FILE` as a request method using the Invoices API." }, { "name": "SMS_CHARGE_BANK_ON_FILE", "description": "Directs Square to charge the customer's bank account on file and to use SMS (text message) to send invoices and receipts.\nThe customer must approve the payment.\n\nThe bank on file payment method applies only to invoices that sellers create in the Seller Dashboard\nor other Square product. The bank account is provided by the customer during the payment flow. \nYou cannot set `SMS_CHARGE_BANK_ON_FILE` as a request method using the Invoices API." } ], "description": "Specifies the action for Square to take for processing the invoice. For example, \nemail the invoice, charge a customer's card on file, or do nothing. DEPRECATED at\nversion 2021-01-21. The corresponding `request_method` field is replaced by the\n`Invoice.delivery_method` and `InvoicePaymentRequest.automatic_payment_source` fields.", "x-release-status": "DEPRECATED" }, "InvoiceRequestType": { "type": "string", "enum": [ "BALANCE", "DEPOSIT", "INSTALLMENT" ], "x-enum-elements": [ { "name": "BALANCE", "description": "A request for a balance payment. The balance amount is computed as follows: \n\n- If the invoice specifies only a balance payment request, the balance amount is the \ntotal amount of the associated order. \n- If the invoice also specifies a deposit request, the balance amount is the amount \nremaining after the deposit.\n\n`INSTALLMENT` and `BALANCE` payment requests are not allowed in the same invoice." }, { "name": "DEPOSIT", "description": "A request for a deposit payment. You have the option of specifying \nan exact amount or a percentage of the total order amount. If you request a deposit, \nit must be due before any other payment requests." }, { "name": "INSTALLMENT", "description": "A request for an installment payment. Installments allow buyers to pay the invoice over time. Installments can optionally be combined with a deposit. \n\nAdding `INSTALLMENT` payment requests to an invoice requires an \n[Invoices Plus subscription](https://developer.squareup.com/docs/invoices-api/overview#invoices-plus-subscription)." } ], "description": "Indicates the type of the payment request. For more information, see \n[Configuring payment requests](https://developer.squareup.com/docs/invoices-api/create-publish-invoices#payment-requests).", "x-release-status": "PUBLIC" }, "InvoiceStatus": { "type": "string", "enum": [ "DRAFT", "UNPAID", "SCHEDULED", "PARTIALLY_PAID", "PAID", "PARTIALLY_REFUNDED", "REFUNDED", "CANCELED", "FAILED", "PAYMENT_PENDING" ], "x-enum-elements": [ { "name": "DRAFT", "description": "The invoice is a draft. You must publish a draft invoice before Square can process it.\nA draft invoice has no `public_url`, so it is not available to customers." }, { "name": "UNPAID", "description": "The invoice is published but not yet paid." }, { "name": "SCHEDULED", "description": "The invoice is scheduled to be processed. On the scheduled date,\nSquare sends the invoice, initiates an automatic payment, or takes no action, depending on\nthe delivery method and payment request settings. Square also sets the invoice status to the\nappropriate state: `UNPAID`, `PAID`, `PARTIALLY_PAID`, or `PAYMENT_PENDING`." }, { "name": "PARTIALLY_PAID", "description": "A partial payment is received for the invoice." }, { "name": "PAID", "description": "The customer paid the invoice in full." }, { "name": "PARTIALLY_REFUNDED", "description": "The invoice is paid (or partially paid) and some but not all the amount paid is\nrefunded." }, { "name": "REFUNDED", "description": "The full amount that the customer paid for the invoice is refunded." }, { "name": "CANCELED", "description": "The invoice is canceled. Square no longer requests payments from the customer.\nThe `public_url` page remains and is accessible, but it displays the invoice\nas canceled and does not accept payment." }, { "name": "FAILED", "description": "Square canceled the invoice due to suspicious activity." }, { "name": "PAYMENT_PENDING", "description": "A payment on the invoice was initiated but has not yet been processed.\n\nWhen in this state, invoices cannot be updated and other payments cannot be initiated." } ], "description": "Indicates the status of an invoice.", "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" } } } } }