openapi: 3.0.0 info: version: '2.0' title: Square ApplePay Invoices 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: Invoices paths: /v2/invoices: get: tags: - Invoices summary: Square List Invoices operationId: ListInvoices x-microcks-operation: delay: 0 dispatcher: FALLBACK description: "Returns a list of invoices for a given location. The response \nis paginated. If truncated, the response includes a `cursor` that you \nuse in a subsequent request to retrieve the next set of invoices." x-release-status: PUBLIC security: - oauth2: - INVOICES_READ parameters: - name: location_id description: The ID of the location for which to list invoices. schema: type: string in: query required: true - name: cursor description: "A pagination cursor returned by a previous call to this endpoint. \nProvide this cursor to retrieve the next set of results for your original query.\n\nFor 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: "The maximum number of invoices to return (200 is the maximum `limit`). \nIf not provided, the server uses a default limit of 100 invoices." schema: type: integer in: query required: false responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ListInvoicesResponse' post: tags: - Invoices summary: Square Create Invoice operationId: CreateInvoice x-microcks-operation: delay: 0 dispatcher: FALLBACK description: "Creates a draft [invoice](entity:Invoice) \nfor an order created using the Orders API.\n\nA draft invoice remains in your account and no action is taken. \nYou must publish the invoice before Square can process it (send it to the customer's email address or charge the customer’s card on file)." x-release-status: PUBLIC security: - oauth2: - ORDERS_WRITE - INVOICES_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/CreateInvoiceRequest' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/CreateInvoiceResponse' x-endpoint-errors: - error-code: INVALID_CARD - error-code: MERCHANT_SUBSCRIPTION_NOT_FOUND /v2/invoices/search: post: tags: - Invoices summary: Square Search Invoices operationId: SearchInvoices x-microcks-operation: delay: 0 dispatcher: FALLBACK description: "Searches for invoices from a location specified in \nthe filter. You can optionally specify customers in the filter for whom to \nretrieve invoices. In the current implementation, you can only specify one location and \noptionally one customer.\n\nThe response is paginated. If truncated, the response includes a `cursor` \nthat you use in a subsequent request to retrieve the next set of invoices." x-release-status: PUBLIC security: - oauth2: - INVOICES_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/SearchInvoicesRequest' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/SearchInvoicesResponse' /v2/invoices/{invoice_id}: delete: tags: - Invoices summary: Square Delete Invoice operationId: DeleteInvoice x-microcks-operation: delay: 0 dispatcher: FALLBACK description: "Deletes the specified invoice. When an invoice is deleted, the \nassociated order status changes to CANCELED. You can only delete a draft \ninvoice (you cannot delete a published invoice, including one that is scheduled for processing)." x-release-status: PUBLIC security: - oauth2: - ORDERS_WRITE - INVOICES_WRITE parameters: - name: invoice_id description: The ID of the invoice to delete. schema: type: string in: path required: true - name: version description: "The version of the [invoice](entity:Invoice) to delete.\nIf you do not know the version, you can call [GetInvoice](api-endpoint:Invoices-GetInvoice) or \n[ListInvoices](api-endpoint:Invoices-ListInvoices)." schema: type: integer in: query required: false responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/DeleteInvoiceResponse' get: tags: - Invoices summary: Square Get Invoice operationId: GetInvoice x-microcks-operation: delay: 0 dispatcher: FALLBACK description: Retrieves an invoice by invoice ID. x-release-status: PUBLIC security: - oauth2: - INVOICES_READ parameters: - name: invoice_id description: The ID of the invoice to retrieve. schema: type: string in: path required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/GetInvoiceResponse' put: tags: - Invoices summary: Square Update Invoice operationId: UpdateInvoice x-microcks-operation: delay: 0 dispatcher: FALLBACK description: 'Updates an invoice. This endpoint supports sparse updates, so you only need to specify the fields you want to change along with the required `version` field. Some restrictions apply to updating invoices. For example, you cannot change the `order_id` or `location_id` field.' x-release-status: PUBLIC security: - oauth2: - ORDERS_WRITE - INVOICES_WRITE parameters: - name: invoice_id description: The ID of the invoice 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/UpdateInvoiceRequest' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/UpdateInvoiceResponse' x-endpoint-errors: - error-code: CARD_DECLINED - error-code: INVALID_CARD - error-code: MERCHANT_SUBSCRIPTION_NOT_FOUND /v2/invoices/{invoice_id}/attachments: post: tags: - Invoices summary: Square Create Invoice Attachment operationId: CreateInvoiceAttachment x-microcks-operation: delay: 0 dispatcher: FALLBACK description: 'Uploads a file and attaches it to an invoice. This endpoint accepts HTTP multipart/form-data file uploads with a JSON `request` part and a `file` part. The `file` part must be a `readable stream` that contains a file in a supported format: GIF, JPEG, PNG, TIFF, BMP, or PDF. Invoices can have up to 10 attachments with a total file size of 25 MB. Attachments can be added only to invoices in the `DRAFT`, `SCHEDULED`, `UNPAID`, or `PARTIALLY_PAID` state.' x-release-status: PUBLIC security: - oauth2: - INVOICES_WRITE parameters: - name: invoice_id description: The ID of the [invoice](entity:Invoice) to attach the file to. 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: multipart/form-data: schema: type: object properties: request: $ref: '#/components/schemas/CreateInvoiceAttachmentRequest' image_file: type: string format: binary encoding: image_file: contentType: image/jpeg request: contentType: application/json; charset=utf-8 responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/CreateInvoiceAttachmentResponse' /v2/invoices/{invoice_id}/attachments/{attachment_id}: delete: tags: - Invoices summary: Square Delete Invoice Attachment operationId: DeleteInvoiceAttachment x-microcks-operation: delay: 0 dispatcher: FALLBACK description: 'Removes an attachment from an invoice and permanently deletes the file. Attachments can be removed only from invoices in the `DRAFT`, `SCHEDULED`, `UNPAID`, or `PARTIALLY_PAID` state.' x-release-status: PUBLIC security: - oauth2: - INVOICES_WRITE parameters: - name: invoice_id description: The ID of the [invoice](entity:Invoice) to delete the attachment from. schema: type: string in: path required: true - name: attachment_id description: The ID of the [attachment](entity:InvoiceAttachment) to delete. schema: type: string in: path required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/DeleteInvoiceAttachmentResponse' /v2/invoices/{invoice_id}/cancel: post: tags: - Invoices summary: Square Cancel Invoice operationId: CancelInvoice x-microcks-operation: delay: 0 dispatcher: FALLBACK description: "Cancels an invoice. The seller cannot collect payments for \nthe canceled invoice.\n\nYou cannot cancel an invoice in the `DRAFT` state or in a terminal state: `PAID`, `REFUNDED`, `CANCELED`, or `FAILED`." x-release-status: PUBLIC security: - oauth2: - ORDERS_WRITE - INVOICES_WRITE parameters: - name: invoice_id description: The ID of the [invoice](entity:Invoice) to cancel. 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/CancelInvoiceRequest' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/CancelInvoiceResponse' x-endpoint-errors: - error-code: VERSION_MISMATCH /v2/invoices/{invoice_id}/publish: post: tags: - Invoices summary: Square Publish Invoice operationId: PublishInvoice x-microcks-operation: delay: 0 dispatcher: FALLBACK description: "Publishes the specified draft invoice. \n\nAfter an invoice is published, Square \nfollows up based on the invoice configuration. For example, Square \nsends the invoice to the customer's email address, charges the customer's card on file, or does \nnothing. Square also makes the invoice available on a Square-hosted invoice page. \n\nThe invoice `status` also changes from `DRAFT` to a status \nbased on the invoice configuration. For example, the status changes to `UNPAID` if \nSquare emails the invoice or `PARTIALLY_PAID` if Square charges a card on file for a portion of the \ninvoice amount.\n\nIn addition to the required `ORDERS_WRITE` and `INVOICES_WRITE` permissions, `CUSTOMERS_READ`\nand `PAYMENTS_WRITE` are required when publishing invoices configured for card-on-file payments." x-release-status: PUBLIC security: - oauth2: - ORDERS_WRITE - INVOICES_WRITE parameters: - name: invoice_id description: The ID of the invoice to publish. 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/PublishInvoiceRequest' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/PublishInvoiceResponse' x-endpoint-errors: - error-code: CARD_DECLINED - error-code: INVALID_CARD components: schemas: InvoiceDeliveryMethod: type: string enum: - EMAIL - SHARE_MANUALLY - SMS x-enum-elements: - name: EMAIL description: Directs Square to send invoices, reminders, and receipts to the customer using email. - name: SHARE_MANUALLY description: 'Directs Square to take no action on the invoice. In this case, the seller or application developer follows up with the customer for payment. For example, a seller might collect a payment in the Seller Dashboard or Point of Sale (POS) application. The seller might also share the URL of the Square-hosted invoice page (`public_url`) with the customer to request payment.' - name: SMS description: 'Directs Square to send invoices and receipts to the customer using SMS (text message). You cannot set `SMS` as a delivery method using the Invoices API, but you can change an `SMS` delivery method to `EMAIL` or `SHARE_MANUALLY`.' description: Indicates how Square delivers the [invoice](entity:Invoice) to the customer. x-release-status: PUBLIC PublishInvoiceRequest: type: object description: Describes a `PublishInvoice` request. x-release-status: PUBLIC required: - version properties: version: type: integer description: 'The version of the [invoice](entity:Invoice) to publish. This must match the current version of the invoice; otherwise, the request is rejected.' idempotency_key: type: string description: "A unique string that identifies the `PublishInvoice` request. If you do not \nprovide `idempotency_key` (or provide an empty string as the value), the endpoint \ntreats each request as independent.\n\nFor more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)." maxLength: 128 nullable: true example: idempotency_key: 32da42d0-1997-41b0-826b-f09464fc2c2e version: 1 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 InvoiceAttachment: type: object description: Represents a file attached to an [invoice](entity:Invoice). x-release-status: PUBLIC properties: id: type: string description: The Square-assigned ID of the attachment. readOnly: true filename: type: string description: The file name of the attachment, which is displayed on the invoice. readOnly: true description: type: string description: 'The description of the attachment, which is displayed on the invoice. This field maps to the seller-defined **Message** field.' readOnly: true filesize: type: integer description: The file size of the attachment in bytes. readOnly: true hash: type: string description: The MD5 hash that was generated from the file contents. readOnly: true mime_type: type: string description: "The mime type of the attachment.\nThe following mime types are supported: \nimage/gif, image/jpeg, image/png, image/tiff, image/bmp, application/pdf." readOnly: true uploaded_at: type: string description: The timestamp when the attachment was uploaded, in RFC 3339 format. readOnly: true 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 GetInvoiceResponse: type: object description: Describes a `GetInvoice` response. x-release-status: PUBLIC properties: invoice: $ref: '#/components/schemas/Invoice' description: The invoice requested. errors: type: array items: $ref: '#/components/schemas/Error' description: Information about errors encountered during the request. example: invoice: accepted_payment_methods: bank_account: false buy_now_pay_later: false card: true cash_app_pay: false square_gift_card: false created_at: '2020-06-18T17:45:13Z' custom_fields: - label: Event Reference Number placement: ABOVE_LINE_ITEMS value: 'Ref. #1234' - label: Terms of Service placement: BELOW_LINE_ITEMS value: The terms of service are... delivery_method: EMAIL description: We appreciate your business! id: inv:0-ChCHu2mZEabLeeHahQnXDjZQECY invoice_number: inv-100 location_id: ES0RJRZYEC39A order_id: CAISENgvlJ6jLWAzERDzjyHVybY payment_requests: - automatic_payment_source: NONE computed_amount_money: amount: 10000 currency: USD due_date: '2030-01-24' reminders: - message: Your invoice is due tomorrow relative_scheduled_days: -1 status: PENDING uid: beebd363-e47f-4075-8785-c235aaa7df11 request_type: BALANCE tipping_enabled: true total_completed_amount_money: amount: 0 currency: USD uid: 2da7964f-f3d2-4f43-81e8-5aa220bf3355 primary_recipient: customer_id: JDKYHBWT1D4F8MFH63DBMEN8Y4 email_address: Amelia.Earhart@example.com family_name: Earhart given_name: Amelia phone_number: 1-212-555-4240 sale_or_service_date: '2030-01-24' scheduled_at: '2030-01-13T10:00:00Z' status: DRAFT store_payment_method_enabled: false timezone: America/Los_Angeles title: Event Planning Services updated_at: '2020-06-18T17:45:13Z' version: 0 InvoiceAutomaticPaymentSource: type: string enum: - NONE - CARD_ON_FILE - BANK_ON_FILE x-enum-elements: - name: NONE description: An automatic payment is not configured for the payment request. - name: CARD_ON_FILE description: 'Use a card on file as the automatic payment method. On the due date, Square charges the card for the amount of the payment request. For `CARD_ON_FILE` payments, the invoice delivery method must be `EMAIL` and `card_id` must be specified for the payment request before the invoice can be published.' - name: BANK_ON_FILE description: "Use a bank account on file as the automatic payment method. On the due date, Square charges the bank\naccount for the amount of the payment request if the buyer has approved the payment. The buyer receives a\nrequest to approve the payment when the invoice is sent or the invoice is updated.\n\nThis payment method applies only to invoices that sellers create in the Seller Dashboard or other\nSquare product. The bank account is provided by the customer during the payment flow. \n\nYou cannot set `BANK_ON_FILE` as a payment method using the Invoices API, but you can change a `BANK_ON_FILE`\npayment method to `NONE` or `CARD_ON_FILE`. For `BANK_ON_FILE` payments, the invoice delivery method must be `EMAIL`." description: Indicates the automatic payment method for an [invoice payment request](entity:InvoicePaymentRequest). x-release-status: PUBLIC ListInvoicesResponse: type: object description: Describes a `ListInvoice` response. x-release-status: PUBLIC properties: invoices: type: array items: $ref: '#/components/schemas/Invoice' description: The invoices retrieved. cursor: type: string description: "When a response is truncated, it includes a cursor that you can use in a \nsubsequent request to retrieve the next set of invoices. If empty, this is the final \nresponse. \nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)." errors: type: array items: $ref: '#/components/schemas/Error' description: Information about errors encountered during the request. example: cursor: ChoIDhIWVm54ZVRhLXhySFBOejBBM2xJb2daUQoFCI4IGAE invoices: - accepted_payment_methods: bank_account: false buy_now_pay_later: false card: true cash_app_pay: false square_gift_card: false attachments: - description: Service contract filename: file.jpg filesize: 102705 hash: 273ee02cb6f5f8a3a8ca23604930dd53 id: inva:0-3bB9ZuDHiziThQhuC4fwWt mime_type: image/jpeg uploaded_at: '2030-01-13T21:24:10Z' created_at: '2030-01-13T17:45:13Z' custom_fields: - label: Event Reference Number placement: ABOVE_LINE_ITEMS value: 'Ref. #1234' - label: Terms of Service placement: BELOW_LINE_ITEMS value: The terms of service are... delivery_method: EMAIL description: We appreciate your business! id: inv:0-ChCHu2mZEabLeeHahQnXDjZQECY invoice_number: inv-100 location_id: ES0RJRZYEC39A order_id: CAISENgvlJ6jLWAzERDzjyHVybY payment_requests: - automatic_payment_source: NONE computed_amount_money: amount: 10000 currency: USD due_date: '2030-01-24' reminders: - message: Your invoice is due tomorrow relative_scheduled_days: -1 status: PENDING uid: beebd363-e47f-4075-8785-c235aaa7df11 request_type: BALANCE tipping_enabled: true total_completed_amount_money: amount: 0 currency: USD uid: 2da7964f-f3d2-4f43-81e8-5aa220bf3355 primary_recipient: customer_id: JDKYHBWT1D4F8MFH63DBMEN8Y4 email_address: Amelia.Earhart@example.com family_name: Earhart given_name: Amelia phone_number: 1-212-555-4240 sale_or_service_date: '2030-01-24' scheduled_at: '2030-01-13T10:00:00Z' status: DRAFT store_payment_method_enabled: false timezone: America/Los_Angeles title: Event Planning Services updated_at: '2030-01-13T21:24:10Z' version: 1 - accepted_payment_methods: bank_account: false buy_now_pay_later: false card: true cash_app_pay: false square_gift_card: true created_at: '2021-01-23T15:29:12Z' delivery_method: EMAIL id: inv:0-ChC366qAfskpGrBI_1bozs9mEA3 invoice_number: inv-455 location_id: ES0RJRZYEC39A next_payment_amount_money: amount: 3000 currency: USD order_id: a65jnS8NXbfprvGJzY9F4fQTuaB payment_requests: - automatic_payment_source: CARD_ON_FILE card_id: ccof:IkWfpLj4tNHMyFii3GB computed_amount_money: amount: 1000 currency: USD due_date: '2021-01-23' percentage_requested: '25' request_type: DEPOSIT tipping_enabled: false total_completed_amount_money: amount: 1000 currency: USD uid: 66c3bdfd-5090-4ff9-a8a0-c1e1a2ffa176 - automatic_payment_source: CARD_ON_FILE card_id: ccof:IkWfpLj4tNHMyFii3GB computed_amount_money: amount: 3000 currency: USD due_date: '2021-06-15' request_type: BALANCE tipping_enabled: false total_completed_amount_money: amount: 0 currency: USD uid: 120c5e18-4f80-4f6b-b159-774cb9bf8f99 primary_recipient: customer_id: JDKYHBWT1D4F8MFH63DBMEN8Y4 email_address: Amelia.Earhart@example.com family_name: Earhart given_name: Amelia phone_number: 1-212-555-4240 public_url: https://squareup.com/pay-invoice/h9sfsfTGTSnYEhISUDBhEQ sale_or_service_date: '2030-01-24' status: PARTIALLY_PAID store_payment_method_enabled: false timezone: America/Los_Angeles updated_at: '2021-01-23T15:29:56Z' version: 3 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 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 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 InvoiceRequestMethod: type: string enum: - EMAIL - CHARGE_CARD_ON_FILE - SHARE_MANUALLY - CHARGE_BANK_ON_FILE - SMS - SMS_CHARGE_CARD_ON_FILE - SMS_CHARGE_BANK_ON_FILE x-enum-elements: - name: EMAIL description: 'Directs Square to send invoices, reminders, and receipts to the customer using email. Square sends the invoice after it is published (either immediately or at the `scheduled_at` time, if specified in the [invoice](entity:Invoice)).' - name: CHARGE_CARD_ON_FILE description: 'Directs Square to charge the card on file on the `due_date` specified in the payment request and to use email to send invoices, reminders, and receipts.' - name: SHARE_MANUALLY description: "Directs Square to take no specific action on the invoice. In this case, the seller \n(or the application developer) follows up with the customer for payment. For example, \na seller might collect a payment in the Seller Dashboard or use the Point of Sale (POS) application. \nThe seller might also share the URL of the Square-hosted invoice page (`public_url`) with the customer requesting payment." - name: CHARGE_BANK_ON_FILE description: "Directs Square to charge the customer's bank account on file and to use email to send invoices, reminders, and receipts.\nThe customer must approve the payment.\n\nThe bank on file payment method applies only to invoices that sellers create in the Seller Dashboard or other\nSquare product. The bank account is provided by the customer during the payment flow. You \ncannot set `CHARGE_BANK_ON_FILE` as a request method using the Invoices API." - name: SMS description: "Directs Square to send invoices and receipts to the customer using SMS (text message). Square sends the invoice\nafter it is published (either immediately or at the `scheduled_at` time, if specified in the [invoice](entity:Invoice)). \n\nYou cannot set `SMS` as a request method using the Invoices API." - name: SMS_CHARGE_CARD_ON_FILE description: "Directs Square to charge the card on file on the `due_date` specified in the payment request and to\nuse SMS (text message) to send invoices and receipts. \n\nYou cannot set `SMS_CHARGE_CARD_ON_FILE` as a request method using the Invoices API." - name: SMS_CHARGE_BANK_ON_FILE description: "Directs Square to charge the customer's bank account on file and to use SMS (text message) to send invoices and receipts.\nThe customer must approve the payment.\n\nThe bank on file payment method applies only to invoices that sellers create in the Seller Dashboard\nor other Square product. The bank account is provided by the customer during the payment flow. \nYou cannot set `SMS_CHARGE_BANK_ON_FILE` as a request method using the Invoices API." description: "Specifies the action for Square to take for processing the invoice. For example, \nemail the invoice, charge a customer's card on file, or do nothing. DEPRECATED at\nversion 2021-01-21. The corresponding `request_method` field is replaced by the\n`Invoice.delivery_method` and `InvoicePaymentRequest.automatic_payment_source` fields." x-release-status: DEPRECATED InvoiceStatus: type: string enum: - DRAFT - UNPAID - SCHEDULED - PARTIALLY_PAID - PAID - PARTIALLY_REFUNDED - REFUNDED - CANCELED - FAILED - PAYMENT_PENDING x-enum-elements: - name: DRAFT description: 'The invoice is a draft. You must publish a draft invoice before Square can process it. A draft invoice has no `public_url`, so it is not available to customers.' - name: UNPAID description: The invoice is published but not yet paid. - name: SCHEDULED description: 'The invoice is scheduled to be processed. On the scheduled date, Square sends the invoice, initiates an automatic payment, or takes no action, depending on the delivery method and payment request settings. Square also sets the invoice status to the appropriate state: `UNPAID`, `PAID`, `PARTIALLY_PAID`, or `PAYMENT_PENDING`.' - name: PARTIALLY_PAID description: A partial payment is received for the invoice. - name: PAID description: The customer paid the invoice in full. - name: PARTIALLY_REFUNDED description: 'The invoice is paid (or partially paid) and some but not all the amount paid is refunded.' - name: REFUNDED description: The full amount that the customer paid for the invoice is refunded. - name: CANCELED description: 'The invoice is canceled. Square no longer requests payments from the customer. The `public_url` page remains and is accessible, but it displays the invoice as canceled and does not accept payment.' - name: FAILED description: Square canceled the invoice due to suspicious activity. - name: PAYMENT_PENDING description: 'A payment on the invoice was initiated but has not yet been processed. When in this state, invoices cannot be updated and other payments cannot be initiated.' description: Indicates the status of an invoice. x-release-status: PUBLIC Money: type: object description: 'Represents an amount of money. `Money` fields can be signed or unsigned. 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 InvoicePaymentRequest: type: object description: "Represents a payment request for an [invoice](entity:Invoice). Invoices can specify a maximum\nof 13 payment requests, with up to 12 `INSTALLMENT` request types. For more information, \nsee [Configuring payment requests](https://developer.squareup.com/docs/invoices-api/create-publish-invoices#payment-requests).\n\nAdding `INSTALLMENT` payment requests to an invoice requires an \n[Invoices Plus subscription](https://developer.squareup.com/docs/invoices-api/overview#invoices-plus-subscription)." x-release-status: PUBLIC properties: uid: type: string description: The Square-generated ID of the payment request in an [invoice](entity:Invoice). minLength: 1 maxLength: 255 nullable: true request_method: $ref: '#/components/schemas/InvoiceRequestMethod' description: 'Indicates how Square processes the payment request. DEPRECATED at version 2021-01-21. Replaced by the `Invoice.delivery_method` and `InvoicePaymentRequest.automatic_payment_source` fields. One of the following is required when creating an invoice: - (Recommended) The `delivery_method` field of the invoice. To configure an automatic payment, the `automatic_payment_source` field of the payment request is also required. - This `request_method` field. Note that `invoice` objects returned in responses do not include `request_method`. See [InvoiceRequestMethod](#type-invoicerequestmethod) for possible values' x-release-status: DEPRECATED nullable: true request_type: $ref: '#/components/schemas/InvoiceRequestType' description: "Identifies the payment request type. This type defines how the payment request amount is determined. \nThis field is required to create a payment request.\nSee [InvoiceRequestType](#type-invoicerequesttype) for possible values" nullable: true due_date: type: string description: 'The due date (in the invoice''s time zone) for the payment request, in `YYYY-MM-DD` format. This field is required to create a payment request. If an `automatic_payment_source` is defined for the request, Square charges the payment source on this date. After this date, the invoice becomes overdue. For example, a payment `due_date` of 2021-03-09 with a `timezone` of America/Los\_Angeles becomes overdue at midnight on March 9 in America/Los\_Angeles (which equals a UTC timestamp of 2021-03-10T08:00:00Z).' nullable: true fixed_amount_requested_money: $ref: '#/components/schemas/Money' description: "If the payment request specifies `DEPOSIT` or `INSTALLMENT` as the `request_type`, \nthis indicates the request amount.\nYou cannot specify this when `request_type` is `BALANCE` or when the \npayment request includes the `percentage_requested` field." nullable: true percentage_requested: type: string description: "Specifies the amount for the payment request in percentage:\n\n- When the payment `request_type` is `DEPOSIT`, it is the percentage of the order's total amount.\n- When the payment `request_type` is `INSTALLMENT`, it is the percentage of the order's total less \nthe deposit, if requested. The sum of the `percentage_requested` in all installment \npayment requests must be equal to 100.\n\nYou cannot specify this when the payment `request_type` is `BALANCE` or when the \npayment request specifies the `fixed_amount_requested_money` field." nullable: true tipping_enabled: type: boolean description: "If set to true, the Square-hosted invoice page (the `public_url` field of the invoice) \nprovides a place for the customer to pay a tip. \n\nThis field is allowed only on the final payment request \nand the payment `request_type` must be `BALANCE` or `INSTALLMENT`." nullable: true automatic_payment_source: $ref: '#/components/schemas/InvoiceAutomaticPaymentSource' description: 'The payment method for an automatic payment. The default value is `NONE`. See [InvoiceAutomaticPaymentSource](#type-invoiceautomaticpaymentsource) for possible values' nullable: true card_id: type: string description: 'The ID of the credit or debit card on file to charge for the payment request. To get the cards on file for a customer, call [ListCards](api-endpoint:Cards-ListCards) and include the `customer_id` of the invoice recipient.' minLength: 1 maxLength: 255 nullable: true reminders: type: array items: $ref: '#/components/schemas/InvoicePaymentReminder' description: A list of one or more reminders to send for the payment request. nullable: true computed_amount_money: $ref: '#/components/schemas/Money' description: 'The amount of the payment request, computed using the order amount and information from the various payment request fields (`request_type`, `fixed_amount_requested_money`, and `percentage_requested`).' readOnly: true total_completed_amount_money: $ref: '#/components/schemas/Money' description: "The amount of money already paid for the specific payment request. \nThis amount might include a rounding adjustment if the most recent invoice payment \nwas in cash in a currency that rounds cash payments (such as, `CAD` or `AUD`)." readOnly: true rounding_adjustment_included_money: $ref: '#/components/schemas/Money' description: "If the most recent payment was a cash payment \nin a currency that rounds cash payments (such as, `CAD` or `AUD`) and the payment \nis rounded from `computed_amount_money` in the payment request, then this \nfield specifies the rounding adjustment applied. This amount \nmight be negative." readOnly: true InvoiceCustomFieldPlacement: type: string enum: - ABOVE_LINE_ITEMS - BELOW_LINE_ITEMS x-enum-elements: - name: ABOVE_LINE_ITEMS description: Render the custom field above the invoice line items. - name: BELOW_LINE_ITEMS description: Render the custom field below the invoice line items. description: "Indicates where to render a custom field on the Square-hosted invoice page and in emailed or PDF \ncopies of the invoice." x-release-status: PUBLIC Invoice: type: object description: 'Stores information about an invoice. You use the Invoices API to create and manage invoices. For more information, see [Invoices API Overview](https://developer.squareup.com/docs/invoices-api/overview).' x-release-status: PUBLIC properties: id: type: string description: The Square-assigned ID of the invoice. readOnly: true version: type: integer description: The Square-assigned version number, which is incremented each time an update is committed to the invoice. location_id: type: string description: "The ID of the location that this invoice is associated with. \n\nIf specified in a `CreateInvoice` request, the value must match the `location_id` of the associated order." minLength: 1 maxLength: 255 nullable: true order_id: type: string description: "The ID of the [order](entity:Order) for which the invoice is created. \nThis field is required when creating an invoice, and the order must be in the `OPEN` state.\n\nTo view the line items and other information for the associated order, call the \n[RetrieveOrder](api-endpoint:Orders-RetrieveOrder) endpoint using the order ID." minLength: 1 maxLength: 255 nullable: true primary_recipient: $ref: '#/components/schemas/InvoiceRecipient' description: "The customer who receives the invoice. This customer data is displayed on the invoice and used by Square to deliver the invoice. \n\nThis field is required to publish an invoice, and it must specify the `customer_id`." nullable: true payment_requests: type: array items: $ref: '#/components/schemas/InvoicePaymentRequest' description: "The payment schedule for the invoice, represented by one or more payment requests that\ndefine payment settings, such as amount due and due date. An invoice supports the following payment request combinations:\n- One balance\n- One deposit with one balance\n- 2–12 installments \n- One deposit with 2–12 installments\n\nThis field is required when creating an invoice. It must contain at least one payment request. \nAll payment requests for the invoice must equal the total order amount. For more information, see \n[Configuring payment requests](https://developer.squareup.com/docs/invoices-api/create-publish-invoices#payment-requests).\n\nAdding `INSTALLMENT` payment requests to an invoice requires an \n[Invoices Plus subscription](https://developer.squareup.com/docs/invoices-api/overview#invoices-plus-subscription)." nullable: true delivery_method: $ref: '#/components/schemas/InvoiceDeliveryMethod' description: 'The delivery method that Square uses to send the invoice, reminders, and receipts to the customer. After the invoice is published, Square processes the invoice based on the delivery method and payment request settings, either immediately or on the `scheduled_at` date, if specified. For example, Square might send the invoice or receipt for an automatic payment. For invoices with automatic payments, this field must be set to `EMAIL`. One of the following is required when creating an invoice: - (Recommended) This `delivery_method` field. To configure an automatic payment, the `automatic_payment_source` field of the payment request is also required. - The deprecated `request_method` field of the payment request. Note that `invoice` objects returned in responses do not include `request_method`. See [InvoiceDeliveryMethod](#type-invoicedeliverymethod) for possible values' nullable: true invoice_number: type: string description: 'A user-friendly invoice number that is displayed on the invoice. The value is unique within a location. If not provided when creating an invoice, Square assigns a value. It increments from 1 and is padded with zeros making it 7 characters long (for example, 0000001 and 0000002).' minLength: 1 maxLength: 191 nullable: true title: type: string description: The title of the invoice, which is displayed on the invoice. minLength: 1 maxLength: 255 nullable: true description: type: string description: The description of the invoice, which is displayed on the invoice. minLength: 1 maxLength: 65536 nullable: true scheduled_at: type: string description: 'The timestamp when the invoice is scheduled for processing, in RFC 3339 format. After the invoice is published, Square processes the invoice on the specified date, according to the delivery method and payment request settings. If the field is not set, Square processes the invoice immediately after it is published.' nullable: true public_url: type: string description: 'The URL of the Square-hosted invoice page. After you publish the invoice using the `PublishInvoice` endpoint, Square hosts the invoice page and returns the page URL in the response.' readOnly: true next_payment_amount_money: $ref: '#/components/schemas/Money' description: 'The current amount due for the invoice. In addition to the amount due on the next payment request, this includes any overdue payment amounts.' readOnly: true status: $ref: '#/components/schemas/InvoiceStatus' description: 'The status of the invoice. See [InvoiceStatus](#type-invoicestatus) for possible values' readOnly: true timezone: type: string description: 'The time zone used to interpret calendar dates on the invoice, such as `due_date`. When an invoice is created, this field is set to the `timezone` specified for the seller location. The value cannot be changed. For example, a payment `due_date` of 2021-03-09 with a `timezone` of America/Los\_Angeles becomes overdue at midnight on March 9 in America/Los\_Angeles (which equals a UTC timestamp of 2021-03-10T08:00:00Z).' readOnly: true created_at: type: string description: The timestamp when the invoice was created, in RFC 3339 format. readOnly: true updated_at: type: string description: The timestamp when the invoice was last updated, in RFC 3339 format. readOnly: true accepted_payment_methods: $ref: '#/components/schemas/InvoiceAcceptedPaymentMethods' description: 'The payment methods that customers can use to pay the invoice on the Square-hosted invoice page. This setting is independent of any automatic payment requests for the invoice. This field is required when creating an invoice and must set at least one payment method to `true`.' nullable: true custom_fields: type: array items: $ref: '#/components/schemas/InvoiceCustomField' description: "Additional seller-defined fields that are displayed on the invoice. For more information, see\n[Custom fields](https://developer.squareup.com/docs/invoices-api/overview#custom-fields).\n\nAdding custom fields to an invoice requires an \n[Invoices Plus subscription](https://developer.squareup.com/docs/invoices-api/overview#invoices-plus-subscription).\n\nMax: 2 custom fields" nullable: true subscription_id: type: string description: 'The ID of the [subscription](entity:Subscription) associated with the invoice. This field is present only on subscription billing invoices.' readOnly: true sale_or_service_date: type: string description: 'The date of the sale or the date that the service is rendered, in `YYYY-MM-DD` format. This field can be used to specify a past or future date which is displayed on the invoice.' nullable: true payment_conditions: type: string description: "**France only.** The payment terms and conditions that are displayed on the invoice. For more information, \nsee [Payment conditions](https://developer.squareup.com/docs/invoices-api/overview#payment-conditions).\n\nFor countries other than France, Square returns an `INVALID_REQUEST_ERROR` with a `BAD_REQUEST` code and \n\"Payment conditions are not supported for this location's country\" detail if this field is included in `CreateInvoice` or `UpdateInvoice` requests." minLength: 1 maxLength: 2000 nullable: true store_payment_method_enabled: type: boolean description: 'Indicates whether to allow a customer to save a credit or debit card as a card on file or a bank transfer as a bank account on file. If `true`, Square displays a __Save my card on file__ or __Save my bank on file__ checkbox on the invoice payment page. Stored payment information can be used for future automatic payments. The default value is `false`.' nullable: true attachments: type: array items: $ref: '#/components/schemas/InvoiceAttachment' description: 'Metadata about the attachments on the invoice. Invoice attachments are managed using the [CreateInvoiceAttachment](api-endpoint:Invoices-CreateInvoiceAttachment) and [DeleteInvoiceAttachment](api-endpoint:Invoices-DeleteInvoiceAttachment) endpoints.' readOnly: true InvoiceSortField: type: string enum: - INVOICE_SORT_DATE x-enum-elements: - name: INVOICE_SORT_DATE description: 'The field works as follows: - If the invoice is a draft, it uses the invoice `created_at` date. - If the invoice is scheduled for publication, it uses the `scheduled_at` date. - If the invoice is published, it uses the invoice publication date.' description: The field to use for sorting. x-release-status: PUBLIC CancelInvoiceResponse: type: object description: The response returned by the `CancelInvoice` request. x-release-status: PUBLIC properties: invoice: $ref: '#/components/schemas/Invoice' description: The canceled invoice. errors: type: array items: $ref: '#/components/schemas/Error' description: Information about errors encountered during the request. example: invoice: accepted_payment_methods: bank_account: false buy_now_pay_later: false card: true cash_app_pay: false square_gift_card: false created_at: '2020-06-18T17:45:13Z' custom_fields: - label: Event Reference Number placement: ABOVE_LINE_ITEMS value: 'Ref. #1234' - label: Terms of Service placement: BELOW_LINE_ITEMS value: The terms of service are... delivery_method: EMAIL description: We appreciate your business! id: inv:0-ChCHu2mZEabLeeHahQnXDjZQECY invoice_number: inv-100 location_id: ES0RJRZYEC39A order_id: CAISENgvlJ6jLWAzERDzjyHVybY payment_requests: - automatic_payment_source: NONE computed_amount_money: amount: 10000 currency: USD due_date: '2030-01-24' reminders: - message: Your invoice is due tomorrow relative_scheduled_days: -1 status: PENDING uid: beebd363-e47f-4075-8785-c235aaa7df11 request_type: BALANCE tipping_enabled: true total_completed_amount_money: amount: 0 currency: USD uid: 2da7964f-f3d2-4f43-81e8-5aa220bf3355 primary_recipient: customer_id: JDKYHBWT1D4F8MFH63DBMEN8Y4 email_address: Amelia.Earhart@example.com family_name: Earhart given_name: Amelia phone_number: 1-212-555-4240 sale_or_service_date: '2030-01-24' scheduled_at: '2030-01-13T10:00:00Z' status: CANCELED store_payment_method_enabled: false timezone: America/Los_Angeles title: Event Planning Services updated_at: '2020-06-18T18:23:11Z' version: 1 InvoiceAcceptedPaymentMethods: type: object description: The payment methods that customers can use to pay an [invoice](entity:Invoice) on the Square-hosted invoice payment page. x-release-status: PUBLIC properties: card: type: boolean description: Indicates whether credit card or debit card payments are accepted. The default value is `false`. nullable: true square_gift_card: type: boolean description: Indicates whether Square gift card payments are accepted. The default value is `false`. nullable: true bank_account: type: boolean description: Indicates whether ACH bank transfer payments are accepted. The default value is `false`. nullable: true buy_now_pay_later: type: boolean description: 'Indicates whether Afterpay (also known as Clearpay) payments are accepted. The default value is `false`. This option is allowed only for invoices that have a single payment request of the `BALANCE` type. This payment method is supported if the seller account accepts Afterpay payments and the seller location is in a country where Afterpay invoice payments are supported. As a best practice, consider enabling an additional payment method when allowing `buy_now_pay_later` payments. For more information, including detailed requirements and processing limits, see [Buy Now Pay Later payments with Afterpay](https://developer.squareup.com/docs/invoices-api/overview#buy-now-pay-later).' nullable: true cash_app_pay: type: boolean description: 'Indicates whether Cash App payments are accepted. The default value is `false`. This payment method is supported only for seller [locations](entity:Location) in the United States.' nullable: true SearchInvoicesRequest: type: object description: Describes a `SearchInvoices` request. x-release-status: PUBLIC required: - query properties: query: $ref: '#/components/schemas/InvoiceQuery' description: Describes the query criteria for searching invoices. limit: type: integer description: "The maximum number of invoices to return (200 is the maximum `limit`). \nIf not provided, the server uses a default limit of 100 invoices." cursor: type: string description: "A pagination cursor returned by a previous call to this endpoint. \nProvide this cursor to retrieve the next set of results for your original query.\n\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)." example: query: filter: customer_ids: - JDKYHBWT1D4F8MFH63DBMEN8Y4 location_ids: - ES0RJRZYEC39A limit: 100 sort: field: INVOICE_SORT_DATE order: DESC CreateInvoiceAttachmentResponse: type: object description: Represents a [CreateInvoiceAttachment](api-endpoint:Invoices-CreateInvoiceAttachment) response. x-release-status: PUBLIC properties: attachment: $ref: '#/components/schemas/InvoiceAttachment' description: Metadata about the attachment that was added to the invoice. errors: type: array items: $ref: '#/components/schemas/Error' description: Information about errors encountered during the request. example: attachment: description: Service contract filename: file.jpg filesize: 102705 hash: 273ee02cb6f5f8a3a8ca23604930dd53 id: inva:0-3bB9ZuDHiziThQhuC4fwWt mime_type: image/jpeg uploaded_at: '2023-02-03T20:28:14Z' PublishInvoiceResponse: type: object description: Describes a `PublishInvoice` response. x-release-status: PUBLIC properties: invoice: $ref: '#/components/schemas/Invoice' description: The published invoice. errors: type: array items: $ref: '#/components/schemas/Error' description: Information about errors encountered during the request. example: invoice: accepted_payment_methods: bank_account: false buy_now_pay_later: false card: true cash_app_pay: false square_gift_card: false created_at: '2020-06-18T17:45:13Z' custom_fields: - label: Event Reference Number placement: ABOVE_LINE_ITEMS value: 'Ref. #1234' - label: Terms of Service placement: BELOW_LINE_ITEMS value: The terms of service are... delivery_method: EMAIL description: We appreciate your business! id: inv:0-ChCHu2mZEabLeeHahQnXDjZQECY invoice_number: inv-100 location_id: ES0RJRZYEC39A order_id: CAISENgvlJ6jLWAzERDzjyHVybY payment_requests: - automatic_payment_source: NONE computed_amount_money: amount: 10000 currency: USD due_date: '2030-01-24' reminders: - message: Your invoice is due tomorrow relative_scheduled_days: -1 status: PENDING uid: beebd363-e47f-4075-8785-c235aaa7df11 request_type: BALANCE tipping_enabled: true total_completed_amount_money: amount: 0 currency: USD uid: 2da7964f-f3d2-4f43-81e8-5aa220bf3355 primary_recipient: customer_id: JDKYHBWT1D4F8MFH63DBMEN8Y4 email_address: Amelia.Earhart@example.com family_name: Earhart given_name: Amelia phone_number: 1-212-555-4240 public_url: https://squareup.com/pay-invoice/inv:0-ChCHu2mZEabLeeHahQnXDjZQECY sale_or_service_date: '2030-01-24' scheduled_at: '2030-01-13T10:00:00Z' status: SCHEDULED store_payment_method_enabled: false timezone: America/Los_Angeles title: Event Planning Services updated_at: '2020-06-18T18:23:11Z' version: 1 InvoicePaymentReminderStatus: type: string enum: - PENDING - NOT_APPLICABLE - SENT x-enum-elements: - name: PENDING description: The reminder will be sent on the `relative_scheduled_date` (if the invoice is published). - name: NOT_APPLICABLE description: 'The reminder is not applicable and is not sent. The following are examples of when reminders are not applicable and are not sent: - You schedule a reminder to be sent before the invoice is published. - The invoice is configured with multiple payment requests and a payment request reminder is configured to be sent after the next payment request `due_date`. - Two reminders (for different payment requests) are configured to be sent on the same date. Therefore, only one reminder is sent. - You configure a reminder to be sent on the date that the invoice is scheduled to be sent. - The payment request is already paid. - The invoice status is `CANCELED` or `FAILED`.' - name: SENT description: The reminder is sent. description: The status of a payment request reminder. x-release-status: PUBLIC UpdateInvoiceRequest: type: object description: Describes a `UpdateInvoice` request. x-release-status: PUBLIC required: - invoice properties: invoice: $ref: '#/components/schemas/Invoice' description: 'The invoice fields to add, change, or clear. Fields can be cleared using null values or the `remove` field (for individual payment requests or reminders). The current invoice `version` is also required. For more information, including requirements, limitations, and more examples, see [Update an Invoice](https://developer.squareup.com/docs/invoices-api/update-invoices).' idempotency_key: type: string description: 'A unique string that identifies the `UpdateInvoice` request. If you do not provide `idempotency_key` (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/build-basics/common-api-patterns/idempotency).' maxLength: 128 nullable: true fields_to_clear: type: array items: type: string description: 'The list of fields to clear. Although this field is currently supported, we recommend using null values or the `remove` field when possible. For examples, see [Update an Invoice](https://developer.squareup.com/docs/invoices-api/update-invoices).' nullable: true example: idempotency_key: 4ee82288-0910-499e-ab4c-5d0071dad1be invoice: payment_requests: - reminders: null tipping_enabled: false uid: 2da7964f-f3d2-4f43-81e8-5aa220bf3355 version: 1 InvoiceQuery: type: object description: Describes query criteria for searching invoices. x-release-status: PUBLIC required: - filter properties: filter: $ref: '#/components/schemas/InvoiceFilter' description: "Query filters to apply in searching invoices. \nFor more information, see [Search for invoices](https://developer.squareup.com/docs/invoices-api/retrieve-list-search-invoices#search-invoices)." sort: $ref: '#/components/schemas/InvoiceSort' description: Describes the sort order for the search result. nullable: true InvoiceSort: type: object description: Identifies the sort field and sort order. x-release-status: PUBLIC required: - field properties: field: $ref: '#/components/schemas/InvoiceSortField' description: 'The field to use for sorting. See [InvoiceSortField](#type-invoicesortfield) for possible values' order: $ref: '#/components/schemas/SortOrder' description: 'The order to use for sorting the results. See [SortOrder](#type-sortorder) for possible values' nullable: true 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.' InvoiceFilter: type: object description: Describes query filters to apply. x-release-status: PUBLIC required: - location_ids properties: location_ids: type: array items: type: string description: "Limits the search to the specified locations. A location is required. \nIn the current implementation, only one location can be specified." customer_ids: type: array items: type: string description: "Limits the search to the specified customers, within the specified locations. \nSpecifying a customer is optional. In the current implementation, \na maximum of one customer can be specified." nullable: true CreateInvoiceResponse: type: object description: The response returned by the `CreateInvoice` request. x-release-status: PUBLIC properties: invoice: $ref: '#/components/schemas/Invoice' description: The newly created invoice. errors: type: array items: $ref: '#/components/schemas/Error' description: Information about errors encountered during the request. example: invoice: accepted_payment_methods: bank_account: false buy_now_pay_later: false card: true cash_app_pay: false square_gift_card: false created_at: '2020-06-18T17:45:13Z' custom_fields: - label: Event Reference Number placement: ABOVE_LINE_ITEMS value: 'Ref. #1234' - label: Terms of Service placement: BELOW_LINE_ITEMS value: The terms of service are... delivery_method: EMAIL description: We appreciate your business! id: inv:0-ChCHu2mZEabLeeHahQnXDjZQECY invoice_number: inv-100 location_id: ES0RJRZYEC39A order_id: CAISENgvlJ6jLWAzERDzjyHVybY payment_requests: - automatic_payment_source: NONE computed_amount_money: amount: 10000 currency: USD due_date: '2030-01-24' reminders: - message: Your invoice is due tomorrow relative_scheduled_days: -1 status: PENDING uid: beebd363-e47f-4075-8785-c235aaa7df11 request_type: BALANCE tipping_enabled: true total_completed_amount_money: amount: 0 currency: USD uid: 2da7964f-f3d2-4f43-81e8-5aa220bf3355 primary_recipient: customer_id: JDKYHBWT1D4F8MFH63DBMEN8Y4 email_address: Amelia.Earhart@example.com family_name: Earhart given_name: Amelia phone_number: 1-212-555-4240 sale_or_service_date: '2030-01-24' scheduled_at: '2030-01-13T10:00:00Z' status: DRAFT store_payment_method_enabled: false timezone: America/Los_Angeles title: Event Planning Services updated_at: '2020-06-18T17:45:13Z' version: 0 CreateInvoiceRequest: type: object description: Describes a `CreateInvoice` request. x-release-status: PUBLIC required: - invoice properties: invoice: $ref: '#/components/schemas/Invoice' description: The invoice to create. idempotency_key: type: string description: "A unique string that identifies the `CreateInvoice` request. If you do not \nprovide `idempotency_key` (or provide an empty string as the value), the endpoint \ntreats each request as independent.\n\nFor more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)." maxLength: 128 example: idempotency_key: ce3748f9-5fc1-4762-aa12-aae5e843f1f4 invoice: accepted_payment_methods: bank_account: false buy_now_pay_later: false card: true cash_app_pay: false square_gift_card: false custom_fields: - label: Event Reference Number placement: ABOVE_LINE_ITEMS value: 'Ref. #1234' - label: Terms of Service placement: BELOW_LINE_ITEMS value: The terms of service are... delivery_method: EMAIL description: We appreciate your business! invoice_number: inv-100 location_id: ES0RJRZYEC39A order_id: CAISENgvlJ6jLWAzERDzjyHVybY payment_requests: - automatic_payment_source: NONE due_date: '2030-01-24' reminders: - message: Your invoice is due tomorrow relative_scheduled_days: -1 request_type: BALANCE tipping_enabled: true primary_recipient: customer_id: JDKYHBWT1D4F8MFH63DBMEN8Y4 sale_or_service_date: '2030-01-24' scheduled_at: '2030-01-13T10:00:00Z' store_payment_method_enabled: false title: Event Planning Services InvoiceRecipientTaxIds: type: object description: "Represents the tax IDs for an invoice recipient. The country of the seller account determines \nwhether the corresponding `tax_ids` field is available for the customer. For more information, \nsee [Invoice recipient tax IDs](https://developer.squareup.com/docs/invoices-api/overview#recipient-tax-ids)." x-release-status: PUBLIC properties: eu_vat: type: string description: The EU VAT identification number for the invoice recipient. For example, `IE3426675K`. readOnly: true CancelInvoiceRequest: type: object description: Describes a `CancelInvoice` request. x-release-status: PUBLIC required: - version properties: version: type: integer description: "The version of the [invoice](entity:Invoice) to cancel.\nIf you do not know the version, you can call \n[GetInvoice](api-endpoint:Invoices-GetInvoice) or [ListInvoices](api-endpoint:Invoices-ListInvoices)." example: version: 0 CreateInvoiceAttachmentRequest: type: object description: Represents a [CreateInvoiceAttachment](api-endpoint:Invoices-CreateInvoiceAttachment) request. x-release-status: PUBLIC properties: idempotency_key: type: string description: 'A unique string that identifies the `CreateInvoiceAttachment` request. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).' maxLength: 128 description: type: string description: The description of the attachment to display on the invoice. maxLength: 128 example: description: Service contract idempotency_key: ae5e84f9-4742-4fc1-ba12-a3ce3748f1c3 SortOrder: type: string enum: - DESC - ASC x-enum-elements: - name: DESC description: The results are returned in descending (e.g., newest-first or Z-A) order. - name: ASC description: The results are returned in ascending (e.g., oldest-first or A-Z) order. description: The order (e.g., chronological or alphabetical) in which results from a request are returned. x-release-status: PUBLIC InvoiceCustomField: type: object description: "An additional seller-defined and customer-facing field to include on the invoice. For more information, \nsee [Custom fields](https://developer.squareup.com/docs/invoices-api/overview#custom-fields).\n\nAdding custom fields to an invoice requires an \n[Invoices Plus subscription](https://developer.squareup.com/docs/invoices-api/overview#invoices-plus-subscription)." x-release-status: PUBLIC properties: label: type: string description: The label or title of the custom field. This field is required for a custom field. maxLength: 30 nullable: true value: type: string description: The text of the custom field. If omitted, only the label is rendered. maxLength: 2000 nullable: true placement: $ref: '#/components/schemas/InvoiceCustomFieldPlacement' description: 'The location of the custom field on the invoice. This field is required for a custom field. See [InvoiceCustomFieldPlacement](#type-invoicecustomfieldplacement) for possible values' nullable: true UpdateInvoiceResponse: type: object description: Describes a `UpdateInvoice` response. x-release-status: PUBLIC properties: invoice: $ref: '#/components/schemas/Invoice' description: The updated invoice. errors: type: array items: $ref: '#/components/schemas/Error' description: Information about errors encountered during the request. example: invoice: accepted_payment_methods: bank_account: false buy_now_pay_later: false card: true cash_app_pay: false square_gift_card: false created_at: '2020-06-18T17:45:13Z' custom_fields: - label: Event Reference Number placement: ABOVE_LINE_ITEMS value: 'Ref. #1234' - label: Terms of Service placement: BELOW_LINE_ITEMS value: The terms of service are... delivery_method: EMAIL description: We appreciate your business! id: inv:0-ChCHu2mZEabLeeHahQnXDjZQECY invoice_number: inv-100 location_id: ES0RJRZYEC39A next_payment_amount_money: amount: 10000 currency: USD order_id: CAISENgvlJ6jLWAzERDzjyHVybY payment_requests: - automatic_payment_source: NONE computed_amount_money: amount: 10000 currency: USD due_date: '2030-01-24' request_type: BALANCE tipping_enabled: false total_completed_amount_money: amount: 0 currency: USD uid: 2da7964f-f3d2-4f43-81e8-5aa220bf3355 primary_recipient: customer_id: JDKYHBWT1D4F8MFH63DBMEN8Y4 email_address: Amelia.Earhart@example.com family_name: Earhart given_name: Amelia phone_number: 1-212-555-4240 sale_or_service_date: '2030-01-24' scheduled_at: '2030-01-13T10:00:00Z' status: UNPAID store_payment_method_enabled: false timezone: America/Los_Angeles title: Event Planning Services updated_at: '2020-06-18T18:23:11Z' version: 2 DeleteInvoiceResponse: type: object description: Describes a `DeleteInvoice` response. x-release-status: PUBLIC properties: errors: type: array items: $ref: '#/components/schemas/Error' description: Information about errors encountered during the request. example: {} InvoiceRecipient: type: object description: "Represents a snapshot of customer data. This object stores customer data that is displayed on the invoice \nand that Square uses to deliver the invoice.\n\nWhen you provide a customer ID for a draft invoice, Square retrieves the associated customer profile and populates \nthe remaining `InvoiceRecipient` fields. You cannot update these fields after the invoice is published. \nSquare updates the customer ID in response to a merge operation, but does not update other fields." x-release-status: PUBLIC properties: customer_id: type: string description: "The ID of the customer. This is the customer profile ID that \nyou provide when creating a draft invoice." minLength: 1 maxLength: 255 nullable: true given_name: type: string description: The recipient's given (that is, first) name. readOnly: true family_name: type: string description: The recipient's family (that is, last) name. readOnly: true email_address: type: string description: The recipient's email address. readOnly: true address: $ref: '#/components/schemas/Address' description: The recipient's physical address. readOnly: true phone_number: type: string description: The recipient's phone number. readOnly: true company_name: type: string description: The name of the recipient's company. readOnly: true tax_ids: $ref: '#/components/schemas/InvoiceRecipientTaxIds' description: "The recipient's tax IDs. The country of the seller account determines whether this field \nis available for the customer. For more information, see [Invoice recipient tax IDs](https://developer.squareup.com/docs/invoices-api/overview#recipient-tax-ids)." readOnly: true InvoicePaymentReminder: type: object description: 'Describes a payment request reminder (automatic notification) that Square sends to the customer. You configure a reminder relative to the payment request `due_date`.' x-release-status: PUBLIC properties: uid: type: string description: 'A Square-assigned ID that uniquely identifies the reminder within the `InvoicePaymentRequest`.' readOnly: true relative_scheduled_days: type: integer description: 'The number of days before (a negative number) or after (a positive number) the payment request `due_date` when the reminder is sent. For example, -3 indicates that the reminder should be sent 3 days before the payment request `due_date`.' minimum: -32767 maximum: 32767 nullable: true message: type: string description: The reminder message. minLength: 1 maxLength: 1000 nullable: true status: $ref: '#/components/schemas/InvoicePaymentReminderStatus' description: 'The status of the reminder. See [InvoicePaymentReminderStatus](#type-invoicepaymentreminderstatus) for possible values' readOnly: true sent_at: type: string description: If sent, the timestamp when the reminder was sent, in RFC 3339 format. readOnly: true InvoiceRequestType: type: string enum: - BALANCE - DEPOSIT - INSTALLMENT x-enum-elements: - name: BALANCE description: "A request for a balance payment. The balance amount is computed as follows: \n\n- If the invoice specifies only a balance payment request, the balance amount is the \ntotal amount of the associated order. \n- If the invoice also specifies a deposit request, the balance amount is the amount \nremaining after the deposit.\n\n`INSTALLMENT` and `BALANCE` payment requests are not allowed in the same invoice." - name: DEPOSIT description: "A request for a deposit payment. You have the option of specifying \nan exact amount or a percentage of the total order amount. If you request a deposit, \nit must be due before any other payment requests." - name: INSTALLMENT description: "A request for an installment payment. Installments allow buyers to pay the invoice over time. Installments can optionally be combined with a deposit. \n\nAdding `INSTALLMENT` payment requests to an invoice requires an \n[Invoices Plus subscription](https://developer.squareup.com/docs/invoices-api/overview#invoices-plus-subscription)." description: "Indicates the type of the payment request. For more information, see \n[Configuring payment requests](https://developer.squareup.com/docs/invoices-api/create-publish-invoices#payment-requests)." x-release-status: PUBLIC SearchInvoicesResponse: type: object description: Describes a `SearchInvoices` response. x-release-status: PUBLIC properties: invoices: type: array items: $ref: '#/components/schemas/Invoice' description: The list of invoices returned by the search. cursor: type: string description: "When a response is truncated, it includes a cursor that you can use in a \nsubsequent request to fetch the next set of invoices. If empty, this is the final \nresponse. \nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)." errors: type: array items: $ref: '#/components/schemas/Error' description: Information about errors encountered during the request. example: cursor: ChoIDhIWVm54ZVRhLXhySFBOejBBM2xJb2daUQoFCI4IGAE invoices: - accepted_payment_methods: bank_account: false buy_now_pay_later: false card: true cash_app_pay: false square_gift_card: false created_at: '2020-06-18T17:45:13Z' custom_fields: - label: Event Reference Number placement: ABOVE_LINE_ITEMS value: 'Ref. #1234' - label: Terms of Service placement: BELOW_LINE_ITEMS value: The terms of service are... delivery_method: EMAIL description: We appreciate your business! id: inv:0-ChCHu2mZEabLeeHahQnXDjZQECY invoice_number: inv-100 location_id: ES0RJRZYEC39A order_id: CAISENgvlJ6jLWAzERDzjyHVybY payment_requests: - automatic_payment_source: NONE computed_amount_money: amount: 10000 currency: USD due_date: '2030-01-24' reminders: - message: Your invoice is due tomorrow relative_scheduled_days: -1 status: PENDING uid: beebd363-e47f-4075-8785-c235aaa7df11 request_type: BALANCE tipping_enabled: true total_completed_amount_money: amount: 0 currency: USD uid: 2da7964f-f3d2-4f43-81e8-5aa220bf3355 primary_recipient: customer_id: JDKYHBWT1D4F8MFH63DBMEN8Y4 email_address: Amelia.Earhart@example.com family_name: Earhart given_name: Amelia phone_number: 1-212-555-4240 sale_or_service_date: '2030-01-24' scheduled_at: '2030-01-13T10:00:00Z' status: DRAFT store_payment_method_enabled: false timezone: America/Los_Angeles title: Event Planning Services updated_at: '2020-06-18T17:45:13Z' version: 0 - accepted_payment_methods: bank_account: false buy_now_pay_later: false card: true cash_app_pay: false square_gift_card: true created_at: '2021-01-23T15:29:12Z' delivery_method: EMAIL id: inv:0-ChC366qAfskpGrBI_1bozs9mEA3 invoice_number: inv-455 location_id: ES0RJRZYEC39A next_payment_amount_money: amount: 3000 currency: USD order_id: a65jnS8NXbfprvGJzY9F4fQTuaB payment_requests: - automatic_payment_source: CARD_ON_FILE card_id: ccof:IkWfpLj4tNHMyFii3GB computed_amount_money: amount: 1000 currency: USD due_date: '2021-01-23' percentage_requested: '25' request_type: DEPOSIT tipping_enabled: false total_completed_amount_money: amount: 1000 currency: USD uid: 66c3bdfd-5090-4ff9-a8a0-c1e1a2ffa176 - automatic_payment_source: CARD_ON_FILE card_id: ccof:IkWfpLj4tNHMyFii3GB computed_amount_money: amount: 3000 currency: USD due_date: '2021-06-15' request_type: BALANCE tipping_enabled: false total_completed_amount_money: amount: 0 currency: USD uid: 120c5e18-4f80-4f6b-b159-774cb9bf8f99 primary_recipient: customer_id: JDKYHBWT1D4F8MFH63DBMEN8Y4 email_address: Amelia.Earhart@example.com family_name: Earhart given_name: Amelia phone_number: 1-212-555-4240 public_url: https://squareup.com/pay-invoice/h9sfsfTGTSnYEhISUDBhEQ sale_or_service_date: '2030-01-24' status: PARTIALLY_PAID store_payment_method_enabled: false timezone: America/Los_Angeles updated_at: '2021-01-23T15:29:56Z' version: 3 DeleteInvoiceAttachmentResponse: type: object description: Represents a [DeleteInvoiceAttachment](api-endpoint:Invoices-DeleteInvoiceAttachment) response. x-release-status: PUBLIC properties: errors: type: array items: $ref: '#/components/schemas/Error' description: Information about errors encountered during the request. example: {} 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">