openapi: 3.0.0 info: version: '2.0' title: Square ApplePay Checkout API description: 'Supercharge Square for sellers of every size. Our entire connected commerce platform from elegant hardware to a rich suite of Square APIs is yours to build with. Whether youre developing an app or composing a bespoke solution, this is the place to make it happen. ' termsOfService: https://connect.squareup.com/tos contact: name: Square Developer Platform email: developers@squareup.com url: https://squareup.com/developers license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html externalDocs: description: 'Read the official documentation here:' url: https://docs.connect.squareup.com/ x-server-configuration: default-environment: production default-server: default environments: - name: production servers: - name: default url: https://connect.squareup.com - name: sandbox servers: - name: default url: https://connect.squareupsandbox.com - name: custom servers: - name: default url: '{custom_url}' parameters: - name: custom_url description: Sets the base URL requests are made to. Defaults to `https://connect.squareup.com` type: string example: https://connect.squareup.com x-square-generic-error-codes: - ACCESS_TOKEN_EXPIRED - ACCESS_TOKEN_REVOKED - API_VERSION_INCOMPATIBLE - APPLICATION_DISABLED - ARRAY_EMPTY - ARRAY_LENGTH_TOO_LONG - ARRAY_LENGTH_TOO_SHORT - BAD_CERTIFICATE - BAD_GATEWAY - BAD_REQUEST - CONFLICT - CONFLICTING_PARAMETERS - CURRENCY_MISMATCH - EXPECTED_ARRAY - EXPECTED_BASE64_ENCODED_BYTE_ARRAY - EXPECTED_BOOLEAN - EXPECTED_FLOAT - EXPECTED_INTEGER - EXPECTED_JSON_BODY - EXPECTED_MAP - EXPECTED_OBJECT - EXPECTED_STRING - FORBIDDEN - GATEWAY_TIMEOUT - GONE - IDEMPOTENCY_KEY_REUSED - INCORRECT_TYPE - INSUFFICIENT_SCOPES - INTERNAL_SERVER_ERROR - INVALID_ARRAY_VALUE - INVALID_CONTENT_TYPE - INVALID_CURSOR - INVALID_ENUM_VALUE - INVALID_FORM_VALUE - INVALID_SORT_ORDER - INVALID_SQUARE_VERSION_FORMAT - INVALID_TIME - INVALID_TIME_RANGE - INVALID_VALUE - LOCATION_MISMATCH - MAP_KEY_LENGTH_TOO_LONG - MAP_KEY_LENGTH_TOO_SHORT - MERCHANT_SUBSCRIPTION_NOT_FOUND - METHOD_NOT_ALLOWED - MISSING_REQUIRED_PARAMETER - NOT_ACCEPTABLE - NOT_FOUND - NOT_IMPLEMENTED - NO_FIELDS_SET - RATE_LIMITED - REQUEST_ENTITY_TOO_LARGE - REQUEST_TIMEOUT - SANDBOX_NOT_SUPPORTED - SERVICE_UNAVAILABLE - TOO_MANY_MAP_ENTRIES - UNAUTHORIZED - UNEXPECTED_VALUE - UNKNOWN_BODY_PARAMETER - UNKNOWN_QUERY_PARAMETER - UNPROCESSABLE_ENTITY - UNSUPPORTED_MEDIA_TYPE - V1_ACCESS_TOKEN - V1_APPLICATION - VALUE_EMPTY - VALUE_REGEX_MISMATCH - VALUE_TOO_HIGH - VALUE_TOO_LONG - VALUE_TOO_LOW - VALUE_TOO_SHORT servers: - url: https://connect.squareup.com variables: {} tags: - name: Checkout paths: /v2/locations/{location_id}/checkouts: post: tags: - Checkout summary: Square Create Checkout operationId: CreateCheckout x-microcks-operation: delay: 0 dispatcher: FALLBACK description: "Links a `checkoutId` to a `checkout_page_url` that customers are\ndirected to in order to provide their payment information using a\npayment processing workflow hosted on connect.squareup.com. \n\n\nNOTE: The Checkout API has been updated with new features. \nFor more information, see [Checkout API highlights](https://developer.squareup.com/docs/checkout-api#checkout-api-highlights)." x-release-status: DEPRECATED deprecated: true x-deprecation: deprecationDate: '2022-08-17' retirementDate: TBD replacedBy: CreatePaymentLink guideUrl: https://developer.squareup.com/docs/migrate-from-v1/guides/v1-checkout security: - oauth2: - PAYMENTS_WRITE - ORDERS_WRITE parameters: - name: location_id description: The ID of the business location to associate the checkout with. schema: type: string in: path required: true requestBody: required: true description: 'An object containing the fields to POST for the request. See the corresponding object definition for field details.' content: application/json: schema: $ref: '#/components/schemas/CreateCheckoutRequest' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/CreateCheckoutResponse' x-endpoint-errors: - error-code: AMOUNT_TOO_HIGH - error-code: CARD_PROCESSING_NOT_ENABLED - error-code: ORDER_EXPIRED /v2/online-checkout/location-settings/{location_id}: get: tags: - Checkout summary: Square Retrieve Location Settings operationId: RetrieveLocationSettings x-microcks-operation: delay: 0 dispatcher: FALLBACK description: Retrieves the location-level settings for a Square-hosted checkout page. x-release-status: BETA security: - oauth2: - MERCHANT_PROFILE_READ parameters: - name: location_id description: The ID of the location for which to retrieve settings. schema: type: string in: path required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/RetrieveLocationSettingsResponse' put: tags: - Checkout summary: Square Update Location Settings operationId: UpdateLocationSettings x-microcks-operation: delay: 0 dispatcher: FALLBACK description: Updates the location-level settings for a Square-hosted checkout page. x-release-status: BETA security: - oauth2: - MERCHANT_PROFILE_WRITE - MERCHANT_PROFILE_READ parameters: - name: location_id description: The ID of the location for which to retrieve settings. schema: type: string in: path required: true requestBody: required: true description: 'An object containing the fields to POST for the request. See the corresponding object definition for field details.' content: application/json: schema: $ref: '#/components/schemas/UpdateLocationSettingsRequest' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/UpdateLocationSettingsResponse' /v2/online-checkout/merchant-settings: get: tags: - Checkout summary: Square Retrieve Merchant Settings operationId: RetrieveMerchantSettings x-microcks-operation: delay: 0 dispatcher: FALLBACK description: Retrieves the merchant-level settings for a Square-hosted checkout page. x-release-status: BETA security: - oauth2: - PAYMENT_METHODS_READ - MERCHANT_PROFILE_READ parameters: [] responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/RetrieveMerchantSettingsResponse' put: tags: - Checkout summary: Square Update Merchant Settings operationId: UpdateMerchantSettings x-microcks-operation: delay: 0 dispatcher: FALLBACK description: Updates the merchant-level settings for a Square-hosted checkout page. x-release-status: BETA security: - oauth2: - MERCHANT_PROFILE_WRITE - PAYMENT_METHODS_READ - MERCHANT_PROFILE_READ parameters: [] requestBody: required: true description: 'An object containing the fields to POST for the request. See the corresponding object definition for field details.' content: application/json: schema: $ref: '#/components/schemas/UpdateMerchantSettingsRequest' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/UpdateMerchantSettingsResponse' /v2/online-checkout/payment-links: get: tags: - Checkout summary: Square List Payment Links operationId: ListPaymentLinks x-microcks-operation: delay: 0 dispatcher: FALLBACK description: Lists all payment links. x-release-status: PUBLIC security: - oauth2: - ORDERS_READ parameters: - name: cursor description: 'A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. If a cursor is not provided, the endpoint returns the first page of the results. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).' schema: type: string in: query required: false - name: limit description: 'A limit on the number of results to return per page. The limit is advisory and the implementation might return more or less results. If the supplied limit is negative, zero, or greater than the maximum limit of 1000, it is ignored. Default value: `100`' schema: type: integer in: query required: false responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ListPaymentLinksResponse' post: tags: - Checkout summary: Square Create Payment Link operationId: CreatePaymentLink x-microcks-operation: delay: 0 dispatcher: FALLBACK description: Creates a Square-hosted checkout page. Applications can share the resulting payment link with their buyer to pay for goods and services. x-release-status: PUBLIC security: - oauth2: - PAYMENTS_WRITE - ORDERS_READ - ORDERS_WRITE parameters: [] requestBody: required: true description: 'An object containing the fields to POST for the request. See the corresponding object definition for field details.' content: application/json: schema: $ref: '#/components/schemas/CreatePaymentLinkRequest' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/CreatePaymentLinkResponse' x-endpoint-errors: - error-code: INVALID_PHONE_NUMBER - error-code: INVALID_EMAIL_ADDRESS - error-code: MISSING_REQUIRED_PARAMETER - error-code: CONFLICTING_PARAMETERS /v2/online-checkout/payment-links/{id}: delete: tags: - Checkout summary: Square Delete Payment Link operationId: DeletePaymentLink x-microcks-operation: delay: 0 dispatcher: FALLBACK description: Deletes a payment link. x-release-status: PUBLIC security: - oauth2: - ORDERS_READ - ORDERS_WRITE parameters: - name: id description: The ID of the payment link to delete. schema: type: string in: path required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/DeletePaymentLinkResponse' get: tags: - Checkout summary: Square Retrieve Payment Link operationId: RetrievePaymentLink x-microcks-operation: delay: 0 dispatcher: FALLBACK description: Retrieves a payment link. x-release-status: PUBLIC security: - oauth2: - ORDERS_READ parameters: - name: id description: The ID of link to retrieve. schema: type: string in: path required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/RetrievePaymentLinkResponse' put: tags: - Checkout summary: Square Update Payment Link operationId: UpdatePaymentLink x-microcks-operation: delay: 0 dispatcher: FALLBACK description: 'Updates a payment link. You can update the `payment_link` fields such as `description`, `checkout_options`, and `pre_populated_data`. You cannot update other fields such as the `order_id`, `version`, `URL`, or `timestamp` field.' x-release-status: PUBLIC security: - oauth2: - PAYMENTS_WRITE - ORDERS_READ - ORDERS_WRITE parameters: - name: id description: The ID of the payment link to update. schema: type: string in: path required: true requestBody: required: true description: 'An object containing the fields to POST for the request. See the corresponding object definition for field details.' content: application/json: schema: $ref: '#/components/schemas/UpdatePaymentLinkRequest' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/UpdatePaymentLinkResponse' x-endpoint-errors: - error-code: INVALID_PHONE_NUMBER - error-code: INVALID_EMAIL_ADDRESS components: schemas: CatalogQuickAmountsSettingsOption: type: string enum: - DISABLED - MANUAL - AUTO x-enum-elements: - name: DISABLED description: Option for seller to disable Quick Amounts. - name: MANUAL description: Option for seller to choose manually created Quick Amounts. - name: AUTO description: Option for seller to choose automatically created Quick Amounts. description: Determines a seller's option on Quick Amounts feature. x-release-status: BETA CatalogItemOptionForItem: type: object description: ' An option that can be assigned to an item. For example, a t-shirt item may offer a color option or a size option.' x-release-status: BETA properties: item_option_id: type: string description: The unique id of the item option, used to form the dimensions of the item option matrix in a specified order. nullable: true 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. Values are in [ISO 3166-1-alpha-2 format](http://www.iso.org/iso/home/standards/country_codes.htm).' x-release-status: PUBLIC OrderLineItemDiscount: type: object description: 'Represents a discount that applies to one or more line items in an order. Fixed-amount, order-scoped discounts are distributed across all non-zero line item totals. The amount distributed to each line item is relative to the amount contributed by the item to the order subtotal.' x-release-status: PUBLIC properties: uid: type: string description: A unique ID that identifies the discount only within this order. maxLength: 60 x-release-status: BETA nullable: true catalog_object_id: type: string description: The catalog object ID referencing [CatalogDiscount](entity:CatalogDiscount). maxLength: 192 nullable: true catalog_version: type: integer description: The version of the catalog object that this discount references. format: int64 nullable: true name: type: string description: The discount's name. maxLength: 255 nullable: true type: $ref: '#/components/schemas/OrderLineItemDiscountType' description: 'The type of the discount. Discounts that do not reference a catalog object ID must have a type of `FIXED_PERCENTAGE` or `FIXED_AMOUNT`. See [OrderLineItemDiscountType](#type-orderlineitemdiscounttype) for possible values' nullable: true percentage: type: string description: 'The percentage of the discount, as a string representation of a decimal number. A value of `7.25` corresponds to a percentage of 7.25%. `percentage` is not set for amount-based discounts.' maxLength: 10 nullable: true amount_money: $ref: '#/components/schemas/Money' description: 'The total declared monetary amount of the discount. `amount_money` is not set for percentage-based discounts.' nullable: true applied_money: $ref: '#/components/schemas/Money' description: 'The amount of discount actually applied to the line item. The amount represents the amount of money applied as a line-item scoped discount. When an amount-based discount is scoped to the entire order, the value of `applied_money` is different than `amount_money` because the total amount of the discount is distributed across all line items.' nullable: true metadata: type: object additionalProperties: type: string description: 'Application-defined data attached to this discount. Metadata fields are intended to store descriptive references or associations with an entity in another system or store brief information about the object. Square does not process this field; it only stores and returns it in relevant API calls. Do not use metadata to store any sensitive information (such as personally identifiable information or card details). Keys written by applications must be 60 characters or less and must be in the character set `[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed with a namespace, separated from the key with a '':'' character. Values have a maximum length of 255 characters. An application can have up to 10 entries per metadata field. Entries written by applications are private and can only be read or modified by the same application. For more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).' x-release-status: BETA nullable: true scope: $ref: '#/components/schemas/OrderLineItemDiscountScope' description: 'Indicates the level at which the discount applies. For `ORDER` scoped discounts, Square generates references in `applied_discounts` on all order line items that do not have them. For `LINE_ITEM` scoped discounts, the discount only applies to line items with a discount reference in their `applied_discounts` field. This field is immutable. To change the scope of a discount, you must delete the discount and re-add it as a new discount. See [OrderLineItemDiscountScope](#type-orderlineitemdiscountscope) for possible values' nullable: true reward_ids: type: array items: type: string description: 'The reward IDs corresponding to this discount. The application and specification of discounts that have `reward_ids` are completely controlled by the backing criteria corresponding to the reward tiers of the rewards that are added to the order through the Loyalty API. To manually unapply discounts that are the result of added rewards, the rewards must be removed from the order through the Loyalty API.' readOnly: true x-release-status: BETA pricing_rule_id: type: string description: 'The object ID of a [pricing rule](entity:CatalogPricingRule) to be applied automatically to this discount. The specification and application of the discounts, to which a `pricing_rule_id` is assigned, are completely controlled by the corresponding pricing rule.' readOnly: true OrderReturn: type: object description: The set of line items, service charges, taxes, discounts, tips, and other items being returned in an order. x-release-status: BETA properties: uid: type: string description: A unique ID that identifies the return only within this order. maxLength: 60 nullable: true source_order_id: type: string description: 'An order that contains the original sale of these return line items. This is unset for unlinked returns.' nullable: true return_line_items: type: array items: $ref: '#/components/schemas/OrderReturnLineItem' description: A collection of line items that are being returned. nullable: true return_service_charges: type: array items: $ref: '#/components/schemas/OrderReturnServiceCharge' description: A collection of service charges that are being returned. nullable: true return_taxes: type: array items: $ref: '#/components/schemas/OrderReturnTax' description: 'A collection of references to taxes being returned for an order, including the total applied tax amount to be returned. The taxes must reference a top-level tax ID from the source order.' readOnly: true return_discounts: type: array items: $ref: '#/components/schemas/OrderReturnDiscount' description: 'A collection of references to discounts being returned for an order, including the total applied discount amount to be returned. The discounts must reference a top-level discount ID from the source order.' readOnly: true return_tips: type: array items: $ref: '#/components/schemas/OrderReturnTip' description: A collection of references to tips being returned for an order. nullable: true rounding_adjustment: $ref: '#/components/schemas/OrderRoundingAdjustment' description: 'A positive or negative rounding adjustment to the total value being returned. Adjustments are commonly used to apply cash rounding when the minimum unit of the account is smaller than the lowest physical denomination of the currency.' nullable: true return_amounts: $ref: '#/components/schemas/OrderMoneyAmounts' description: An aggregate monetary value being returned by this return entry. nullable: true ItemVariationLocationOverrides: type: object description: Price and inventory alerting overrides for a `CatalogItemVariation` at a specific `Location`. x-release-status: PUBLIC properties: location_id: type: string description: The ID of the `Location`. This can include locations that are deactivated. nullable: true price_money: $ref: '#/components/schemas/Money' description: The price of the `CatalogItemVariation` at the given `Location`, or blank for variable pricing. nullable: true pricing_type: $ref: '#/components/schemas/CatalogPricingType' description: 'The pricing type (fixed or variable) for the `CatalogItemVariation` at the given `Location`. See [CatalogPricingType](#type-catalogpricingtype) for possible values' nullable: true track_inventory: type: boolean description: If `true`, inventory tracking is active for the `CatalogItemVariation` at this `Location`. nullable: true inventory_alert_type: $ref: '#/components/schemas/InventoryAlertType' description: 'Indicates whether the `CatalogItemVariation` displays an alert when its inventory quantity is less than or equal to its `inventory_alert_threshold`. See [InventoryAlertType](#type-inventoryalerttype) for possible values' nullable: true inventory_alert_threshold: type: integer description: 'If the inventory quantity for the variation is less than or equal to this value and `inventory_alert_type` is `LOW_QUANTITY`, the variation displays an alert in the merchant dashboard. This value is always an integer.' format: int64 nullable: true sold_out: type: boolean description: 'Indicates whether the overridden item variation is sold out at the specified location. When inventory tracking is enabled on the item variation either globally or at the specified location, the item variation is automatically marked as sold out when its inventory count reaches zero. The seller can manually set the item variation as sold out even when the inventory count is greater than zero. Attempts by an application to set this attribute are ignored. Regardless how the sold-out status is set, applications should treat its inventory count as zero when this attribute value is `true`.' readOnly: true sold_out_valid_until: type: string description: 'The seller-assigned timestamp, of the RFC 3339 format, to indicate when this sold-out variation becomes available again at the specified location. Attempts by an application to set this attribute are ignored. When the current time is later than this attribute value, the affected item variation is no longer sold out.' readOnly: true ModifierLocationOverrides: type: object description: Location-specific overrides for specified properties of a `CatalogModifier` object. x-release-status: PUBLIC properties: location_id: type: string description: The ID of the `Location` object representing the location. This can include a deactivated location. nullable: true price_money: $ref: '#/components/schemas/Money' description: 'The overridden price at the specified location. If this is unspecified, the modifier price is not overridden. The modifier becomes free of charge at the specified location, when this `price_money` field is set to 0.' nullable: true sold_out: type: boolean description: 'Indicates whether the modifier is sold out at the specified location or not. As an example, for cheese (modifier) burger (item), when the modifier is sold out, it is the cheese, but not the burger, that is sold out. The seller can manually set this sold out status. Attempts by an application to set this attribute are ignored.' readOnly: true TenderType: type: string enum: - CARD - CASH - THIRD_PARTY_CARD - SQUARE_GIFT_CARD - NO_SALE - BANK_ACCOUNT - WALLET - BUY_NOW_PAY_LATER - SQUARE_ACCOUNT - OTHER x-enum-elements: - name: CARD description: A credit card. - name: CASH description: Cash. - name: THIRD_PARTY_CARD description: 'A credit card processed with a card processor other than Square. This value applies only to merchants in countries where Square does not yet provide card processing.' - name: SQUARE_GIFT_CARD description: A Square gift card. - name: NO_SALE description: This tender represents the register being opened for a "no sale" event. - name: BANK_ACCOUNT description: A bank account payment. - name: WALLET description: 'A payment from a digital wallet, e.g. Cash App, Paypay, Rakuten Pay, Au Pay, D Barai, Merpay, Wechat Pay, Alipay. Note: Some "digital wallets", including Google Pay and Apple Pay, facilitate card payments. Those payments have the `CARD` type.' - name: BUY_NOW_PAY_LATER description: A Buy Now Pay Later payment. - name: SQUARE_ACCOUNT description: A Square House Account payment. - name: OTHER description: A form of tender that does not match any other value. description: Indicates a tender's type. x-release-status: PUBLIC PaymentLinkRelatedResources: type: object x-release-status: PUBLIC properties: orders: type: array items: $ref: '#/components/schemas/Order' description: The order associated with the payment link. nullable: true subscription_plans: type: array items: $ref: '#/components/schemas/CatalogObject' description: The subscription plan associated with the payment link. nullable: true FulfillmentDeliveryDetailsOrderFulfillmentDeliveryDetailsScheduleType: type: string enum: - SCHEDULED - ASAP x-enum-elements: - name: SCHEDULED description: Indicates the fulfillment to deliver at a scheduled deliver time. - name: ASAP description: 'Indicates that the fulfillment to deliver as soon as possible and should be prepared immediately.' description: The schedule type of the delivery fulfillment. x-release-status: BETA CatalogItemFoodAndBeverageDetailsIngredient: type: object description: Describes the ingredient used in a `FOOD_AND_BEV` item. x-release-status: PUBLIC properties: type: $ref: '#/components/schemas/CatalogItemFoodAndBeverageDetailsDietaryPreferenceType' description: 'The dietary preference type of the ingredient. Supported values include `STANDARD` and `CUSTOM` as specified in `FoodAndBeverageDetails.DietaryPreferenceType`. See [DietaryPreferenceType](#type-dietarypreferencetype) for possible values' nullable: true standard_name: $ref: '#/components/schemas/CatalogItemFoodAndBeverageDetailsIngredientStandardIngredient' description: 'The name of the ingredient from a standard pre-defined list. This should be null if it''s a custom dietary preference. See [StandardIngredient](#type-standardingredient) for possible values' nullable: true custom_name: type: string description: The name of a custom user-defined ingredient. This should be null if it's a standard dietary preference. nullable: true CatalogModifierListSelectionType: type: string enum: - SINGLE - MULTIPLE x-enum-elements: - name: SINGLE description: 'Indicates that a CatalogModifierList allows only a single CatalogModifier to be selected.' - name: MULTIPLE description: 'Indicates that a CatalogModifierList allows multiple CatalogModifier to be selected.' description: Indicates whether a CatalogModifierList supports multiple selections. x-release-status: PUBLIC CatalogCategory: type: object description: A category to which a `CatalogItem` instance belongs. x-release-status: PUBLIC properties: name: type: string description: The category name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points. maxLength: 255 nullable: true image_ids: type: array items: type: string description: 'The IDs of images associated with this `CatalogCategory` instance. Currently these images are not displayed by Square, but are free to be displayed in 3rd party applications.' nullable: true category_type: $ref: '#/components/schemas/CatalogCategoryType' description: 'The type of the category. See [CatalogCategoryType](#type-catalogcategorytype) for possible values' nullable: true parent_category: $ref: '#/components/schemas/CatalogObjectCategory' description: The ID of the parent category of this category instance. nullable: true is_top_level: type: boolean description: Indicates whether a category is a top level category, which does not have any parent_category. nullable: true channels: type: array items: type: string description: A list of IDs representing channels, such as a Square Online site, where the category can be made visible. nullable: true availability_period_ids: type: array items: type: string description: The IDs of the `CatalogAvailabilityPeriod` objects associated with the category. nullable: true online_visibility: type: boolean description: Indicates whether the category is visible (`true`) or hidden (`false`) on all of the seller's Square Online sites. nullable: true root_category: type: string description: The top-level category in a category hierarchy. readOnly: true ecom_seo_data: $ref: '#/components/schemas/CatalogEcomSeoData' description: The SEO data for a seller's Square Online store. nullable: true path_to_root: type: array items: $ref: '#/components/schemas/CategoryPathToRootNode' description: 'The path from the category to its root category. The first node of the path is the parent of the category and the last is the root category. The path is empty if the category is a root category.' nullable: true example: object: category_data: name: Beverages id: '#Beverages' present_at_all_locations: true type: CATEGORY Money: type: object description: 'Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information.' x-release-status: PUBLIC properties: amount: type: integer description: 'The amount of money, in the smallest denomination of the currency indicated by `currency`. For example, when `currency` is `USD`, `amount` is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case.' format: int64 nullable: true currency: $ref: '#/components/schemas/Currency' description: 'The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](entity:Currency) for possible values. See [Currency](#type-currency) for possible values' nullable: true CheckoutLocationSettingsBrandingButtonShape: type: string enum: - SQUARED - ROUNDED - PILL x-enum-elements: - name: SQUARED description: '' - name: ROUNDED description: '' - name: PILL description: '' x-release-status: BETA FulfillmentPickupDetails: type: object description: Contains details necessary to fulfill a pickup order. x-release-status: PUBLIC properties: recipient: $ref: '#/components/schemas/FulfillmentRecipient' description: 'Information about the person to pick up this fulfillment from a physical location.' nullable: true expires_at: type: string description: 'The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates) indicating when this fulfillment expires if it is not marked in progress. The timestamp must be in RFC 3339 format (for example, "2016-09-04T23:59:33.123Z"). The expiration time can only be set up to 7 days in the future. If `expires_at` is not set, any new payments attached to the order are automatically completed.' nullable: true auto_complete_duration: type: string description: 'The duration of time after which an in progress pickup fulfillment is automatically moved to the `COMPLETED` state. The duration must be in RFC 3339 format (for example, "P1W3D"). If not set, this pickup fulfillment remains in progress until it is canceled or completed.' nullable: true schedule_type: $ref: '#/components/schemas/FulfillmentPickupDetailsScheduleType' description: 'The schedule type of the pickup fulfillment. Defaults to `SCHEDULED`. See [FulfillmentPickupDetailsScheduleType](#type-fulfillmentpickupdetailsscheduletype) for possible values' nullable: true pickup_at: type: string description: 'The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates) that represents the start of the pickup window. Must be in RFC 3339 timestamp format, e.g., "2016-09-04T23:59:33.123Z". For fulfillments with the schedule type `ASAP`, this is automatically set to the current time plus the expected duration to prepare the fulfillment.' nullable: true pickup_window_duration: type: string description: 'The window of time in which the order should be picked up after the `pickup_at` timestamp. Must be in RFC 3339 duration format, e.g., "P1W3D". Can be used as an informational guideline for merchants.' nullable: true prep_time_duration: type: string description: 'The duration of time it takes to prepare this fulfillment. The duration must be in RFC 3339 format (for example, "P1W3D").' nullable: true note: type: string description: 'A note to provide additional instructions about the pickup fulfillment displayed in the Square Point of Sale application and set by the API.' maxLength: 500 nullable: true placed_at: type: string description: 'The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates) indicating when the fulfillment was placed. The timestamp must be in RFC 3339 format (for example, "2016-09-04T23:59:33.123Z").' readOnly: true accepted_at: type: string description: 'The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates) indicating when the fulfillment was marked in progress. The timestamp must be in RFC 3339 format (for example, "2016-09-04T23:59:33.123Z").' readOnly: true rejected_at: type: string description: 'The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates) indicating when the fulfillment was rejected. The timestamp must be in RFC 3339 format (for example, "2016-09-04T23:59:33.123Z").' readOnly: true ready_at: type: string description: 'The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates) indicating when the fulfillment is marked as ready for pickup. The timestamp must be in RFC 3339 format (for example, "2016-09-04T23:59:33.123Z").' readOnly: true expired_at: type: string description: 'The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates) indicating when the fulfillment expired. The timestamp must be in RFC 3339 format (for example, "2016-09-04T23:59:33.123Z").' readOnly: true picked_up_at: type: string description: 'The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates) indicating when the fulfillment was picked up by the recipient. The timestamp must be in RFC 3339 format (for example, "2016-09-04T23:59:33.123Z").' readOnly: true canceled_at: type: string description: 'The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates) indicating when the fulfillment was canceled. The timestamp must be in RFC 3339 format (for example, "2016-09-04T23:59:33.123Z").' readOnly: true cancel_reason: type: string description: 'A description of why the pickup was canceled. The maximum length: 100 characters.' maxLength: 100 nullable: true is_curbside_pickup: type: boolean description: If set to `true`, indicates that this pickup order is for curbside pickup, not in-store pickup. x-release-status: BETA nullable: true curbside_pickup_details: $ref: '#/components/schemas/FulfillmentPickupDetailsCurbsidePickupDetails' description: Specific details for curbside pickup. These details can only be populated if `is_curbside_pickup` is set to `true`. x-release-status: BETA nullable: true CatalogObject: type: object description: 'The wrapper object for the catalog entries of a given object type. Depending on the `type` attribute value, a `CatalogObject` instance assumes a type-specific data to yield the corresponding type of catalog object. For example, if `type=ITEM`, the `CatalogObject` instance must have the ITEM-specific data set on the `item_data` attribute. The resulting `CatalogObject` instance is also a `CatalogItem` instance. In general, if `type=`, the `CatalogObject` instance must have the ``-specific data set on the `_data` attribute. The resulting `CatalogObject` instance is also a `Catalog` instance. For a more detailed discussion of the Catalog data model, please see the [Design a Catalog](https://developer.squareup.com/docs/catalog-api/design-a-catalog) guide.' x-release-status: PUBLIC required: - type - id properties: type: $ref: '#/components/schemas/CatalogObjectType' description: 'The type of this object. Each object type has expected properties expressed in a structured format within its corresponding `*_data` field below. See [CatalogObjectType](#type-catalogobjecttype) for possible values' id: type: string description: 'An identifier to reference this object in the catalog. When a new `CatalogObject` is inserted, the client should set the id to a temporary identifier starting with a "`#`" character. Other objects being inserted or updated within the same request may use this identifier to refer to the new object. When the server receives the new object, it will supply a unique identifier that replaces the temporary identifier for all future references.' minLength: 1 updated_at: type: string description: 'Last modification [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates) in RFC 3339 format, e.g., `"2016-08-15T23:59:33.123Z"` would indicate the UTC time (denoted by `Z`) of August 15, 2016 at 23:59:33 and 123 milliseconds.' readOnly: true version: type: integer description: 'The version of the object. When updating an object, the version supplied must match the version in the database, otherwise the write will be rejected as conflicting.' format: int64 is_deleted: type: boolean description: 'If `true`, the object has been deleted from the database. Must be `false` for new objects being inserted. When deleted, the `updated_at` field will equal the deletion time.' nullable: true custom_attribute_values: type: object additionalProperties: $ref: '#/components/schemas/CatalogCustomAttributeValue' description: 'A map (key-value pairs) of application-defined custom attribute values. The value of a key-value pair is a [CatalogCustomAttributeValue](entity:CatalogCustomAttributeValue) object. The key is the `key` attribute value defined in the associated [CatalogCustomAttributeDefinition](entity:CatalogCustomAttributeDefinition) object defined by the application making the request. If the `CatalogCustomAttributeDefinition` object is defined by another application, the `CatalogCustomAttributeDefinition`''s key attribute value is prefixed by the defining application ID. For example, if the `CatalogCustomAttributeDefinition` has a `key` attribute of `"cocoa_brand"` and the defining application ID is `"abcd1234"`, the key in the map is `"abcd1234:cocoa_brand"` if the application making the request is different from the application defining the custom attribute definition. Otherwise, the key used in the map is simply `"cocoa_brand"`. Application-defined custom attributes are set at a global (location-independent) level. Custom attribute values are intended to store additional information about a catalog object or associations with an entity in another system. Do not use custom attributes to store any sensitive information (personally identifiable information, card details, etc.).' nullable: true catalog_v1_ids: type: array items: $ref: '#/components/schemas/CatalogV1Id' description: 'The Connect v1 IDs for this object at each location where it is present, where they differ from the object''s Connect V2 ID. The field will only be present for objects that have been created or modified by legacy APIs.' nullable: true present_at_all_locations: type: boolean description: 'If `true`, this object is present at all locations (including future locations), except where specified in the `absent_at_location_ids` field. If `false`, this object is not present at any locations (including future locations), except where specified in the `present_at_location_ids` field. If not specified, defaults to `true`.' nullable: true present_at_location_ids: type: array items: type: string description: 'A list of locations where the object is present, even if `present_at_all_locations` is `false`. This can include locations that are deactivated.' nullable: true absent_at_location_ids: type: array items: type: string description: 'A list of locations where the object is not present, even if `present_at_all_locations` is `true`. This can include locations that are deactivated.' nullable: true item_data: $ref: '#/components/schemas/CatalogItem' description: Structured data for a `CatalogItem`, set for CatalogObjects of type `ITEM`. nullable: true category_data: $ref: '#/components/schemas/CatalogCategory' description: Structured data for a `CatalogCategory`, set for CatalogObjects of type `CATEGORY`. nullable: true item_variation_data: $ref: '#/components/schemas/CatalogItemVariation' description: Structured data for a `CatalogItemVariation`, set for CatalogObjects of type `ITEM_VARIATION`. nullable: true tax_data: $ref: '#/components/schemas/CatalogTax' description: Structured data for a `CatalogTax`, set for CatalogObjects of type `TAX`. nullable: true discount_data: $ref: '#/components/schemas/CatalogDiscount' description: Structured data for a `CatalogDiscount`, set for CatalogObjects of type `DISCOUNT`. nullable: true modifier_list_data: $ref: '#/components/schemas/CatalogModifierList' description: Structured data for a `CatalogModifierList`, set for CatalogObjects of type `MODIFIER_LIST`. nullable: true modifier_data: $ref: '#/components/schemas/CatalogModifier' description: Structured data for a `CatalogModifier`, set for CatalogObjects of type `MODIFIER`. nullable: true time_period_data: $ref: '#/components/schemas/CatalogTimePeriod' description: Structured data for a `CatalogTimePeriod`, set for CatalogObjects of type `TIME_PERIOD`. nullable: true product_set_data: $ref: '#/components/schemas/CatalogProductSet' description: Structured data for a `CatalogProductSet`, set for CatalogObjects of type `PRODUCT_SET`. nullable: true pricing_rule_data: $ref: '#/components/schemas/CatalogPricingRule' description: 'Structured data for a `CatalogPricingRule`, set for CatalogObjects of type `PRICING_RULE`. A `CatalogPricingRule` object often works with a `CatalogProductSet` object or a `CatalogTimePeriod` object.' nullable: true image_data: $ref: '#/components/schemas/CatalogImage' description: Structured data for a `CatalogImage`, set for CatalogObjects of type `IMAGE`. nullable: true measurement_unit_data: $ref: '#/components/schemas/CatalogMeasurementUnit' description: Structured data for a `CatalogMeasurementUnit`, set for CatalogObjects of type `MEASUREMENT_UNIT`. nullable: true subscription_plan_data: $ref: '#/components/schemas/CatalogSubscriptionPlan' description: Structured data for a `CatalogSubscriptionPlan`, set for CatalogObjects of type `SUBSCRIPTION_PLAN`. nullable: true item_option_data: $ref: '#/components/schemas/CatalogItemOption' description: Structured data for a `CatalogItemOption`, set for CatalogObjects of type `ITEM_OPTION`. nullable: true item_option_value_data: $ref: '#/components/schemas/CatalogItemOptionValue' description: Structured data for a `CatalogItemOptionValue`, set for CatalogObjects of type `ITEM_OPTION_VAL`. nullable: true custom_attribute_definition_data: $ref: '#/components/schemas/CatalogCustomAttributeDefinition' description: Structured data for a `CatalogCustomAttributeDefinition`, set for CatalogObjects of type `CUSTOM_ATTRIBUTE_DEFINITION`. nullable: true quick_amounts_settings_data: $ref: '#/components/schemas/CatalogQuickAmountsSettings' description: Structured data for a `CatalogQuickAmountsSettings`, set for CatalogObjects of type `QUICK_AMOUNTS_SETTINGS`. x-release-status: BETA nullable: true subscription_plan_variation_data: $ref: '#/components/schemas/CatalogSubscriptionPlanVariation' description: Structured data for a `CatalogSubscriptionPlanVariation`, set for CatalogObjects of type `SUBSCRIPTION_PLAN_VARIATION`. nullable: true availability_period_data: $ref: '#/components/schemas/CatalogAvailabilityPeriod' description: Structured data for a `CatalogAvailabilityPeriod`, set for CatalogObjects of type `AVAILABILITY_PERIOD`. nullable: true example: catalog_object: absent_at_location_ids: - '{{ LOCATIONID-1 }}' - '{{ LOCATIONID-N }}' category_data: '{{ CatalogCategory object only if type=CATEGORY }}' connect_v1_ids: catalog_v1_id: '{{ itemID from Catalog v1 }}' location_id: '{{ location where v1 ID is used }}' discount_data: '{{ CatalogDiscount object only if type=DISCOUNT }}' id: '{{ set by Catalog during object creation }}' is_deleted: '{{ [true | false] }}' item_data: '{{ CatalogItem object only if type=ITEM }}' item_variation_data: '{{ CatalogItemVariation object only if type=ITEM_VARIATION }}' modifier_data: '{{ CatalogModifier object only if type=MODIFIER }}' modifier_list_data: '{{ CatalogModifierList object only if type=MODIFIER_LIST }}' present_at_all_locations: '{{ [true | false] }}' present_at_location_ids: - '{{ LOCATIONID-1 }}' - '{{ LOCATIONID-N }}' tax_data: '{{ CatalogTax object only if type=TAX }}' type: '{{ [ITEM | ITEM_VARIATION | MODIFIER | MODIFIER_LIST | CATEGORY | DISCOUNT | TAX] }}' updated_at: '{{ date & time of most recent update }}' version: '{{ version of the CatalogObject }}' CatalogCustomAttributeDefinitionStringConfig: type: object description: Configuration associated with Custom Attribute Definitions of type `STRING`. x-release-status: PUBLIC properties: enforce_uniqueness: type: boolean description: 'If true, each Custom Attribute instance associated with this Custom Attribute Definition must have a unique value within the seller''s catalog. For example, this may be used for a value like a SKU that should not be duplicated within a seller''s catalog. May not be modified after the definition has been created.' nullable: true FulfillmentFulfillmentEntry: type: object description: 'Links an order line item to a fulfillment. Each entry must reference a valid `uid` for an order line item in the `line_item_uid` field, as well as a `quantity` to fulfill.' x-release-status: BETA required: - line_item_uid - quantity properties: uid: type: string description: A unique ID that identifies the fulfillment entry only within this order. maxLength: 60 nullable: true line_item_uid: type: string description: The `uid` from the order line item. minLength: 1 quantity: type: string description: 'The quantity of the line item being fulfilled, formatted as a decimal number. For example, `"3"`. Fulfillments for line items with a `quantity_unit` can have non-integer quantities. For example, `"1.70000"`.' minLength: 1 maxLength: 12 metadata: type: object additionalProperties: type: string description: 'Application-defined data attached to this fulfillment entry. Metadata fields are intended to store descriptive references or associations with an entity in another system or store brief information about the object. Square does not process this field; it only stores and returns it in relevant API calls. Do not use metadata to store any sensitive information (such as personally identifiable information or card details). Keys written by applications must be 60 characters or less and must be in the character set `[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed with a namespace, separated from the key with a '':'' character. Values have a maximum length of 255 characters. An application can have up to 10 entries per metadata field. Entries written by applications are private and can only be read or modified by the same application. For more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).' nullable: true OrderLineItemModifier: type: object description: A [CatalogModifier](entity:CatalogModifier). x-release-status: PUBLIC properties: uid: type: string description: A unique ID that identifies the modifier only within this order. maxLength: 60 x-release-status: BETA nullable: true catalog_object_id: type: string description: The catalog object ID referencing [CatalogModifier](entity:CatalogModifier). maxLength: 192 nullable: true catalog_version: type: integer description: The version of the catalog object that this modifier references. format: int64 nullable: true name: type: string description: The name of the item modifier. maxLength: 255 nullable: true quantity: type: string description: 'The quantity of the line item modifier. The modifier quantity can be 0 or more. For example, suppose a restaurant offers a cheeseburger on the menu. When a buyer orders this item, the restaurant records the purchase by creating an `Order` object with a line item for a burger. The line item includes a line item modifier: the name is cheese and the quantity is 1. The buyer has the option to order extra cheese (or no cheese). If the buyer chooses the extra cheese option, the modifier quantity increases to 2. If the buyer does not want any cheese, the modifier quantity is set to 0.' nullable: true base_price_money: $ref: '#/components/schemas/Money' description: 'The base price for the modifier. `base_price_money` is required for ad hoc modifiers. If both `catalog_object_id` and `base_price_money` are set, `base_price_money` will override the predefined [CatalogModifier](entity:CatalogModifier) price.' nullable: true total_price_money: $ref: '#/components/schemas/Money' description: 'The total price of the item modifier for its line item. This is the modifier''s `base_price_money` multiplied by the line item''s quantity.' readOnly: true metadata: type: object additionalProperties: type: string description: 'Application-defined data attached to this order. Metadata fields are intended to store descriptive references or associations with an entity in another system or store brief information about the object. Square does not process this field; it only stores and returns it in relevant API calls. Do not use metadata to store any sensitive information (such as personally identifiable information or card details). Keys written by applications must be 60 characters or less and must be in the character set `[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed with a namespace, separated from the key with a '':'' character. Values have a maximum length of 255 characters. An application can have up to 10 entries per metadata field. Entries written by applications are private and can only be read or modified by the same application. For more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).' x-release-status: BETA nullable: true CheckoutLocationSettingsPolicy: type: object x-release-status: BETA properties: uid: type: string description: A unique ID to identify the policy when making changes. You must set the UID for policy updates, but it’s optional when setting new policies. nullable: true title: type: string description: The title of the policy. This is required when setting the description, though you can update it in a different request. maxLength: 50 nullable: true description: type: string description: The description of the policy. maxLength: 4096 nullable: true OrderServiceChargeTreatmentType: type: string enum: - LINE_ITEM_TREATMENT - APPORTIONED_TREATMENT x-enum-elements: - name: LINE_ITEM_TREATMENT description: '' - name: APPORTIONED_TREATMENT description: '' description: 'Indicates whether the service charge will be treated as a value-holding line item or apportioned toward a line item.' x-release-status: BETA FulfillmentPickupDetailsScheduleType: type: string enum: - SCHEDULED - ASAP x-enum-elements: - name: SCHEDULED description: Indicates that the fulfillment will be picked up at a scheduled pickup time. - name: ASAP description: 'Indicates that the fulfillment will be picked up as soon as possible and should be prepared immediately.' description: The schedule type of the pickup fulfillment. x-release-status: PUBLIC CardType: type: string enum: - UNKNOWN_CARD_TYPE - CREDIT - DEBIT x-enum-elements: - name: UNKNOWN_CARD_TYPE description: '' - name: CREDIT description: '' - name: DEBIT description: '' description: Indicates a card's type, such as `CREDIT` or `DEBIT`. x-release-status: PUBLIC CreatePaymentLinkResponse: type: object x-release-status: PUBLIC properties: errors: type: array items: $ref: '#/components/schemas/Error' description: Any errors that occurred during the request. payment_link: $ref: '#/components/schemas/PaymentLink' description: The created payment link. related_resources: $ref: '#/components/schemas/PaymentLinkRelatedResources' description: The list of related objects. example: payment_link: created_at: '2022-04-25T23:58:01Z' id: PKVT6XGJZXYUP3NZ long_url: https://checkout.square.site/EXAMPLE order_id: o4b7saqp4HzhNttf5AJxC0Srjd4F url: https://square.link/u/EXAMPLE version: 1 related_resources: orders: - created_at: '2022-03-03T00:53:15.829Z' fulfillments: - state: PROPOSED type: DIGITAL uid: bBpNrxjdQxGQP16sTmdzi id: o4b7saqp4HzhNttf5AJxC0Srjd4F line_items: - base_price_money: amount: 12500 currency: USD gross_sales_money: amount: 12500 currency: USD item_type: ITEM name: Auto Detailing quantity: '1' total_discount_money: amount: 0 currency: USD total_money: amount: 12500 currency: USD total_tax_money: amount: 0 currency: USD uid: 8YX13D1U3jO7czP8JVrAR variation_total_price_money: amount: 12500 currency: USD location_id: '{LOCATION_ID}' net_amounts: discount_money: amount: 0 currency: USD service_charge_money: amount: 0 currency: USD tax_money: amount: 0 currency: USD tip_money: amount: 0 currency: USD total_money: amount: 12500 currency: USD source: name: Test Online Checkout Application state: DRAFT total_discount_money: amount: 0 currency: USD total_money: amount: 12500 currency: USD total_service_charge_money: amount: 0 currency: USD total_tax_money: amount: 0 currency: USD total_tip_money: amount: 0 currency: USD updated_at: '2022-03-03T00:53:15.829Z' version: 1 OrderState: type: string enum: - OPEN - COMPLETED - CANCELED - DRAFT x-enum-elements: - name: OPEN description: Indicates that the order is open. Open orders can be updated. - name: COMPLETED description: Indicates that the order is completed. Completed orders are fully paid. This is a terminal state. - name: CANCELED description: Indicates that the order is canceled. Canceled orders are not paid. This is a terminal state. - name: DRAFT description: 'Indicates that the order is in a draft state. Draft orders can be updated, but cannot be paid or fulfilled. For more information, see [Create Orders](https://developer.squareup.com/docs/orders-api/create-orders).' description: The state of the order. x-release-status: PUBLIC OrderPricingOptions: type: object description: 'Pricing options for an order. The options affect how the order''s price is calculated. They can be used, for example, to apply automatic price adjustments that are based on preconfigured [pricing rules](entity:CatalogPricingRule).' x-release-status: PUBLIC properties: auto_apply_discounts: type: boolean description: 'The option to determine whether pricing rule-based discounts are automatically applied to an order.' nullable: true auto_apply_taxes: type: boolean description: 'The option to determine whether rule-based taxes are automatically applied to an order when the criteria of the corresponding rules are met.' x-release-status: BETA nullable: true OrderServiceChargeScope: type: string enum: - OTHER_SERVICE_CHARGE_SCOPE - LINE_ITEM - ORDER x-enum-elements: - name: OTHER_SERVICE_CHARGE_SCOPE description: 'Used for reporting only. The original transaction service charge scope is currently not supported by the API.' - name: LINE_ITEM description: 'The service charge should be applied to only line items specified by `OrderLineItemAppliedServiceCharge` reference records.' - name: ORDER description: The service charge should be applied to the entire order. description: 'Indicates whether this is a line-item or order-level apportioned service charge.' x-release-status: BETA CatalogItemOptionValueForItemVariation: type: object description: 'A `CatalogItemOptionValue` links an item variation to an item option as an item option value. For example, a t-shirt item may offer a color option and a size option. An item option value would represent each variation of t-shirt: For example, "Color:Red, Size:Small" or "Color:Blue, Size:Medium".' x-release-status: PUBLIC properties: item_option_id: type: string description: The unique id of an item option. nullable: true item_option_value_id: type: string description: The unique id of the selected value for the item option. nullable: true CatalogItemFoodAndBeverageDetailsDietaryPreference: type: object description: Dietary preferences that can be assigned to an `FOOD_AND_BEV` item and its ingredients. x-release-status: PUBLIC properties: type: $ref: '#/components/schemas/CatalogItemFoodAndBeverageDetailsDietaryPreferenceType' description: 'The dietary preference type. Supported values include `STANDARD` and `CUSTOM` as specified in `FoodAndBeverageDetails.DietaryPreferenceType`. See [DietaryPreferenceType](#type-dietarypreferencetype) for possible values' nullable: true standard_name: $ref: '#/components/schemas/CatalogItemFoodAndBeverageDetailsDietaryPreferenceStandardDietaryPreference' description: 'The name of the dietary preference from a standard pre-defined list. This should be null if it''s a custom dietary preference. See [StandardDietaryPreference](#type-standarddietarypreference) for possible values' nullable: true custom_name: type: string description: The name of a user-defined custom dietary preference. This should be null if it's a standard dietary preference. nullable: true DeletePaymentLinkResponse: type: object x-release-status: PUBLIC properties: errors: type: array items: $ref: '#/components/schemas/Error' id: type: string description: The ID of the link that is deleted. cancelled_order_id: type: string description: 'The ID of the order that is canceled. When a payment link is deleted, Square updates the the `state` (of the order that the checkout link created) to CANCELED.' example: cancelled_order_id: asx8LgZ6MRzD0fObfkJ6obBmSh4F id: MQASNYL6QB6DFCJ3 CreatePaymentLinkRequest: type: object x-release-status: PUBLIC properties: idempotency_key: type: string description: 'A unique string that identifies this `CreatePaymentLinkRequest` request. If you do not provide a unique string (or provide an empty string as the value), the endpoint treats each request as independent. For more information, see [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency).' maxLength: 192 description: type: string description: 'A description of the payment link. You provide this optional description that is useful in your application context. It is not used anywhere.' maxLength: 4096 quick_pay: $ref: '#/components/schemas/QuickPay' description: 'Describes an ad hoc item and price for which to generate a quick pay checkout link. For more information, see [Quick Pay Checkout](https://developer.squareup.com/docs/checkout-api/quick-pay-checkout).' order: $ref: '#/components/schemas/Order' description: 'Describes the `Order` for which to create a checkout link. For more information, see [Square Order Checkout](https://developer.squareup.com/docs/checkout-api/square-order-checkout).' checkout_options: $ref: '#/components/schemas/CheckoutOptions' description: 'Describes optional fields to add to the resulting checkout page. For more information, see [Optional Checkout Configurations](https://developer.squareup.com/docs/checkout-api/optional-checkout-configurations).' pre_populated_data: $ref: '#/components/schemas/PrePopulatedData' description: 'Describes fields to prepopulate in the resulting checkout page. For more information, see [Prepopulate the shipping address](https://developer.squareup.com/docs/checkout-api/optional-checkout-configurations#prepopulate-the-shipping-address).' payment_note: type: string description: A note for the payment. After processing the payment, Square adds this note to the resulting `Payment`. maxLength: 500 example: idempotency_key: cd9e25dc-d9f2-4430-aedb-61605070e95f quick_pay: location_id: A9Y43N9ABXZBP name: Auto Detailing price_money: amount: 10000 currency: USD UpdateMerchantSettingsResponse: type: object x-release-status: BETA properties: errors: type: array items: $ref: '#/components/schemas/Error' description: Any errors that occurred when updating the merchant settings. merchant_settings: $ref: '#/components/schemas/CheckoutMerchantSettings' description: The updated merchant settings. example: merchant_settings: merchant_id: MERCHANT_ID payment_methods: afterpay_clearpay: enabled: true item_eligibility_range: max: amount: 10000 currency: USD min: amount: 100 currency: USD order_eligibility_range: max: amount: 10000 currency: USD min: amount: 100 currency: USD apple_pay: enabled: false cash_app_pay: enabled: true google_pay: enabled: true updated_at: '2022-06-16T22:25:35Z' OrderReturnDiscount: type: object description: 'Represents a discount being returned that applies to one or more return line items in an order. Fixed-amount, order-scoped discounts are distributed across all non-zero return line item totals. The amount distributed to each return line item is relative to that item’s contribution to the order subtotal.' x-release-status: BETA properties: uid: type: string description: A unique ID that identifies the returned discount only within this order. maxLength: 60 nullable: true source_discount_uid: type: string description: The discount `uid` from the order that contains the original application of this discount. maxLength: 60 nullable: true catalog_object_id: type: string description: The catalog object ID referencing [CatalogDiscount](entity:CatalogDiscount). maxLength: 192 nullable: true catalog_version: type: integer description: The version of the catalog object that this discount references. format: int64 nullable: true name: type: string description: The discount's name. maxLength: 255 nullable: true type: $ref: '#/components/schemas/OrderLineItemDiscountType' description: 'The type of the discount. If it is created by the API, it is `FIXED_PERCENTAGE` or `FIXED_AMOUNT`. Discounts that do not reference a catalog object ID must have a type of `FIXED_PERCENTAGE` or `FIXED_AMOUNT`. See [OrderLineItemDiscountType](#type-orderlineitemdiscounttype) for possible values' nullable: true percentage: type: string description: 'The percentage of the tax, as a string representation of a decimal number. A value of `"7.25"` corresponds to a percentage of 7.25%. `percentage` is not set for amount-based discounts.' maxLength: 10 nullable: true amount_money: $ref: '#/components/schemas/Money' description: 'The total declared monetary amount of the discount. `amount_money` is not set for percentage-based discounts.' nullable: true applied_money: $ref: '#/components/schemas/Money' description: 'The amount of discount actually applied to this line item. When an amount-based discount is at the order level, this value is different from `amount_money` because the discount is distributed across the line items.' readOnly: true scope: $ref: '#/components/schemas/OrderLineItemDiscountScope' description: 'Indicates the level at which the `OrderReturnDiscount` applies. For `ORDER` scoped discounts, the server generates references in `applied_discounts` on all `OrderReturnLineItem`s. For `LINE_ITEM` scoped discounts, the discount is only applied to `OrderReturnLineItem`s with references in their `applied_discounts` field. See [OrderLineItemDiscountScope](#type-orderlineitemdiscountscope) for possible values' nullable: true ChargeRequestAdditionalRecipient: type: object description: 'Represents an additional recipient (other than the merchant) entitled to a portion of the tender. Support is currently limited to USD, CAD and GBP currencies' x-release-status: DEPRECATED required: - location_id - description - amount_money properties: location_id: type: string description: The location ID for a recipient (other than the merchant) receiving a portion of the tender. minLength: 1 maxLength: 50 description: type: string description: The description of the additional recipient. minLength: 1 maxLength: 100 amount_money: $ref: '#/components/schemas/Money' description: The amount of money distributed to the recipient. TaxCalculationPhase: type: string enum: - TAX_SUBTOTAL_PHASE - TAX_TOTAL_PHASE x-enum-elements: - name: TAX_SUBTOTAL_PHASE description: The fee is calculated based on the payment's subtotal. - name: TAX_TOTAL_PHASE description: The fee is calculated based on the payment's total. description: When to calculate the taxes due on a cart. x-release-status: PUBLIC CatalogDiscountType: type: string enum: - FIXED_PERCENTAGE - FIXED_AMOUNT - VARIABLE_PERCENTAGE - VARIABLE_AMOUNT x-enum-elements: - name: FIXED_PERCENTAGE description: Apply the discount as a fixed percentage (e.g., 5%) off the item price. - name: FIXED_AMOUNT description: Apply the discount as a fixed amount (e.g., $1.00) off the item price. - name: VARIABLE_PERCENTAGE description: Apply the discount as a variable percentage off the item price. The percentage will be specified at the time of sale. - name: VARIABLE_AMOUNT description: Apply the discount as a variable amount off the item price. The amount will be specified at the time of sale. description: How to apply a CatalogDiscount to a CatalogItem. x-release-status: PUBLIC CatalogImage: type: object description: 'An image file to use in Square catalogs. It can be associated with `CatalogItem`, `CatalogItemVariation`, `CatalogCategory`, and `CatalogModifierList` objects. Only the images on items and item variations are exposed in Dashboard. Only the first image on an item is displayed in Square Point of Sale (SPOS). Images on items and variations are displayed through Square Online Store. Images on other object types are for use by 3rd party application developers.' x-release-status: PUBLIC properties: name: type: string description: 'The internal name to identify this image in calls to the Square API. This is a searchable attribute for use in applicable query filters using the [SearchCatalogObjects](api-endpoint:Catalog-SearchCatalogObjects). It is not unique and should not be shown in a buyer facing context.' nullable: true url: type: string description: 'The URL of this image, generated by Square after an image is uploaded using the [CreateCatalogImage](api-endpoint:Catalog-CreateCatalogImage) endpoint. To modify the image, use the UpdateCatalogImage endpoint. Do not change the URL field.' nullable: true caption: type: string description: 'A caption that describes what is shown in the image. Displayed in the Square Online Store. This is a searchable attribute for use in applicable query filters using the [SearchCatalogObjects](api-endpoint:Catalog-SearchCatalogObjects).' nullable: true photo_studio_order_id: type: string description: The immutable order ID for this image object created by the Photo Studio service in Square Online Store. nullable: true MeasurementUnitUnitType: type: string enum: - TYPE_CUSTOM - TYPE_AREA - TYPE_LENGTH - TYPE_VOLUME - TYPE_WEIGHT - TYPE_GENERIC x-enum-elements: - name: TYPE_CUSTOM description: The unit details are contained in the custom_unit field. - name: TYPE_AREA description: The unit details are contained in the area_unit field. - name: TYPE_LENGTH description: The unit details are contained in the length_unit field. - name: TYPE_VOLUME description: The unit details are contained in the volume_unit field. - name: TYPE_WEIGHT description: The unit details are contained in the weight_unit field. - name: TYPE_GENERIC description: The unit details are contained in the generic_unit field. description: Describes the type of this unit and indicates which field contains the unit information. This is an ‘open’ enum. x-release-status: PUBLIC Order: type: object description: 'Contains all information related to a single order to process with Square, including line items that specify the products to purchase. `Order` objects also include information about any associated tenders, refunds, and returns. All Connect V2 Transactions have all been converted to Orders including all associated itemization data.' x-release-status: PUBLIC required: - location_id properties: id: type: string description: The order's unique ID. readOnly: true location_id: type: string description: The ID of the seller location that this order is associated with. minLength: 1 reference_id: type: string description: 'A client-specified ID to associate an entity in another system with this order.' maxLength: 40 nullable: true source: $ref: '#/components/schemas/OrderSource' description: The origination details of the order. nullable: true customer_id: type: string description: 'The ID of the [customer](entity:Customer) associated with the order. You should specify a `customer_id` on the order (or the payment) to ensure that transactions are reliably linked to customers. Omitting this field might result in the creation of new [instant profiles](https://developer.squareup.com/docs/customers-api/what-it-does#instant-profiles).' maxLength: 191 x-release-status: BETA nullable: true line_items: type: array items: $ref: '#/components/schemas/OrderLineItem' description: The line items included in the order. nullable: true taxes: type: array items: $ref: '#/components/schemas/OrderLineItemTax' description: 'The list of all taxes associated with the order. Taxes can be scoped to either `ORDER` or `LINE_ITEM`. For taxes with `LINE_ITEM` scope, an `OrderLineItemAppliedTax` must be added to each line item that the tax applies to. For taxes with `ORDER` scope, the server generates an `OrderLineItemAppliedTax` for every line item. On reads, each tax in the list includes the total amount of that tax applied to the order. __IMPORTANT__: If `LINE_ITEM` scope is set on any taxes in this field, using the deprecated `line_items.taxes` field results in an error. Use `line_items.applied_taxes` instead.' nullable: true discounts: type: array items: $ref: '#/components/schemas/OrderLineItemDiscount' description: 'The list of all discounts associated with the order. Discounts can be scoped to either `ORDER` or `LINE_ITEM`. For discounts scoped to `LINE_ITEM`, an `OrderLineItemAppliedDiscount` must be added to each line item that the discount applies to. For discounts with `ORDER` scope, the server generates an `OrderLineItemAppliedDiscount` for every line item. __IMPORTANT__: If `LINE_ITEM` scope is set on any discounts in this field, using the deprecated `line_items.discounts` field results in an error. Use `line_items.applied_discounts` instead.' nullable: true service_charges: type: array items: $ref: '#/components/schemas/OrderServiceCharge' description: A list of service charges applied to the order. nullable: true fulfillments: type: array items: $ref: '#/components/schemas/Fulfillment' description: 'Details about order fulfillment. Orders can only be created with at most one fulfillment. However, orders returned by the API might contain multiple fulfillments.' nullable: true returns: type: array items: $ref: '#/components/schemas/OrderReturn' description: 'A collection of items from sale orders being returned in this one. Normally part of an itemized return or exchange. There is exactly one `Return` object per sale `Order` being referenced.' readOnly: true x-release-status: BETA return_amounts: $ref: '#/components/schemas/OrderMoneyAmounts' description: The rollup of the returned money amounts. readOnly: true x-release-status: BETA net_amounts: $ref: '#/components/schemas/OrderMoneyAmounts' description: The net money amounts (sale money - return money). readOnly: true x-release-status: BETA rounding_adjustment: $ref: '#/components/schemas/OrderRoundingAdjustment' description: 'A positive rounding adjustment to the total of the order. This adjustment is commonly used to apply cash rounding when the minimum unit of account is smaller than the lowest physical denomination of the currency.' readOnly: true x-release-status: BETA tenders: type: array items: $ref: '#/components/schemas/Tender' description: The tenders that were used to pay for the order. readOnly: true x-release-status: BETA refunds: type: array items: $ref: '#/components/schemas/Refund' description: The refunds that are part of this order. readOnly: true x-release-status: BETA metadata: type: object additionalProperties: type: string description: 'Application-defined data attached to this order. Metadata fields are intended to store descriptive references or associations with an entity in another system or store brief information about the object. Square does not process this field; it only stores and returns it in relevant API calls. Do not use metadata to store any sensitive information (such as personally identifiable information or card details). Keys written by applications must be 60 characters or less and must be in the character set `[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed with a namespace, separated from the key with a '':'' character. Values have a maximum length of 255 characters. An application can have up to 10 entries per metadata field. Entries written by applications are private and can only be read or modified by the same application. For more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).' x-release-status: BETA nullable: true created_at: type: string description: The timestamp for when the order was created, at server side, in RFC 3339 format (for example, "2016-09-04T23:59:33.123Z"). readOnly: true updated_at: type: string description: The timestamp for when the order was last updated, at server side, in RFC 3339 format (for example, "2016-09-04T23:59:33.123Z"). readOnly: true closed_at: type: string description: The timestamp for when the order reached a terminal [state](entity:OrderState), in RFC 3339 format (for example "2016-09-04T23:59:33.123Z"). readOnly: true state: $ref: '#/components/schemas/OrderState' description: 'The current state of the order. See [OrderState](#type-orderstate) for possible values' nullable: true version: type: integer description: 'The version number, which is incremented each time an update is committed to the order. Orders not created through the API do not include a version number and therefore cannot be updated. [Read more about working with versions](https://developer.squareup.com/docs/orders-api/manage-orders/update-orders).' x-release-status: BETA total_money: $ref: '#/components/schemas/Money' description: The total amount of money to collect for the order. readOnly: true total_tax_money: $ref: '#/components/schemas/Money' description: The total amount of tax money to collect for the order. readOnly: true total_discount_money: $ref: '#/components/schemas/Money' description: The total amount of discount money to collect for the order. readOnly: true total_tip_money: $ref: '#/components/schemas/Money' description: The total amount of tip money to collect for the order. readOnly: true total_service_charge_money: $ref: '#/components/schemas/Money' description: 'The total amount of money collected in service charges for the order. Note: `total_service_charge_money` is the sum of `applied_money` fields for each individual service charge. Therefore, `total_service_charge_money` only includes inclusive tax amounts, not additive tax amounts.' readOnly: true ticket_name: type: string description: 'A short-term identifier for the order (such as a customer first name, table number, or auto-generated order number that resets daily).' maxLength: 30 x-release-status: BETA nullable: true pricing_options: $ref: '#/components/schemas/OrderPricingOptions' description: 'Pricing options for an order. The options affect how the order''s price is calculated. They can be used, for example, to apply automatic price adjustments that are based on preconfigured [pricing rules](entity:CatalogPricingRule).' nullable: true rewards: type: array items: $ref: '#/components/schemas/OrderReward' description: A set-like list of Rewards that have been added to the Order. readOnly: true x-release-status: BETA net_amount_due_money: $ref: '#/components/schemas/Money' description: The net amount of money due on the order. readOnly: true CatalogItemFoodAndBeverageDetailsDietaryPreferenceType: type: string enum: - STANDARD - CUSTOM x-enum-elements: - name: STANDARD description: A standard value from a pre-determined list. - name: CUSTOM description: A user-defined custom value. description: The type of dietary preference for the `FOOD_AND_BEV` type of items and integredients. x-release-status: PUBLIC RefundStatus: type: string enum: - PENDING - APPROVED - REJECTED - FAILED x-enum-elements: - name: PENDING description: The refund is pending. - name: APPROVED description: The refund has been approved by Square. - name: REJECTED description: The refund has been rejected by Square. - name: FAILED description: The refund failed. description: Indicates a refund's current status. x-release-status: PUBLIC TenderSquareAccountDetails: type: object description: Represents the details of a tender with `type` `SQUARE_ACCOUNT`. x-release-status: PUBLIC properties: status: $ref: '#/components/schemas/TenderSquareAccountDetailsStatus' description: 'The Square Account payment''s current state (such as `AUTHORIZED` or `CAPTURED`). See [TenderSquareAccountDetailsStatus](entity:TenderSquareAccountDetailsStatus) for possible values. See [Status](#type-status) for possible values' nullable: true CatalogPricingRule: type: object description: 'Defines how discounts are automatically applied to a set of items that match the pricing rule during the active time period.' x-release-status: PUBLIC properties: name: type: string description: 'User-defined name for the pricing rule. For example, "Buy one get one free" or "10% off".' nullable: true time_period_ids: type: array items: type: string description: 'A list of unique IDs for the catalog time periods when this pricing rule is in effect. If left unset, the pricing rule is always in effect.' nullable: true discount_id: type: string description: 'Unique ID for the `CatalogDiscount` to take off the price of all matched items.' nullable: true match_products_id: type: string description: 'Unique ID for the `CatalogProductSet` that will be matched by this rule. A match rule matches within the entire cart, and can match multiple times. This field will always be set.' nullable: true apply_products_id: type: string description: '__Deprecated__: Please use the `exclude_products_id` field to apply an exclude set instead. Exclude sets allow better control over quantity ranges and offer more flexibility for which matched items receive a discount. `CatalogProductSet` to apply the pricing to. An apply rule matches within the subset of the cart that fits the match rules (the match set). An apply rule can only match once in the match set. If not supplied, the pricing will be applied to all products in the match set. Other products retain their base price, or a price generated by other rules.' x-release-status: DEPRECATED nullable: true exclude_products_id: type: string description: '`CatalogProductSet` to exclude from the pricing rule. An exclude rule matches within the subset of the cart that fits the match rules (the match set). An exclude rule can only match once in the match set. If not supplied, the pricing will be applied to all products in the match set. Other products retain their base price, or a price generated by other rules.' nullable: true valid_from_date: type: string description: Represents the date the Pricing Rule is valid from. Represented in RFC 3339 full-date format (YYYY-MM-DD). nullable: true valid_from_local_time: type: string description: 'Represents the local time the pricing rule should be valid from. Represented in RFC 3339 partial-time format (HH:MM:SS). Partial seconds will be truncated.' nullable: true valid_until_date: type: string description: Represents the date the Pricing Rule is valid until. Represented in RFC 3339 full-date format (YYYY-MM-DD). nullable: true valid_until_local_time: type: string description: 'Represents the local time the pricing rule should be valid until. Represented in RFC 3339 partial-time format (HH:MM:SS). Partial seconds will be truncated.' nullable: true exclude_strategy: $ref: '#/components/schemas/ExcludeStrategy' description: 'If an `exclude_products_id` was given, controls which subset of matched products is excluded from any discounts. Default value: `LEAST_EXPENSIVE` See [ExcludeStrategy](#type-excludestrategy) for possible values' nullable: true minimum_order_subtotal_money: $ref: '#/components/schemas/Money' description: 'The minimum order subtotal (before discounts or taxes are applied) that must be met before this rule may be applied.' nullable: true customer_group_ids_any: type: array items: type: string description: 'A list of IDs of customer groups, the members of which are eligible for discounts specified in this pricing rule. Notice that a group ID is generated by the Customers API. If this field is not set, the specified discount applies to matched products sold to anyone whether the buyer has a customer profile created or not. If this `customer_group_ids_any` field is set, the specified discount applies only to matched products sold to customers belonging to the specified customer groups.' nullable: true CatalogModifierListModifierType: type: string enum: - LIST - TEXT x-enum-elements: - name: LIST description: The `CatalogModifierList` instance is a non-empty list of non text-based modifiers. - name: TEXT description: The `CatalogModifierList` instance is a single text-based modifier. description: Defines the type of `CatalogModifierList`. x-release-status: BETA CatalogObjectCategory: type: object description: "A category that can be assigned to an item or a parent category that can be assigned \nto another category. For example, a clothing category can be assigned to a t-shirt item or \nbe made as the parent category to the pants category." x-release-status: BETA properties: id: type: string description: The ID of the object's category. ordinal: type: integer description: The order of the object within the context of the category. format: int64 nullable: true CheckoutLocationSettingsTipping: type: object x-release-status: BETA properties: percentages: type: array items: type: integer description: Set three custom percentage amounts that buyers can select at checkout. If Smart Tip is enabled, this only applies to transactions totaling $10 or more. nullable: true smart_tipping_enabled: type: boolean description: "Enables Smart Tip Amounts. If Smart Tip Amounts is enabled, tipping works as follows:\nIf a transaction is less than $10, the available tipping options include No Tip, $1, $2, or $3.\nIf a transaction is $10 or more, the available tipping options include No Tip, 15%, 20%, or 25%. \nYou can set custom percentage amounts with the `percentages` field." nullable: true default_percent: type: integer description: Set the pre-selected percentage amounts that appear at checkout. If Smart Tip is enabled, this only applies to transactions totaling $10 or more. nullable: true smart_tips: type: array items: $ref: '#/components/schemas/Money' description: Show the Smart Tip Amounts for this location. nullable: true default_smart_tip: $ref: '#/components/schemas/Money' description: Set the pre-selected whole amount that appears at checkout when Smart Tip is enabled and the transaction amount is less than $10. nullable: true SubscriptionPhase: type: object description: Describes a phase in a subscription plan variation. For more information, see [Subscription Plans and Variations](https://developer.squareup.com/docs/subscriptions-api/plans-and-variations). x-release-status: PUBLIC required: - cadence properties: uid: type: string description: The Square-assigned ID of the subscription phase. This field cannot be changed after a `SubscriptionPhase` is created. nullable: true cadence: $ref: '#/components/schemas/SubscriptionCadence' description: 'The billing cadence of the phase. For example, weekly or monthly. This field cannot be changed after a `SubscriptionPhase` is created. See [SubscriptionCadence](#type-subscriptioncadence) for possible values' periods: type: integer description: The number of `cadence`s the phase lasts. If not set, the phase never ends. Only the last phase can be indefinite. This field cannot be changed after a `SubscriptionPhase` is created. nullable: true recurring_price_money: $ref: '#/components/schemas/Money' description: The amount to bill for each `cadence`. Failure to specify this field results in a `MISSING_REQUIRED_PARAMETER` error at runtime. nullable: true ordinal: type: integer description: The position this phase appears in the sequence of phases defined for the plan, indexed from 0. This field cannot be changed after a `SubscriptionPhase` is created. format: int64 nullable: true pricing: $ref: '#/components/schemas/SubscriptionPricing' description: The subscription pricing. nullable: true CatalogItemFoodAndBeverageDetailsIngredientStandardIngredient: type: string enum: - CELERY - CRUSTACEANS - EGGS - FISH - GLUTEN - LUPIN - MILK - MOLLUSCS - MUSTARD - PEANUTS - SESAME - SOY - SULPHITES - TREE_NUTS x-enum-elements: - name: CELERY description: '' - name: CRUSTACEANS description: '' - name: EGGS description: '' - name: FISH description: '' - name: GLUTEN description: '' - name: LUPIN description: '' - name: MILK description: '' - name: MOLLUSCS description: '' - name: MUSTARD description: '' - name: PEANUTS description: '' - name: SESAME description: '' - name: SOY description: '' - name: SULPHITES description: '' - name: TREE_NUTS description: '' description: Standard ingredients for food and beverage items that are recommended on item creation. x-release-status: PUBLIC CatalogSubscriptionPlanVariation: type: object description: 'Describes a subscription plan variation. A subscription plan variation represents how the subscription for a product or service is sold. For more information, see [Subscription Plans and Variations](https://developer.squareup.com/docs/subscriptions-api/plans-and-variations).' x-release-status: PUBLIC required: - name - phases properties: name: type: string description: The name of the plan variation. phases: type: array items: $ref: '#/components/schemas/SubscriptionPhase' description: A list containing each [SubscriptionPhase](entity:SubscriptionPhase) for this plan variation. subscription_plan_id: type: string description: The id of the subscription plan, if there is one. nullable: true monthly_billing_anchor_date: type: integer description: The day of the month the billing period starts. format: int64 minimum: 1 maximum: 31 nullable: true can_prorate: type: boolean description: Whether bills for this plan variation can be split for proration. nullable: true successor_plan_variation_id: type: string description: 'The ID of a "successor" plan variation to this one. If the field is set, and this object is disabled at all locations, it indicates that this variation is deprecated and the object identified by the successor ID be used in its stead.' nullable: true OrderServiceChargeCalculationPhase: type: string enum: - SUBTOTAL_PHASE - TOTAL_PHASE - APPORTIONED_PERCENTAGE_PHASE - APPORTIONED_AMOUNT_PHASE x-enum-elements: - name: SUBTOTAL_PHASE description: 'The service charge is applied after discounts, but before taxes.' - name: TOTAL_PHASE description: 'The service charge is applied after all discounts and taxes are applied.' - name: APPORTIONED_PERCENTAGE_PHASE description: 'The service charge is calculated as a compounding adjustment after any discounts, but before amount based apportioned service charges and any tax considerations.' - name: APPORTIONED_AMOUNT_PHASE description: 'The service charge is calculated as a compounding adjustment after any discounts and percentage based apportioned service charges, but before any tax considerations.' description: 'Represents a phase in the process of calculating order totals. Service charges are applied after the indicated phase. [Read more about how order totals are calculated.](https://developer.squareup.com/docs/orders-api/how-it-works#how-totals-are-calculated)' x-release-status: PUBLIC 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 a missing, malformed, or otherwise invalid `Authorization` header.' - name: INVALID_REQUEST_ERROR description: 'The request was invalid. Most commonly, a required parameter was missing, 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 to Square APIs in a short period of time. Your 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) schedule 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, the details of the payment method were invalid (such as a card''s CVV or 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 request to the Connect API.' x-release-status: PUBLIC OrderLineItemAppliedTax: type: object description: 'Represents an applied portion of a tax to a line item in an order. Order-scoped taxes automatically include the applied taxes in each line item. Line item taxes must be referenced from any applicable line items. The corresponding applied money is automatically computed, based on the set of participating line items.' x-release-status: BETA required: - tax_uid properties: uid: type: string description: A unique ID that identifies the applied tax only within this order. maxLength: 60 nullable: true tax_uid: type: string description: 'The `uid` of the tax for which this applied tax represents. It must reference a tax present in the `order.taxes` field. This field is immutable. To change which taxes apply to a line item, delete and add a new `OrderLineItemAppliedTax`.' minLength: 1 maxLength: 60 applied_money: $ref: '#/components/schemas/Money' description: The amount of money applied by the tax to the line item. readOnly: true 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 to [ISO 4217](https://wikipedia.org/wiki/ISO_4217).' x-release-status: PUBLIC CardPrepaidType: type: string enum: - UNKNOWN_PREPAID_TYPE - NOT_PREPAID - PREPAID x-enum-elements: - name: UNKNOWN_PREPAID_TYPE description: '' - name: NOT_PREPAID description: '' - name: PREPAID description: '' description: Indicates a card's prepaid type, such as `NOT_PREPAID` or `PREPAID`. x-release-status: PUBLIC CustomField: type: object description: 'Describes a custom form field to add to the checkout page to collect more information from buyers during checkout. For more information, see [Specify checkout options](https://developer.squareup.com/docs/checkout-api/optional-checkout-configurations#specify-checkout-options-1).' x-release-status: PUBLIC required: - title properties: title: type: string description: The title of the custom field. minLength: 1 maxLength: 50 CreateOrderRequest: type: object x-release-status: PUBLIC properties: order: $ref: '#/components/schemas/Order' description: 'The order to create. If this field is set, the only other top-level field that can be set is the `idempotency_key`.' idempotency_key: type: string description: 'A value you specify that uniquely identifies this order among orders you have created. If you are unsure whether a particular order was created successfully, you can try it again with the same idempotency key without worrying about creating duplicate orders. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).' maxLength: 192 example: idempotency_key: 8193148c-9586-11e6-99f9-28cfe92138cf order: discounts: - name: Labor Day Sale percentage: '5' scope: ORDER uid: labor-day-sale - catalog_object_id: DB7L55ZH2BGWI4H23ULIWOQ7 scope: ORDER uid: membership-discount - amount_money: amount: 100 currency: USD name: Sale - $1.00 off scope: LINE_ITEM uid: one-dollar-off line_items: - base_price_money: amount: 1599 currency: USD name: New York Strip Steak quantity: '1' - applied_discounts: - discount_uid: one-dollar-off catalog_object_id: BEMYCSMIJL46OCDV4KYIKXIB modifiers: - catalog_object_id: CHQX7Y4KY6N5KINJKZCFURPZ quantity: '2' location_id: 057P5VYJ4A5X1 reference_id: my-order-001 taxes: - name: State Sales Tax percentage: '9' scope: ORDER uid: state-sales-tax CatalogDiscount: type: object description: A discount applicable to items. x-release-status: PUBLIC properties: name: type: string description: The discount name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points. maxLength: 255 nullable: true discount_type: $ref: '#/components/schemas/CatalogDiscountType' description: 'Indicates whether the discount is a fixed amount or percentage, or entered at the time of sale. See [CatalogDiscountType](#type-catalogdiscounttype) for possible values' nullable: true percentage: type: string description: 'The percentage of the discount as a string representation of a decimal number, using a `.` as the decimal separator and without a `%` sign. A value of `7.5` corresponds to `7.5%`. Specify a percentage of `0` if `discount_type` is `VARIABLE_PERCENTAGE`. Do not use this field for amount-based or variable discounts.' nullable: true amount_money: $ref: '#/components/schemas/Money' description: 'The amount of the discount. Specify an amount of `0` if `discount_type` is `VARIABLE_AMOUNT`. Do not use this field for percentage-based or variable discounts.' nullable: true pin_required: type: boolean description: 'Indicates whether a mobile staff member needs to enter their PIN to apply the discount to a payment in the Square Point of Sale app.' nullable: true label_color: type: string description: The color of the discount display label in the Square Point of Sale app. This must be a valid hex color code. nullable: true modify_tax_basis: $ref: '#/components/schemas/CatalogDiscountModifyTaxBasis' description: 'Indicates whether this discount should reduce the price used to calculate tax. Most discounts should use `MODIFY_TAX_BASIS`. However, in some circumstances taxes must be calculated based on an item''s price, ignoring a particular discount. For example, in many US jurisdictions, a manufacturer coupon or instant rebate reduces the price a customer pays but does not reduce the sale price used to calculate how much sales tax is due. In this case, the discount representing that manufacturer coupon should have `DO_NOT_MODIFY_TAX_BASIS` for this field. If you are unsure whether you need to use this field, consult your tax professional. See [CatalogDiscountModifyTaxBasis](#type-catalogdiscountmodifytaxbasis) for possible values' nullable: true maximum_amount_money: $ref: '#/components/schemas/Money' description: 'For a percentage discount, the maximum absolute value of the discount. For example, if a 50% discount has a `maximum_amount_money` of $20, a $100 purchase will yield a $20 discount, not a $50 discount.' nullable: true example: object: discount_data: discount_type: FIXED_PERCENTAGE label_color: red name: Welcome to the Dark(Roast) Side! percentage: '5.4' pin_required: false id: '#Maythe4th' present_at_all_locations: true type: DISCOUNT OrderLineItemPricingBlocklistsBlockedTax: type: object description: 'A tax to block from applying to a line item. The tax must be identified by either `tax_uid` or `tax_catalog_object_id`, but not both.' x-release-status: BETA properties: uid: type: string description: A unique ID of the `BlockedTax` within the order. maxLength: 60 nullable: true tax_uid: type: string description: 'The `uid` of the tax that should be blocked. Use this field to block ad hoc taxes. For catalog, taxes use the `tax_catalog_object_id` field.' maxLength: 60 nullable: true tax_catalog_object_id: type: string description: 'The `catalog_object_id` of the tax that should be blocked. Use this field to block catalog taxes. For ad hoc taxes, use the `tax_uid` field.' maxLength: 192 nullable: true OrderLineItem: type: object description: 'Represents a line item in an order. Each line item describes a different product to purchase, with its own quantity and price details.' x-release-status: PUBLIC required: - quantity properties: uid: type: string description: A unique ID that identifies the line item only within this order. maxLength: 60 x-release-status: BETA nullable: true name: type: string description: The name of the line item. maxLength: 512 nullable: true quantity: type: string description: 'The count, or measurement, of a line item being purchased: If `quantity` is a whole number, and `quantity_unit` is not specified, then `quantity` denotes an item count. For example: `3` apples. If `quantity` is a whole or decimal number, and `quantity_unit` is also specified, then `quantity` denotes a measurement. For example: `2.25` pounds of broccoli. For more information, see [Specify item quantity and measurement unit](https://developer.squareup.com/docs/orders-api/create-orders#specify-item-quantity-and-measurement-unit). Line items with a quantity of `0` are automatically removed when paying for or otherwise completing the order.' minLength: 1 maxLength: 12 quantity_unit: $ref: '#/components/schemas/OrderQuantityUnit' description: The measurement unit and decimal precision that this line item's quantity is measured in. nullable: true note: type: string description: An optional note associated with the line item. maxLength: 2000 nullable: true catalog_object_id: type: string description: The [CatalogItemVariation](entity:CatalogItemVariation) ID applied to this line item. maxLength: 192 nullable: true catalog_version: type: integer description: The version of the catalog object that this line item references. format: int64 nullable: true variation_name: type: string description: The name of the variation applied to this line item. maxLength: 400 nullable: true item_type: $ref: '#/components/schemas/OrderLineItemItemType' description: 'The type of line item: an itemized sale, a non-itemized sale (custom amount), or the activation or reloading of a gift card. See [OrderLineItemItemType](#type-orderlineitemitemtype) for possible values' nullable: true metadata: type: object additionalProperties: type: string description: 'Application-defined data attached to this line item. Metadata fields are intended to store descriptive references or associations with an entity in another system or store brief information about the object. Square does not process this field; it only stores and returns it in relevant API calls. Do not use metadata to store any sensitive information (such as personally identifiable information or card details). Keys written by applications must be 60 characters or less and must be in the character set `[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed with a namespace, separated from the key with a '':'' character. Values have a maximum length of 255 characters. An application can have up to 10 entries per metadata field. Entries written by applications are private and can only be read or modified by the same application. For more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).' x-release-status: BETA nullable: true modifiers: type: array items: $ref: '#/components/schemas/OrderLineItemModifier' description: The [CatalogModifier](entity:CatalogModifier)s applied to this line item. nullable: true applied_taxes: type: array items: $ref: '#/components/schemas/OrderLineItemAppliedTax' description: 'The list of references to taxes applied to this line item. Each `OrderLineItemAppliedTax` has a `tax_uid` that references the `uid` of a top-level `OrderLineItemTax` applied to the line item. On reads, the amount applied is populated. An `OrderLineItemAppliedTax` is automatically created on every line item for all `ORDER` scoped taxes added to the order. `OrderLineItemAppliedTax` records for `LINE_ITEM` scoped taxes must be added in requests for the tax to apply to any line items. To change the amount of a tax, modify the referenced top-level tax.' x-release-status: BETA nullable: true applied_discounts: type: array items: $ref: '#/components/schemas/OrderLineItemAppliedDiscount' description: 'The list of references to discounts applied to this line item. Each `OrderLineItemAppliedDiscount` has a `discount_uid` that references the `uid` of a top-level `OrderLineItemDiscounts` applied to the line item. On reads, the amount applied is populated. An `OrderLineItemAppliedDiscount` is automatically created on every line item for all `ORDER` scoped discounts that are added to the order. `OrderLineItemAppliedDiscount` records for `LINE_ITEM` scoped discounts must be added in requests for the discount to apply to any line items. To change the amount of a discount, modify the referenced top-level discount.' x-release-status: BETA nullable: true applied_service_charges: type: array items: $ref: '#/components/schemas/OrderLineItemAppliedServiceCharge' description: 'The list of references to service charges applied to this line item. Each `OrderLineItemAppliedServiceCharge` has a `service_charge_id` that references the `uid` of a top-level `OrderServiceCharge` applied to the line item. On reads, the amount applied is populated. To change the amount of a service charge, modify the referenced top-level service charge.' x-release-status: BETA nullable: true base_price_money: $ref: '#/components/schemas/Money' description: The base price for a single unit of the line item. nullable: true variation_total_price_money: $ref: '#/components/schemas/Money' description: 'The total price of all item variations sold in this line item. The price is calculated as `base_price_money` multiplied by `quantity`. It does not include modifiers.' readOnly: true gross_sales_money: $ref: '#/components/schemas/Money' description: 'The amount of money made in gross sales for this line item. The amount is calculated as the sum of the variation''s total price and each modifier''s total price. For inclusive tax items in the US, Canada, and Japan, tax is deducted from `gross_sales_money`. For Europe and Australia, inclusive tax remains as part of the gross sale calculation.' readOnly: true total_tax_money: $ref: '#/components/schemas/Money' description: The total amount of tax money to collect for the line item. readOnly: true total_discount_money: $ref: '#/components/schemas/Money' description: The total amount of discount money to collect for the line item. readOnly: true total_money: $ref: '#/components/schemas/Money' description: The total amount of money to collect for this line item. readOnly: true pricing_blocklists: $ref: '#/components/schemas/OrderLineItemPricingBlocklists' description: 'Describes pricing adjustments that are blocked from automatic application to a line item. For more information, see [Apply Taxes and Discounts](https://developer.squareup.com/docs/orders-api/apply-taxes-and-discounts).' x-release-status: BETA nullable: true total_service_charge_money: $ref: '#/components/schemas/Money' description: The total amount of apportioned service charge money to collect for the line item. readOnly: true x-release-status: BETA CatalogStockConversion: type: object description: 'Represents the rule of conversion between a stockable [CatalogItemVariation](entity:CatalogItemVariation) and a non-stockable sell-by or receive-by `CatalogItemVariation` that share the same underlying stock.' x-release-status: BETA required: - stockable_item_variation_id - stockable_quantity - nonstockable_quantity properties: stockable_item_variation_id: type: string description: 'References to the stockable [CatalogItemVariation](entity:CatalogItemVariation) for this stock conversion. Selling, receiving or recounting the non-stockable `CatalogItemVariation` defined with a stock conversion results in adjustments of this stockable `CatalogItemVariation`. This immutable field must reference a stockable `CatalogItemVariation` that shares the parent [CatalogItem](entity:CatalogItem) of the converted `CatalogItemVariation.`' minLength: 1 stockable_quantity: type: string description: 'The quantity of the stockable item variation (as identified by `stockable_item_variation_id`) equivalent to the non-stockable item variation quantity (as specified in `nonstockable_quantity`) as defined by this stock conversion. It accepts a decimal number in a string format that can take up to 10 digits before the decimal point and up to 5 digits after the decimal point.' minLength: 1 maxLength: 16 nonstockable_quantity: type: string description: 'The converted equivalent quantity of the non-stockable [CatalogItemVariation](entity:CatalogItemVariation) in its measurement unit. The `stockable_quantity` value and this `nonstockable_quantity` value together define the conversion ratio between stockable item variation and the non-stockable item variation. It accepts a decimal number in a string format that can take up to 10 digits before the decimal point and up to 5 digits after the decimal point.' minLength: 1 maxLength: 16 CheckoutMerchantSettingsPaymentMethodsAfterpayClearpayEligibilityRange: type: object description: A range of purchase price that qualifies. x-release-status: BETA required: - min - max properties: min: $ref: '#/components/schemas/Money' max: $ref: '#/components/schemas/Money' FulfillmentFulfillmentLineItemApplication: type: string enum: - ALL - ENTRY_LIST x-enum-elements: - name: ALL description: If `ALL`, `entries` must be unset. - name: ENTRY_LIST description: If `ENTRY_LIST`, supply a list of `entries`. description: 'The `line_item_application` describes what order line items this fulfillment applies to. It can be `ALL` or `ENTRY_LIST` with a supplied list of fulfillment entries.' x-release-status: BETA OrderReturnLineItem: type: object description: The line item being returned in an order. x-release-status: BETA required: - quantity properties: uid: type: string description: A unique ID for this return line-item entry. maxLength: 60 nullable: true source_line_item_uid: type: string description: The `uid` of the line item in the original sale order. maxLength: 60 nullable: true name: type: string description: The name of the line item. maxLength: 512 nullable: true quantity: type: string description: 'The quantity returned, formatted as a decimal number. For example, `"3"`. Line items with a `quantity_unit` can have non-integer quantities. For example, `"1.70000"`.' minLength: 1 maxLength: 12 quantity_unit: $ref: '#/components/schemas/OrderQuantityUnit' description: The unit and precision that this return line item's quantity is measured in. nullable: true note: type: string description: The note of the return line item. maxLength: 2000 nullable: true catalog_object_id: type: string description: The [CatalogItemVariation](entity:CatalogItemVariation) ID applied to this return line item. maxLength: 192 nullable: true catalog_version: type: integer description: The version of the catalog object that this line item references. format: int64 nullable: true variation_name: type: string description: The name of the variation applied to this return line item. maxLength: 400 nullable: true item_type: $ref: '#/components/schemas/OrderLineItemItemType' description: 'The type of line item: an itemized return, a non-itemized return (custom amount), or the return of an unactivated gift card sale. See [OrderLineItemItemType](#type-orderlineitemitemtype) for possible values' nullable: true return_modifiers: type: array items: $ref: '#/components/schemas/OrderReturnLineItemModifier' description: The [CatalogModifier](entity:CatalogModifier)s applied to this line item. nullable: true applied_taxes: type: array items: $ref: '#/components/schemas/OrderLineItemAppliedTax' description: 'The list of references to `OrderReturnTax` entities applied to the return line item. Each `OrderLineItemAppliedTax` has a `tax_uid` that references the `uid` of a top-level `OrderReturnTax` applied to the return line item. On reads, the applied amount is populated.' nullable: true applied_discounts: type: array items: $ref: '#/components/schemas/OrderLineItemAppliedDiscount' description: 'The list of references to `OrderReturnDiscount` entities applied to the return line item. Each `OrderLineItemAppliedDiscount` has a `discount_uid` that references the `uid` of a top-level `OrderReturnDiscount` applied to the return line item. On reads, the applied amount is populated.' nullable: true base_price_money: $ref: '#/components/schemas/Money' description: The base price for a single unit of the line item. nullable: true variation_total_price_money: $ref: '#/components/schemas/Money' description: 'The total price of all item variations returned in this line item. The price is calculated as `base_price_money` multiplied by `quantity` and does not include modifiers.' readOnly: true gross_return_money: $ref: '#/components/schemas/Money' description: The gross return amount of money calculated as (item base price + modifiers price) * quantity. readOnly: true total_tax_money: $ref: '#/components/schemas/Money' description: The total amount of tax money to return for the line item. readOnly: true total_discount_money: $ref: '#/components/schemas/Money' description: The total amount of discount money to return for the line item. readOnly: true total_money: $ref: '#/components/schemas/Money' description: The total amount of money to return for this line item. readOnly: true applied_service_charges: type: array items: $ref: '#/components/schemas/OrderLineItemAppliedServiceCharge' description: 'The list of references to `OrderReturnServiceCharge` entities applied to the return line item. Each `OrderLineItemAppliedServiceCharge` has a `service_charge_uid` that references the `uid` of a top-level `OrderReturnServiceCharge` applied to the return line item. On reads, the applied amount is populated.' nullable: true total_service_charge_money: $ref: '#/components/schemas/Money' description: The total amount of apportioned service charge money to return for the line item. readOnly: true OrderServiceChargeType: type: string enum: - AUTO_GRATUITY - CUSTOM x-enum-elements: - name: AUTO_GRATUITY description: '' - name: CUSTOM description: '' x-release-status: PUBLIC Error: type: object description: 'Represents an error encountered during a request to the Connect API. See [Handling errors](https://developer.squareup.com/docs/build-basics/handling-errors) for more information.' x-release-status: PUBLIC required: - category - code properties: category: $ref: '#/components/schemas/ErrorCategory' description: 'The high-level category for the error. See [ErrorCategory](#type-errorcategory) for possible values' code: $ref: '#/components/schemas/ErrorCode' description: 'The specific code of the error. See [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 the error pertains to.' CatalogQuickAmountsSettings: type: object description: A parent Catalog Object model represents a set of Quick Amounts and the settings control the amounts. x-release-status: BETA required: - option properties: option: $ref: '#/components/schemas/CatalogQuickAmountsSettingsOption' description: 'Represents the option seller currently uses on Quick Amounts. See [CatalogQuickAmountsSettingsOption](#type-catalogquickamountssettingsoption) for possible values' eligible_for_auto_amounts: type: boolean description: 'Represents location''s eligibility for auto amounts The boolean should be consistent with whether there are AUTO amounts in the `amounts`.' nullable: true amounts: type: array items: $ref: '#/components/schemas/CatalogQuickAmount' description: Represents a set of Quick Amounts at this location. nullable: true OrderReward: type: object description: 'Represents a reward that can be applied to an order if the necessary reward tier criteria are met. Rewards are created through the Loyalty API.' x-release-status: BETA required: - id - reward_tier_id properties: id: type: string description: The identifier of the reward. minLength: 1 reward_tier_id: type: string description: The identifier of the reward tier corresponding to this reward. minLength: 1 CatalogEcomSeoData: type: object description: SEO data for for a seller's Square Online store. x-release-status: PUBLIC properties: page_title: type: string description: The SEO title used for the Square Online store. nullable: true page_description: type: string description: The SEO description used for the Square Online store. nullable: true permalink: type: string description: The SEO permalink used for the Square Online store. nullable: true InventoryAlertType: type: string enum: - NONE - LOW_QUANTITY x-enum-elements: - name: NONE description: The variation does not display an alert. - name: LOW_QUANTITY description: The variation generates an alert when its quantity is low. description: Indicates whether Square should alert the merchant when the inventory quantity of a CatalogItemVariation is low. x-release-status: PUBLIC OrderLineItemPricingBlocklistsBlockedDiscount: type: object description: 'A discount to block from applying to a line item. The discount must be identified by either `discount_uid` or `discount_catalog_object_id`, but not both.' x-release-status: BETA properties: uid: type: string description: A unique ID of the `BlockedDiscount` within the order. maxLength: 60 nullable: true discount_uid: type: string description: 'The `uid` of the discount that should be blocked. Use this field to block ad hoc discounts. For catalog discounts, use the `discount_catalog_object_id` field.' maxLength: 60 nullable: true discount_catalog_object_id: type: string description: 'The `catalog_object_id` of the discount that should be blocked. Use this field to block catalog discounts. For ad hoc discounts, use the `discount_uid` field.' maxLength: 192 nullable: true SubscriptionPricing: type: object description: Describes the pricing for the subscription. x-release-status: PUBLIC properties: type: $ref: '#/components/schemas/SubscriptionPricingType' description: 'RELATIVE or STATIC See [SubscriptionPricingType](#type-subscriptionpricingtype) for possible values' nullable: true discount_ids: type: array items: type: string description: The ids of the discount catalog objects nullable: true price_money: $ref: '#/components/schemas/Money' description: The price of the subscription, if STATIC nullable: true CatalogModifierList: type: object description: "For a text-based modifier, this encapsulates the modifier's text when its `modifier_type` is `TEXT`. \nFor example, to sell T-shirts with custom prints, a text-based modifier can be used to capture the buyer-supplied \ntext string to be selected for the T-shirt at the time of sale.\n\nFor non text-based modifiers, this encapsulates a non-empty list of modifiers applicable to items \nat the time of sale. Each element of the modifier list is a `CatalogObject` instance of the `MODIFIER` type. \nFor example, a \"Condiments\" modifier list applicable to a \"Hot Dog\" item\nmay contain \"Ketchup\", \"Mustard\", and \"Relish\" modifiers. \n\nA non text-based modifier can be applied to the modified item once or multiple times, if the `selection_type` field \nis set to `SINGLE` or `MULTIPLE`, respectively. On the other hand, a text-based modifier can be applied to the item \nonly once and the `selection_type` field is always set to `SINGLE`." x-release-status: PUBLIC properties: name: type: string description: "The name of the `CatalogModifierList` instance. This is a searchable attribute for use in applicable query filters, and its value length is of \nUnicode code points." maxLength: 255 nullable: true ordinal: type: integer description: The position of this `CatalogModifierList` within a list of `CatalogModifierList` instances. nullable: true selection_type: $ref: '#/components/schemas/CatalogModifierListSelectionType' description: 'Indicates whether a single (`SINGLE`) or multiple (`MULTIPLE`) modifiers from the list can be applied to a single `CatalogItem`. For text-based modifiers, the `selection_type` attribute is always `SINGLE`. The other value is ignored. See [CatalogModifierListSelectionType](#type-catalogmodifierlistselectiontype) for possible values' nullable: true modifiers: type: array items: $ref: '#/components/schemas/CatalogObject' description: "A non-empty list of `CatalogModifier` objects to be included in the `CatalogModifierList`, \nfor non text-based modifiers when the `modifier_type` attribute is `LIST`. Each element of this list \nis a `CatalogObject` instance of the `MODIFIER` type, containing the following attributes:\n```\n{\n\"id\": \"{{catalog_modifier_id}}\",\n\"type\": \"MODIFIER\", \n\"modifier_data\": {{a CatalogModifier instance>}} \n}\n```" nullable: true image_ids: type: array items: type: string description: 'The IDs of images associated with this `CatalogModifierList` instance. Currently these images are not displayed on Square products, but may be displayed in 3rd-party applications.' nullable: true modifier_type: $ref: '#/components/schemas/CatalogModifierListModifierType' description: "The type of the modifier. \n\nWhen this `modifier_type` value is `TEXT`, the `CatalogModifierList` represents a text-based modifier. \nWhen this `modifier_type` value is `LIST`, the `CatalogModifierList` contains a list of `CatalogModifier` objects.\nSee [CatalogModifierListModifierType](#type-catalogmodifierlistmodifiertype) for possible values" x-release-status: BETA nullable: true max_length: type: integer description: "The maximum length, in Unicode points, of the text string of the text-based modifier as represented by \nthis `CatalogModifierList` object with the `modifier_type` set to `TEXT`." x-release-status: BETA nullable: true text_required: type: boolean description: 'Whether the text string must be a non-empty string (`true`) or not (`false`) for a text-based modifier as represented by this `CatalogModifierList` object with the `modifier_type` set to `TEXT`.' x-release-status: BETA nullable: true internal_name: type: string description: "A note for internal use by the business. \n\nFor example, for a text-based modifier applied to a T-shirt item, if the buyer-supplied text of \"Hello, Kitty!\" \nis to be printed on the T-shirt, this `internal_name` attribute can be \"Use italic face\" as \nan instruction for the business to follow. \n\nFor non text-based modifiers, this `internal_name` attribute can be \nused to include SKUs, internal codes, or supplemental descriptions for internal use." maxLength: 512 x-release-status: BETA nullable: true example: id: '#MilkType' modifier_list_data: allow_quantities: false modifiers: - modifier_data: name: Whole Milk price_money: amount: 0 currency: USD present_at_all_locations: true type: MODIFIER - modifier_data: name: Almond Milk price_money: amount: 250 currency: USD present_at_all_locations: true type: MODIFIER - modifier_data: name: Soy Milk price_money: amount: 250 currency: USD present_at_all_locations: true type: MODIFIER name: Milk Type selection_type: SINGLE present_at_all_locations: true type: MODIFIER_LIST CatalogQuickAmount: type: object description: Represents a Quick Amount in the Catalog. x-release-status: BETA required: - type - amount properties: type: $ref: '#/components/schemas/CatalogQuickAmountType' description: 'Represents the type of the Quick Amount. See [CatalogQuickAmountType](#type-catalogquickamounttype) for possible values' amount: $ref: '#/components/schemas/Money' description: Represents the actual amount of the Quick Amount with Money type. score: type: integer description: 'Describes the ranking of the Quick Amount provided by machine learning model, in the range [0, 100]. MANUAL type amount will always have score = 100.' format: int64 nullable: true ordinal: type: integer description: The order in which this Quick Amount should be displayed. format: int64 nullable: true CatalogItem: type: object description: A [CatalogObject](entity:CatalogObject) instance of the `ITEM` type, also referred to as an item, in the catalog. x-release-status: PUBLIC properties: name: type: string description: The item's name. This is a searchable attribute for use in applicable query filters, its value must not be empty, and the length is of Unicode code points. maxLength: 512 nullable: true description: type: string description: 'The item''s description. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points. Deprecated at 2022-07-20, this field is planned to retire in 6 months. You should migrate to use `description_html` to set the description of the [CatalogItem](entity:CatalogItem) instance. The `description` and `description_html` field values are kept in sync. If you try to set the both fields, the `description_html` text value overwrites the `description` value. Updates in one field are also reflected in the other, except for when you use an early version before Square API 2022-07-20 and `description_html` is set to blank, setting the `description` value to null does not nullify `description_html`.' maxLength: 4096 x-release-status: DEPRECATED nullable: true abbreviation: type: string description: 'The text of the item''s display label in the Square Point of Sale app. Only up to the first five characters of the string are used. This attribute is searchable, and its value length is of Unicode code points.' maxLength: 24 nullable: true label_color: type: string description: The color of the item's display label in the Square Point of Sale app. This must be a valid hex color code. nullable: true is_taxable: type: boolean description: Indicates whether the item is taxable (`true`) or non-taxable (`false`). Default is `true`. nullable: true category_id: type: string description: The ID of the item's category, if any. Deprecated since 2023-12-13. Use `CatalogItem.categories`, instead. x-release-status: DEPRECATED nullable: true tax_ids: type: array items: type: string description: 'A set of IDs indicating the taxes enabled for this item. When updating an item, any taxes listed here will be added to the item. Taxes may also be added to or deleted from an item using `UpdateItemTaxes`.' nullable: true modifier_list_info: type: array items: $ref: '#/components/schemas/CatalogItemModifierListInfo' description: 'A set of `CatalogItemModifierListInfo` objects representing the modifier lists that apply to this item, along with the overrides and min and max limits that are specific to this item. Modifier lists may also be added to or deleted from an item using `UpdateItemModifierLists`.' nullable: true variations: type: array items: $ref: '#/components/schemas/CatalogObject' description: 'A list of [CatalogItemVariation](entity:CatalogItemVariation) objects for this item. An item must have at least one variation.' nullable: true product_type: $ref: '#/components/schemas/CatalogItemProductType' description: 'The product type of the item. Once set, the `product_type` value cannot be modified. Items of the `LEGACY_SQUARE_ONLINE_SERVICE` and `LEGACY_SQUARE_ONLINE_MEMBERSHIP` product types can be updated but cannot be created using the API. See [CatalogItemProductType](#type-catalogitemproducttype) for possible values' nullable: true skip_modifier_screen: type: boolean description: 'If `false`, the Square Point of Sale app will present the `CatalogItem`''s details screen immediately, allowing the merchant to choose `CatalogModifier`s before adding the item to the cart. This is the default behavior. If `true`, the Square Point of Sale app will immediately add the item to the cart with the pre-selected modifiers, and merchants can edit modifiers by drilling down onto the item''s details. Third-party clients are encouraged to implement similar behaviors.' nullable: true item_options: type: array items: $ref: '#/components/schemas/CatalogItemOptionForItem' description: 'List of item options IDs for this item. Used to manage and group item variations in a specified order. Maximum: 6 item options.' nullable: true image_ids: type: array items: type: string description: 'The IDs of images associated with this `CatalogItem` instance. These images will be shown to customers in Square Online Store. The first image will show up as the icon for this item in POS.' x-release-status: BETA nullable: true sort_name: type: string description: 'A name to sort the item by. If this name is unspecified, namely, the `sort_name` field is absent, the regular `name` field is used for sorting. Its value must not be empty. It is currently supported for sellers of the Japanese locale only.' x-release-status: BETA nullable: true categories: type: array items: $ref: '#/components/schemas/CatalogObjectCategory' description: The list of categories. nullable: true description_html: type: string description: 'The item''s description as expressed in valid HTML elements. The length of this field value, including those of HTML tags, is of Unicode points. With application query filters, the text values of the HTML elements and attributes are searchable. Invalid or unsupported HTML elements or attributes are ignored. Supported HTML elements include: - `a`: Link. Supports linking to website URLs, email address, and telephone numbers. - `b`, `strong`: Bold text - `br`: Line break - `code`: Computer code - `div`: Section - `h1-h6`: Headings - `i`, `em`: Italics - `li`: List element - `ol`: Numbered list - `p`: Paragraph - `ul`: Bullet list - `u`: Underline Supported HTML attributes include: - `align`: Alignment of the text content - `href`: Link destination - `rel`: Relationship between link''s target and source - `target`: Place to open the linked document' maxLength: 65535 nullable: true description_plaintext: type: string description: A server-generated plaintext version of the `description_html` field, without formatting tags. maxLength: 65535 readOnly: true channels: type: array items: type: string description: 'A list of IDs representing channels, such as a Square Online site, where the item can be made visible or available. This field is read only and cannot be edited.' nullable: true is_archived: type: boolean description: Indicates whether this item is archived (`true`) or not (`false`). nullable: true ecom_seo_data: $ref: '#/components/schemas/CatalogEcomSeoData' description: The SEO data for a seller's Square Online store. nullable: true food_and_beverage_details: $ref: '#/components/schemas/CatalogItemFoodAndBeverageDetails' description: The food and beverage-specific details for the `FOOD_AND_BEV` item. nullable: true reporting_category: $ref: '#/components/schemas/CatalogObjectCategory' description: The item's reporting category. nullable: true example: object: id: '#Cocoa' item_data: abbreviation: Ch description: Hot chocolate name: Cocoa visibility: PRIVATE present_at_all_locations: true type: ITEM CatalogCustomAttributeDefinitionAppVisibility: type: string enum: - APP_VISIBILITY_HIDDEN - APP_VISIBILITY_READ_ONLY - APP_VISIBILITY_READ_WRITE_VALUES x-enum-elements: - name: APP_VISIBILITY_HIDDEN description: Other applications cannot read this custom attribute. - name: APP_VISIBILITY_READ_ONLY description: 'Other applications can read this custom attribute definition and values.' - name: APP_VISIBILITY_READ_WRITE_VALUES description: 'Other applications can read and write custom attribute values on objects. They can read but cannot edit the custom attribute definition.' description: 'Defines the visibility of a custom attribute to applications other than their creating application.' x-release-status: PUBLIC OrderReturnServiceCharge: type: object description: Represents the service charge applied to the original order. x-release-status: PUBLIC properties: uid: type: string description: A unique ID that identifies the return service charge only within this order. maxLength: 60 x-release-status: BETA nullable: true source_service_charge_uid: type: string description: 'The service charge `uid` from the order containing the original service charge. `source_service_charge_uid` is `null` for unlinked returns.' maxLength: 60 nullable: true name: type: string description: The name of the service charge. maxLength: 255 nullable: true catalog_object_id: type: string description: The catalog object ID of the associated [OrderServiceCharge](entity:OrderServiceCharge). maxLength: 192 nullable: true catalog_version: type: integer description: The version of the catalog object that this service charge references. format: int64 nullable: true percentage: type: string description: 'The percentage of the service charge, as a string representation of a decimal number. For example, a value of `"7.25"` corresponds to a percentage of 7.25%. Either `percentage` or `amount_money` should be set, but not both.' maxLength: 10 nullable: true amount_money: $ref: '#/components/schemas/Money' description: 'The amount of a non-percentage-based service charge. Either `percentage` or `amount_money` should be set, but not both.' nullable: true applied_money: $ref: '#/components/schemas/Money' description: 'The amount of money applied to the order by the service charge, including any inclusive tax amounts, as calculated by Square. - For fixed-amount service charges, `applied_money` is equal to `amount_money`. - For percentage-based service charges, `applied_money` is the money calculated using the percentage.' readOnly: true total_money: $ref: '#/components/schemas/Money' description: 'The total amount of money to collect for the service charge. __NOTE__: If an inclusive tax is applied to the service charge, `total_money` does not equal `applied_money` plus `total_tax_money` because the inclusive tax amount is already included in both `applied_money` and `total_tax_money`.' readOnly: true total_tax_money: $ref: '#/components/schemas/Money' description: The total amount of tax money to collect for the service charge. readOnly: true calculation_phase: $ref: '#/components/schemas/OrderServiceChargeCalculationPhase' description: 'The calculation phase after which to apply the service charge. See [OrderServiceChargeCalculationPhase](#type-orderservicechargecalculationphase) for possible values' readOnly: true taxable: type: boolean description: 'Indicates whether the surcharge can be taxed. Service charges calculated in the `TOTAL_PHASE` cannot be marked as taxable.' nullable: true applied_taxes: type: array items: $ref: '#/components/schemas/OrderLineItemAppliedTax' description: 'The list of references to `OrderReturnTax` entities applied to the `OrderReturnServiceCharge`. Each `OrderLineItemAppliedTax` has a `tax_uid` that references the `uid` of a top-level `OrderReturnTax` that is being applied to the `OrderReturnServiceCharge`. On reads, the applied amount is populated.' x-release-status: BETA nullable: true treatment_type: $ref: '#/components/schemas/OrderServiceChargeTreatmentType' description: 'The treatment type of the service charge. See [OrderServiceChargeTreatmentType](#type-orderservicechargetreatmenttype) for possible values' x-release-status: BETA nullable: true scope: $ref: '#/components/schemas/OrderServiceChargeScope' description: 'Indicates the level at which the apportioned service charge applies. For `ORDER` scoped service charges, Square generates references in `applied_service_charges` on all order line items that do not have them. For `LINE_ITEM` scoped service charges, the service charge only applies to line items with a service charge reference in their `applied_service_charges` field. This field is immutable. To change the scope of an apportioned service charge, you must delete the apportioned service charge and re-add it as a new apportioned service charge. See [OrderServiceChargeScope](#type-orderservicechargescope) for possible values' x-release-status: BETA nullable: true OrderLineItemTaxScope: type: string enum: - OTHER_TAX_SCOPE - LINE_ITEM - ORDER x-enum-elements: - name: OTHER_TAX_SCOPE description: 'Used for reporting only. The original transaction tax scope is currently not supported by the API.' - name: LINE_ITEM description: 'The tax should be applied only to line items specified by the `OrderLineItemAppliedTax` reference records.' - name: ORDER description: The tax should be applied to the entire order. description: Indicates whether this is a line-item or order-level tax. x-release-status: PUBLIC MeasurementUnit: type: object description: 'Represents a unit of measurement to use with a quantity, such as ounces or inches. Exactly one of the following fields are required: `custom_unit`, `area_unit`, `length_unit`, `volume_unit`, and `weight_unit`.' x-release-status: PUBLIC properties: custom_unit: $ref: '#/components/schemas/MeasurementUnitCustom' description: 'A custom unit of measurement defined by the seller using the Point of Sale app or ad-hoc as an order line item.' nullable: true area_unit: $ref: '#/components/schemas/MeasurementUnitArea' description: 'Represents a standard area unit. See [MeasurementUnitArea](#type-measurementunitarea) for possible values' nullable: true length_unit: $ref: '#/components/schemas/MeasurementUnitLength' description: 'Represents a standard length unit. See [MeasurementUnitLength](#type-measurementunitlength) for possible values' nullable: true volume_unit: $ref: '#/components/schemas/MeasurementUnitVolume' description: 'Represents a standard volume unit. See [MeasurementUnitVolume](#type-measurementunitvolume) for possible values' nullable: true weight_unit: $ref: '#/components/schemas/MeasurementUnitWeight' description: 'Represents a standard unit of weight or mass. See [MeasurementUnitWeight](#type-measurementunitweight) for possible values' nullable: true generic_unit: $ref: '#/components/schemas/MeasurementUnitGeneric' description: 'Reserved for API integrations that lack the ability to specify a real measurement unit See [MeasurementUnitGeneric](#type-measurementunitgeneric) for possible values' nullable: true time_unit: $ref: '#/components/schemas/MeasurementUnitTime' description: 'Represents a standard unit of time. See [MeasurementUnitTime](#type-measurementunittime) for possible values' nullable: true type: $ref: '#/components/schemas/MeasurementUnitUnitType' description: 'Represents the type of the measurement unit. See [MeasurementUnitUnitType](#type-measurementunitunittype) for possible values' nullable: true ShippingFee: type: object x-release-status: PUBLIC required: - charge properties: name: type: string description: The name for the shipping fee. nullable: true charge: $ref: '#/components/schemas/Money' description: The amount and currency for the shipping fee. FulfillmentState: type: string enum: - PROPOSED - RESERVED - PREPARED - COMPLETED - CANCELED - FAILED x-enum-elements: - name: PROPOSED description: Indicates that the fulfillment has been proposed. - name: RESERVED description: Indicates that the fulfillment has been reserved. - name: PREPARED description: Indicates that the fulfillment has been prepared. - name: COMPLETED description: Indicates that the fulfillment was successfully completed. - name: CANCELED description: Indicates that the fulfillment was canceled. - name: FAILED description: 'Indicates that the fulfillment failed to be completed, but was not explicitly canceled.' description: The current state of this fulfillment. x-release-status: PUBLIC TaxInclusionType: type: string enum: - ADDITIVE - INCLUSIVE x-enum-elements: - name: ADDITIVE description: 'The tax is an additive tax. The tax amount is added on top of the CatalogItemVariation price. For example, a $1.00 item with a 10% additive tax would have a total cost to the buyer of $1.10.' - name: INCLUSIVE description: 'The tax is an inclusive tax. The tax amount is included in the CatalogItemVariation price. For example, a $1.00 item with a 10% inclusive tax would have a total cost to the buyer of $1.00, with $0.91 (91 cents) of that total being the cost of the item and $0.09 (9 cents) being tax.' description: Whether to the tax amount should be additional to or included in the CatalogItem price. x-release-status: PUBLIC TenderBuyNowPayLaterDetailsBrand: type: string enum: - OTHER_BRAND - AFTERPAY x-enum-elements: - name: OTHER_BRAND description: '' - name: AFTERPAY description: '' x-release-status: PUBLIC OrderSource: type: object description: Represents the origination details of an order. x-release-status: PUBLIC properties: name: type: string description: 'The name used to identify the place (physical or digital) that an order originates. If unset, the name defaults to the name of the application that created the order.' nullable: true Fulfillment: type: object description: 'Contains details about how to fulfill this order. Orders can only be created with at most one fulfillment using the API. However, orders returned by the Orders API might contain multiple fulfillments because sellers can create multiple fulfillments using Square products such as Square Online.' x-release-status: PUBLIC properties: uid: type: string description: A unique ID that identifies the fulfillment only within this order. maxLength: 60 x-release-status: BETA nullable: true type: $ref: '#/components/schemas/FulfillmentType' description: 'The type of the fulfillment. See [FulfillmentType](#type-fulfillmenttype) for possible values' nullable: true state: $ref: '#/components/schemas/FulfillmentState' description: 'The state of the fulfillment. See [FulfillmentState](#type-fulfillmentstate) for possible values' nullable: true line_item_application: $ref: '#/components/schemas/FulfillmentFulfillmentLineItemApplication' description: 'Describes what order line items this fulfillment applies to. It can be `ALL` or `ENTRY_LIST` with a supplied list of fulfillment entries. See [FulfillmentFulfillmentLineItemApplication](#type-fulfillmentfulfillmentlineitemapplication) for possible values' readOnly: true x-release-status: BETA entries: type: array items: $ref: '#/components/schemas/FulfillmentFulfillmentEntry' description: 'A list of entries pertaining to the fulfillment of an order. Each entry must reference a valid `uid` for an order line item in the `line_item_uid` field, as well as a `quantity` to fulfill. Multiple entries can reference the same line item `uid`, as long as the total quantity among all fulfillment entries referencing a single line item does not exceed the quantity of the order''s line item itself. An order cannot be marked as `COMPLETED` before all fulfillments are `COMPLETED`, `CANCELED`, or `FAILED`. Fulfillments can be created and completed independently before order completion.' readOnly: true x-release-status: BETA metadata: type: object additionalProperties: type: string description: 'Application-defined data attached to this fulfillment. Metadata fields are intended to store descriptive references or associations with an entity in another system or store brief information about the object. Square does not process this field; it only stores and returns it in relevant API calls. Do not use metadata to store any sensitive information (such as personally identifiable information or card details). Keys written by applications must be 60 characters or less and must be in the character set `[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed with a namespace, separated from the key with a '':'' character. Values have a maximum length of 255 characters. An application can have up to 10 entries per metadata field. Entries written by applications are private and can only be read or modified by the same application. For more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).' x-release-status: BETA nullable: true pickup_details: $ref: '#/components/schemas/FulfillmentPickupDetails' description: 'Contains details for a pickup fulfillment. These details are required when the fulfillment type is `PICKUP`.' nullable: true shipment_details: $ref: '#/components/schemas/FulfillmentShipmentDetails' description: 'Contains details for a shipment fulfillment. These details are required when the fulfillment type is `SHIPMENT`. A shipment fulfillment''s relationship to fulfillment `state`: `PROPOSED`: A shipment is requested. `RESERVED`: Fulfillment in progress. Shipment processing. `PREPARED`: Shipment packaged. Shipping label created. `COMPLETED`: Package has been shipped. `CANCELED`: Shipment has been canceled. `FAILED`: Shipment has failed.' x-release-status: BETA nullable: true delivery_details: $ref: '#/components/schemas/FulfillmentDeliveryDetails' description: Describes delivery details of an order fulfillment. x-release-status: BETA nullable: true FulfillmentPickupDetailsCurbsidePickupDetails: type: object description: Specific details for curbside pickup. x-release-status: BETA properties: curbside_details: type: string description: Specific details for curbside pickup, such as parking number and vehicle model. maxLength: 250 nullable: true buyer_arrived_at: type: string description: 'The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates) indicating when the buyer arrived and is waiting for pickup. The timestamp must be in RFC 3339 format (for example, "2016-09-04T23:59:33.123Z").' nullable: true OrderLineItemDiscountScope: type: string enum: - OTHER_DISCOUNT_SCOPE - LINE_ITEM - ORDER x-enum-elements: - name: OTHER_DISCOUNT_SCOPE description: 'Used for reporting only. The original transaction discount scope is currently not supported by the API.' - name: LINE_ITEM description: 'The discount should be applied to only line items specified by `OrderLineItemAppliedDiscount` reference records.' - name: ORDER description: The discount should be applied to the entire order. description: Indicates whether this is a line-item or order-level discount. x-release-status: PUBLIC CatalogTax: type: object description: A tax applicable to an item. x-release-status: PUBLIC properties: name: type: string description: The tax's name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points. maxLength: 255 nullable: true calculation_phase: $ref: '#/components/schemas/TaxCalculationPhase' description: 'Whether the tax is calculated based on a payment''s subtotal or total. See [TaxCalculationPhase](#type-taxcalculationphase) for possible values' nullable: true inclusion_type: $ref: '#/components/schemas/TaxInclusionType' description: 'Whether the tax is `ADDITIVE` or `INCLUSIVE`. See [TaxInclusionType](#type-taxinclusiontype) for possible values' nullable: true percentage: type: string description: 'The percentage of the tax in decimal form, using a `''.''` as the decimal separator and without a `''%''` sign. A value of `7.5` corresponds to 7.5%. For a location-specific tax rate, contact the tax authority of the location or a tax consultant.' nullable: true applies_to_custom_amounts: type: boolean description: 'If `true`, the fee applies to custom amounts entered into the Square Point of Sale app that are not associated with a particular `CatalogItem`.' nullable: true enabled: type: boolean description: A Boolean flag to indicate whether the tax is displayed as enabled (`true`) in the Square Point of Sale app or not (`false`). nullable: true applies_to_product_set_id: type: string description: The ID of a `CatalogProductSet` object. If set, the tax is applicable to all products in the product set. x-release-status: BETA nullable: true example: object: id: '#SalesTax' present_at_all_locations: true tax_data: calculation_phase: TAX_SUBTOTAL_PHASE enabled: true fee_applies_to_custom_amounts: true inclusion_type: ADDITIVE name: Sales Tax percentage: '5.0' type: TAX RetrieveMerchantSettingsResponse: type: object x-release-status: BETA properties: errors: type: array items: $ref: '#/components/schemas/Error' description: Any errors that occurred during the request. merchant_settings: $ref: '#/components/schemas/CheckoutMerchantSettings' description: The merchant settings. example: merchant_settings: merchant_id: MERCHANT_ID payment_methods: afterpay_clearpay: enabled: true item_eligibility_range: max: amount: 10000 currency: USD min: amount: 100 currency: USD order_eligibility_range: max: amount: 10000 currency: USD min: amount: 100 currency: USD apple_pay: enabled: true cash_app_pay: enabled: true google_pay: enabled: true updated_at: '2022-06-16T22:25:35Z' CatalogCustomAttributeDefinition: type: object description: 'Contains information defining a custom attribute. Custom attributes are intended to store additional information about a catalog object or to associate a catalog object with an entity in another system. Do not use custom attributes to store any sensitive information (personally identifiable information, card details, etc.). [Read more about custom attributes](https://developer.squareup.com/docs/catalog-api/add-custom-attributes)' x-release-status: PUBLIC required: - type - name - allowed_object_types properties: type: $ref: '#/components/schemas/CatalogCustomAttributeDefinitionType' description: 'The type of this custom attribute. Cannot be modified after creation. Required. See [CatalogCustomAttributeDefinitionType](#type-catalogcustomattributedefinitiontype) for possible values' name: type: string description: ' The name of this definition for API and seller-facing UI purposes. The name must be unique within the (merchant, application) pair. Required. May not be empty and may not exceed 255 characters. Can be modified after creation.' minLength: 1 maxLength: 255 description: type: string description: 'Seller-oriented description of the meaning of this Custom Attribute, any constraints that the seller should observe, etc. May be displayed as a tooltip in Square UIs.' maxLength: 255 nullable: true source_application: $ref: '#/components/schemas/SourceApplication' description: '__Read only.__ Contains information about the application that created this custom attribute definition.' nullable: true allowed_object_types: type: array items: $ref: '#/components/schemas/CatalogObjectType' description: 'The set of `CatalogObject` types that this custom atttribute may be applied to. Currently, only `ITEM`, `ITEM_VARIATION`, `MODIFIER`, `MODIFIER_LIST`, and `CATEGORY` are allowed. At least one type must be included. See [CatalogObjectType](#type-catalogobjecttype) for possible values' seller_visibility: $ref: '#/components/schemas/CatalogCustomAttributeDefinitionSellerVisibility' description: 'The visibility of a custom attribute in seller-facing UIs (including Square Point of Sale applications and Square Dashboard). May be modified. See [CatalogCustomAttributeDefinitionSellerVisibility](#type-catalogcustomattributedefinitionsellervisibility) for possible values' nullable: true app_visibility: $ref: '#/components/schemas/CatalogCustomAttributeDefinitionAppVisibility' description: 'The visibility of a custom attribute to applications other than the application that created the attribute. See [CatalogCustomAttributeDefinitionAppVisibility](#type-catalogcustomattributedefinitionappvisibility) for possible values' nullable: true string_config: $ref: '#/components/schemas/CatalogCustomAttributeDefinitionStringConfig' description: Optionally, populated when `type` = `STRING`, unset otherwise. nullable: true number_config: $ref: '#/components/schemas/CatalogCustomAttributeDefinitionNumberConfig' description: Optionally, populated when `type` = `NUMBER`, unset otherwise. nullable: true selection_config: $ref: '#/components/schemas/CatalogCustomAttributeDefinitionSelectionConfig' description: Populated when `type` is set to `SELECTION`, unset otherwise. nullable: true custom_attribute_usage_count: type: integer description: 'The number of custom attributes that reference this custom attribute definition. Set by the server in response to a ListCatalog request with `include_counts` set to `true`. If the actual count is greater than 100, `custom_attribute_usage_count` will be set to `100`.' readOnly: true key: type: string description: 'The name of the desired custom attribute key that can be used to access the custom attribute value on catalog objects. Cannot be modified after the custom attribute definition has been created. Must be between 1 and 60 characters, and may only contain the characters `[a-zA-Z0-9_-]`.' minLength: 1 maxLength: 60 pattern: ^[a-zA-Z0-9_-]*$ nullable: true SubscriptionPricingType: type: string enum: - STATIC - RELATIVE x-enum-elements: - name: STATIC description: Static pricing - name: RELATIVE description: Relative pricing description: Determines the pricing of a [Subscription](entity:Subscription) x-release-status: PUBLIC PrePopulatedData: type: object description: 'Describes buyer data to prepopulate in the payment form. For more information, see [Optional Checkout Configurations](https://developer.squareup.com/docs/checkout-api/optional-checkout-configurations).' x-release-status: PUBLIC properties: buyer_email: type: string description: The buyer email to prepopulate in the payment form. maxLength: 256 nullable: true buyer_phone_number: type: string description: The buyer phone number to prepopulate in the payment form. maxLength: 17 nullable: true buyer_address: $ref: '#/components/schemas/Address' description: The buyer address to prepopulate in the payment form. nullable: true CatalogItemFoodAndBeverageDetails: type: object description: The food and beverage-specific details of a `FOOD_AND_BEV` item. x-release-status: PUBLIC properties: calorie_count: type: integer description: The calorie count (in the unit of kcal) for the `FOOD_AND_BEV` type of items. nullable: true dietary_preferences: type: array items: $ref: '#/components/schemas/CatalogItemFoodAndBeverageDetailsDietaryPreference' description: The dietary preferences for the `FOOD_AND_BEV` item. nullable: true ingredients: type: array items: $ref: '#/components/schemas/CatalogItemFoodAndBeverageDetailsIngredient' description: The ingredients for the `FOOD_AND_BEV` type item. nullable: true OrderLineItemDiscountType: type: string enum: - UNKNOWN_DISCOUNT - FIXED_PERCENTAGE - FIXED_AMOUNT - VARIABLE_PERCENTAGE - VARIABLE_AMOUNT x-enum-elements: - name: UNKNOWN_DISCOUNT description: 'Used for reporting only. The original transaction discount type is currently not supported by the API.' - name: FIXED_PERCENTAGE description: Apply the discount as a fixed percentage (such as 5%) off the item price. - name: FIXED_AMOUNT description: Apply the discount as a fixed monetary value (such as $1.00) off the item price. - name: VARIABLE_PERCENTAGE description: 'Apply the discount as a variable percentage based on the item price. The specific discount percentage of a `VARIABLE_PERCENTAGE` discount is assigned at the time of the purchase.' - name: VARIABLE_AMOUNT description: 'Apply the discount as a variable amount based on the item price. The specific discount amount of a `VARIABLE_AMOUNT` discount is assigned at the time of the purchase.' description: Indicates how the discount is applied to the associated line item or order. x-release-status: PUBLIC CheckoutLocationSettingsBrandingHeaderType: type: string enum: - BUSINESS_NAME - FRAMED_LOGO - FULL_WIDTH_LOGO x-enum-elements: - name: BUSINESS_NAME description: '' - name: FRAMED_LOGO description: '' - name: FULL_WIDTH_LOGO description: '' x-release-status: BETA MeasurementUnitTime: type: string enum: - GENERIC_MILLISECOND - GENERIC_SECOND - GENERIC_MINUTE - GENERIC_HOUR - GENERIC_DAY x-enum-elements: - name: GENERIC_MILLISECOND description: The time is measured in milliseconds. - name: GENERIC_SECOND description: The time is measured in seconds. - name: GENERIC_MINUTE description: The time is measured in minutes. - name: GENERIC_HOUR description: The time is measured in hours. - name: GENERIC_DAY description: The time is measured in days. description: Unit of time used to measure a quantity (a duration). x-release-status: PUBLIC CheckoutMerchantSettings: type: object x-release-status: BETA properties: payment_methods: $ref: '#/components/schemas/CheckoutMerchantSettingsPaymentMethods' description: The set of payment methods accepted for the merchant's account. nullable: true updated_at: type: string description: 'The timestamp when the settings were last updated, in RFC 3339 format. Examples for January 25th, 2020 6:25:34pm Pacific Standard Time: UTC: 2020-01-26T02:25:34Z Pacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00' readOnly: true AcceptedPaymentMethods: type: object x-release-status: PUBLIC properties: apple_pay: type: boolean description: Whether Apple Pay is accepted at checkout. nullable: true google_pay: type: boolean description: Whether Google Pay is accepted at checkout. nullable: true cash_app_pay: type: boolean description: Whether Cash App Pay is accepted at checkout. nullable: true afterpay_clearpay: type: boolean description: Whether Afterpay/Clearpay is accepted at checkout. nullable: true MeasurementUnitVolume: type: string enum: - GENERIC_FLUID_OUNCE - GENERIC_SHOT - GENERIC_CUP - GENERIC_PINT - GENERIC_QUART - GENERIC_GALLON - IMPERIAL_CUBIC_INCH - IMPERIAL_CUBIC_FOOT - IMPERIAL_CUBIC_YARD - METRIC_MILLILITER - METRIC_LITER x-enum-elements: - name: GENERIC_FLUID_OUNCE description: The volume is measured in ounces. - name: GENERIC_SHOT description: The volume is measured in shots. - name: GENERIC_CUP description: The volume is measured in cups. - name: GENERIC_PINT description: The volume is measured in pints. - name: GENERIC_QUART description: The volume is measured in quarts. - name: GENERIC_GALLON description: The volume is measured in gallons. - name: IMPERIAL_CUBIC_INCH description: The volume is measured in cubic inches. - name: IMPERIAL_CUBIC_FOOT description: The volume is measured in cubic feet. - name: IMPERIAL_CUBIC_YARD description: The volume is measured in cubic yards. - name: METRIC_MILLILITER description: The volume is measured in metric milliliters. - name: METRIC_LITER description: The volume is measured in metric liters. description: The unit of volume used to measure a quantity. x-release-status: PUBLIC 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 to 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 2016-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 created prior to 2016-03-30 and is not compatible with v2 Square API calls.' error-category: INVALID_REQUEST_ERROR - name: CARD_PROCESSING_NOT_ENABLED description: 'The location provided in the API call is not enabled 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 body parameter.' error-category: INVALID_REQUEST_ERROR - name: INCORRECT_TYPE description: 'The value provided in the request is the wrong type. For example, a string instead of an integer.' error-category: INVALID_REQUEST_ERROR - name: INVALID_TIME description: 'Formatting for the provided time value is incorrect.' error-category: INVALID_REQUEST_ERROR - name: INVALID_TIME_RANGE description: 'The time range provided in the request is invalid. For 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, including `%` in a phone number.' error-category: INVALID_REQUEST_ERROR - name: INVALID_CURSOR description: 'The pagination cursor included in the request is invalid.' error-category: INVALID_REQUEST_ERROR - name: UNKNOWN_QUERY_PARAMETER description: 'The query parameters provided is invalid for the requested endpoint.' error-category: INVALID_REQUEST_ERROR - name: CONFLICTING_PARAMETERS description: 'One or more of the request parameters conflict with each 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. Currently, 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 regular expression.' error-category: INVALID_REQUEST_ERROR - name: VALUE_TOO_SHORT description: 'The provided string value is shorter than the minimum length allowed.' error-category: INVALID_REQUEST_ERROR - name: VALUE_TOO_LONG description: 'The provided string value is longer than the maximum length allowed.' error-category: INVALID_REQUEST_ERROR - name: VALUE_TOO_LOW description: 'The provided value is less than the supported minimum.' error-category: INVALID_REQUEST_ERROR - name: VALUE_TOO_HIGH description: 'The provided value is greater than the supported maximum.' error-category: INVALID_REQUEST_ERROR - name: VALUE_EMPTY description: 'The provided value has a default (empty) value such 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 boolean.' error-category: INVALID_REQUEST_ERROR - name: EXPECTED_INTEGER description: 'The endpoint expected the provided value to be an integer.' error-category: INVALID_REQUEST_ERROR - name: EXPECTED_FLOAT description: 'The endpoint expected the provided value to be a float.' error-category: INVALID_REQUEST_ERROR - name: EXPECTED_STRING description: 'The endpoint expected the provided value to be a string.' error-category: INVALID_REQUEST_ERROR - name: EXPECTED_OBJECT description: 'The endpoint expected the provided value to be a JSON object.' error-category: INVALID_REQUEST_ERROR - name: EXPECTED_ARRAY description: 'The endpoint expected the provided value to be an array or list.' error-category: INVALID_REQUEST_ERROR - name: EXPECTED_MAP description: 'The endpoint expected the provided value to be a map or associative array.' error-category: INVALID_REQUEST_ERROR - name: EXPECTED_BASE64_ENCODED_BYTE_ARRAY description: 'The endpoint expected the provided value to be an array encoded in base64.' error-category: INVALID_REQUEST_ERROR - name: INVALID_ARRAY_VALUE description: 'One or more objects in the array does not match the array type.' error-category: INVALID_REQUEST_ERROR - name: INVALID_ENUM_VALUE description: 'The provided static string is not valid for the field.' 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 2016-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) transaction with a request for the card''s PIN. This code will be returned alongside `CARD_DECLINED_VERIFICATION_REQUIRED` as a supplemental error, and will include an issuer-provided token in the `details` field that is needed to initiate the PIN collection 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, it 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, it 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, it 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. The 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. If the payment information seems correct, the buyer can contact their issuer 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 funding source. For example, a gift card funded in USD cannot be used to process payments 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 this payment. For example, Square may limit which merchants are allowed 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. For 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. A 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. The API returns the error code mostly for credit cards (for example, the card reached the credit limit). However, sometimes the issuer bank can indicate the error for debit or 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 incorrect 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 card is expired.' error-category: PAYMENT_METHOD_ERROR - name: CARD_NOT_SUPPORTED description: 'The card is not supported either in the geographic region or by the [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 by adding the `accept_partial_authorization` parameter in the request. However, taking such a partial payment does not work if your request also includes `tip_money`, `app_fee_money`, or both. Square declines such payments and returns the `GIFT_CARD_AVAILABLE_AMOUNT` error. For more information, see [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. This could happen if the reward tier created in a first party application 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 for 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 for additional verification.' error-category: PAYMENT_METHOD_ERROR - name: BAD_EXPIRATION description: 'The card expiration date is either missing or incorrectly formatted.' error-category: PAYMENT_METHOD_ERROR - name: CHIP_INSERTION_REQUIRED description: 'The card issuer requires that the card be read using a chip reader.' error-category: PAYMENT_METHOD_ERROR - name: ALLOWABLE_PIN_TRIES_EXCEEDED description: 'The card has exhausted its available pin entry retries set by the card issuer. Resolving the error typically requires the card 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 condition 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 using 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 Square API.' x-release-status: PUBLIC CatalogV1Id: type: object description: A Square API V1 identifier of an item, including the object ID and its associated location ID. x-release-status: PUBLIC properties: catalog_v1_id: type: string description: The ID for an object used in the Square API V1, if the object ID differs from the Square API V2 object ID. nullable: true location_id: type: string description: The ID of the `Location` this Connect V1 ID is associated with. nullable: true CatalogDiscountModifyTaxBasis: type: string enum: - MODIFY_TAX_BASIS - DO_NOT_MODIFY_TAX_BASIS x-enum-elements: - name: MODIFY_TAX_BASIS description: Application of the discount will modify the tax basis. - name: DO_NOT_MODIFY_TAX_BASIS description: Application of the discount will not modify the tax basis. x-release-status: PUBLIC CatalogTimePeriod: type: object description: Represents a time period - either a single period or a repeating period. x-release-status: PUBLIC properties: event: type: string description: 'An iCalendar (RFC 5545) [event](https://tools.ietf.org/html/rfc5545#section-3.6.1), which specifies the name, timing, duration and recurrence of this time period. Example: ``` DTSTART:20190707T180000 DURATION:P2H RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR ``` Only `SUMMARY`, `DTSTART`, `DURATION` and `RRULE` fields are supported. `DTSTART` must be in local (unzoned) time format. Note that while `BEGIN:VEVENT` and `END:VEVENT` is not required in the request. The response will always include them.' nullable: true TenderCashDetails: type: object description: Represents the details of a tender with `type` `CASH`. x-release-status: PUBLIC properties: buyer_tendered_money: $ref: '#/components/schemas/Money' description: The total amount of cash provided by the buyer, before change is given. nullable: true change_back_money: $ref: '#/components/schemas/Money' description: The amount of change returned to the buyer. nullable: true TenderBuyNowPayLaterDetails: type: object description: Represents the details of a tender with `type` `BUY_NOW_PAY_LATER`. x-release-status: PUBLIC properties: buy_now_pay_later_brand: $ref: '#/components/schemas/TenderBuyNowPayLaterDetailsBrand' description: 'The Buy Now Pay Later brand. See [Brand](#type-brand) for possible values' readOnly: true status: $ref: '#/components/schemas/TenderBuyNowPayLaterDetailsStatus' description: 'The buy now pay later payment''s current state (such as `AUTHORIZED` or `CAPTURED`). See [TenderBuyNowPayLaterDetailsStatus](entity:TenderBuyNowPayLaterDetailsStatus) for possible values. See [Status](#type-status) for possible values' nullable: true CatalogCustomAttributeDefinitionSellerVisibility: type: string enum: - SELLER_VISIBILITY_HIDDEN - SELLER_VISIBILITY_READ_WRITE_VALUES x-enum-elements: - name: SELLER_VISIBILITY_HIDDEN description: 'Sellers cannot read this custom attribute in Square client applications or Square APIs.' - name: SELLER_VISIBILITY_READ_WRITE_VALUES description: 'Sellers can read and write this custom attribute value in catalog objects, but cannot edit the custom attribute definition.' description: 'Defines the visibility of a custom attribute to sellers in Square client applications, Square APIs or in Square UIs (including Square Point of Sale applications and Square Dashboard).' x-release-status: PUBLIC CheckoutLocationSettingsBranding: type: object x-release-status: BETA properties: header_type: $ref: '#/components/schemas/CheckoutLocationSettingsBrandingHeaderType' description: 'Show the location logo on the checkout page. See [HeaderType](#type-headertype) for possible values' nullable: true button_color: type: string description: The HTML-supported hex color for the button on the checkout page (for example, "#FFFFFF"). minLength: 7 maxLength: 7 nullable: true button_shape: $ref: '#/components/schemas/CheckoutLocationSettingsBrandingButtonShape' description: 'The shape of the button on the checkout page. See [ButtonShape](#type-buttonshape) for possible values' nullable: true UpdateLocationSettingsRequest: type: object x-release-status: BETA required: - location_settings properties: location_settings: $ref: '#/components/schemas/CheckoutLocationSettings' description: Describe your updates using the `location_settings` object. Make sure it contains only the fields that have changed. OrderLineItemAppliedServiceCharge: type: object x-release-status: BETA required: - service_charge_uid properties: uid: type: string description: A unique ID that identifies the applied service charge only within this order. maxLength: 60 nullable: true service_charge_uid: type: string description: 'The `uid` of the service charge that the applied service charge represents. It must reference a service charge present in the `order.service_charges` field. This field is immutable. To change which service charges apply to a line item, delete and add a new `OrderLineItemAppliedServiceCharge`.' minLength: 1 maxLength: 60 applied_money: $ref: '#/components/schemas/Money' description: The amount of money applied by the service charge to the line item. readOnly: true CatalogItemOption: type: object description: A group of variations for a `CatalogItem`. x-release-status: PUBLIC properties: name: type: string description: 'The item option''s display name for the seller. Must be unique across all item options. This is a searchable attribute for use in applicable query filters.' nullable: true display_name: type: string description: The item option's display name for the customer. This is a searchable attribute for use in applicable query filters. nullable: true description: type: string description: 'The item option''s human-readable description. Displayed in the Square Point of Sale app for the seller and in the Online Store or on receipts for the buyer. This is a searchable attribute for use in applicable query filters.' nullable: true show_colors: type: boolean description: If true, display colors for entries in `values` when present. nullable: true values: type: array items: $ref: '#/components/schemas/CatalogObject' description: 'A list of CatalogObjects containing the `CatalogItemOptionValue`s for this item.' nullable: true CheckoutMerchantSettingsPaymentMethodsPaymentMethod: type: object description: The settings allowed for a payment method. x-release-status: BETA properties: enabled: type: boolean description: Indicates whether the payment method is enabled for the account. nullable: true CatalogCustomAttributeDefinitionSelectionConfigCustomAttributeSelection: type: object description: A named selection for this `SELECTION`-type custom attribute definition. x-release-status: PUBLIC required: - name properties: uid: type: string description: Unique ID set by Square. nullable: true name: type: string description: Selection name, unique within `allowed_selections`. minLength: 1 maxLength: 255 CategoryPathToRootNode: type: object description: A node in the path from a retrieved category to its root node. x-release-status: PUBLIC properties: category_id: type: string description: The category's ID. nullable: true category_name: type: string description: The category's name. nullable: true CardCoBrand: type: string enum: - UNKNOWN - AFTERPAY - CLEARPAY x-enum-elements: - name: UNKNOWN description: '' - name: AFTERPAY description: '' - name: CLEARPAY description: '' description: Indicates the brand for a co-branded card. x-release-status: PUBLIC MeasurementUnitGeneric: type: string enum: - UNIT x-enum-elements: - name: UNIT description: The generic unit. x-release-status: PUBLIC FulfillmentType: type: string enum: - PICKUP - SHIPMENT - DELIVERY x-enum-elements: - name: PICKUP description: A recipient to pick up the fulfillment from a physical [location](entity:Location). - name: SHIPMENT description: A shipping carrier to ship the fulfillment. - name: DELIVERY description: A courier to deliver the fulfillment. description: The type of fulfillment. x-release-status: PUBLIC CatalogPricingType: type: string enum: - FIXED_PRICING - VARIABLE_PRICING x-enum-elements: - name: FIXED_PRICING description: The catalog item variation's price is fixed. - name: VARIABLE_PRICING description: The catalog item variation's price is entered at the time of sale. description: Indicates whether the price of a CatalogItemVariation should be entered manually at the time of sale. x-release-status: PUBLIC CheckoutLocationSettingsCoupons: type: object x-release-status: BETA properties: enabled: type: boolean description: Indicates whether coupons are enabled for this location. nullable: true OrderLineItemTaxType: type: string enum: - UNKNOWN_TAX - ADDITIVE - INCLUSIVE x-enum-elements: - name: UNKNOWN_TAX description: 'Used for reporting only. The original transaction tax type is currently not supported by the API.' - name: ADDITIVE description: 'The tax is an additive tax. The tax amount is added on top of the price. For example, an item with a cost of 1.00 USD and a 10% additive tax has a total cost to the buyer of 1.10 USD.' - name: INCLUSIVE description: 'The tax is an inclusive tax. Inclusive taxes are already included in the line item price or order total. For example, an item with a cost of 1.00 USD and a 10% inclusive tax has a pretax cost of 0.91 USD (91 cents) and a 0.09 (9 cents) tax for a total cost of 1.00 USD to the buyer.' description: Indicates how the tax is applied to the associated line item or order. x-release-status: PUBLIC CheckoutLocationSettings: type: object x-release-status: BETA properties: location_id: type: string description: The ID of the location that these settings apply to. nullable: true customer_notes_enabled: type: boolean description: Indicates whether customers are allowed to leave notes at checkout. nullable: true policies: type: array items: $ref: '#/components/schemas/CheckoutLocationSettingsPolicy' description: 'Policy information is displayed at the bottom of the checkout pages. You can set a maximum of two policies.' nullable: true branding: $ref: '#/components/schemas/CheckoutLocationSettingsBranding' description: The branding settings for this location. nullable: true tipping: $ref: '#/components/schemas/CheckoutLocationSettingsTipping' description: The tip settings for this location. nullable: true coupons: $ref: '#/components/schemas/CheckoutLocationSettingsCoupons' description: The coupon settings for this location. nullable: true updated_at: type: string description: 'The timestamp when the settings were last updated, in RFC 3339 format. Examples for January 25th, 2020 6:25:34pm Pacific Standard Time: UTC: 2020-01-26T02:25:34Z Pacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00' readOnly: true CatalogCustomAttributeDefinitionType: type: string enum: - STRING - BOOLEAN - NUMBER - SELECTION x-enum-elements: - name: STRING description: A free-form string containing up to 255 characters. - name: BOOLEAN description: A `true` or `false` value. - name: NUMBER description: A decimal string representation of a number. Can support up to 5 digits after the decimal point. - name: SELECTION description: One or more choices from `allowed_selections`. description: Defines the possible types for a custom attribute. x-release-status: PUBLIC Card: type: object description: 'Represents the payment details of a card to be used for payments. These details are determined by the payment token generated by Web Payments SDK.' x-release-status: PUBLIC properties: id: type: string description: Unique ID for this card. Generated by Square. maxLength: 64 readOnly: true card_brand: $ref: '#/components/schemas/CardBrand' description: 'The card''s brand. See [CardBrand](#type-cardbrand) for possible values' readOnly: true last_4: type: string description: The last 4 digits of the card number. maxLength: 4 readOnly: true exp_month: type: integer description: The expiration month of the associated card as an integer between 1 and 12. format: int64 nullable: true exp_year: type: integer description: The four-digit year of the card's expiration date. format: int64 nullable: true cardholder_name: type: string description: The name of the cardholder. maxLength: 96 nullable: true billing_address: $ref: '#/components/schemas/Address' description: The billing address for this card. nullable: true fingerprint: type: string description: 'Intended as a Square-assigned identifier, based on the card number, to identify the card across multiple locations within a single application.' maxLength: 255 readOnly: true customer_id: type: string description: '**Required** The ID of a customer created using the Customers API to be associated with the card.' nullable: true merchant_id: type: string description: The ID of the merchant associated with the card. readOnly: true reference_id: type: string description: 'An optional user-defined reference ID that associates this card with another entity in an external system. For example, a customer ID from an external customer management system.' maxLength: 128 nullable: true enabled: type: boolean description: Indicates whether or not a card can be used for payments. readOnly: true card_type: $ref: '#/components/schemas/CardType' description: 'The type of the card. The Card object includes this field only in response to Payments API calls. See [CardType](#type-cardtype) for possible values' readOnly: true prepaid_type: $ref: '#/components/schemas/CardPrepaidType' description: 'Indicates whether the Card is prepaid or not. The Card object includes this field only in response to Payments API calls. See [CardPrepaidType](#type-cardprepaidtype) for possible values' readOnly: true bin: type: string description: 'The first six digits of the card number, known as the Bank Identification Number (BIN). Only the Payments API returns this field.' maxLength: 6 readOnly: true version: type: integer description: 'Current version number of the card. Increments with each card update. Requests to update an existing Card object will be rejected unless the version in the request matches the current version for the Card.' format: int64 card_co_brand: $ref: '#/components/schemas/CardCoBrand' description: 'The card''s co-brand if available. For example, an Afterpay virtual card would have a co-brand of AFTERPAY. See [CardCoBrand](#type-cardcobrand) for possible values' readOnly: true TenderBuyNowPayLaterDetailsStatus: type: string enum: - AUTHORIZED - CAPTURED - VOIDED - FAILED x-enum-elements: - name: AUTHORIZED description: The buy now pay later payment has been authorized but not yet captured. - name: CAPTURED description: The buy now pay later payment was authorized and subsequently captured (i.e., completed). - name: VOIDED description: The buy now pay later payment was authorized and subsequently voided (i.e., canceled). - name: FAILED description: The buy now pay later payment failed. x-release-status: PUBLIC AdditionalRecipient: type: object description: Represents an additional recipient (other than the merchant) receiving a portion of this tender. x-release-status: DEPRECATED required: - location_id - amount_money properties: location_id: type: string description: The location ID for a recipient (other than the merchant) receiving a portion of this tender. minLength: 1 maxLength: 50 description: type: string description: The description of the additional recipient. maxLength: 100 nullable: true amount_money: $ref: '#/components/schemas/Money' description: The amount of money distributed to the recipient. receivable_id: type: string description: The unique ID for the RETIRED `AdditionalRecipientReceivable` object. This field should be empty for any `AdditionalRecipient` objects created after the retirement. maxLength: 192 nullable: true OrderLineItemTax: type: object description: 'Represents a tax that applies to one or more line item in the order. Fixed-amount, order-scoped taxes are distributed across all non-zero line item totals. The amount distributed to each line item is relative to the amount the item contributes to the order subtotal.' x-release-status: PUBLIC properties: uid: type: string description: A unique ID that identifies the tax only within this order. maxLength: 60 x-release-status: BETA nullable: true catalog_object_id: type: string description: The catalog object ID referencing [CatalogTax](entity:CatalogTax). maxLength: 192 nullable: true catalog_version: type: integer description: The version of the catalog object that this tax references. format: int64 nullable: true name: type: string description: The tax's name. maxLength: 255 nullable: true type: $ref: '#/components/schemas/OrderLineItemTaxType' description: 'Indicates the calculation method used to apply the tax. See [OrderLineItemTaxType](#type-orderlineitemtaxtype) for possible values' nullable: true percentage: type: string description: 'The percentage of the tax, as a string representation of a decimal number. For example, a value of `"7.25"` corresponds to a percentage of 7.25%.' maxLength: 10 nullable: true metadata: type: object additionalProperties: type: string description: 'Application-defined data attached to this tax. Metadata fields are intended to store descriptive references or associations with an entity in another system or store brief information about the object. Square does not process this field; it only stores and returns it in relevant API calls. Do not use metadata to store any sensitive information (such as personally identifiable information or card details). Keys written by applications must be 60 characters or less and must be in the character set `[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed with a namespace, separated from the key with a '':'' character. Values have a maximum length of 255 characters. An application can have up to 10 entries per metadata field. Entries written by applications are private and can only be read or modified by the same application. For more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).' x-release-status: BETA nullable: true applied_money: $ref: '#/components/schemas/Money' description: 'The amount of money applied to the order by the tax. - For percentage-based taxes, `applied_money` is the money calculated using the percentage.' nullable: true scope: $ref: '#/components/schemas/OrderLineItemTaxScope' description: 'Indicates the level at which the tax applies. For `ORDER` scoped taxes, Square generates references in `applied_taxes` on all order line items that do not have them. For `LINE_ITEM` scoped taxes, the tax only applies to line items with references in their `applied_taxes` field. This field is immutable. To change the scope, you must delete the tax and re-add it as a new tax. See [OrderLineItemTaxScope](#type-orderlineitemtaxscope) for possible values' nullable: true auto_applied: type: boolean description: 'Determines whether the tax was automatically applied to the order based on the catalog configuration. For an example, see [Automatically Apply Taxes to an Order](https://developer.squareup.com/docs/orders-api/apply-taxes-and-discounts/auto-apply-taxes).' readOnly: true x-release-status: BETA UpdatePaymentLinkRequest: type: object x-release-status: PUBLIC required: - payment_link properties: payment_link: $ref: '#/components/schemas/PaymentLink' description: 'The `payment_link` object describing the updates to apply. For more information, see [Update a payment link](https://developer.squareup.com/docs/checkout-api/manage-checkout#update-a-payment-link).' example: payment_link: checkout_options: ask_for_shipping_address: true version: 1 RetrievePaymentLinkResponse: type: object x-release-status: PUBLIC properties: errors: type: array items: $ref: '#/components/schemas/Error' description: Any errors that occurred during the request. payment_link: $ref: '#/components/schemas/PaymentLink' description: The payment link that is retrieved. example: payment_link: created_at: '2022-04-26T00:10:29Z' id: LLO5Q3FRCFICDB4B long_url: https://checkout.square.site/EXAMPLE order_id: 4uKASDATqSd1QQ9jV86sPhMdVEbSJc4F url: https://square.link/u/EXAMPLE version: 1 CatalogObjectType: type: string enum: - ITEM - IMAGE - CATEGORY - ITEM_VARIATION - TAX - DISCOUNT - MODIFIER_LIST - MODIFIER - PRICING_RULE - PRODUCT_SET - TIME_PERIOD - MEASUREMENT_UNIT - SUBSCRIPTION_PLAN_VARIATION - ITEM_OPTION - ITEM_OPTION_VAL - CUSTOM_ATTRIBUTE_DEFINITION - QUICK_AMOUNTS_SETTINGS - SUBSCRIPTION_PLAN - AVAILABILITY_PERIOD x-enum-elements: - name: ITEM description: 'The `CatalogObject` instance is of the [CatalogItem](entity:CatalogItem) type and represents an item. The item-specific data must be set on the `item_data` field.' - name: IMAGE description: 'The `CatalogObject` instance is of the [CatalogImage](entity:CatalogImage) type and represents an image. The image-specific data must be set on the `image_data` field.' - name: CATEGORY description: 'The `CatalogObject` instance is of the [CatalogCategory](entity:CatalogCategory) type and represents a category. The category-specific data must be set on the `category_data` field.' - name: ITEM_VARIATION description: 'The `CatalogObject` instance is of the [CatalogItemVariation](entity:CatalogItemVariation) type and represents an item variation, also referred to as variation. The item variation-specific data must be set on the `item_variation_data` field.' - name: TAX description: 'The `CatalogObject` instance is of the [CatalogTax](entity:CatalogTax) type and represents a tax. The tax-specific data must be set on the `tax_data` field.' - name: DISCOUNT description: 'The `CatalogObject` instance is of the [CatalogDiscount](entity:CatalogDiscount) type and represents a discount. The discount-specific data must be set on the `discount_data` field.' - name: MODIFIER_LIST description: 'The `CatalogObject` instance is of the [CatalogModifierList](entity:CatalogModifierList) type and represents a modifier list. The modifier-list-specific data must be set on the `modifier_list_data` field.' - name: MODIFIER description: 'The `CatalogObject` instance is of the [CatalogModifier](entity:CatalogModifier) type and represents a modifier. The modifier-specific data must be set on the `modifier_data` field.' - name: PRICING_RULE description: 'The `CatalogObject` instance is of the [CatalogPricingRule](entity:CatalogPricingRule) type and represents a pricing rule. The pricing-rule-specific data must be set on the `pricing_rule_data` field.' - name: PRODUCT_SET description: 'The `CatalogObject` instance is of the [CatalogProductSet](entity:CatalogProductSet) type and represents a product set. The product-set-specific data will be stored in the `product_set_data` field.' - name: TIME_PERIOD description: 'The `CatalogObject` instance is of the [CatalogTimePeriod](entity:CatalogTimePeriod) type and represents a time period. The time-period-specific data must be set on the `time_period_data` field.' - name: MEASUREMENT_UNIT description: 'The `CatalogObject` instance is of the [CatalogMeasurementUnit](entity:CatalogMeasurementUnit) type and represents a measurement unit specifying the unit of measure and precision in which an item variation is sold. The measurement-unit-specific data must set on the `measurement_unit_data` field.' - name: SUBSCRIPTION_PLAN_VARIATION description: 'The `CatalogObject` instance is of the [CatalogSubscriptionPlan](entity:CatalogSubscriptionPlan) type and represents a subscription plan. The subscription-plan-specific data must be stored on the `subscription_plan_data` field.' - name: ITEM_OPTION description: 'The `CatalogObject` instance is of the [CatalogItemOption](entity:CatalogItemOption) type and represents a list of options (such as a color or size of a T-shirt) that can be assigned to item variations. The item-option-specific data must be on the `item_option_data` field.' - name: ITEM_OPTION_VAL description: 'The `CatalogObject` instance is of the [CatalogItemOptionValue](entity:CatalogItemOptionValue) type and represents a value associated with one or more item options. For example, an item option of "Size" may have item option values such as "Small" or "Medium". The item-option-value-specific data must be on the `item_option_value_data` field.' - name: CUSTOM_ATTRIBUTE_DEFINITION description: 'The `CatalogObject` instance is of the [CatalogCustomAttributeDefinition](entity:CatalogCustomAttributeDefinition) type and represents the definition of a custom attribute. The custom-attribute-definition-specific data must be set on the `custom_attribute_definition_data` field.' - name: QUICK_AMOUNTS_SETTINGS description: 'The `CatalogObject` instance is of the [CatalogQuickAmountsSettings](entity:CatalogQuickAmountsSettings) type and represents settings to configure preset charges for quick payments at each location. For example, a location may have a list of both AUTO and MANUAL quick amounts that are set to DISABLED. The quick-amounts-settings-specific data must be set on the `quick_amounts_settings_data` field.' - name: SUBSCRIPTION_PLAN description: 'The `CatalogObject` instance is of the [CatalogSubscriptionPlan](entity:CatalogSubscriptionPlan) type and represents a subscription plan. The subscription plan specific data must be stored on the `subscription_plan_data` field.' - name: AVAILABILITY_PERIOD description: 'The `CatalogObject` instance is of the [CatalogAvailabilityPeriod](entity:CatalogAvailabilityPeriod) type and represents an availability period. The availability period specific data must be stored on the `availability_period_data` field.' description: 'Possible types of CatalogObjects returned from the catalog, each containing type-specific properties in the `*_data` field corresponding to the specified object type.' x-release-status: PUBLIC TenderCardDetailsEntryMethod: type: string enum: - SWIPED - KEYED - EMV - ON_FILE - CONTACTLESS x-enum-elements: - name: SWIPED description: The card was swiped through a Square reader or Square stand. - name: KEYED description: 'The card information was keyed manually into Square Point of Sale or a Square-hosted web form.' - name: EMV description: The card was processed via EMV with a Square reader. - name: ON_FILE description: The buyer's card details were already on file with Square. - name: CONTACTLESS description: 'The card was processed via a contactless (i.e., NFC) transaction with a Square reader.' description: Indicates the method used to enter the card's details. x-release-status: PUBLIC OrderReturnLineItemModifier: type: object description: A line item modifier being returned. x-release-status: BETA properties: uid: type: string description: A unique ID that identifies the return modifier only within this order. maxLength: 60 nullable: true source_modifier_uid: type: string description: 'The modifier `uid` from the order''s line item that contains the original sale of this line item modifier.' maxLength: 60 nullable: true catalog_object_id: type: string description: The catalog object ID referencing [CatalogModifier](entity:CatalogModifier). maxLength: 192 nullable: true catalog_version: type: integer description: The version of the catalog object that this line item modifier references. format: int64 nullable: true name: type: string description: The name of the item modifier. maxLength: 255 nullable: true base_price_money: $ref: '#/components/schemas/Money' description: 'The base price for the modifier. `base_price_money` is required for ad hoc modifiers. If both `catalog_object_id` and `base_price_money` are set, `base_price_money` overrides the predefined [CatalogModifier](entity:CatalogModifier) price.' nullable: true total_price_money: $ref: '#/components/schemas/Money' description: 'The total price of the item modifier for its line item. This is the modifier''s `base_price_money` multiplied by the line item''s quantity.' readOnly: true quantity: type: string description: 'The quantity of the line item modifier. The modifier quantity can be 0 or more. For example, suppose a restaurant offers a cheeseburger on the menu. When a buyer orders this item, the restaurant records the purchase by creating an `Order` object with a line item for a burger. The line item includes a line item modifier: the name is cheese and the quantity is 1. The buyer has the option to order extra cheese (or no cheese). If the buyer chooses the extra cheese option, the modifier quantity increases to 2. If the buyer does not want any cheese, the modifier quantity is set to 0.' nullable: true CatalogSubscriptionPlan: type: object description: 'Describes a subscription plan. A subscription plan represents what you want to sell in a subscription model, and includes references to each of the associated subscription plan variations. For more information, see [Subscription Plans and Variations](https://developer.squareup.com/docs/subscriptions-api/plans-and-variations).' x-release-status: PUBLIC required: - name properties: name: type: string description: The name of the plan. phases: type: array items: $ref: '#/components/schemas/SubscriptionPhase' description: 'A list of SubscriptionPhase containing the [SubscriptionPhase](entity:SubscriptionPhase) for this plan. This field it required. Not including this field will throw a REQUIRED_FIELD_MISSING error' nullable: true subscription_plan_variations: type: array items: $ref: '#/components/schemas/CatalogObject' description: The list of subscription plan variations available for this product nullable: true eligible_item_ids: type: array items: type: string description: The list of IDs of `CatalogItems` that are eligible for subscription by this SubscriptionPlan's variations. nullable: true eligible_category_ids: type: array items: type: string description: The list of IDs of `CatalogCategory` that are eligible for subscription by this SubscriptionPlan's variations. nullable: true all_items: type: boolean description: If true, all items in the merchant's catalog are subscribable by this SubscriptionPlan. nullable: true DayOfWeek: type: string enum: - SUN - MON - TUE - WED - THU - FRI - SAT x-enum-elements: - name: SUN description: Sunday - name: MON description: Monday - name: TUE description: Tuesday - name: WED description: Wednesday - name: THU description: Thursday - name: FRI description: Friday - name: SAT description: Saturday description: Indicates the specific day of the week. x-release-status: PUBLIC CatalogItemModifierListInfo: type: object description: 'References a text-based modifier or a list of non text-based modifiers applied to a `CatalogItem` instance and specifies supported behaviors of the application.' x-release-status: PUBLIC required: - modifier_list_id properties: modifier_list_id: type: string description: The ID of the `CatalogModifierList` controlled by this `CatalogModifierListInfo`. minLength: 1 modifier_overrides: type: array items: $ref: '#/components/schemas/CatalogModifierOverride' description: A set of `CatalogModifierOverride` objects that override whether a given `CatalogModifier` is enabled by default. nullable: true min_selected_modifiers: type: integer description: "If 0 or larger, the smallest number of `CatalogModifier`s that must be selected from this `CatalogModifierList`.\nThe default value is `-1`.\n\nWhen `CatalogModifierList.selection_type` is `MULTIPLE`, `CatalogModifierListInfo.min_selected_modifiers=-1` \nand `CatalogModifierListInfo.max_selected_modifier=-1` means that from zero to the maximum number of modifiers of\nthe `CatalogModifierList` can be selected from the `CatalogModifierList`. \n\nWhen the `CatalogModifierList.selection_type` is `SINGLE`, `CatalogModifierListInfo.min_selected_modifiers=-1`\nand `CatalogModifierListInfo.max_selected_modifier=-1` means that exactly one modifier must be present in \nand can be selected from the `CatalogModifierList`" nullable: true max_selected_modifiers: type: integer description: "If 0 or larger, the largest number of `CatalogModifier`s that can be selected from this `CatalogModifierList`.\nThe default value is `-1`.\n\nWhen `CatalogModifierList.selection_type` is `MULTIPLE`, `CatalogModifierListInfo.min_selected_modifiers=-1` \nand `CatalogModifierListInfo.max_selected_modifier=-1` means that from zero to the maximum number of modifiers of\nthe `CatalogModifierList` can be selected from the `CatalogModifierList`. \n\nWhen the `CatalogModifierList.selection_type` is `SINGLE`, `CatalogModifierListInfo.min_selected_modifiers=-1`\nand `CatalogModifierListInfo.max_selected_modifier=-1` means that exactly one modifier must be present in \nand can be selected from the `CatalogModifierList`" nullable: true enabled: type: boolean description: If `true`, enable this `CatalogModifierList`. The default value is `true`. nullable: true ordinal: type: integer description: "The position of this `CatalogItemModifierListInfo` object within the `modifier_list_info` list applied \nto a `CatalogItem` instance." x-release-status: BETA nullable: true FulfillmentRecipient: type: object description: Information about the fulfillment recipient. x-release-status: PUBLIC properties: customer_id: type: string description: 'The ID of the customer associated with the fulfillment. If `customer_id` is provided, the fulfillment recipient''s `display_name`, `email_address`, and `phone_number` are automatically populated from the targeted customer profile. If these fields are set in the request, the request values override the information from the customer profile. If the targeted customer profile does not contain the necessary information and these fields are left unset, the request results in an error.' maxLength: 191 nullable: true display_name: type: string description: 'The display name of the fulfillment recipient. This field is required. If provided, the display name overrides the corresponding customer profile value indicated by `customer_id`.' maxLength: 255 nullable: true email_address: type: string description: 'The email address of the fulfillment recipient. If provided, the email address overrides the corresponding customer profile value indicated by `customer_id`.' maxLength: 255 nullable: true phone_number: type: string description: 'The phone number of the fulfillment recipient. This field is required. If provided, the phone number overrides the corresponding customer profile value indicated by `customer_id`.' maxLength: 17 nullable: true address: $ref: '#/components/schemas/Address' description: 'The address of the fulfillment recipient. This field is required. If provided, the address overrides the corresponding customer profile value indicated by `customer_id`.' x-release-status: BETA nullable: true OrderReturnTax: type: object description: 'Represents a tax being returned that applies to one or more return line items in an order. Fixed-amount, order-scoped taxes are distributed across all non-zero return line item totals. The amount distributed to each return line item is relative to that item’s contribution to the order subtotal.' x-release-status: BETA properties: uid: type: string description: A unique ID that identifies the returned tax only within this order. maxLength: 60 nullable: true source_tax_uid: type: string description: The tax `uid` from the order that contains the original tax charge. maxLength: 60 nullable: true catalog_object_id: type: string description: The catalog object ID referencing [CatalogTax](entity:CatalogTax). maxLength: 192 nullable: true catalog_version: type: integer description: The version of the catalog object that this tax references. format: int64 nullable: true name: type: string description: The tax's name. maxLength: 255 nullable: true type: $ref: '#/components/schemas/OrderLineItemTaxType' description: 'Indicates the calculation method used to apply the tax. See [OrderLineItemTaxType](#type-orderlineitemtaxtype) for possible values' nullable: true percentage: type: string description: 'The percentage of the tax, as a string representation of a decimal number. For example, a value of `"7.25"` corresponds to a percentage of 7.25%.' maxLength: 10 nullable: true applied_money: $ref: '#/components/schemas/Money' description: The amount of money applied by the tax in an order. readOnly: true scope: $ref: '#/components/schemas/OrderLineItemTaxScope' description: 'Indicates the level at which the `OrderReturnTax` applies. For `ORDER` scoped taxes, Square generates references in `applied_taxes` on all `OrderReturnLineItem`s. For `LINE_ITEM` scoped taxes, the tax is only applied to `OrderReturnLineItem`s with references in their `applied_discounts` field. See [OrderLineItemTaxScope](#type-orderlineitemtaxscope) for possible values' nullable: true CatalogModifier: type: object description: A modifier applicable to items at the time of sale. An example of a modifier is a Cheese add-on to a Burger item. x-release-status: PUBLIC properties: name: type: string description: The modifier name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points. maxLength: 255 nullable: true price_money: $ref: '#/components/schemas/Money' description: The modifier price. nullable: true ordinal: type: integer description: Determines where this `CatalogModifier` appears in the `CatalogModifierList`. nullable: true modifier_list_id: type: string description: The ID of the `CatalogModifierList` associated with this modifier. nullable: true location_overrides: type: array items: $ref: '#/components/schemas/ModifierLocationOverrides' description: Location-specific price overrides. nullable: true image_id: type: string description: 'The ID of the image associated with this `CatalogModifier` instance. Currently this image is not displayed by Square, but is free to be displayed in 3rd party applications.' x-release-status: BETA nullable: true example: object: modifier_data: name: Almond Milk price_money: amount: 250 currency: USD present_at_all_locations: true type: MODIFIER UpdatePaymentLinkResponse: type: object x-release-status: PUBLIC properties: errors: type: array items: $ref: '#/components/schemas/Error' description: Any errors that occurred when updating the payment link. payment_link: $ref: '#/components/schemas/PaymentLink' description: The updated payment link. example: payment_link: checkout_options: ask_for_shipping_address: true created_at: '2022-04-26T00:15:15Z' id: TY4BWEDJ6AI5MBIV long_url: https://checkout.square.site/EXAMPLE order_id: Qqc8ypQGvxVwc46Cch4zHTaJqc4F payment_note: test updated_at: '2022-04-26T00:18:24Z' url: https://square.link/u/EXAMPLE version: 2 CreateCheckoutResponse: type: object description: 'Defines the fields that are included in the response body of a request to the `CreateCheckout` endpoint.' x-release-status: PUBLIC properties: checkout: $ref: '#/components/schemas/Checkout' description: The newly created `checkout` object associated with the provided idempotency key. errors: type: array items: $ref: '#/components/schemas/Error' description: Any errors that occurred during the request. example: checkout: additional_recipients: - amount_money: amount: 60 currency: USD description: Application fees location_id: 057P5VYJ4A5X1 ask_for_shipping_address: true checkout_page_url: https://connect.squareup.com/v2/checkout?c=CAISEHGimXh-C3RIT4og1a6u1qw&l=CYTKRM7R7JMV8 created_at: '2017-06-16T22:25:35Z' id: CAISEHGimXh-C3RIT4og1a6u1qw merchant_support_email: merchant+support@website.com order: customer_id: customer_id discounts: - amount_money: amount: 100 currency: USD applied_money: amount: 100 currency: USD scope: LINE_ITEM type: FIXED_AMOUNT uid: 56ae1696-z1e3-9328-af6d-f1e04d947gd4 line_items: - applied_discounts: - applied_money: amount: 100 currency: USD discount_uid: 56ae1696-z1e3-9328-af6d-f1e04d947gd4 applied_taxes: - applied_money: amount: 103 currency: USD tax_uid: 38ze1696-z1e3-5628-af6d-f1e04d947fg3 base_price_money: amount: 1500 currency: USD name: Printed T Shirt quantity: '2' total_discount_money: amount: 100 currency: USD total_money: amount: 1503 currency: USD total_tax_money: amount: 103 currency: USD - base_price_money: amount: 2500 currency: USD name: Slim Jeans quantity: '1' total_money: amount: 2500 currency: USD - base_price_money: amount: 3500 currency: USD name: Woven Sweater quantity: '3' total_money: amount: 10500 currency: USD location_id: location_id reference_id: reference_id taxes: - percentage: '7.75' scope: LINE_ITEM type: INCLUSIVE uid: 38ze1696-z1e3-5628-af6d-f1e04d947fg3 total_discount_money: amount: 100 currency: USD total_money: amount: 14503 currency: USD total_tax_money: amount: 103 currency: USD pre_populate_buyer_email: example@email.com pre_populate_shipping_address: address_line_1: 1455 Market St. address_line_2: Suite 600 administrative_district_level_1: CA country: US first_name: Jane last_name: Doe locality: San Francisco postal_code: '94103' redirect_url: https://merchant.website.com/order-confirm version: 1 MeasurementUnitWeight: type: string enum: - IMPERIAL_WEIGHT_OUNCE - IMPERIAL_POUND - IMPERIAL_STONE - METRIC_MILLIGRAM - METRIC_GRAM - METRIC_KILOGRAM x-enum-elements: - name: IMPERIAL_WEIGHT_OUNCE description: The weight is measured in ounces. - name: IMPERIAL_POUND description: The weight is measured in pounds. - name: IMPERIAL_STONE description: The weight is measured in stones. - name: METRIC_MILLIGRAM description: The weight is measured in milligrams. - name: METRIC_GRAM description: The weight is measured in grams. - name: METRIC_KILOGRAM description: The weight is measured in kilograms. description: Unit of weight used to measure a quantity. x-release-status: PUBLIC CatalogItemVariation: type: object description: 'An item variation, representing a product for sale, in the Catalog object model. Each [item](entity:CatalogItem) must have at least one item variation and can have at most 250 item variations. An item variation can be sellable, stockable, or both if it has a unit of measure for its count for the sold number of the variation, the stocked number of the variation, or both. For example, when a variation representing wine is stocked and sold by the bottle, the variation is both stockable and sellable. But when a variation of the wine is sold by the glass, the sold units cannot be used as a measure of the stocked units. This by-the-glass variation is sellable, but not stockable. To accurately keep track of the wine''s inventory count at any time, the sellable count must be converted to stockable count. Typically, the seller defines this unit conversion. For example, 1 bottle equals 5 glasses. The Square API exposes the `stockable_conversion` property on the variation to specify the conversion. Thus, when two glasses of the wine are sold, the sellable count decreases by 2, and the stockable count automatically decreases by 0.4 bottle according to the conversion.' x-release-status: PUBLIC properties: item_id: type: string description: The ID of the `CatalogItem` associated with this item variation. nullable: true name: type: string description: 'The item variation''s name. This is a searchable attribute for use in applicable query filters. Its value has a maximum length of 255 Unicode code points. However, when the parent [item](entity:CatalogItem) uses [item options](entity:CatalogItemOption), this attribute is auto-generated, read-only, and can be longer than 255 Unicode code points.' nullable: true sku: type: string description: The item variation's SKU, if any. This is a searchable attribute for use in applicable query filters. nullable: true upc: type: string description: 'The universal product code (UPC) of the item variation, if any. This is a searchable attribute for use in applicable query filters. The value of this attribute should be a number of 12-14 digits long. This restriction is enforced on the Square Seller Dashboard, Square Point of Sale or Retail Point of Sale apps, where this attribute shows in the GTIN field. If a non-compliant UPC value is assigned to this attribute using the API, the value is not editable on the Seller Dashboard, Square Point of Sale or Retail Point of Sale apps unless it is updated to fit the expected format.' nullable: true ordinal: type: integer description: 'The order in which this item variation should be displayed. This value is read-only. On writes, the ordinal for each item variation within a parent `CatalogItem` is set according to the item variations''s position. On reads, the value is not guaranteed to be sequential or unique.' readOnly: true pricing_type: $ref: '#/components/schemas/CatalogPricingType' description: 'Indicates whether the item variation''s price is fixed or determined at the time of sale. See [CatalogPricingType](#type-catalogpricingtype) for possible values' nullable: true price_money: $ref: '#/components/schemas/Money' description: The item variation's price, if fixed pricing is used. nullable: true location_overrides: type: array items: $ref: '#/components/schemas/ItemVariationLocationOverrides' description: Per-location price and inventory overrides. nullable: true track_inventory: type: boolean description: If `true`, inventory tracking is active for the variation. nullable: true inventory_alert_type: $ref: '#/components/schemas/InventoryAlertType' description: 'Indicates whether the item variation displays an alert when its inventory quantity is less than or equal to its `inventory_alert_threshold`. See [InventoryAlertType](#type-inventoryalerttype) for possible values' nullable: true inventory_alert_threshold: type: integer description: 'If the inventory quantity for the variation is less than or equal to this value and `inventory_alert_type` is `LOW_QUANTITY`, the variation displays an alert in the merchant dashboard. This value is always an integer.' format: int64 nullable: true user_data: type: string description: Arbitrary user metadata to associate with the item variation. This attribute value length is of Unicode code points. maxLength: 255 nullable: true service_duration: type: integer description: 'If the `CatalogItem` that owns this item variation is of type `APPOINTMENTS_SERVICE`, then this is the duration of the service in milliseconds. For example, a 30 minute appointment would have the value `1800000`, which is equal to 30 (minutes) * 60 (seconds per minute) * 1000 (milliseconds per second).' format: int64 nullable: true available_for_booking: type: boolean description: 'If the `CatalogItem` that owns this item variation is of type `APPOINTMENTS_SERVICE`, a bool representing whether this service is available for booking.' x-release-status: BETA nullable: true item_option_values: type: array items: $ref: '#/components/schemas/CatalogItemOptionValueForItemVariation' description: 'List of item option values associated with this item variation. Listed in the same order as the item options of the parent item.' nullable: true measurement_unit_id: type: string description: 'ID of the ‘CatalogMeasurementUnit’ that is used to measure the quantity sold of this item variation. If left unset, the item will be sold in whole quantities.' nullable: true sellable: type: boolean description: 'Whether this variation can be sold. The inventory count of a sellable variation indicates the number of units available for sale. When a variation is both stockable and sellable, its sellable inventory count can be smaller than or equal to its stockable count.' x-release-status: BETA nullable: true stockable: type: boolean description: 'Whether stock is counted directly on this variation (TRUE) or only on its components (FALSE). When a variation is both stockable and sellable, the inventory count of a stockable variation keeps track of the number of units of this variation in stock and is not an indicator of the number of units of the variation that can be sold.' x-release-status: BETA nullable: true image_ids: type: array items: type: string description: 'The IDs of images associated with this `CatalogItemVariation` instance. These images will be shown to customers in Square Online Store.' nullable: true team_member_ids: type: array items: type: string description: 'Tokens of employees that can perform the service represented by this variation. Only valid for variations of type `APPOINTMENTS_SERVICE`.' x-release-status: BETA nullable: true stockable_conversion: $ref: '#/components/schemas/CatalogStockConversion' description: 'The unit conversion rule, as prescribed by the [CatalogStockConversion](entity:CatalogStockConversion) type, that describes how this non-stockable (i.e., sellable/receivable) item variation is converted to/from the stockable item variation sharing the same parent item. With the stock conversion, you can accurately track inventory when an item variation is sold in one unit, but stocked in another unit.' x-release-status: BETA nullable: true CatalogCustomAttributeDefinitionNumberConfig: type: object x-release-status: PUBLIC properties: precision: type: integer description: 'An integer between 0 and 5 that represents the maximum number of positions allowed after the decimal in number custom attribute values For example: - if the precision is 0, the quantity can be 1, 2, 3, etc. - if the precision is 1, the quantity can be 0.1, 0.2, etc. - if the precision is 2, the quantity can be 0.01, 0.12, etc. Default: 5' maximum: 5 nullable: true CatalogQuickAmountType: type: string enum: - QUICK_AMOUNT_TYPE_MANUAL - QUICK_AMOUNT_TYPE_AUTO x-enum-elements: - name: QUICK_AMOUNT_TYPE_MANUAL description: Quick Amount is created manually by the seller. - name: QUICK_AMOUNT_TYPE_AUTO description: Quick Amount is generated automatically by machine learning algorithms. description: Determines the type of a specific Quick Amount. x-release-status: BETA TenderCardDetailsStatus: type: string enum: - AUTHORIZED - CAPTURED - VOIDED - FAILED x-enum-elements: - name: AUTHORIZED description: The card transaction has been authorized but not yet captured. - name: CAPTURED description: The card transaction was authorized and subsequently captured (i.e., completed). - name: VOIDED description: The card transaction was authorized and subsequently voided (i.e., canceled). - name: FAILED description: The card transaction failed. description: Indicates the card transaction's current status. x-release-status: PUBLIC QuickPay: type: object description: 'Describes an ad hoc item and price to generate a quick pay checkout link. For more information, see [Quick Pay Checkout](https://developer.squareup.com/docs/checkout-api/quick-pay-checkout).' x-release-status: PUBLIC required: - name - price_money - location_id properties: name: type: string description: The ad hoc item name. In the resulting `Order`, this name appears as the line item name. minLength: 1 maxLength: 255 price_money: $ref: '#/components/schemas/Money' description: The price of the item. location_id: type: string description: The ID of the business location the checkout is associated with. TenderCardDetails: type: object description: Represents additional details of a tender with `type` `CARD` or `SQUARE_GIFT_CARD` x-release-status: PUBLIC properties: status: $ref: '#/components/schemas/TenderCardDetailsStatus' description: 'The credit card payment''s current state (such as `AUTHORIZED` or `CAPTURED`). See [TenderCardDetailsStatus](entity:TenderCardDetailsStatus) for possible values. See [TenderCardDetailsStatus](#type-tendercarddetailsstatus) for possible values' nullable: true card: $ref: '#/components/schemas/Card' description: The credit card's non-confidential details. nullable: true entry_method: $ref: '#/components/schemas/TenderCardDetailsEntryMethod' description: 'The method used to enter the card''s details for the transaction. See [TenderCardDetailsEntryMethod](#type-tendercarddetailsentrymethod) for possible values' nullable: true 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 description: 'The first line of the address. Fields that start with `address_line` provide the address''s most specific details, like street number, street name, and building name. They do *not* provide less specific details like city, state/province, or country (these details are provided in other fields).' nullable: true address_line_2: type: string description: The second line of the address, if any. nullable: true address_line_3: type: string description: The third line of the address, if any. nullable: true locality: type: string 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). nullable: true sublocality: type: string description: A civil region within the address's `locality`, if any. nullable: true sublocality_2: type: string description: A civil region within the address's `sublocality`, if any. nullable: true sublocality_3: type: string description: A civil region within the address's `sublocality_2`, if any. nullable: true administrative_district_level_1: type: string description: 'A civil entity within the address''s country. In the US, this is 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).' nullable: true administrative_district_level_2: type: string description: 'A civil entity within the address''s `administrative_district_level_1`. In the US, this is the county.' nullable: true administrative_district_level_3: type: string description: 'A civil entity within the address''s `administrative_district_level_2`, if any.' nullable: true postal_code: type: string 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). nullable: true country: $ref: '#/components/schemas/Country' description: 'The address''s country, in the two-letter format of ISO 3166. For example, `US` or `FR`. See [Country](#type-country) for possible values' nullable: true first_name: type: string description: Optional first name when it's representing recipient. nullable: true last_name: type: string description: Optional last name when it's representing recipient. nullable: true CheckoutOptions: type: object x-release-status: PUBLIC properties: allow_tipping: type: boolean description: Indicates whether the payment allows tipping. nullable: true custom_fields: type: array items: $ref: '#/components/schemas/CustomField' description: The custom fields requesting information from the buyer. nullable: true subscription_plan_id: type: string description: 'The ID of the subscription plan for the buyer to pay and subscribe. For more information, see [Subscription Plan Checkout](https://developer.squareup.com/docs/checkout-api/subscription-plan-checkout).' maxLength: 255 nullable: true redirect_url: type: string description: The confirmation page URL to redirect the buyer to after Square processes the payment. maxLength: 2048 nullable: true merchant_support_email: type: string description: The email address that buyers can use to contact the seller. maxLength: 256 nullable: true ask_for_shipping_address: type: boolean description: Indicates whether to include the address fields in the payment form. nullable: true accepted_payment_methods: $ref: '#/components/schemas/AcceptedPaymentMethods' description: The methods allowed for buyers during checkout. nullable: true app_fee_money: $ref: '#/components/schemas/Money' description: 'The amount of money that the developer is taking as a fee for facilitating the payment on behalf of the seller. The amount cannot be more than 90% of the total amount of the payment. The amount must be specified in the smallest denomination of the applicable currency (for example, US dollar amounts are specified in cents). For more information, see [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/common-data-types/working-with-monetary-amounts). The fee currency code must match the currency associated with the seller that is accepting the payment. The application must be from a developer account in the same country and using the same currency code as the seller. For more information about the application fee scenario, see [Take Payments and Collect Fees](https://developer.squareup.com/docs/payments-api/take-payments-and-collect-fees). To set this field, `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` OAuth permission is required. For more information, see [Permissions](https://developer.squareup.com/docs/payments-api/collect-fees/additional-considerations#permissions).' nullable: true shipping_fee: $ref: '#/components/schemas/ShippingFee' description: The fee associated with shipping to be applied to the `Order` as a service charge. nullable: true enable_coupon: type: boolean description: Indicates whether to include the `Add coupon` section for the buyer to provide a Square marketing coupon in the payment form. nullable: true enable_loyalty: type: boolean description: Indicates whether to include the `REWARDS` section for the buyer to opt in to loyalty, redeem rewards in the payment form, or both. nullable: true CatalogAvailabilityPeriod: type: object description: Represents a time period of availability. x-release-status: BETA properties: start_local_time: type: string description: 'The start time of an availability period, specified in local time using partial-time RFC 3339 format. For example, `8:30:00` for a period starting at 8:30 in the morning. Note that the seconds value is always :00, but it is appended for conformance to the RFC.' nullable: true end_local_time: type: string description: 'The end time of an availability period, specified in local time using partial-time RFC 3339 format. For example, `21:00:00` for a period ending at 9:00 in the evening. Note that the seconds value is always :00, but it is appended for conformance to the RFC.' nullable: true day_of_week: $ref: '#/components/schemas/DayOfWeek' description: 'The day of the week for this availability period. See [DayOfWeek](#type-dayofweek) for possible values' nullable: true CatalogItemOptionValue: type: object description: 'An enumerated value that can link a `CatalogItemVariation` to an item option as one of its item option values.' x-release-status: PUBLIC properties: item_option_id: type: string description: Unique ID of the associated item option. nullable: true name: type: string description: Name of this item option value. This is a searchable attribute for use in applicable query filters. nullable: true description: type: string description: A human-readable description for the option value. This is a searchable attribute for use in applicable query filters. nullable: true color: type: string description: 'The HTML-supported hex color for the item option (e.g., "#ff8d4e85"). Only displayed if `show_colors` is enabled on the parent `ItemOption`. When left unset, `color` defaults to white ("#ffffff") when `show_colors` is enabled on the parent `ItemOption`.' nullable: true ordinal: type: integer description: Determines where this option value appears in a list of option values. nullable: true CatalogItemProductType: type: string enum: - REGULAR - GIFT_CARD - APPOINTMENTS_SERVICE - FOOD_AND_BEV - EVENT - DIGITAL - DONATION - LEGACY_SQUARE_ONLINE_SERVICE - LEGACY_SQUARE_ONLINE_MEMBERSHIP x-enum-elements: - name: REGULAR description: An ordinary item. - name: GIFT_CARD description: A Square gift card. - name: APPOINTMENTS_SERVICE description: A service that can be booked using the Square Appointments app. - name: FOOD_AND_BEV description: A food or beverage item that can be sold by restaurants and other food venues. - name: EVENT description: An event which tickets can be sold for, including location, address, and times. - name: DIGITAL description: A digital item like an ebook or song. - name: DONATION description: A donation which site visitors can send for any cause. - name: LEGACY_SQUARE_ONLINE_SERVICE description: A legacy Square Online service that is manually fulfilled. This corresponds to the `Other` item type displayed in the Square Seller Dashboard and Square POS apps. - name: LEGACY_SQUARE_ONLINE_MEMBERSHIP description: A legacy Square Online membership that is manually fulfilled. This corresponds to the `Membership` item type displayed in the Square Seller Dashboard and Square POS apps. description: The type of a CatalogItem. Connect V2 only allows the creation of `REGULAR` or `APPOINTMENTS_SERVICE` items. x-release-status: PUBLIC Tender: type: object description: Represents a tender (i.e., a method of payment) used in a Square transaction. x-release-status: PUBLIC required: - type properties: id: type: string description: The tender's unique ID. It is the associated payment ID. maxLength: 192 location_id: type: string description: The ID of the transaction's associated location. maxLength: 50 nullable: true transaction_id: type: string description: The ID of the tender's associated transaction. maxLength: 192 nullable: true created_at: type: string description: The timestamp for when the tender was created, in RFC 3339 format. maxLength: 32 readOnly: true note: type: string description: An optional note associated with the tender at the time of payment. maxLength: 500 nullable: true amount_money: $ref: '#/components/schemas/Money' description: 'The total amount of the tender, including `tip_money`. If the tender has a `payment_id`, the `total_money` of the corresponding [Payment](entity:Payment) will be equal to the `amount_money` of the tender.' nullable: true tip_money: $ref: '#/components/schemas/Money' description: The tip's amount of the tender. nullable: true processing_fee_money: $ref: '#/components/schemas/Money' description: 'The amount of any Square processing fees applied to the tender. This field is not immediately populated when a new transaction is created. It is usually available after about ten seconds.' nullable: true customer_id: type: string description: 'If the tender is associated with a customer or represents a customer''s card on file, this is the ID of the associated customer.' maxLength: 191 nullable: true type: $ref: '#/components/schemas/TenderType' description: 'The type of tender, such as `CARD` or `CASH`. See [TenderType](#type-tendertype) for possible values' card_details: $ref: '#/components/schemas/TenderCardDetails' description: 'The details of the card tender. This value is present only if the value of `type` is `CARD`.' nullable: true cash_details: $ref: '#/components/schemas/TenderCashDetails' description: 'The details of the cash tender. This value is present only if the value of `type` is `CASH`.' nullable: true bank_account_details: $ref: '#/components/schemas/TenderBankAccountDetails' description: 'The details of the bank account tender. This value is present only if the value of `type` is `BANK_ACCOUNT`.' nullable: true buy_now_pay_later_details: $ref: '#/components/schemas/TenderBuyNowPayLaterDetails' description: 'The details of a Buy Now Pay Later tender. This value is present only if the value of `type` is `BUY_NOW_PAY_LATER`.' nullable: true square_account_details: $ref: '#/components/schemas/TenderSquareAccountDetails' description: 'The details of a Square Account tender. This value is present only if the value of `type` is `SQUARE_ACCOUNT`.' nullable: true additional_recipients: type: array items: $ref: '#/components/schemas/AdditionalRecipient' description: 'Additional recipients (other than the merchant) receiving a portion of this tender. For example, fees assessed on the purchase by a third party integration.' x-release-status: DEPRECATED nullable: true payment_id: type: string description: 'The ID of the [Payment](entity:Payment) that corresponds to this tender. This value is only present for payments created with the v2 Payments API.' maxLength: 192 nullable: true Checkout: type: object description: 'Square Checkout lets merchants accept online payments for supported payment types using a checkout workflow hosted on squareup.com.' x-release-status: PUBLIC properties: id: type: string description: ID generated by Square Checkout when a new checkout is requested. checkout_page_url: type: string description: 'The URL that the buyer''s browser should be redirected to after the checkout is completed.' nullable: true ask_for_shipping_address: type: boolean description: 'If `true`, Square Checkout will collect shipping information on your behalf and store that information with the transaction information in your Square Dashboard. Default: `false`.' nullable: true merchant_support_email: type: string description: 'The email address to display on the Square Checkout confirmation page and confirmation email that the buyer can use to contact the merchant. If this value is not set, the confirmation page and email will display the primary email address associated with the merchant''s Square account. Default: none; only exists if explicitly set.' nullable: true pre_populate_buyer_email: type: string description: 'If provided, the buyer''s email is pre-populated on the checkout page as an editable text field. Default: none; only exists if explicitly set.' nullable: true pre_populate_shipping_address: $ref: '#/components/schemas/Address' description: 'If provided, the buyer''s shipping info is pre-populated on the checkout page as editable text fields. Default: none; only exists if explicitly set.' nullable: true redirect_url: type: string description: 'The URL to redirect to after checkout is completed with `checkoutId`, Square''s `orderId`, `transactionId`, and `referenceId` appended as URL parameters. For example, if the provided redirect_url is `http://www.example.com/order-complete`, a successful transaction redirects the customer to: 
http://www.example.com/order-complete?checkoutId=xxxxxx&orderId=xxxxxx&referenceId=xxxxxx&transactionId=xxxxxx
If you do not provide a redirect URL, Square Checkout will display an order confirmation page on your behalf; however Square strongly recommends that you provide a redirect URL so you can verify the transaction results and finalize the order through your existing/normal confirmation workflow.' nullable: true order: $ref: '#/components/schemas/Order' description: Order to be checked out. nullable: true created_at: type: string description: The time when the checkout was created, in RFC 3339 format. readOnly: true additional_recipients: type: array items: $ref: '#/components/schemas/AdditionalRecipient' description: 'Additional recipients (other than the merchant) receiving a portion of this checkout. For example, fees assessed on the purchase by a third party integration.' x-release-status: DEPRECATED nullable: true MeasurementUnitLength: type: string enum: - IMPERIAL_INCH - IMPERIAL_FOOT - IMPERIAL_YARD - IMPERIAL_MILE - METRIC_MILLIMETER - METRIC_CENTIMETER - METRIC_METER - METRIC_KILOMETER x-enum-elements: - name: IMPERIAL_INCH description: The length is measured in inches. - name: IMPERIAL_FOOT description: The length is measured in feet. - name: IMPERIAL_YARD description: The length is measured in yards. - name: IMPERIAL_MILE description: The length is measured in miles. - name: METRIC_MILLIMETER description: The length is measured in millimeters. - name: METRIC_CENTIMETER description: The length is measured in centimeters. - name: METRIC_METER description: The length is measured in meters. - name: METRIC_KILOMETER description: The length is measured in kilometers. description: The unit of length used to measure a quantity. x-release-status: PUBLIC TenderBankAccountDetails: type: object description: 'Represents the details of a tender with `type` `BANK_ACCOUNT`. See [BankAccountPaymentDetails](entity:BankAccountPaymentDetails) for more exposed details of a bank account payment.' x-release-status: PUBLIC properties: status: $ref: '#/components/schemas/TenderBankAccountDetailsStatus' description: 'The bank account payment''s current state. See [TenderBankAccountPaymentDetailsStatus](entity:TenderBankAccountDetailsStatus) for possible values. See [TenderBankAccountDetailsStatus](#type-tenderbankaccountdetailsstatus) for possible values' nullable: true CatalogCategoryType: type: string enum: - REGULAR_CATEGORY - MENU_CATEGORY - KITCHEN_CATEGORY x-enum-elements: - name: REGULAR_CATEGORY description: The regular category. - name: MENU_CATEGORY description: The menu category. - name: KITCHEN_CATEGORY description: Kitchen categories are used by KDS (Kitchen Display System) to route items to specific clients description: Indicates the type of a category. x-release-status: PUBLIC OrderServiceCharge: type: object description: Represents a service charge applied to an order. x-release-status: PUBLIC properties: uid: type: string description: A unique ID that identifies the service charge only within this order. maxLength: 60 x-release-status: BETA nullable: true name: type: string description: The name of the service charge. maxLength: 512 nullable: true catalog_object_id: type: string description: The catalog object ID referencing the service charge [CatalogObject](entity:CatalogObject). maxLength: 192 nullable: true catalog_version: type: integer description: The version of the catalog object that this service charge references. format: int64 nullable: true percentage: type: string description: 'The service charge percentage as a string representation of a decimal number. For example, `"7.25"` indicates a service charge of 7.25%. Exactly 1 of `percentage` or `amount_money` should be set.' maxLength: 10 nullable: true amount_money: $ref: '#/components/schemas/Money' description: 'The amount of a non-percentage-based service charge. Exactly one of `percentage` or `amount_money` should be set.' nullable: true applied_money: $ref: '#/components/schemas/Money' description: 'The amount of money applied to the order by the service charge, including any inclusive tax amounts, as calculated by Square. - For fixed-amount service charges, `applied_money` is equal to `amount_money`. - For percentage-based service charges, `applied_money` is the money calculated using the percentage.' readOnly: true total_money: $ref: '#/components/schemas/Money' description: 'The total amount of money to collect for the service charge. __Note__: If an inclusive tax is applied to the service charge, `total_money` does not equal `applied_money` plus `total_tax_money` because the inclusive tax amount is already included in both `applied_money` and `total_tax_money`.' readOnly: true total_tax_money: $ref: '#/components/schemas/Money' description: The total amount of tax money to collect for the service charge. readOnly: true calculation_phase: $ref: '#/components/schemas/OrderServiceChargeCalculationPhase' description: 'The calculation phase at which to apply the service charge. See [OrderServiceChargeCalculationPhase](#type-orderservicechargecalculationphase) for possible values' nullable: true taxable: type: boolean description: 'Indicates whether the service charge can be taxed. If set to `true`, order-level taxes automatically apply to the service charge. Note that service charges calculated in the `TOTAL_PHASE` cannot be marked as taxable.' nullable: true applied_taxes: type: array items: $ref: '#/components/schemas/OrderLineItemAppliedTax' description: 'The list of references to the taxes applied to this service charge. Each `OrderLineItemAppliedTax` has a `tax_uid` that references the `uid` of a top-level `OrderLineItemTax` that is being applied to this service charge. On reads, the amount applied is populated. An `OrderLineItemAppliedTax` is automatically created on every taxable service charge for all `ORDER` scoped taxes that are added to the order. `OrderLineItemAppliedTax` records for `LINE_ITEM` scoped taxes must be added in requests for the tax to apply to any taxable service charge. Taxable service charges have the `taxable` field set to `true` and calculated in the `SUBTOTAL_PHASE`. To change the amount of a tax, modify the referenced top-level tax.' x-release-status: BETA nullable: true metadata: type: object additionalProperties: type: string description: 'Application-defined data attached to this service charge. Metadata fields are intended to store descriptive references or associations with an entity in another system or store brief information about the object. Square does not process this field; it only stores and returns it in relevant API calls. Do not use metadata to store any sensitive information (such as personally identifiable information or card details). Keys written by applications must be 60 characters or less and must be in the character set `[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed with a namespace, separated from the key with a '':'' character. Values have a maximum length of 255 characters. An application can have up to 10 entries per metadata field. Entries written by applications are private and can only be read or modified by the same application. For more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).' x-release-status: BETA nullable: true type: $ref: '#/components/schemas/OrderServiceChargeType' description: 'The type of the service charge. See [OrderServiceChargeType](#type-orderservicechargetype) for possible values' readOnly: true treatment_type: $ref: '#/components/schemas/OrderServiceChargeTreatmentType' description: 'The treatment type of the service charge. See [OrderServiceChargeTreatmentType](#type-orderservicechargetreatmenttype) for possible values' x-release-status: BETA nullable: true scope: $ref: '#/components/schemas/OrderServiceChargeScope' description: 'Indicates the level at which the apportioned service charge applies. For `ORDER` scoped service charges, Square generates references in `applied_service_charges` on all order line items that do not have them. For `LINE_ITEM` scoped service charges, the service charge only applies to line items with a service charge reference in their `applied_service_charges` field. This field is immutable. To change the scope of an apportioned service charge, you must delete the apportioned service charge and re-add it as a new apportioned service charge. See [OrderServiceChargeScope](#type-orderservicechargescope) for possible values' x-release-status: BETA nullable: true CatalogCustomAttributeValue: type: object description: 'An instance of a custom attribute. Custom attributes can be defined and added to `ITEM` and `ITEM_VARIATION` type catalog objects. [Read more about custom attributes](https://developer.squareup.com/docs/catalog-api/add-custom-attributes).' x-release-status: PUBLIC properties: name: type: string description: The name of the custom attribute. nullable: true string_value: type: string description: The string value of the custom attribute. Populated if `type` = `STRING`. nullable: true custom_attribute_definition_id: type: string description: The id of the [CatalogCustomAttributeDefinition](entity:CatalogCustomAttributeDefinition) this value belongs to. readOnly: true type: $ref: '#/components/schemas/CatalogCustomAttributeDefinitionType' description: 'A copy of type from the associated `CatalogCustomAttributeDefinition`. See [CatalogCustomAttributeDefinitionType](#type-catalogcustomattributedefinitiontype) for possible values' readOnly: true number_value: type: string description: 'Populated if `type` = `NUMBER`. Contains a string representation of a decimal number, using a `.` as the decimal separator.' nullable: true boolean_value: type: boolean description: A `true` or `false` value. Populated if `type` = `BOOLEAN`. nullable: true selection_uid_values: type: array items: type: string description: One or more choices from `allowed_selections`. Populated if `type` = `SELECTION`. nullable: true key: type: string description: 'If the associated `CatalogCustomAttributeDefinition` object is defined by another application, this key is prefixed by the defining application ID. For example, if the CatalogCustomAttributeDefinition has a key attribute of "cocoa_brand" and the defining application ID is "abcd1234", this key is "abcd1234:cocoa_brand" when the application making the request is different from the application defining the custom attribute definition. Otherwise, the key is simply "cocoa_brand".' readOnly: true SourceApplication: type: object description: Represents information about the application used to generate a change. x-release-status: PUBLIC properties: product: $ref: '#/components/schemas/Product' description: '__Read only__ The [product](entity:Product) type of the application. See [Product](#type-product) for possible values' nullable: true application_id: type: string description: '__Read only__ The Square-assigned ID of the application. This field is used only if the [product](entity:Product) type is `EXTERNAL_API`.' nullable: true name: type: string description: '__Read only__ The display name of the application (for example, `"Custom Application"` or `"Square POS 4.74 for Android"`).' nullable: true CatalogCustomAttributeDefinitionSelectionConfig: type: object description: Configuration associated with `SELECTION`-type custom attribute definitions. x-release-status: PUBLIC properties: max_allowed_selections: type: integer description: 'The maximum number of selections that can be set. The maximum value for this attribute is 100. The default value is 1. The value can be modified, but changing the value will not affect existing custom attribute values on objects. Clients need to handle custom attributes with more selected values than allowed by this limit.' maximum: 100 nullable: true allowed_selections: type: array items: $ref: '#/components/schemas/CatalogCustomAttributeDefinitionSelectionConfigCustomAttributeSelection' description: 'The set of valid `CatalogCustomAttributeSelections`. Up to a maximum of 100 selections can be defined. Can be modified.' nullable: true SubscriptionCadence: type: string enum: - DAILY - WEEKLY - EVERY_TWO_WEEKS - THIRTY_DAYS - SIXTY_DAYS - NINETY_DAYS - MONTHLY - EVERY_TWO_MONTHS - QUARTERLY - EVERY_FOUR_MONTHS - EVERY_SIX_MONTHS - ANNUAL - EVERY_TWO_YEARS x-enum-elements: - name: DAILY description: Once per day - name: WEEKLY description: Once per week - name: EVERY_TWO_WEEKS description: Every two weeks - name: THIRTY_DAYS description: Once every 30 days - name: SIXTY_DAYS description: Once every 60 days - name: NINETY_DAYS description: Once every 90 days - name: MONTHLY description: Once per month - name: EVERY_TWO_MONTHS description: Once every two months - name: QUARTERLY description: Once every three months - name: EVERY_FOUR_MONTHS description: Once every four months - name: EVERY_SIX_MONTHS description: Once every six months - name: ANNUAL description: Once per year - name: EVERY_TWO_YEARS description: Once every two years description: Determines the billing cadence of a [Subscription](entity:Subscription) x-release-status: PUBLIC UpdateMerchantSettingsRequest: type: object x-release-status: BETA required: - merchant_settings properties: merchant_settings: $ref: '#/components/schemas/CheckoutMerchantSettings' description: Describe your updates using the `merchant_settings` object. Make sure it contains only the fields that have changed. OrderMoneyAmounts: type: object description: A collection of various money amounts. x-release-status: BETA properties: total_money: $ref: '#/components/schemas/Money' description: The total money. nullable: true tax_money: $ref: '#/components/schemas/Money' description: The money associated with taxes. nullable: true discount_money: $ref: '#/components/schemas/Money' description: The money associated with discounts. nullable: true tip_money: $ref: '#/components/schemas/Money' description: The money associated with tips. nullable: true service_charge_money: $ref: '#/components/schemas/Money' description: The money associated with service charges. nullable: true CatalogItemFoodAndBeverageDetailsDietaryPreferenceStandardDietaryPreference: type: string enum: - DAIRY_FREE - GLUTEN_FREE - HALAL - KOSHER - NUT_FREE - VEGAN - VEGETARIAN x-enum-elements: - name: DAIRY_FREE description: '' - name: GLUTEN_FREE description: '' - name: HALAL description: '' - name: KOSHER description: '' - name: NUT_FREE description: '' - name: VEGAN description: '' - name: VEGETARIAN description: '' description: Standard dietary preferences for food and beverage items that are recommended on item creation. x-release-status: PUBLIC CatalogModifierOverride: type: object description: Options to control how to override the default behavior of the specified modifier. x-release-status: PUBLIC required: - modifier_id properties: modifier_id: type: string description: The ID of the `CatalogModifier` whose default behavior is being overridden. minLength: 1 on_by_default: type: boolean description: If `true`, this `CatalogModifier` should be selected by default for this `CatalogItem`. nullable: true ExcludeStrategy: type: string enum: - LEAST_EXPENSIVE - MOST_EXPENSIVE x-enum-elements: - name: LEAST_EXPENSIVE description: 'The least expensive matched products are excluded from the pricing. If the pricing rule is set to exclude one product and multiple products in the match set qualify as least expensive, then one will be excluded at random. Excluding the least expensive product gives the best discount value to the buyer.' - name: MOST_EXPENSIVE description: 'The most expensive matched product is excluded from the pricing rule. If multiple products have the same price and all qualify as least expensive, one will be excluded at random. This guarantees that the most expensive product is purchased at full price.' description: 'Indicates which products matched by a CatalogPricingRule will be excluded if the pricing rule uses an exclude set.' x-release-status: BETA OrderLineItemItemType: type: string enum: - ITEM - CUSTOM_AMOUNT - GIFT_CARD x-enum-elements: - name: ITEM description: Indicates that the line item is an itemized sale. - name: CUSTOM_AMOUNT description: Indicates that the line item is a non-itemized sale. - name: GIFT_CARD description: 'Indicates that the line item is a gift card sale. Gift cards sold through the Orders API are sold in an unactivated state and can be activated through the Gift Cards API using the line item `uid`.' description: Represents the line item type. x-release-status: BETA Product: type: string enum: - SQUARE_POS - EXTERNAL_API - BILLING - APPOINTMENTS - INVOICES - ONLINE_STORE - PAYROLL - DASHBOARD - ITEM_LIBRARY_IMPORT - OTHER x-enum-elements: - name: SQUARE_POS description: Square Point of Sale application. - name: EXTERNAL_API description: Square Connect APIs (for example, Orders API or Checkout API). - name: BILLING description: A Square subscription (various products). - name: APPOINTMENTS description: Square Appointments. - name: INVOICES description: Square Invoices. - name: ONLINE_STORE description: Square Online Store. - name: PAYROLL description: Square Payroll. - name: DASHBOARD description: Square Dashboard. - name: ITEM_LIBRARY_IMPORT description: Item Library Import. - name: OTHER description: A Square product that does not match any other value. description: Indicates the Square product used to generate a change. x-release-status: PUBLIC FulfillmentDeliveryDetails: type: object description: Describes delivery details of an order fulfillment. x-release-status: BETA properties: recipient: $ref: '#/components/schemas/FulfillmentRecipient' description: The contact information for the person to receive the fulfillment. nullable: true schedule_type: $ref: '#/components/schemas/FulfillmentDeliveryDetailsOrderFulfillmentDeliveryDetailsScheduleType' description: 'Indicates the fulfillment delivery schedule type. If `SCHEDULED`, then `deliver_at` is required. If `ASAP`, then `prep_time_duration` is required. The default is `SCHEDULED`. See [OrderFulfillmentDeliveryDetailsScheduleType](#type-orderfulfillmentdeliverydetailsscheduletype) for possible values' nullable: true placed_at: type: string description: 'The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates) indicating when the fulfillment was placed. The timestamp must be in RFC 3339 format (for example, "2016-09-04T23:59:33.123Z"). Must be in RFC 3339 timestamp format, e.g., "2016-09-04T23:59:33.123Z".' readOnly: true deliver_at: type: string description: 'The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates) that represents the start of the delivery period. When the fulfillment `schedule_type` is `ASAP`, the field is automatically set to the current time plus the `prep_time_duration`. Otherwise, the application can set this field while the fulfillment `state` is `PROPOSED`, `RESERVED`, or `PREPARED` (any time before the terminal state such as `COMPLETED`, `CANCELED`, and `FAILED`). The timestamp must be in RFC 3339 format (for example, "2016-09-04T23:59:33.123Z").' nullable: true prep_time_duration: type: string description: 'The duration of time it takes to prepare and deliver this fulfillment. The duration must be in RFC 3339 format (for example, "P1W3D").' nullable: true delivery_window_duration: type: string description: 'The time period after `deliver_at` in which to deliver the order. Applications can set this field when the fulfillment `state` is `PROPOSED`, `RESERVED`, or `PREPARED` (any time before the terminal state such as `COMPLETED`, `CANCELED`, and `FAILED`). The duration must be in RFC 3339 format (for example, "P1W3D").' nullable: true note: type: string description: 'Provides additional instructions about the delivery fulfillment. It is displayed in the Square Point of Sale application and set by the API.' maxLength: 550 nullable: true completed_at: type: string description: 'The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates) indicates when the seller completed the fulfillment. This field is automatically set when fulfillment `state` changes to `COMPLETED`. The timestamp must be in RFC 3339 format (for example, "2016-09-04T23:59:33.123Z").' nullable: true in_progress_at: type: string description: 'The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates) indicates when the seller started processing the fulfillment. This field is automatically set when the fulfillment `state` changes to `RESERVED`. The timestamp must be in RFC 3339 format (for example, "2016-09-04T23:59:33.123Z").' readOnly: true rejected_at: type: string description: 'The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates) indicating when the fulfillment was rejected. This field is automatically set when the fulfillment `state` changes to `FAILED`. The timestamp must be in RFC 3339 format (for example, "2016-09-04T23:59:33.123Z").' readOnly: true ready_at: type: string description: 'The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates) indicating when the seller marked the fulfillment as ready for courier pickup. This field is automatically set when the fulfillment `state` changes to PREPARED. The timestamp must be in RFC 3339 format (for example, "2016-09-04T23:59:33.123Z").' readOnly: true delivered_at: type: string description: 'The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates) indicating when the fulfillment was delivered to the recipient. The timestamp must be in RFC 3339 format (for example, "2016-09-04T23:59:33.123Z").' readOnly: true canceled_at: type: string description: 'The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates) indicating when the fulfillment was canceled. This field is automatically set when the fulfillment `state` changes to `CANCELED`. The timestamp must be in RFC 3339 format (for example, "2016-09-04T23:59:33.123Z").' readOnly: true cancel_reason: type: string description: 'The delivery cancellation reason. Max length: 100 characters.' maxLength: 100 nullable: true courier_pickup_at: type: string description: 'The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates) indicating when an order can be picked up by the courier for delivery. The timestamp must be in RFC 3339 format (for example, "2016-09-04T23:59:33.123Z").' nullable: true courier_pickup_window_duration: type: string description: 'The time period after `courier_pickup_at` in which the courier should pick up the order. The duration must be in RFC 3339 format (for example, "P1W3D").' nullable: true is_no_contact_delivery: type: boolean description: Whether the delivery is preferred to be no contact. nullable: true dropoff_notes: type: string description: A note to provide additional instructions about how to deliver the order. maxLength: 550 nullable: true courier_provider_name: type: string description: The name of the courier provider. maxLength: 255 nullable: true courier_support_phone_number: type: string description: The support phone number of the courier. maxLength: 17 nullable: true square_delivery_id: type: string description: The identifier for the delivery created by Square. maxLength: 50 nullable: true external_delivery_id: type: string description: The identifier for the delivery created by the third-party courier service. maxLength: 50 nullable: true managed_delivery: type: boolean description: 'The flag to indicate the delivery is managed by a third party (ie DoorDash), which means we may not receive all recipient information for PII purposes.' nullable: true CatalogMeasurementUnit: type: object description: 'Represents the unit used to measure a `CatalogItemVariation` and specifies the precision for decimal quantities.' x-release-status: PUBLIC properties: measurement_unit: $ref: '#/components/schemas/MeasurementUnit' description: Indicates the unit used to measure the quantity of a catalog item variation. nullable: true precision: type: integer description: 'An integer between 0 and 5 that represents the maximum number of positions allowed after the decimal in quantities measured with this unit. For example: - if the precision is 0, the quantity can be 1, 2, 3, etc. - if the precision is 1, the quantity can be 0.1, 0.2, etc. - if the precision is 2, the quantity can be 0.01, 0.12, etc. Default: 3' nullable: true CatalogProductSet: type: object description: 'Represents a collection of catalog objects for the purpose of applying a `PricingRule`. Including a catalog object will include all of its subtypes. For example, including a category in a product set will include all of its items and associated item variations in the product set. Including an item in a product set will also include its item variations.' x-release-status: PUBLIC properties: name: type: string description: 'User-defined name for the product set. For example, "Clearance Items" or "Winter Sale Items".' nullable: true product_ids_any: type: array items: type: string description: ' Unique IDs for any `CatalogObject` included in this product set. Any number of these catalog objects can be in an order for a pricing rule to apply. This can be used with `product_ids_all` in a parent `CatalogProductSet` to match groups of products for a bulk discount, such as a discount for an entree and side combo. Only one of `product_ids_all`, `product_ids_any`, or `all_products` can be set. Max: 500 catalog object IDs.' nullable: true product_ids_all: type: array items: type: string description: 'Unique IDs for any `CatalogObject` included in this product set. All objects in this set must be included in an order for a pricing rule to apply. Only one of `product_ids_all`, `product_ids_any`, or `all_products` can be set. Max: 500 catalog object IDs.' nullable: true quantity_exact: type: integer description: 'If set, there must be exactly this many items from `products_any` or `products_all` in the cart for the discount to apply. Cannot be combined with either `quantity_min` or `quantity_max`.' format: int64 nullable: true quantity_min: type: integer description: 'If set, there must be at least this many items from `products_any` or `products_all` in a cart for the discount to apply. See `quantity_exact`. Defaults to 0 if `quantity_exact`, `quantity_min` and `quantity_max` are all unspecified.' format: int64 nullable: true quantity_max: type: integer description: 'If set, the pricing rule will apply to a maximum of this many items from `products_any` or `products_all`.' format: int64 nullable: true all_products: type: boolean description: 'If set to `true`, the product set will include every item in the catalog. Only one of `product_ids_all`, `product_ids_any`, or `all_products` can be set.' nullable: true UpdateLocationSettingsResponse: type: object x-release-status: BETA properties: errors: type: array items: $ref: '#/components/schemas/Error' description: Any errors that occurred when updating the location settings. location_settings: $ref: '#/components/schemas/CheckoutLocationSettings' description: The updated location settings. example: location_settings: branding: button_color: '#00b23b' button_shape: ROUNDED header_type: FRAMED_LOGO customer_notes_enabled: false location_id: LOCATION_ID_1 policies: - description: This is my Return Policy title: Return Policy uid: POLICY_ID_1 - description: Items may be returned within 30 days of purchase. title: Return Policy uid: POLICY_ID_2 tipping: default_percent: 20 default_whole_amount_money: amount: 100 currency: USD percentages: - 15 - 20 - 25 smart_tipping_enabled: true whole_amounts: - amount: 1000 currency: USD - amount: 1500 currency: USD - amount: 2000 currency: USD updated_at: '2022-06-16T22:25:35Z' CheckoutMerchantSettingsPaymentMethods: type: object x-release-status: BETA properties: apple_pay: $ref: '#/components/schemas/CheckoutMerchantSettingsPaymentMethodsPaymentMethod' nullable: true google_pay: $ref: '#/components/schemas/CheckoutMerchantSettingsPaymentMethodsPaymentMethod' nullable: true cash_app: $ref: '#/components/schemas/CheckoutMerchantSettingsPaymentMethodsPaymentMethod' nullable: true afterpay_clearpay: $ref: '#/components/schemas/CheckoutMerchantSettingsPaymentMethodsAfterpayClearpay' nullable: true Refund: type: object description: Represents a refund processed for a Square transaction. x-release-status: PUBLIC required: - id - location_id - tender_id - reason - amount_money - status properties: id: type: string description: The refund's unique ID. maxLength: 255 location_id: type: string description: The ID of the refund's associated location. maxLength: 50 transaction_id: type: string description: The ID of the transaction that the refunded tender is part of. maxLength: 192 nullable: true tender_id: type: string description: The ID of the refunded tender. maxLength: 192 created_at: type: string description: The timestamp for when the refund was created, in RFC 3339 format. maxLength: 32 readOnly: true reason: type: string description: The reason for the refund being issued. maxLength: 192 amount_money: $ref: '#/components/schemas/Money' description: The amount of money refunded to the buyer. status: $ref: '#/components/schemas/RefundStatus' description: 'The current status of the refund (`PENDING`, `APPROVED`, `REJECTED`, or `FAILED`). See [RefundStatus](#type-refundstatus) for possible values' processing_fee_money: $ref: '#/components/schemas/Money' description: The amount of Square processing fee money refunded to the *merchant*. nullable: true additional_recipients: type: array items: $ref: '#/components/schemas/AdditionalRecipient' description: 'Additional recipients (other than the merchant) receiving a portion of this refund. For example, fees assessed on a refund of a purchase by a third party integration.' x-release-status: DEPRECATED nullable: true RetrieveLocationSettingsResponse: type: object x-release-status: BETA properties: errors: type: array items: $ref: '#/components/schemas/Error' description: Any errors that occurred during the request. location_settings: $ref: '#/components/schemas/CheckoutLocationSettings' description: The location settings. example: location_settings: branding: button_color: '#ffffff' button_shape: ROUNDED header_type: FRAMED_LOGO customer_notes_enabled: true location_id: LOCATION_ID_1 policies: - description: This is my Return Policy title: Return Policy uid: POLICY_ID_1 tipping: default_percent: 15 default_whole_amount_money: amount: 100 currency: USD percentages: - 10 - 15 - 20 smart_tipping_enabled: true whole_amounts: - amount: 1000 currency: USD - amount: 1500 currency: USD - amount: 2000 currency: USD updated_at: '2022-06-16T22:25:35Z' MeasurementUnitCustom: type: object description: The information needed to define a custom unit, provided by the seller. x-release-status: PUBLIC required: - name - abbreviation properties: name: type: string description: The name of the custom unit, for example "bushel". abbreviation: type: string description: 'The abbreviation of the custom unit, such as "bsh" (bushel). This appears in the cart for the Point of Sale app, and in reports.' OrderQuantityUnit: type: object description: 'Contains the measurement unit for a quantity and a precision that specifies the number of digits after the decimal point for decimal quantities.' x-release-status: PUBLIC properties: measurement_unit: $ref: '#/components/schemas/MeasurementUnit' description: 'A [MeasurementUnit](entity:MeasurementUnit) that represents the unit of measure for the quantity.' nullable: true precision: type: integer description: 'For non-integer quantities, represents the number of digits after the decimal point that are recorded for this quantity. For example, a precision of 1 allows quantities such as `"1.0"` and `"1.1"`, but not `"1.01"`. Min: 0. Max: 5.' nullable: true catalog_object_id: type: string description: 'The catalog object ID referencing the [CatalogMeasurementUnit](entity:CatalogMeasurementUnit). This field is set when this is a catalog-backed measurement unit.' nullable: true catalog_version: type: integer description: 'The version of the catalog object that this measurement unit references. This field is set when this is a catalog-backed measurement unit.' format: int64 nullable: true CheckoutMerchantSettingsPaymentMethodsAfterpayClearpay: type: object description: The settings allowed for AfterpayClearpay. x-release-status: BETA properties: order_eligibility_range: $ref: '#/components/schemas/CheckoutMerchantSettingsPaymentMethodsAfterpayClearpayEligibilityRange' description: Afterpay is shown as an option for order totals falling within the configured range. nullable: true item_eligibility_range: $ref: '#/components/schemas/CheckoutMerchantSettingsPaymentMethodsAfterpayClearpayEligibilityRange' description: Afterpay is shown as an option for item totals falling within the configured range. nullable: true enabled: type: boolean description: Indicates whether the payment method is enabled for the account. readOnly: true CardBrand: type: string enum: - OTHER_BRAND - VISA - MASTERCARD - AMERICAN_EXPRESS - DISCOVER - DISCOVER_DINERS - JCB - CHINA_UNIONPAY - SQUARE_GIFT_CARD - SQUARE_CAPITAL_CARD - INTERAC - EFTPOS - FELICA - EBT x-enum-elements: - name: OTHER_BRAND description: '' - name: VISA description: '' - name: MASTERCARD description: '' - name: AMERICAN_EXPRESS description: '' - name: DISCOVER description: '' - name: DISCOVER_DINERS description: '' - name: JCB description: '' - name: CHINA_UNIONPAY description: '' - name: SQUARE_GIFT_CARD description: '' - name: SQUARE_CAPITAL_CARD description: '' - name: INTERAC description: '' - name: EFTPOS description: '' - name: FELICA description: '' - name: EBT description: '' description: Indicates a card's brand, such as `VISA` or `MASTERCARD`. x-release-status: PUBLIC CreateCheckoutRequest: type: object description: 'Defines the parameters that can be included in the body of a request to the `CreateCheckout` endpoint.' x-release-status: PUBLIC required: - idempotency_key - order properties: idempotency_key: type: string description: "A unique string that identifies this checkout among others you have created. It can be\nany valid string but must be unique for every order sent to Square Checkout for a given location ID.\n\nThe idempotency key is used to avoid processing the same order more than once. If you are \nunsure whether a particular checkout was created successfully, you can attempt it again with\nthe same idempotency key and all the same other parameters without worrying about creating duplicates.\n\nYou should use a random number/string generator native to the language\nyou are working in to generate strings for your idempotency keys.\n\nFor more information, see [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency)." minLength: 1 maxLength: 192 order: $ref: '#/components/schemas/CreateOrderRequest' description: The order including line items to be checked out. ask_for_shipping_address: type: boolean description: "If `true`, Square Checkout collects shipping information on your behalf and stores \nthat information with the transaction information in the Square Seller Dashboard.\n\nDefault: `false`." merchant_support_email: type: string description: 'The email address to display on the Square Checkout confirmation page and confirmation email that the buyer can use to contact the seller. If this value is not set, the confirmation page and email display the primary email address associated with the seller''s Square account. Default: none; only exists if explicitly set.' maxLength: 254 pre_populate_buyer_email: type: string description: 'If provided, the buyer''s email is prepopulated on the checkout page as an editable text field. Default: none; only exists if explicitly set.' maxLength: 254 pre_populate_shipping_address: $ref: '#/components/schemas/Address' description: 'If provided, the buyer''s shipping information is prepopulated on the checkout page as editable text fields. Default: none; only exists if explicitly set.' redirect_url: type: string description: 'The URL to redirect to after the checkout is completed with `checkoutId`, `transactionId`, and `referenceId` appended as URL parameters. For example, if the provided redirect URL is `http://www.example.com/order-complete`, a successful transaction redirects the customer to: `http://www.example.com/order-complete?checkoutId=xxxxxx&referenceId=xxxxxx&transactionId=xxxxxx` If you do not provide a redirect URL, Square Checkout displays an order confirmation page on your behalf; however, it is strongly recommended that you provide a redirect URL so you can verify the transaction results and finalize the order through your existing/normal confirmation workflow. Default: none; only exists if explicitly set.' maxLength: 800 additional_recipients: type: array items: $ref: '#/components/schemas/ChargeRequestAdditionalRecipient' description: 'The basic primitive of a multi-party transaction. The value is optional. The transaction facilitated by you can be split from here. If you provide this value, the `amount_money` value in your `additional_recipients` field cannot be more than 90% of the `total_money` calculated by Square for your order. The `location_id` must be a valid seller location where the checkout is occurring. This field requires `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` OAuth permission. This field is currently not supported in the Square Sandbox.' note: type: string description: 'An optional note to associate with the `checkout` object. This value cannot exceed 60 characters.' maxLength: 60 example: additional_recipients: - amount_money: amount: 60 currency: USD description: Application fees location_id: 057P5VYJ4A5X1 ask_for_shipping_address: true idempotency_key: 86ae1696-b1e3-4328-af6d-f1e04d947ad6 merchant_support_email: merchant+support@website.com order: idempotency_key: 12ae1696-z1e3-4328-af6d-f1e04d947gd4 order: customer_id: customer_id discounts: - amount_money: amount: 100 currency: USD scope: LINE_ITEM type: FIXED_AMOUNT uid: 56ae1696-z1e3-9328-af6d-f1e04d947gd4 line_items: - applied_discounts: - discount_uid: 56ae1696-z1e3-9328-af6d-f1e04d947gd4 applied_taxes: - tax_uid: 38ze1696-z1e3-5628-af6d-f1e04d947fg3 base_price_money: amount: 1500 currency: USD name: Printed T Shirt quantity: '2' - base_price_money: amount: 2500 currency: USD name: Slim Jeans quantity: '1' - base_price_money: amount: 3500 currency: USD name: Woven Sweater quantity: '3' location_id: location_id reference_id: reference_id taxes: - percentage: '7.75' scope: LINE_ITEM type: INCLUSIVE uid: 38ze1696-z1e3-5628-af6d-f1e04d947fg3 pre_populate_buyer_email: example@email.com pre_populate_shipping_address: address_line_1: 1455 Market St. address_line_2: Suite 600 administrative_district_level_1: CA country: US first_name: Jane last_name: Doe locality: San Francisco postal_code: '94103' redirect_url: https://merchant.website.com/order-confirm x-sq-sdk-sample-code: csharp: /sdk_samples/CreateCheckout/CreateCheckoutRequest.csharp java: /sdk_samples/CreateCheckout/CreateCheckoutRequest.java javascript: /sdk_samples/CreateCheckout/CreateCheckoutRequest.javascript php: /sdk_samples/CreateCheckout/CreateCheckoutRequest.php python: /sdk_samples/CreateCheckout/CreateCheckoutRequest.python ruby: /sdk_samples/CreateCheckout/CreateCheckoutRequest.ruby OrderRoundingAdjustment: type: object description: 'A rounding adjustment of the money being returned. Commonly used to apply cash rounding when the minimum unit of the account is smaller than the lowest physical denomination of the currency.' x-release-status: BETA properties: uid: type: string description: A unique ID that identifies the rounding adjustment only within this order. maxLength: 60 nullable: true name: type: string description: The name of the rounding adjustment from the original sale order. nullable: true amount_money: $ref: '#/components/schemas/Money' description: The actual rounding adjustment amount. nullable: true MeasurementUnitArea: type: string enum: - IMPERIAL_ACRE - IMPERIAL_SQUARE_INCH - IMPERIAL_SQUARE_FOOT - IMPERIAL_SQUARE_YARD - IMPERIAL_SQUARE_MILE - METRIC_SQUARE_CENTIMETER - METRIC_SQUARE_METER - METRIC_SQUARE_KILOMETER x-enum-elements: - name: IMPERIAL_ACRE description: The area is measured in acres. - name: IMPERIAL_SQUARE_INCH description: The area is measured in square inches. - name: IMPERIAL_SQUARE_FOOT description: The area is measured in square feet. - name: IMPERIAL_SQUARE_YARD description: The area is measured in square yards. - name: IMPERIAL_SQUARE_MILE description: The area is measured in square miles. - name: METRIC_SQUARE_CENTIMETER description: The area is measured in square centimeters. - name: METRIC_SQUARE_METER description: The area is measured in square meters. - name: METRIC_SQUARE_KILOMETER description: The area is measured in square kilometers. description: Unit of area used to measure a quantity. x-release-status: PUBLIC TenderSquareAccountDetailsStatus: type: string enum: - AUTHORIZED - CAPTURED - VOIDED - FAILED x-enum-elements: - name: AUTHORIZED description: The Square Account payment has been authorized but not yet captured. - name: CAPTURED description: The Square Account payment was authorized and subsequently captured (i.e., completed). - name: VOIDED description: The Square Account payment was authorized and subsequently voided (i.e., canceled). - name: FAILED description: The Square Account payment failed. x-release-status: PUBLIC OrderReturnTip: type: object description: A tip being returned. x-release-status: BETA properties: uid: type: string description: A unique ID that identifies the tip only within this order. maxLength: 60 nullable: true applied_money: $ref: '#/components/schemas/Money' description: 'The amount of tip being returned --' readOnly: true source_tender_uid: type: string description: The tender `uid` from the order that contains the original application of this tip. maxLength: 192 nullable: true source_tender_id: type: string description: The tender `id` from the order that contains the original application of this tip. maxLength: 192 nullable: true TenderBankAccountDetailsStatus: type: string enum: - PENDING - COMPLETED - FAILED x-enum-elements: - name: PENDING description: The bank account payment is in progress. - name: COMPLETED description: The bank account payment has been completed. - name: FAILED description: The bank account payment failed. description: Indicates the bank account payment's current status. x-release-status: PUBLIC OrderLineItemPricingBlocklists: type: object description: 'Describes pricing adjustments that are blocked from automatic application to a line item. For more information, see [Apply Taxes and Discounts](https://developer.squareup.com/docs/orders-api/apply-taxes-and-discounts).' x-release-status: BETA properties: blocked_discounts: type: array items: $ref: '#/components/schemas/OrderLineItemPricingBlocklistsBlockedDiscount' description: 'A list of discounts blocked from applying to the line item. Discounts can be blocked by the `discount_uid` (for ad hoc discounts) or the `discount_catalog_object_id` (for catalog discounts).' nullable: true blocked_taxes: type: array items: $ref: '#/components/schemas/OrderLineItemPricingBlocklistsBlockedTax' description: 'A list of taxes blocked from applying to the line item. Taxes can be blocked by the `tax_uid` (for ad hoc taxes) or the `tax_catalog_object_id` (for catalog taxes).' nullable: true PaymentLink: type: object x-release-status: PUBLIC required: - version properties: id: type: string description: The Square-assigned ID of the payment link. readOnly: true version: type: integer description: The Square-assigned version number, which is incremented each time an update is committed to the payment link. maximum: 65535 description: type: string description: 'The optional description of the `payment_link` object. It is primarily for use by your application and is not used anywhere.' maxLength: 4096 nullable: true order_id: type: string description: The ID of the order associated with the payment link. maxLength: 192 readOnly: true checkout_options: $ref: '#/components/schemas/CheckoutOptions' description: 'The checkout options configured for the payment link. For more information, see [Optional Checkout Configurations](https://developer.squareup.com/docs/checkout-api/optional-checkout-configurations).' nullable: true pre_populated_data: $ref: '#/components/schemas/PrePopulatedData' description: 'Describes buyer data to prepopulate on the checkout page.' nullable: true url: type: string description: The shortened URL of the payment link. maxLength: 255 readOnly: true long_url: type: string description: The long URL of the payment link. maxLength: 255 readOnly: true created_at: type: string description: The timestamp when the payment link was created, in RFC 3339 format. updated_at: type: string description: The timestamp when the payment link was last updated, in RFC 3339 format. payment_note: type: string description: 'An optional note. After Square processes the payment, this note is added to the resulting `Payment`.' maxLength: 500 nullable: true ListPaymentLinksResponse: type: object x-release-status: PUBLIC properties: errors: type: array items: $ref: '#/components/schemas/Error' description: Errors that occurred during the request. payment_links: type: array items: $ref: '#/components/schemas/PaymentLink' description: The list of payment links. cursor: type: string description: ' When a response is truncated, it includes a cursor that you can use in a subsequent request to retrieve the next set of gift cards. If a cursor is not present, this is the final response. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).' example: cursor: MTY1NQ== payment_links: - checkout_options: ask_for_shipping_address: true created_at: '2022-04-26T00:15:15Z' id: TN4BWEDJ9AI5MBIV order_id: Qqc6yppGvxVwc46Cch4zHTaJqc4F payment_note: test updated_at: '2022-04-26T00:18:24Z' url: https://square.link/u/EXAMPLE version: 2 - created_at: '2022-04-11T23:14:59Z' description: '' id: RY5UNCUMPJN5XKCT order_id: EmBmGt3zJD15QeO1dxzBTxMxtwfZY url: https://square.link/u/EXAMPLE version: 1 OrderLineItemAppliedDiscount: type: object description: 'Represents an applied portion of a discount to a line item in an order. Order scoped discounts have automatically applied discounts present for each line item. Line-item scoped discounts must have applied discounts added manually for any applicable line items. The corresponding applied money is automatically computed based on participating line items.' x-release-status: BETA required: - discount_uid properties: uid: type: string description: A unique ID that identifies the applied discount only within this order. maxLength: 60 nullable: true discount_uid: type: string description: 'The `uid` of the discount that the applied discount represents. It must reference a discount present in the `order.discounts` field. This field is immutable. To change which discounts apply to a line item, you must delete the discount and re-add it as a new `OrderLineItemAppliedDiscount`.' minLength: 1 maxLength: 60 applied_money: $ref: '#/components/schemas/Money' description: The amount of money applied by the discount to the line item. readOnly: true FulfillmentShipmentDetails: type: object description: Contains the details necessary to fulfill a shipment order. x-release-status: BETA properties: recipient: $ref: '#/components/schemas/FulfillmentRecipient' description: Information about the person to receive this shipment fulfillment. nullable: true carrier: type: string description: The shipping carrier being used to ship this fulfillment (such as UPS, FedEx, or USPS). maxLength: 50 nullable: true shipping_note: type: string description: A note with additional information for the shipping carrier. maxLength: 500 nullable: true shipping_type: type: string description: 'A description of the type of shipping product purchased from the carrier (such as First Class, Priority, or Express).' maxLength: 50 nullable: true tracking_number: type: string description: The reference number provided by the carrier to track the shipment's progress. maxLength: 100 nullable: true tracking_url: type: string description: A link to the tracking webpage on the carrier's website. maxLength: 2000 nullable: true placed_at: type: string description: 'The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates) indicating when the shipment was requested. The timestamp must be in RFC 3339 format (for example, "2016-09-04T23:59:33.123Z").' readOnly: true in_progress_at: type: string description: 'The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates) indicating when this fulfillment was moved to the `RESERVED` state, which indicates that preparation of this shipment has begun. The timestamp must be in RFC 3339 format (for example, "2016-09-04T23:59:33.123Z").' readOnly: true packaged_at: type: string description: 'The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates) indicating when this fulfillment was moved to the `PREPARED` state, which indicates that the fulfillment is packaged. The timestamp must be in RFC 3339 format (for example, "2016-09-04T23:59:33.123Z").' readOnly: true expected_shipped_at: type: string description: 'The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates) indicating when the shipment is expected to be delivered to the shipping carrier. The timestamp must be in RFC 3339 format (for example, "2016-09-04T23:59:33.123Z").' nullable: true shipped_at: type: string description: 'The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates) indicating when this fulfillment was moved to the `COMPLETED` state, which indicates that the fulfillment has been given to the shipping carrier. The timestamp must be in RFC 3339 format (for example, "2016-09-04T23:59:33.123Z").' readOnly: true canceled_at: type: string description: 'The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates) indicating the shipment was canceled. The timestamp must be in RFC 3339 format (for example, "2016-09-04T23:59:33.123Z").' nullable: true cancel_reason: type: string description: A description of why the shipment was canceled. maxLength: 100 nullable: true failed_at: type: string description: 'The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates) indicating when the shipment failed to be completed. The timestamp must be in RFC 3339 format (for example, "2016-09-04T23:59:33.123Z").' readOnly: true failure_reason: type: string description: A description of why the shipment failed to be completed. maxLength: 100 nullable: true securitySchemes: oauth2: type: oauth2 x-additional-headers: - name: Square-Version description: Square Connect API versions schema: default: '2025-01-23' flows: authorizationCode: authorizationUrl: https://connect.squareup.com/oauth2/authorize tokenUrl: https://connect.squareup.com/oauth2/token scopes: ADDON_CONFIGURATIONS_READ: '__HTTP Method__: `GET` Grants write access for third-party Add-ons to read configurations of their Add-ons, for example, when calling `RetrieveConfiguration` endpoint.' ADDON_CONFIGURATIONS_WRITE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Grants write access for third-party Add-ons to store configurations of their Add-ons, for example, when calling `CreateConfiguration` endpoint.' APPOINTMENTS_ALL_READ: '__HTTP Method__: `GET`, `POST` Grants read access to all of a seller''s booking information, calendar, and business details. This permission must be accompanied by the `APPOINTMENTS_READ` permission.' APPOINTMENTS_ALL_WRITE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Grants write access to all booking details, including double-booking a seller. This permission must be accompanied by the `APPOINTMENTS_WRITE` permission.' APPOINTMENTS_BUSINESS_SETTINGS_READ: '__HTTP Method__: `GET` Grants read access to booking business settings. For example, to call the ListTeamMemberBookingProfiles endpoint.' APPOINTMENTS_READ: '__HTTP Method__: `GET`, `POST` Grants read access to booking information. For example, to call the RetrieveBooking endpoint.' APPOINTMENTS_WRITE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Grants write access to booking information. For example, to call the CreateBooking endpoint.' BANK_ACCOUNTS_READ: '__HTTP Method__: `GET` Grants read access to bank account information associated with the targeted Square account. For example, to call the Connect v1 ListBankAccounts endpoint.' CASH_DRAWER_READ: '__HTTP Method__: `GET` Grants read access to cash drawer shift information. For example, to call the ListCashDrawerShifts endpoint.' CHANNELS_CREATE: '__HTTP Method__: `POST` Grants write access to create channels, for example, when calling the `CreateChannel` endpoint.' CHANNELS_READ: '__HTTP Method__: `GET` Grants read access to view channels, for example, when calling the `RetrieveChannel` endpoint.' CHANNELS_UPDATE: '__HTTP Method__: `PUT` Grants write access to update channels, for example, when calling the `UpdateChannel` endpoint.' CUSTOMERS_READ: '__HTTP Method__: `GET` Grants read access to customer information. For example, to call the ListCustomers endpoint.' CUSTOMERS_WRITE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Grants write access to customer information. For example, to create and update customer profiles.' DEVICES_READ: '__HTTP Method__: `GET` Grants read access to device information. For example, to call the `GetDevice` and `ListDevices` endpoints.' DEVICE_CREDENTIAL_MANAGEMENT: '__HTTP Method__: `POST`, `GET` Grants read/write access to device credentials information. For example, to call the CreateDeviceCode endpoint.' DISPUTES_READ: '__HTTP Method__: `GET` Grants read access to dispute information. For example, to call the RetrieveDispute endpoint.' DISPUTES_WRITE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Grants write access to dispute information. For example, to call the SubmitEvidence endpoint.' EMPLOYEES_READ: '__HTTP Method__: `GET` Grants read access to employee profile information. For example, to call the Connect v1 Employees API.' EMPLOYEES_WRITE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Grants write access to employee profile information. For example, to create and modify employee profiles.' GIFTCARDS_READ: '__HTTP Method__: `GET`, `POST` Grants read access to gift card information. For example, to call the RetrieveGiftCard endpoint.' GIFTCARDS_WRITE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Grants write access to gift card information. For example, to call the CreateGiftCard endpoint.' INVENTORY_READ: '__HTTP Method__: `GET` Grants read access to inventory information. For example, to call the RetrieveInventoryCount endpoint.' INVENTORY_WRITE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Grants write access to inventory information. For example, to call the BatchChangeInventory endpoint.' INVOICES_READ: '__HTTP Method__: `GET`, `POST` Grants read access to invoice information. For example, to call the ListInvoices endpoint.' INVOICES_WRITE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Grants write access to invoice information. For example, to call the CreateInvoice endpoint.' ITEMS_READ: '__HTTP Method__: `GET` Grants read access to product catalog information. For example, to obtain objects in a product catalog.' ITEMS_WRITE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Grants write access to product catalog information. For example, to modify or add to a product catalog.' LOYALTY_READ: '__HTTP Method__: `GET` Grants read access to loyalty information. For example, to call the ListLoyaltyPrograms endpoint.' LOYALTY_WRITE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Grants write access to loyalty information. For example, to call the CreateLoyaltyAccount endpoint.' MERCHANT_PROFILE_READ: '__HTTP Method__: `GET` Grants read access to business and location information. For example, to obtain a location ID for subsequent activity.' MERCHANT_PROFILE_WRITE: '__HTTP Method__: `POST`, `PUT` Grants write access to business and location information. For example, to create a new location or update the business hours at an existing location.' ONLINE_STORE_SITE_READ: '__HTTP Method__: `GET`, `POST` Read access to ECOM online store site details.' ONLINE_STORE_SNIPPETS_READ: '__HTTP Method__: `GET`, `POST` Read access to ECOM online store snippets on published websites.' ONLINE_STORE_SNIPPETS_WRITE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Write access to ECOM online store snippets on published websites.' ORDERS_READ: '__HTTP Method__: `GET` Grants read access to order information. For example, to call the BatchRetrieveOrders endpoint.' ORDERS_WRITE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Grants write access to order information. For example, to call the CreateCheckout endpoint.' PAYMENTS_READ: '__HTTP Method__: `GET` Grants read access to transaction and refund information. For example, to call the RetrieveTransaction endpoint.' PAYMENTS_WRITE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Grants write access to transaction and refunds information. For example, to process payments with the Payments or Checkout API.' PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS: '__HTTP Method__: `POST`, `PUT`, `DELETE` Allow third party applications to deduct a portion of each transaction amount. __Required__ to use multiparty transaction functionality with the Payments API.' PAYMENTS_WRITE_IN_PERSON: '__HTTP Method__: `POST`, `PUT`, `DELETE` Grants write access to payments and refunds information. For example, to process in-person payments.' PAYMENTS_WRITE_SHARED_ONFILE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Allows the developer to process payments on behalf of a seller using a shared on file payment method.' PAYOUTS_READ: '__HTTP Method__: `GET` Grants read access to payouts and payout entries information. For example, to call the Connect v2 `ListPayouts` endpoint.' PERMISSION_SETS_READ: '__HTTP Method__: `GET` Grants read access to Permission Sets. For example, to call the `ListPermissionSets` and `RetrievePermissionSet` endpoints.' PERMISSION_SETS_WRITE: '__HTTP Method__: `PUT` Grants write access to Permission Sets.' RESERVATIONS_READ: '__HTTP Method__: `GET` Grants read access to reservation information, for example, when calling the `RetrieveReservation` endpoint.' RESERVATIONS_WRITE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Grants write access to reservation information, for example, when calling the `CreateReservation` endpoint.' RESTAURANT_CHECKS_READ: '__HTTP Method__: `GET` Grants read access to check information, for example, when calling the `RetrieveCheck` endpoint.' SETTLEMENTS_READ: '__HTTP Method__: `GET` Grants read access to settlement (deposit) information. For example, to call the Connect v1 ListSettlements endpoint.' SUBSCRIPTIONS_READ: '__HTTP Method__: `GET`, `POST` Grants read access to subscription information. For example, to call the RetrieveSubscription endpoint.' SUBSCRIPTIONS_WRITE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Grants write access to subscription information. For example, to call the CreateSubscription endpoint.' TIMECARDS_READ: '__HTTP Method__: `GET` Grants read access to employee timecard information. For example, to call the Connect v2 SearchShifts endpoint.' TIMECARDS_SETTINGS_READ: '__HTTP Method__: `GET` Grants read access to employee timecard settings information. For example, to call the GetBreakType endpoint.' TIMECARDS_SETTINGS_WRITE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Grants write access to employee timecard settings information. For example, to call the UpdateBreakType endpoint.' TIMECARDS_WRITE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Grants write access to employee shift information. For example, to create and modify employee shifts.' VENDOR_READ: '__HTTP Method__: `GET`, `POST` Grants read access to vendor information, for example, when calling the `RetrieveVendor` endpoint.' VENDOR_WRITE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Grants write access to vendor information, for example, when calling the `BulkUpdateVendors` endpoint.' oauth2ClientSecret: type: apiKey in: header name: Authorization x-fern-global-headers: - header: Square-Version name: version optional: true env: VERSION type: literal<"2025-01-23">