{ "swagger": "2.0", "info": { "version": "2.0", "title": "Square Connect API", "description": "Client library for accessing the Square Connect APIs", "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/" }, "host": "connect.squareup.com", "schemes": [ "https" ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "securityDefinitions": { "oauth2": { "type": "oauth2", "authorizationUrl": "https://connect.squareup.com/oauth2/authorize", "flow": "accessCode", "tokenUrl": "https://connect.squareup.com/oauth2/token", "scopes": { "BANK_ACCOUNTS_READ": "__HTTP Method__: `GET`\n\nGrants read access to bank account information associated with the targeted\nSquare account. For example, to call the Connect v1 ListBankAccounts endpoint.", "CASH_DRAWER_READ": "__HTTP Method__: `GET`\n\nGrants read access to cash drawer shift information. For example, to call the\nListCashDrawerShifts endpoint.", "CUSTOMERS_READ": "__HTTP Method__: `GET`\n\nGrants read access to customer information. For example, to call the\nListCustomers endpoint.", "CUSTOMERS_WRITE": "__HTTP Method__: `POST`, `PUT`, `DELETE`\n\nGrants write access to customer information. For example, to create and update\ncustomer profiles.", "DEVICE_CREDENTIAL_MANAGEMENT": "__HTTP Method__: `POST`, `GET`\n\nGrants read/write access to device credentials information. For example, to\ncall the CreateDeviceCode endpoint.", "EMPLOYEES_READ": "__HTTP Method__: `GET`\n\nGrants read access to employee profile information. For example, to call the\nConnect v1 Employees API.", "EMPLOYEES_WRITE": "__HTTP Method__: `POST`, `PUT`, `DELETE`\n\nGrants write access to employee profile information. For example, to create\nand modify employee profiles.", "INVENTORY_READ": "__HTTP Method__: `GET`\n\nGrants read access to inventory information. For example, to call the\nRetrieveInventoryCount endpoint.", "INVENTORY_WRITE": "__HTTP Method__: `POST`, `PUT`, `DELETE`\n\nGrants write access to inventory information. For example, to call the\nBatchChangeInventory endpoint.", "ITEMS_READ": "__HTTP Method__: `GET`\n\nGrants read access to product catalog information. For example, to obtain objects in a product catalog.", "ITEMS_WRITE": "__HTTP Method__: `POST`, `PUT`, `DELETE`\n\nGrants write access to product catalog information. For example, to modify or\nadd to a product catalog.", "LOYALTY_READ": "__HTTP Method__: `GET`\n\nGrants read access to loyalty information. For example, to call the\nListLoyaltyPrograms endpoint.", "LOYALTY_WRITE": "__HTTP Method__: `POST`, `PUT`, `DELETE`\n\nGrants write access to loyalty information. For example, to call the\nCreateLoyaltyAccount endpoint.", "MERCHANT_PROFILE_READ": "__HTTP Method__: `GET`\n\nGrants read access to business and location information. For example, to\nobtain a location ID for subsequent activity.", "ORDERS_READ": "__HTTP Method__: `GET`\n\nGrants read access to order information. For example, to call the\nBatchRetrieveOrders endpoint.", "ORDERS_WRITE": "__HTTP Method__: `POST`, `PUT`, `DELETE`\n\nGrants write access to order information. For example, to call the\nCreateCheckout endpoint.", "PAYMENTS_READ": "__HTTP Method__: `GET`\n\nGrants read access to transaction and refund information. For example, to call\nthe RetrieveTransaction endpoint.", "PAYMENTS_WRITE": "__HTTP Method__: `POST`, `PUT`, `DELETE`\n\nGrants write access to transaction and refunds information. For example, to\nprocess payments with the Payments or Checkout API.", "PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS": "__HTTP Method__: `POST`, `PUT`, `DELETE`\n\nAllow third party applications to deduct a portion of each transaction amount.\n__Required__ to use multiparty transaction functionality with the Payments\nAPI.", "PAYMENTS_WRITE_IN_PERSON": "__HTTP Method__: `POST`, `PUT`, `DELETE`\n\nGrants write access to payments and refunds information. For example, to\nprocess in-person payments.", "SETTLEMENTS_READ": "__HTTP Method__: `GET`\n\nGrants read access to settlement (deposit) information. For example, to call\nthe Connect v1 ListSettlements endpoint.", "TIMECARDS_READ": "__HTTP Method__: `GET`\n\nGrants read access to employee timecard information. For example, to call the\nConnect v2 SearchShifts endpoint.", "TIMECARDS_WRITE": "__HTTP Method__: `POST`, `PUT`, `DELETE`\n\nGrants write access to employee shift information. For example, to create\nand modify employee shifts.", "TIMECARDS_SETTINGS_READ": "__HTTP Method__: `GET`\n\nGrants read access to employee timecard settings information. For example, to\ncall the GetBreakType endpoint.", "TIMECARDS_SETTINGS_WRITE": "__HTTP Method__: `POST`, `PUT`, `DELETE`\n\nGrants write access to employee timecard settings information. For example, to\ncall the UpdateBreakType endpoint.", "APPOINTMENTS_READ": "__HTTP Method__: `GET`, `POST`\n\nGrants read access to booking information. For example, to call the\nRetrieveBooking endpoint.", "APPOINTMENTS_WRITE": "__HTTP Method__: `POST`, `PUT`, `DELETE`\n\nGrants write access to booking information. For example, to call the CreateBooking endpoint.", "APPOINTMENTS_BUSINESS_SETTINGS_READ": "__HTTP Method__: `GET`\n\nGrants read access to booking business settings. For example, to call the\nListTeamMemberBookingProfiles endpoint.", "INVOICES_READ": "__HTTP Method__: `GET`, `POST`\n\nGrants read access to invoice information. For example, to call the ListInvoices endpoint.", "INVOICES_WRITE": "__HTTP Method__: `POST`, `PUT`, `DELETE`\n\nGrants write access to invoice information. For example, to call the CreateInvoice endpoint.", "SUBSCRIPTIONS_READ": "__HTTP Method__: `GET`, `POST`\n\nGrants read access to subscription information. For example, to call the RetrieveSubscription\nendpoint.", "SUBSCRIPTIONS_WRITE": "__HTTP Method__: `POST`, `PUT`, `DELETE`\n\nGrants write access to subscription information. For example, to call the CreateSubscription\nendpoint.", "DISPUTES_READ": "__HTTP Method__: `GET`\n\nGrants read access to dispute information. For example, to call the RetrieveDispute\nendpoint.", "DISPUTES_WRITE": "__HTTP Method__: `POST`, `PUT`, `DELETE`\n\nGrants write access to dispute information. For example, to call the SubmitEvidence\nendpoint.", "GIFTCARDS_READ": "__HTTP Method__: `GET`, `POST`\n\nGrants read access to gift card information. For example, to call the RetrieveGiftCard\nendpoint.", "GIFTCARDS_WRITE": "__HTTP Method__: `POST`, `PUT`, `DELETE`\n\nGrants write access to gift card information. For example, to call the CreateGiftCard\nendpoint.", "ONLINE_STORE_SNIPPETS_WRITE": "__HTTP Method__: `POST`, `PUT`, `DELETE`\n\nWrite access to ECOM online store snippets on published websites.", "ONLINE_STORE_SNIPPETS_READ": "__HTTP Method__: `GET`, `POST`\n\nRead access to ECOM online store snippets on published websites.", "ONLINE_STORE_SITE_READ": "__HTTP Method__: `GET`, `POST`\n\nRead access to ECOM online store site details.", "PAYMENTS_WRITE_SHARED_ONFILE": "__HTTP Method__: `POST`, `PUT`, `DELETE`\n\nAllows the developer to process payments on behalf of a seller using a shared on file payment method.", "APPOINTMENTS_ALL_READ": "__HTTP Method__: `GET`, `POST`\n\nGrants read access to all of a seller\u0027s booking information, calendar, and business details.\nThis permission must be accompanied by the `APPOINTMENTS_READ` permission.", "APPOINTMENTS_ALL_WRITE": "__HTTP Method__: `POST`, `PUT`, `DELETE`\n\nGrants write access to all booking details, including double-booking a seller.\nThis permission must be accompanied by the `APPOINTMENTS_WRITE` permission.", "MERCHANT_PROFILE_WRITE": "__HTTP Method__: `POST`, `PUT`\n\nGrants write access to business and location information. For example, to create a new location or\nupdate the business hours at an existing location.", "VENDOR_READ": "__HTTP Method__: `GET`, `POST`\n\nGrants read access to vendor information, for example, when calling the\n`RetrieveVendor` endpoint.", "VENDOR_WRITE": "__HTTP Method__: `POST`, `PUT`, `DELETE`\n\nGrants write access to vendor information, for example, when calling the\n`BulkUpdateVendors` endpoint.", "PAYOUTS_READ": "__HTTP Method__: `GET`\n\nGrants read access to payouts and payout entries information. For example,\nto call the Connect v2 `ListPayouts` endpoint.", "RESERVATIONS_READ": "__HTTP Method__: `GET`\n\nGrants read access to reservation information, for example, when calling the\n`RetrieveReservation` endpoint.", "RESERVATIONS_WRITE": "__HTTP Method__: `POST`, `PUT`, `DELETE`\n\nGrants write access to reservation information, for example, when calling the\n`CreateReservation` endpoint.", "RESTAURANT_CHECKS_READ": "__HTTP Method__: `GET`\n\nGrants read access to check information, for example, when calling the\n`RetrieveCheck` endpoint.", "DEVICES_READ": "__HTTP Method__: `GET`\n\nGrants read access to device information. For example, to\ncall the `GetDevice` and `ListDevices` endpoints.", "CHANNELS_READ": "__HTTP Method__: `GET`\n\nGrants read access to view channels, for example, when calling the\n`RetrieveChannel` endpoint.", "CHANNELS_CREATE": "__HTTP Method__: `POST`\n\nGrants write access to create channels, for example, when calling the\n`CreateChannel` endpoint.", "CHANNELS_UPDATE": "__HTTP Method__: `PUT`\n\nGrants write access to update channels, for example, when calling the\n`UpdateChannel` endpoint.", "ADDON_CONFIGURATIONS_READ": "__HTTP Method__: `GET`\n\nGrants 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`\n\nGrants write access for third-party Add-ons to store configurations of their Add-ons, for example, when calling `CreateConfiguration` endpoint.", "PERMISSION_SETS_READ": "__HTTP Method__: `GET`\n\nGrants read access to Permission Sets. For example, to\ncall the `ListPermissionSets` and `RetrievePermissionSet` endpoints.", "PERMISSION_SETS_WRITE": "__HTTP Method__: `PUT`\n\nGrants write access to Permission Sets." } }, "oauth2ClientSecret": { "type": "apiKey", "in": "header", "name": "Authorization" } }, "paths": { "/mobile/authorization-code": { "post": { "tags": [ "MobileAuthorization" ], "summary": "CreateMobileAuthorizationCode", "operationId": "CreateMobileAuthorizationCode", "description": "Generates code to authorize a mobile application to connect to a Square card reader.\n\nAuthorization codes are one-time-use codes and expire 60 minutes after being issued.\n\n__Important:__ The `Authorization` header you provide to this endpoint must have the following format:\n\n```\nAuthorization: Bearer ACCESS_TOKEN\n```\n\nReplace `ACCESS_TOKEN` with a\n[valid production authorization credential](https://developer.squareup.com/docs/build-basics/access-tokens).", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "PAYMENTS_WRITE_IN_PERSON" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "PAYMENTS_WRITE_IN_PERSON" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CreateMobileAuthorizationCodeRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CreateMobileAuthorizationCodeResponse" } } } } }, "/oauth2/revoke": { "post": { "tags": [ "OAuth" ], "summary": "RevokeToken", "operationId": "RevokeToken", "description": "Revokes an access token generated with the OAuth flow.\n\nIf an account has more than one OAuth access token for your application, this\nendpoint revokes all of them, regardless of which token you specify. \n\n__Important:__ The `Authorization` header for this endpoint must have the\nfollowing format:\n\n```\nAuthorization: Client APPLICATION_SECRET\n```\n\nReplace `APPLICATION_SECRET` with the application secret on the **OAuth**\npage for your application in the Developer Dashboard.", "x-release-status": "PUBLIC", "x-sq-version": "2024-10-17", "security": [ { "oauth2ClientSecret": [] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/RevokeTokenRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RevokeTokenResponse" } } } } }, "/oauth2/token": { "post": { "tags": [ "OAuth" ], "summary": "ObtainToken", "operationId": "ObtainToken", "description": "Returns an OAuth access token and a refresh token unless the \n`short_lived` parameter is set to `true`, in which case the endpoint \nreturns only an access token.\n\nThe `grant_type` parameter specifies the type of OAuth request. If \n`grant_type` is `authorization_code`, you must include the authorization \ncode you received when a seller granted you authorization. If `grant_type` \nis `refresh_token`, you must provide a valid refresh token. If you\u0027re using \nan old version of the Square APIs (prior to March 13, 2019), `grant_type` \ncan be `migration_token` and you must provide a valid migration token.\n\nYou can use the `scopes` parameter to limit the set of permissions granted \nto the access token and refresh token. You can use the `short_lived` parameter \nto create an access token that expires in 24 hours.\n\n__Note:__ OAuth tokens should be encrypted and stored on a secure server. \nApplication clients should never interact directly with OAuth tokens.", "x-release-status": "PUBLIC", "x-sq-version": "2024-10-17", "security": [], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/ObtainTokenRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ObtainTokenResponse" } } } } }, "/oauth2/token/status": { "post": { "tags": [ "OAuth" ], "summary": "RetrieveTokenStatus", "operationId": "RetrieveTokenStatus", "description": "Returns information about an [OAuth access token](https://developer.squareup.com/docs/build-basics/access-tokens#get-an-oauth-access-token) or an application’s [personal access token](https://developer.squareup.com/docs/build-basics/access-tokens#get-a-personal-access-token).\n\nAdd the access token to the Authorization header of the request.\n\n__Important:__ The `Authorization` header you provide to this endpoint must have the following format:\n\n```\nAuthorization: Bearer ACCESS_TOKEN\n```\n\nwhere `ACCESS_TOKEN` is a\n[valid production authorization credential](https://developer.squareup.com/docs/build-basics/access-tokens).\n\nIf the access token is expired or not a valid access token, the endpoint returns an `UNAUTHORIZED` error.", "x-release-status": "PUBLIC", "x-oauthpermissions": [], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [] } ], "parameters": [], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveTokenStatusResponse" } } } } }, "/v1/{location_id}/orders": { "get": { "tags": [ "V1Transactions" ], "summary": "V1ListOrders", "operationId": "V1ListOrders", "description": "Provides summary information for a merchant\u0027s online store orders.", "x-release-status": "DEPRECATED", "x-is-deprecated": true, "x-visibility": "SDK_ONLY", "x-oauthpermissions": [ "ORDERS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ORDERS_READ" ] } ], "parameters": [ { "name": "location_id", "description": "The ID of the location to list online store orders for.", "x-is-deprecated": true, "type": "string", "in": "path", "required": true }, { "name": "order", "description": "The order in which payments are listed in the response.", "x-is-deprecated": true, "type": "string", "in": "query", "required": false }, { "name": "limit", "description": "The maximum number of payments to return in a single response. This value cannot exceed 200.", "x-is-deprecated": true, "type": "integer", "in": "query", "required": false }, { "name": "batch_token", "description": "A pagination cursor to retrieve the next set of results for your\noriginal query to the endpoint.", "x-is-deprecated": true, "type": "string", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "type": "array", "items": { "$ref": "#/definitions/V1Order" } } } } } }, "/v1/{location_id}/orders/{order_id}": { "get": { "tags": [ "V1Transactions" ], "summary": "V1RetrieveOrder", "operationId": "V1RetrieveOrder", "description": "Provides comprehensive information for a single online store order, including the order\u0027s history.", "x-release-status": "DEPRECATED", "x-is-deprecated": true, "x-visibility": "SDK_ONLY", "x-oauthpermissions": [ "ORDERS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ORDERS_READ" ] } ], "parameters": [ { "name": "location_id", "description": "The ID of the order\u0027s associated location.", "x-is-deprecated": true, "type": "string", "in": "path", "required": true }, { "name": "order_id", "description": "The order\u0027s Square-issued ID. You obtain this value from Order objects returned by the List Orders endpoint", "x-is-deprecated": true, "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/V1Order" } } } }, "put": { "tags": [ "V1Transactions" ], "summary": "V1UpdateOrder", "operationId": "V1UpdateOrder", "description": "Updates the details of an online store order. Every update you perform on an order corresponds to one of three actions:", "x-release-status": "DEPRECATED", "x-is-deprecated": true, "x-visibility": "SDK_ONLY", "x-oauthpermissions": [ "ORDERS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ORDERS_WRITE" ] } ], "parameters": [ { "name": "location_id", "description": "The ID of the order\u0027s associated location.", "x-is-deprecated": true, "type": "string", "in": "path", "required": true }, { "name": "order_id", "description": "The order\u0027s Square-issued ID. You obtain this value from Order objects returned by the List Orders endpoint", "x-is-deprecated": true, "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/V1UpdateOrderRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/V1Order" } } } } }, "/v2/apple-pay/domains": { "post": { "tags": [ "ApplePay" ], "summary": "RegisterDomain", "operationId": "RegisterDomain", "description": "Activates a domain for use with Apple Pay on the Web and Square. A validation\nis performed on this domain by Apple to ensure that it is properly set up as\nan Apple Pay enabled domain.\n\nThis endpoint provides an easy way for platform developers to bulk activate\nApple Pay on the Web with Square for merchants using their platform.\n\nNote: You will need to host a valid domain verification file on your domain to support Apple Pay. The\ncurrent version of this file is always available at https://app.squareup.com/digital-wallets/apple-pay/apple-developer-merchantid-domain-association,\nand should be hosted at `.well_known/apple-developer-merchantid-domain-association` on your\ndomain. This file is subject to change; we strongly recommend checking for updates regularly and avoiding\nlong-lived caches that might not keep in sync with the correct file version.\n\nTo learn more about the Web Payments SDK and how to add Apple Pay, see [Take an Apple Pay Payment](https://developer.squareup.com/docs/web-payments/apple-pay).", "x-release-status": "PUBLIC", "x-oauthpermissions": [], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/RegisterDomainRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RegisterDomainResponse" } } } } }, "/v2/bank-accounts": { "get": { "tags": [ "BankAccounts" ], "summary": "ListBankAccounts", "operationId": "ListBankAccounts", "description": "Returns a list of [BankAccount](https://developer.squareup.com/reference/square_2024-10-17/objects/BankAccount) objects linked to a Square account.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "BANK_ACCOUNTS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "BANK_ACCOUNTS_READ" ] } ], "parameters": [ { "name": "cursor", "description": "The pagination cursor returned by a previous call to this endpoint.\nUse it in the next `ListBankAccounts` request to retrieve the next set \nof results.\n\nSee the [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination) guide for more information.", "type": "string", "in": "query", "required": false }, { "name": "limit", "description": "Upper limit on the number of bank accounts to return in the response. \nCurrently, 1000 is the largest supported limit. You can specify a limit \nof up to 1000 bank accounts. This is also the default limit.", "type": "integer", "in": "query", "required": false }, { "name": "location_id", "description": "Location ID. You can specify this optional filter \nto retrieve only the linked bank accounts belonging to a specific location.", "type": "string", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListBankAccountsResponse" } } } } }, "/v2/bank-accounts/by-v1-id/{v1_bank_account_id}": { "get": { "tags": [ "BankAccounts" ], "summary": "GetBankAccountByV1Id", "operationId": "GetBankAccountByV1Id", "description": "Returns details of a [BankAccount](https://developer.squareup.com/reference/square_2024-10-17/objects/BankAccount) identified by V1 bank account ID.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "BANK_ACCOUNTS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "BANK_ACCOUNTS_READ" ] } ], "parameters": [ { "name": "v1_bank_account_id", "description": "Connect V1 ID of the desired `BankAccount`. For more information, see \n[Retrieve a bank account by using an ID issued by V1 Bank Accounts API](https://developer.squareup.com/docs/bank-accounts-api#retrieve-a-bank-account-by-using-an-id-issued-by-v1-bank-accounts-api).", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/GetBankAccountByV1IdResponse" } } } } }, "/v2/bank-accounts/{bank_account_id}": { "get": { "tags": [ "BankAccounts" ], "summary": "GetBankAccount", "operationId": "GetBankAccount", "description": "Returns details of a [BankAccount](https://developer.squareup.com/reference/square_2024-10-17/objects/BankAccount)\nlinked to a Square account.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "BANK_ACCOUNTS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "BANK_ACCOUNTS_READ" ] } ], "parameters": [ { "name": "bank_account_id", "description": "Square-issued ID of the desired `BankAccount`.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/GetBankAccountResponse" } } } } }, "/v2/bookings": { "get": { "tags": [ "Bookings" ], "summary": "ListBookings", "operationId": "ListBookings", "description": "Retrieve a collection of bookings.\n\nTo call this endpoint with buyer-level permissions, set `APPOINTMENTS_READ` for the OAuth scope.\nTo call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_READ` and `APPOINTMENTS_READ` for the OAuth scope.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "APPOINTMENTS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "APPOINTMENTS_READ" ] } ], "parameters": [ { "name": "limit", "description": "The maximum number of results per page to return in a paged response.", "type": "integer", "in": "query", "required": false }, { "name": "cursor", "description": "The pagination cursor from the preceding response to return the next page of the results. Do not set this when retrieving the first page of the results.", "type": "string", "in": "query", "required": false }, { "name": "customer_id", "description": "The [customer](https://developer.squareup.com/reference/square_2024-10-17/objects/Customer) for whom to retrieve bookings. If this is not set, bookings for all customers are retrieved.", "type": "string", "in": "query", "required": false }, { "name": "team_member_id", "description": "The team member for whom to retrieve bookings. If this is not set, bookings of all members are retrieved.", "type": "string", "in": "query", "required": false }, { "name": "location_id", "description": "The location for which to retrieve bookings. If this is not set, all locations\u0027 bookings are retrieved.", "type": "string", "in": "query", "required": false }, { "name": "start_at_min", "description": "The RFC 3339 timestamp specifying the earliest of the start time. If this is not set, the current time is used.", "type": "string", "in": "query", "required": false }, { "name": "start_at_max", "description": "The RFC 3339 timestamp specifying the latest of the start time. If this is not set, the time of 31 days after `start_at_min` is used.", "type": "string", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListBookingsResponse" } } } }, "post": { "tags": [ "Bookings" ], "summary": "CreateBooking", "operationId": "CreateBooking", "description": "Creates a booking.\n\nThe required input must include the following:\n- `Booking.location_id`\n- `Booking.start_at`\n- `Booking.AppointmentSegment.team_member_id`\n- `Booking.AppointmentSegment.service_variation_id`\n- `Booking.AppointmentSegment.service_variation_version`\n\nTo call this endpoint with buyer-level permissions, set `APPOINTMENTS_WRITE` for the OAuth scope.\nTo call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_WRITE` and `APPOINTMENTS_WRITE` for the OAuth scope.\n\nFor calls to this endpoint with seller-level permissions to succeed, the seller must have subscribed to *Appointments Plus*\nor *Appointments Premium*.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "APPOINTMENTS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "APPOINTMENTS_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CreateBookingRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CreateBookingResponse" } } } } }, "/v2/bookings/availability/search": { "post": { "tags": [ "Bookings" ], "summary": "SearchAvailability", "operationId": "SearchAvailability", "description": "Searches for availabilities for booking.\n\nTo call this endpoint with buyer-level permissions, set `APPOINTMENTS_READ` for the OAuth scope.\nTo call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_READ` and `APPOINTMENTS_READ` for the OAuth scope.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "APPOINTMENTS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "APPOINTMENTS_READ" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/SearchAvailabilityRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/SearchAvailabilityResponse" } } } } }, "/v2/bookings/bulk-retrieve": { "post": { "tags": [ "Bookings" ], "summary": "BulkRetrieveBookings", "operationId": "BulkRetrieveBookings", "description": "Bulk-Retrieves a list of bookings by booking IDs.\n\nTo call this endpoint with buyer-level permissions, set `APPOINTMENTS_READ` for the OAuth scope.\nTo call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_READ` and `APPOINTMENTS_READ` for the OAuth scope.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "APPOINTMENTS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "APPOINTMENTS_READ" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/BulkRetrieveBookingsRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/BulkRetrieveBookingsResponse" } } } } }, "/v2/bookings/business-booking-profile": { "get": { "tags": [ "Bookings" ], "summary": "RetrieveBusinessBookingProfile", "operationId": "RetrieveBusinessBookingProfile", "description": "Retrieves a seller\u0027s booking profile.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "APPOINTMENTS_BUSINESS_SETTINGS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "APPOINTMENTS_BUSINESS_SETTINGS_READ" ] } ], "parameters": [], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveBusinessBookingProfileResponse" } } } } }, "/v2/bookings/custom-attribute-definitions": { "get": { "tags": [ "BookingCustomAttributes" ], "summary": "ListBookingCustomAttributeDefinitions", "operationId": "ListBookingCustomAttributeDefinitions", "description": "Get all bookings custom attribute definitions.\n\nTo call this endpoint with buyer-level permissions, set `APPOINTMENTS_READ` for the OAuth scope.\nTo call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_READ` and `APPOINTMENTS_READ` for the OAuth scope.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "APPOINTMENTS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "APPOINTMENTS_READ" ] } ], "parameters": [ { "name": "limit", "description": "The maximum number of results to return in a single paged response. This limit is advisory.\nThe response might contain more or fewer results. The minimum value is 1 and the maximum value is 100.\nThe default value is 20. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "type": "integer", "in": "query", "required": false }, { "name": "cursor", "description": "The cursor returned in the paged response from the previous call to this endpoint.\nProvide this cursor to retrieve the next page of results for your original request.\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "type": "string", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListBookingCustomAttributeDefinitionsResponse" } } } }, "post": { "tags": [ "BookingCustomAttributes" ], "summary": "CreateBookingCustomAttributeDefinition", "operationId": "CreateBookingCustomAttributeDefinition", "description": "Creates a bookings custom attribute definition.\n\nTo call this endpoint with buyer-level permissions, set `APPOINTMENTS_WRITE` for the OAuth scope.\nTo call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_WRITE` and `APPOINTMENTS_WRITE` for the OAuth scope.\n\nFor calls to this endpoint with seller-level permissions to succeed, the seller must have subscribed to *Appointments Plus*\nor *Appointments Premium*.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "APPOINTMENTS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "APPOINTMENTS_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CreateBookingCustomAttributeDefinitionRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CreateBookingCustomAttributeDefinitionResponse" } } } } }, "/v2/bookings/custom-attribute-definitions/{key}": { "delete": { "tags": [ "BookingCustomAttributes" ], "summary": "DeleteBookingCustomAttributeDefinition", "operationId": "DeleteBookingCustomAttributeDefinition", "description": "Deletes a bookings custom attribute definition.\n\nTo call this endpoint with buyer-level permissions, set `APPOINTMENTS_WRITE` for the OAuth scope.\nTo call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_WRITE` and `APPOINTMENTS_WRITE` for the OAuth scope.\n\nFor calls to this endpoint with seller-level permissions to succeed, the seller must have subscribed to *Appointments Plus*\nor *Appointments Premium*.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "APPOINTMENTS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "APPOINTMENTS_WRITE" ] } ], "parameters": [ { "name": "key", "description": "The key of the custom attribute definition to delete.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/DeleteBookingCustomAttributeDefinitionResponse" } } } }, "get": { "tags": [ "BookingCustomAttributes" ], "summary": "RetrieveBookingCustomAttributeDefinition", "operationId": "RetrieveBookingCustomAttributeDefinition", "description": "Retrieves a bookings custom attribute definition.\n\nTo call this endpoint with buyer-level permissions, set `APPOINTMENTS_READ` for the OAuth scope.\nTo call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_READ` and `APPOINTMENTS_READ` for the OAuth scope.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "APPOINTMENTS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "APPOINTMENTS_READ" ] } ], "parameters": [ { "name": "key", "description": "The key of the custom attribute definition to retrieve. If the requesting application\nis not the definition owner, you must use the qualified key.", "type": "string", "in": "path", "required": true }, { "name": "version", "description": "The current version of the custom attribute definition, which is used for strongly consistent\nreads to guarantee that you receive the most up-to-date data. When included in the request,\nSquare returns the specified version or a higher version if one exists. If the specified version\nis higher than the current version, Square returns a `BAD_REQUEST` error.", "type": "integer", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveBookingCustomAttributeDefinitionResponse" } } } }, "put": { "tags": [ "BookingCustomAttributes" ], "summary": "UpdateBookingCustomAttributeDefinition", "operationId": "UpdateBookingCustomAttributeDefinition", "description": "Updates a bookings custom attribute definition.\n\nTo call this endpoint with buyer-level permissions, set `APPOINTMENTS_WRITE` for the OAuth scope.\nTo call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_WRITE` and `APPOINTMENTS_WRITE` for the OAuth scope.\n\nFor calls to this endpoint with seller-level permissions to succeed, the seller must have subscribed to *Appointments Plus*\nor *Appointments Premium*.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "APPOINTMENTS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "APPOINTMENTS_WRITE" ] } ], "parameters": [ { "name": "key", "description": "The key of the custom attribute definition to update.", "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/UpdateBookingCustomAttributeDefinitionRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/UpdateBookingCustomAttributeDefinitionResponse" } } } } }, "/v2/bookings/custom-attributes/bulk-delete": { "post": { "tags": [ "BookingCustomAttributes" ], "summary": "BulkDeleteBookingCustomAttributes", "operationId": "BulkDeleteBookingCustomAttributes", "description": "Bulk deletes bookings custom attributes.\n\nTo call this endpoint with buyer-level permissions, set `APPOINTMENTS_WRITE` for the OAuth scope.\nTo call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_WRITE` and `APPOINTMENTS_WRITE` for the OAuth scope.\n\nFor calls to this endpoint with seller-level permissions to succeed, the seller must have subscribed to *Appointments Plus*\nor *Appointments Premium*.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "APPOINTMENTS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "APPOINTMENTS_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/BulkDeleteBookingCustomAttributesRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/BulkDeleteBookingCustomAttributesResponse" } } } } }, "/v2/bookings/custom-attributes/bulk-upsert": { "post": { "tags": [ "BookingCustomAttributes" ], "summary": "BulkUpsertBookingCustomAttributes", "operationId": "BulkUpsertBookingCustomAttributes", "description": "Bulk upserts bookings custom attributes.\n\nTo call this endpoint with buyer-level permissions, set `APPOINTMENTS_WRITE` for the OAuth scope.\nTo call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_WRITE` and `APPOINTMENTS_WRITE` for the OAuth scope.\n\nFor calls to this endpoint with seller-level permissions to succeed, the seller must have subscribed to *Appointments Plus*\nor *Appointments Premium*.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "APPOINTMENTS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "APPOINTMENTS_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/BulkUpsertBookingCustomAttributesRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/BulkUpsertBookingCustomAttributesResponse" } } } } }, "/v2/bookings/location-booking-profiles": { "get": { "tags": [ "Bookings" ], "summary": "ListLocationBookingProfiles", "operationId": "ListLocationBookingProfiles", "description": "Lists location booking profiles of a seller.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "APPOINTMENTS_BUSINESS_SETTINGS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "APPOINTMENTS_BUSINESS_SETTINGS_READ" ] } ], "parameters": [ { "name": "limit", "description": "The maximum number of results to return in a paged response.", "type": "integer", "in": "query", "required": false }, { "name": "cursor", "description": "The pagination cursor from the preceding response to return the next page of the results. Do not set this when retrieving the first page of the results.", "type": "string", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListLocationBookingProfilesResponse" } } } } }, "/v2/bookings/location-booking-profiles/{location_id}": { "get": { "tags": [ "Bookings" ], "summary": "RetrieveLocationBookingProfile", "operationId": "RetrieveLocationBookingProfile", "description": "Retrieves a seller\u0027s location booking profile.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "APPOINTMENTS_BUSINESS_SETTINGS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "APPOINTMENTS_BUSINESS_SETTINGS_READ" ] } ], "parameters": [ { "name": "location_id", "description": "The ID of the location to retrieve the booking profile.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveLocationBookingProfileResponse" } } } } }, "/v2/bookings/team-member-booking-profiles": { "get": { "tags": [ "Bookings" ], "summary": "ListTeamMemberBookingProfiles", "operationId": "ListTeamMemberBookingProfiles", "description": "Lists booking profiles for team members.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "APPOINTMENTS_BUSINESS_SETTINGS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "APPOINTMENTS_BUSINESS_SETTINGS_READ" ] } ], "parameters": [ { "name": "bookable_only", "description": "Indicates whether to include only bookable team members in the returned result (`true`) or not (`false`).", "type": "boolean", "in": "query", "required": false }, { "name": "limit", "description": "The maximum number of results to return in a paged response.", "type": "integer", "in": "query", "required": false }, { "name": "cursor", "description": "The pagination cursor from the preceding response to return the next page of the results. Do not set this when retrieving the first page of the results.", "type": "string", "in": "query", "required": false }, { "name": "location_id", "description": "Indicates whether to include only team members enabled at the given location in the returned result.", "type": "string", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListTeamMemberBookingProfilesResponse" } } } } }, "/v2/bookings/team-member-booking-profiles/bulk-retrieve": { "post": { "tags": [ "Bookings" ], "summary": "BulkRetrieveTeamMemberBookingProfiles", "operationId": "BulkRetrieveTeamMemberBookingProfiles", "description": "Retrieves one or more team members\u0027 booking profiles.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "APPOINTMENTS_BUSINESS_SETTINGS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "APPOINTMENTS_BUSINESS_SETTINGS_READ" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/BulkRetrieveTeamMemberBookingProfilesRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/BulkRetrieveTeamMemberBookingProfilesResponse" } } } } }, "/v2/bookings/team-member-booking-profiles/{team_member_id}": { "get": { "tags": [ "Bookings" ], "summary": "RetrieveTeamMemberBookingProfile", "operationId": "RetrieveTeamMemberBookingProfile", "description": "Retrieves a team member\u0027s booking profile.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "APPOINTMENTS_BUSINESS_SETTINGS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "APPOINTMENTS_BUSINESS_SETTINGS_READ" ] } ], "parameters": [ { "name": "team_member_id", "description": "The ID of the team member to retrieve.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveTeamMemberBookingProfileResponse" } } } } }, "/v2/bookings/{booking_id}": { "get": { "tags": [ "Bookings" ], "summary": "RetrieveBooking", "operationId": "RetrieveBooking", "description": "Retrieves a booking.\n\nTo call this endpoint with buyer-level permissions, set `APPOINTMENTS_READ` for the OAuth scope.\nTo call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_READ` and `APPOINTMENTS_READ` for the OAuth scope.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "APPOINTMENTS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "APPOINTMENTS_READ" ] } ], "parameters": [ { "name": "booking_id", "description": "The ID of the [Booking](https://developer.squareup.com/reference/square_2024-10-17/objects/Booking) object representing the to-be-retrieved booking.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveBookingResponse" } } } }, "put": { "tags": [ "Bookings" ], "summary": "UpdateBooking", "operationId": "UpdateBooking", "description": "Updates a booking.\n\nTo call this endpoint with buyer-level permissions, set `APPOINTMENTS_WRITE` for the OAuth scope.\nTo call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_WRITE` and `APPOINTMENTS_WRITE` for the OAuth scope.\n\nFor calls to this endpoint with seller-level permissions to succeed, the seller must have subscribed to *Appointments Plus*\nor *Appointments Premium*.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "APPOINTMENTS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "APPOINTMENTS_WRITE" ] } ], "parameters": [ { "name": "booking_id", "description": "The ID of the [Booking](https://developer.squareup.com/reference/square_2024-10-17/objects/Booking) object representing the to-be-updated booking.", "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/UpdateBookingRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/UpdateBookingResponse" } } } } }, "/v2/bookings/{booking_id}/cancel": { "post": { "tags": [ "Bookings" ], "summary": "CancelBooking", "operationId": "CancelBooking", "description": "Cancels an existing booking.\n\nTo call this endpoint with buyer-level permissions, set `APPOINTMENTS_WRITE` for the OAuth scope.\nTo call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_WRITE` and `APPOINTMENTS_WRITE` for the OAuth scope.\n\nFor calls to this endpoint with seller-level permissions to succeed, the seller must have subscribed to *Appointments Plus*\nor *Appointments Premium*.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "APPOINTMENTS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "APPOINTMENTS_WRITE" ] } ], "parameters": [ { "name": "booking_id", "description": "The ID of the [Booking](https://developer.squareup.com/reference/square_2024-10-17/objects/Booking) object representing the to-be-cancelled booking.", "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CancelBookingRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CancelBookingResponse" } } } } }, "/v2/bookings/{booking_id}/custom-attributes": { "get": { "tags": [ "BookingCustomAttributes" ], "summary": "ListBookingCustomAttributes", "operationId": "ListBookingCustomAttributes", "description": "Lists a booking\u0027s custom attributes.\n\nTo call this endpoint with buyer-level permissions, set `APPOINTMENTS_READ` for the OAuth scope.\nTo call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_READ` and `APPOINTMENTS_READ` for the OAuth scope.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "APPOINTMENTS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "APPOINTMENTS_READ" ] } ], "parameters": [ { "name": "booking_id", "description": "The ID of the target [booking](https://developer.squareup.com/reference/square_2024-10-17/objects/Booking).", "type": "string", "in": "path", "required": true }, { "name": "limit", "description": "The maximum number of results to return in a single paged response. This limit is advisory.\nThe response might contain more or fewer results. The minimum value is 1 and the maximum value is 100.\nThe default value is 20. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "type": "integer", "in": "query", "required": false }, { "name": "cursor", "description": "The cursor returned in the paged response from the previous call to this endpoint.\nProvide this cursor to retrieve the next page of results for your original request. For more\ninformation, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "type": "string", "in": "query", "required": false }, { "name": "with_definitions", "description": "Indicates whether to return the [custom attribute definition](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttributeDefinition) in the `definition` field of each\ncustom attribute. Set this parameter to `true` to get the name and description of each custom\nattribute, information about the data type, or other definition details. The default value is `false`.", "type": "boolean", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListBookingCustomAttributesResponse" } } } } }, "/v2/bookings/{booking_id}/custom-attributes/{key}": { "delete": { "tags": [ "BookingCustomAttributes" ], "summary": "DeleteBookingCustomAttribute", "operationId": "DeleteBookingCustomAttribute", "description": "Deletes a bookings custom attribute.\n\nTo call this endpoint with buyer-level permissions, set `APPOINTMENTS_WRITE` for the OAuth scope.\nTo call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_WRITE` and `APPOINTMENTS_WRITE` for the OAuth scope.\n\nFor calls to this endpoint with seller-level permissions to succeed, the seller must have subscribed to *Appointments Plus*\nor *Appointments Premium*.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "APPOINTMENTS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "APPOINTMENTS_WRITE" ] } ], "parameters": [ { "name": "booking_id", "description": "The ID of the target [booking](https://developer.squareup.com/reference/square_2024-10-17/objects/Booking).", "type": "string", "in": "path", "required": true }, { "name": "key", "description": "The key of the custom attribute to delete. This key must match the `key` of a custom\nattribute definition in the Square seller account. If the requesting application is not the\ndefinition owner, you must use the qualified key.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/DeleteBookingCustomAttributeResponse" } } } }, "get": { "tags": [ "BookingCustomAttributes" ], "summary": "RetrieveBookingCustomAttribute", "operationId": "RetrieveBookingCustomAttribute", "description": "Retrieves a bookings custom attribute.\n\nTo call this endpoint with buyer-level permissions, set `APPOINTMENTS_READ` for the OAuth scope.\nTo call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_READ` and `APPOINTMENTS_READ` for the OAuth scope.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "APPOINTMENTS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "APPOINTMENTS_READ" ] } ], "parameters": [ { "name": "booking_id", "description": "The ID of the target [booking](https://developer.squareup.com/reference/square_2024-10-17/objects/Booking).", "type": "string", "in": "path", "required": true }, { "name": "key", "description": "The key of the custom attribute to retrieve. This key must match the `key` of a custom\nattribute definition in the Square seller account. If the requesting application is not the\ndefinition owner, you must use the qualified key.", "type": "string", "in": "path", "required": true }, { "name": "with_definition", "description": "Indicates whether to return the [custom attribute definition](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttributeDefinition) in the `definition` field of\nthe custom attribute. Set this parameter to `true` to get the name and description of the custom\nattribute, information about the data type, or other definition details. The default value is `false`.", "type": "boolean", "in": "query", "required": false }, { "name": "version", "description": "The current version of the custom attribute, which is used for strongly consistent reads to\nguarantee that you receive the most up-to-date data. When included in the request, Square\nreturns the specified version or a higher version if one exists. If the specified version is\nhigher than the current version, Square returns a `BAD_REQUEST` error.", "type": "integer", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveBookingCustomAttributeResponse" } } } }, "put": { "tags": [ "BookingCustomAttributes" ], "summary": "UpsertBookingCustomAttribute", "operationId": "UpsertBookingCustomAttribute", "description": "Upserts a bookings custom attribute.\n\nTo call this endpoint with buyer-level permissions, set `APPOINTMENTS_WRITE` for the OAuth scope.\nTo call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_WRITE` and `APPOINTMENTS_WRITE` for the OAuth scope.\n\nFor calls to this endpoint with seller-level permissions to succeed, the seller must have subscribed to *Appointments Plus*\nor *Appointments Premium*.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "APPOINTMENTS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "APPOINTMENTS_WRITE" ] } ], "parameters": [ { "name": "booking_id", "description": "The ID of the target [booking](https://developer.squareup.com/reference/square_2024-10-17/objects/Booking).", "type": "string", "in": "path", "required": true }, { "name": "key", "description": "The key of the custom attribute to create or update. This key must match the `key` of a\ncustom attribute definition in the Square seller account. If the requesting application is not\nthe definition owner, you must use the qualified key.", "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/UpsertBookingCustomAttributeRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/UpsertBookingCustomAttributeResponse" } } } } }, "/v2/cards": { "get": { "tags": [ "Cards" ], "summary": "ListCards", "operationId": "ListCards", "description": "Retrieves a list of cards owned by the account making the request.\nA max of 25 cards will be returned.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "PAYMENTS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "PAYMENTS_READ" ] } ], "parameters": [ { "name": "cursor", "description": "A pagination cursor returned by a previous call to this endpoint.\nProvide this to retrieve the next set of results for your original query.\n\nSee [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination) for more information.", "type": "string", "in": "query", "required": false }, { "name": "customer_id", "description": "Limit results to cards associated with the customer supplied.\nBy default, all cards owned by the merchant are returned.", "type": "string", "in": "query", "required": false }, { "name": "include_disabled", "description": "Includes disabled cards.\nBy default, all enabled cards owned by the merchant are returned.", "type": "boolean", "in": "query", "required": false }, { "name": "reference_id", "description": "Limit results to cards associated with the reference_id supplied.", "type": "string", "in": "query", "required": false }, { "name": "sort_order", "description": "Sorts the returned list by when the card was created with the specified order.\nThis field defaults to ASC.", "type": "string", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListCardsResponse" } } } }, "post": { "tags": [ "Cards" ], "summary": "CreateCard", "operationId": "CreateCard", "description": "Adds a card on file to an existing merchant.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "PAYMENTS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "PAYMENTS_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CreateCardRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CreateCardResponse" } } } } }, "/v2/cards/{card_id}": { "get": { "tags": [ "Cards" ], "summary": "RetrieveCard", "operationId": "RetrieveCard", "description": "Retrieves details for a specific Card.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "PAYMENTS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "PAYMENTS_READ" ] } ], "parameters": [ { "name": "card_id", "description": "Unique ID for the desired Card.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveCardResponse" } } } } }, "/v2/cards/{card_id}/disable": { "post": { "tags": [ "Cards" ], "summary": "DisableCard", "operationId": "DisableCard", "description": "Disables the card, preventing any further updates or charges.\nDisabling an already disabled card is allowed but has no effect.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "PAYMENTS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "PAYMENTS_WRITE" ] } ], "parameters": [ { "name": "card_id", "description": "Unique ID for the desired Card.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/DisableCardResponse" } } } } }, "/v2/cash-drawers/shifts": { "get": { "tags": [ "CashDrawers" ], "summary": "ListCashDrawerShifts", "operationId": "ListCashDrawerShifts", "description": "Provides the details for all of the cash drawer shifts for a location\nin a date range.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "CASH_DRAWER_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CASH_DRAWER_READ" ] } ], "parameters": [ { "name": "location_id", "description": "The ID of the location to query for a list of cash drawer shifts.", "type": "string", "in": "query", "required": true }, { "name": "sort_order", "description": "The order in which cash drawer shifts are listed in the response,\nbased on their opened_at field. Default value: ASC", "type": "string", "in": "query", "required": false }, { "name": "begin_time", "description": "The inclusive start time of the query on opened_at, in ISO 8601 format.", "type": "string", "in": "query", "required": false }, { "name": "end_time", "description": "The exclusive end date of the query on opened_at, in ISO 8601 format.", "type": "string", "in": "query", "required": false }, { "name": "limit", "description": "Number of cash drawer shift events in a page of results (200 by\ndefault, 1000 max).", "type": "integer", "in": "query", "required": false }, { "name": "cursor", "description": "Opaque cursor for fetching the next page of results.", "type": "string", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListCashDrawerShiftsResponse" } } } } }, "/v2/cash-drawers/shifts/{shift_id}": { "get": { "tags": [ "CashDrawers" ], "summary": "RetrieveCashDrawerShift", "operationId": "RetrieveCashDrawerShift", "description": "Provides the summary details for a single cash drawer shift. See\n[ListCashDrawerShiftEvents](https://developer.squareup.com/reference/square_2024-10-17/cash-drawers-api/list-cash-drawer-shift-events) for a list of cash drawer shift events.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "CASH_DRAWER_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CASH_DRAWER_READ" ] } ], "parameters": [ { "name": "location_id", "description": "The ID of the location to retrieve cash drawer shifts from.", "type": "string", "in": "query", "required": true }, { "name": "shift_id", "description": "The shift ID.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveCashDrawerShiftResponse" } } } } }, "/v2/cash-drawers/shifts/{shift_id}/events": { "get": { "tags": [ "CashDrawers" ], "summary": "ListCashDrawerShiftEvents", "operationId": "ListCashDrawerShiftEvents", "description": "Provides a paginated list of events for a single cash drawer shift.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "CASH_DRAWER_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CASH_DRAWER_READ" ] } ], "parameters": [ { "name": "location_id", "description": "The ID of the location to list cash drawer shifts for.", "type": "string", "in": "query", "required": true }, { "name": "shift_id", "description": "The shift ID.", "type": "string", "in": "path", "required": true }, { "name": "limit", "description": "Number of resources to be returned in a page of results (200 by\ndefault, 1000 max).", "type": "integer", "in": "query", "required": false }, { "name": "cursor", "description": "Opaque cursor for fetching the next page of results.", "type": "string", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListCashDrawerShiftEventsResponse" } } } } }, "/v2/catalog/batch-delete": { "post": { "tags": [ "Catalog" ], "summary": "BatchDeleteCatalogObjects", "operationId": "BatchDeleteCatalogObjects", "description": "Deletes a set of [CatalogItem](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogItem)s based on the\nprovided list of target IDs and returns a set of successfully deleted IDs in\nthe response. Deletion is a cascading event such that all children of the\ntargeted object are also deleted. For example, deleting a CatalogItem will\nalso delete all of its [CatalogItemVariation](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogItemVariation)\nchildren.\n\n`BatchDeleteCatalogObjects` succeeds even if only a portion of the targeted\nIDs can be deleted. The response will only include IDs that were\nactually deleted.\n\nTo ensure consistency, only one delete request is processed at a time per seller account.\nWhile one (batch or non-batch) delete request is being processed, other (batched and non-batched)\ndelete requests are rejected with the `429` error code.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "ITEMS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ITEMS_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/BatchDeleteCatalogObjectsRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/BatchDeleteCatalogObjectsResponse" } } } } }, "/v2/catalog/batch-retrieve": { "post": { "tags": [ "Catalog" ], "summary": "BatchRetrieveCatalogObjects", "operationId": "BatchRetrieveCatalogObjects", "description": "Returns a set of objects based on the provided ID.\nEach [CatalogItem](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogItem) returned in the set includes all of its\nchild information including: all of its\n[CatalogItemVariation](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogItemVariation) objects, references to\nits [CatalogModifierList](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogModifierList) objects, and the ids of\nany [CatalogTax](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogTax) objects that apply to it.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "ITEMS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ITEMS_READ" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/BatchRetrieveCatalogObjectsRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/BatchRetrieveCatalogObjectsResponse" } } } } }, "/v2/catalog/batch-upsert": { "post": { "tags": [ "Catalog" ], "summary": "BatchUpsertCatalogObjects", "operationId": "BatchUpsertCatalogObjects", "description": "Creates or updates up to 10,000 target objects based on the provided\nlist of objects. The target objects are grouped into batches and each batch is\ninserted/updated in an all-or-nothing manner. If an object within a batch is\nmalformed in some way, or violates a database constraint, the entire batch\ncontaining that item will be disregarded. However, other batches in the same\nrequest may still succeed. Each batch may contain up to 1,000 objects, and\nbatches will be processed in order as long as the total object count for the\nrequest (items, variations, modifier lists, discounts, and taxes) is no more\nthan 10,000.\n\nTo ensure consistency, only one update request is processed at a time per seller account.\nWhile one (batch or non-batch) update request is being processed, other (batched and non-batched)\nupdate requests are rejected with the `429` error code.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "ITEMS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ITEMS_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/BatchUpsertCatalogObjectsRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/BatchUpsertCatalogObjectsResponse" } } } } }, "/v2/catalog/info": { "get": { "tags": [ "Catalog" ], "summary": "CatalogInfo", "operationId": "CatalogInfo", "description": "Retrieves information about the Square Catalog API, such as batch size\nlimits that can be used by the `BatchUpsertCatalogObjects` endpoint.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "ITEMS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ITEMS_READ" ] } ], "parameters": [], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CatalogInfoResponse" } } } } }, "/v2/catalog/list": { "get": { "tags": [ "Catalog" ], "summary": "ListCatalog", "operationId": "ListCatalog", "description": "Returns a list of all [CatalogObject](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogObject)s of the specified types in the catalog.\n\nThe `types` parameter is specified as a comma-separated list of the [CatalogObjectType](https://developer.squareup.com/reference/square_2024-10-17/enums/CatalogObjectType) values,\nfor example, \"`ITEM`, `ITEM_VARIATION`, `MODIFIER`, `MODIFIER_LIST`, `CATEGORY`, `DISCOUNT`, `TAX`, `IMAGE`\".\n\n__Important:__ ListCatalog does not return deleted catalog items. To retrieve\ndeleted catalog items, use [SearchCatalogObjects](https://developer.squareup.com/reference/square_2024-10-17/catalog-api/search-catalog-objects)\nand set the `include_deleted_objects` attribute value to `true`.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "ITEMS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ITEMS_READ" ] } ], "parameters": [ { "name": "cursor", "description": "The pagination cursor returned in the previous response. Leave unset for an initial request.\nThe page size is currently set to be 100.\nSee [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination) for more information.", "type": "string", "in": "query", "required": false }, { "name": "types", "description": "An optional case-insensitive, comma-separated list of object types to retrieve.\n\nThe valid values are defined in the [CatalogObjectType](https://developer.squareup.com/reference/square_2024-10-17/enums/CatalogObjectType) enum, for example,\n`ITEM`, `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`, `TAX`,\n`MODIFIER`, `MODIFIER_LIST`, `IMAGE`, etc.\n\nIf this is unspecified, the operation returns objects of all the top level types at the version\nof the Square API used to make the request. Object types that are nested onto other object types\nare not included in the defaults.\n\nAt the current API version the default object types are:\nITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, \nPRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT,\nSUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION, QUICK_AMOUNT_SETTINGS.", "type": "string", "in": "query", "required": false }, { "name": "catalog_version", "description": "The specific version of the catalog objects to be included in the response.\nThis allows you to retrieve historical versions of objects. The specified version value is matched against\nthe [CatalogObject](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogObject)s\u0027 `version` attribute. If not included, results will be from the\ncurrent version of the catalog.", "x-is-beta": true, "type": "integer", "format": "int64", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListCatalogResponse" } } } } }, "/v2/catalog/object": { "post": { "tags": [ "Catalog" ], "summary": "UpsertCatalogObject", "operationId": "UpsertCatalogObject", "description": "Creates a new or updates the specified [CatalogObject](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogObject).\n\nTo ensure consistency, only one update request is processed at a time per seller account.\nWhile one (batch or non-batch) update request is being processed, other (batched and non-batched)\nupdate requests are rejected with the `429` error code.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "ITEMS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ITEMS_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/UpsertCatalogObjectRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/UpsertCatalogObjectResponse" } } } } }, "/v2/catalog/object/{object_id}": { "delete": { "tags": [ "Catalog" ], "summary": "DeleteCatalogObject", "operationId": "DeleteCatalogObject", "description": "Deletes a single [CatalogObject](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogObject) based on the\nprovided ID and returns the set of successfully deleted IDs in the response.\nDeletion is a cascading event such that all children of the targeted object\nare also deleted. For example, deleting a [CatalogItem](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogItem)\nwill also delete all of its\n[CatalogItemVariation](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogItemVariation) children.\n\nTo ensure consistency, only one delete request is processed at a time per seller account.\nWhile one (batch or non-batch) delete request is being processed, other (batched and non-batched)\ndelete requests are rejected with the `429` error code.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "ITEMS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ITEMS_WRITE" ] } ], "parameters": [ { "name": "object_id", "description": "The ID of the catalog object to be deleted. When an object is deleted, other\nobjects in the graph that depend on that object will be deleted as well (for example, deleting a\ncatalog item will delete its catalog item variations).", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/DeleteCatalogObjectResponse" } } } }, "get": { "tags": [ "Catalog" ], "summary": "RetrieveCatalogObject", "operationId": "RetrieveCatalogObject", "description": "Returns a single [CatalogItem](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogItem) as a\n[CatalogObject](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogObject) based on the provided ID. The returned\nobject includes all of the relevant [CatalogItem](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogItem)\ninformation including: [CatalogItemVariation](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogItemVariation)\nchildren, references to its\n[CatalogModifierList](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogModifierList) objects, and the ids of\nany [CatalogTax](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogTax) objects that apply to it.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "ITEMS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ITEMS_READ" ] } ], "parameters": [ { "name": "object_id", "description": "The object ID of any type of catalog objects to be retrieved.", "type": "string", "in": "path", "required": true }, { "name": "include_related_objects", "description": "If `true`, the response will include additional objects that are related to the\nrequested objects. Related objects are defined as any objects referenced by ID by the results in the `objects` field\nof the response. These objects are put in the `related_objects` field. Setting this to `true` is\nhelpful when the objects are needed for immediate display to a user.\nThis process only goes one level deep. Objects referenced by the related objects will not be included. For example,\n\nif the `objects` field of the response contains a CatalogItem, its associated\nCatalogCategory objects, CatalogTax objects, CatalogImage objects and\nCatalogModifierLists will be returned in the `related_objects` field of the\nresponse. If the `objects` field of the response contains a CatalogItemVariation,\nits parent CatalogItem will be returned in the `related_objects` field of\nthe response.\n\nDefault value: `false`", "type": "boolean", "in": "query", "required": false }, { "name": "catalog_version", "description": "Requests objects as of a specific version of the catalog. This allows you to retrieve historical\nversions of objects. The value to retrieve a specific version of an object can be found\nin the version field of [CatalogObject](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogObject)s. If not included, results will\nbe from the current version of the catalog.", "x-is-beta": true, "type": "integer", "format": "int64", "in": "query", "required": false }, { "name": "include_category_path_to_root", "description": "Specifies whether or not to include the `path_to_root` list for each returned category instance. The `path_to_root` list consists\nof `CategoryPathToRootNode` objects and specifies the path that starts with the immediate parent category of the returned category\nand ends with its root category. If the returned category is a top-level category, the `path_to_root` list is empty and is not returned\nin the response payload.", "type": "boolean", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveCatalogObjectResponse" } } } } }, "/v2/catalog/search": { "post": { "tags": [ "Catalog" ], "summary": "SearchCatalogObjects", "operationId": "SearchCatalogObjects", "description": "Searches for [CatalogObject](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogObject) of any type by matching supported search attribute values,\nexcluding custom attribute values on items or item variations, against one or more of the specified query filters.\n\nThis (`SearchCatalogObjects`) endpoint differs from the [SearchCatalogItems](https://developer.squareup.com/reference/square_2024-10-17/catalog-api/search-catalog-items)\nendpoint in the following aspects:\n\n- `SearchCatalogItems` can only search for items or item variations, whereas `SearchCatalogObjects` can search for any type of catalog objects.\n- `SearchCatalogItems` supports the custom attribute query filters to return items or item variations that contain custom attribute values, where `SearchCatalogObjects` does not.\n- `SearchCatalogItems` does not support the `include_deleted_objects` filter to search for deleted items or item variations, whereas `SearchCatalogObjects` does.\n- The both endpoints have different call conventions, including the query filter formats.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "ITEMS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ITEMS_READ" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/SearchCatalogObjectsRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/SearchCatalogObjectsResponse" } } } } }, "/v2/catalog/search-catalog-items": { "post": { "tags": [ "Catalog" ], "summary": "SearchCatalogItems", "operationId": "SearchCatalogItems", "description": "Searches for catalog items or item variations by matching supported search attribute values, including\ncustom attribute values, against one or more of the specified query filters.\n\nThis (`SearchCatalogItems`) endpoint differs from the [SearchCatalogObjects](https://developer.squareup.com/reference/square_2024-10-17/catalog-api/search-catalog-objects)\nendpoint in the following aspects:\n\n- `SearchCatalogItems` can only search for items or item variations, whereas `SearchCatalogObjects` can search for any type of catalog objects.\n- `SearchCatalogItems` supports the custom attribute query filters to return items or item variations that contain custom attribute values, where `SearchCatalogObjects` does not.\n- `SearchCatalogItems` does not support the `include_deleted_objects` filter to search for deleted items or item variations, whereas `SearchCatalogObjects` does.\n- The both endpoints use different call conventions, including the query filter formats.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "ITEMS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ITEMS_READ" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/SearchCatalogItemsRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/SearchCatalogItemsResponse" } } } } }, "/v2/catalog/update-item-modifier-lists": { "post": { "tags": [ "Catalog" ], "summary": "UpdateItemModifierLists", "operationId": "UpdateItemModifierLists", "description": "Updates the [CatalogModifierList](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogModifierList) objects\nthat apply to the targeted [CatalogItem](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogItem) without having\nto perform an upsert on the entire item.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "ITEMS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ITEMS_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/UpdateItemModifierListsRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/UpdateItemModifierListsResponse" } } } } }, "/v2/catalog/update-item-taxes": { "post": { "tags": [ "Catalog" ], "summary": "UpdateItemTaxes", "operationId": "UpdateItemTaxes", "description": "Updates the [CatalogTax](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogTax) objects that apply to the\ntargeted [CatalogItem](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogItem) without having to perform an\nupsert on the entire item.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "ITEMS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ITEMS_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/UpdateItemTaxesRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/UpdateItemTaxesResponse" } } } } }, "/v2/customers": { "get": { "tags": [ "Customers" ], "summary": "ListCustomers", "operationId": "ListCustomers", "description": "Lists customer profiles associated with a Square account.\n\nUnder normal operating conditions, newly created or updated customer profiles become available\nfor the listing operation in well under 30 seconds. Occasionally, propagation of the new or updated\nprofiles can take closer to one minute or longer, especially during network incidents and outages.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "CUSTOMERS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CUSTOMERS_READ" ] } ], "parameters": [ { "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).", "type": "string", "in": "query", "required": false }, { "name": "limit", "description": "The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results.\nIf the specified limit is less than 1 or greater than 100, Square returns a `400 VALUE_TOO_LOW` or `400 VALUE_TOO_HIGH` error. The default value is 100.\n\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "type": "integer", "in": "query", "required": false }, { "name": "sort_field", "description": "Indicates how customers should be sorted.\n\nThe default value is `DEFAULT`.", "type": "string", "in": "query", "required": false }, { "name": "sort_order", "description": "Indicates whether customers should be sorted in ascending (`ASC`) or\ndescending (`DESC`) order.\n\nThe default value is `ASC`.", "type": "string", "in": "query", "required": false }, { "name": "count", "description": "Indicates whether to return the total count of customers in the `count` field of the response.\n\nThe default value is `false`.", "type": "boolean", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListCustomersResponse" } } } }, "post": { "tags": [ "Customers" ], "summary": "CreateCustomer", "operationId": "CreateCustomer", "description": "Creates a new customer for a business.\n\nYou must provide at least one of the following values in your request to this\nendpoint:\n\n- `given_name`\n- `family_name`\n- `company_name`\n- `email_address`\n- `phone_number`", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "CUSTOMERS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CUSTOMERS_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CreateCustomerRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CreateCustomerResponse" } } } } }, "/v2/customers/bulk-create": { "post": { "tags": [ "Customers" ], "summary": "BulkCreateCustomers", "operationId": "BulkCreateCustomers", "description": "Creates multiple [customer profiles](https://developer.squareup.com/reference/square_2024-10-17/objects/Customer) for a business.\n\nThis endpoint takes a map of individual create requests and returns a map of responses.\n\nYou must provide at least one of the following values in each create request:\n\n- `given_name`\n- `family_name`\n- `company_name`\n- `email_address`\n- `phone_number`", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "CUSTOMERS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CUSTOMERS_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/BulkCreateCustomersRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/BulkCreateCustomersResponse" } } } } }, "/v2/customers/bulk-delete": { "post": { "tags": [ "Customers" ], "summary": "BulkDeleteCustomers", "operationId": "BulkDeleteCustomers", "description": "Deletes multiple customer profiles.\n\nThe endpoint takes a list of customer IDs and returns a map of responses.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "CUSTOMERS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CUSTOMERS_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/BulkDeleteCustomersRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/BulkDeleteCustomersResponse" } } } } }, "/v2/customers/bulk-retrieve": { "post": { "tags": [ "Customers" ], "summary": "BulkRetrieveCustomers", "operationId": "BulkRetrieveCustomers", "description": "Retrieves multiple customer profiles.\n\nThis endpoint takes a list of customer IDs and returns a map of responses.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "CUSTOMERS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CUSTOMERS_READ" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/BulkRetrieveCustomersRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/BulkRetrieveCustomersResponse" } } } } }, "/v2/customers/bulk-update": { "post": { "tags": [ "Customers" ], "summary": "BulkUpdateCustomers", "operationId": "BulkUpdateCustomers", "description": "Updates multiple customer profiles.\n\nThis endpoint takes a map of individual update requests and returns a map of responses.\n\nYou cannot use this endpoint to change cards on file. To make changes, use the [Cards API](https://developer.squareup.com/reference/square_2024-10-17/cards-api) or [Gift Cards API](https://developer.squareup.com/reference/square_2024-10-17/gift-cards-api).", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "CUSTOMERS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CUSTOMERS_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/BulkUpdateCustomersRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/BulkUpdateCustomersResponse" } } } } }, "/v2/customers/custom-attribute-definitions": { "get": { "tags": [ "CustomerCustomAttributes" ], "summary": "ListCustomerCustomAttributeDefinitions", "operationId": "ListCustomerCustomAttributeDefinitions", "description": "Lists the customer-related [custom attribute definitions](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttributeDefinition) that belong to a Square seller account.\n\nWhen all response pages are retrieved, the results include all custom attribute definitions\nthat are visible to the requesting application, including those that are created by other\napplications and set to `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`. Note that\nseller-defined custom attributes (also known as custom fields) are always set to `VISIBILITY_READ_WRITE_VALUES`.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "CUSTOMERS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CUSTOMERS_READ" ] } ], "parameters": [ { "name": "limit", "description": "The maximum number of results to return in a single paged response. This limit is advisory.\nThe response might contain more or fewer results. The minimum value is 1 and the maximum value is 100.\nThe default value is 20. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "type": "integer", "in": "query", "required": false }, { "name": "cursor", "description": "The cursor returned in the paged response from the previous call to this endpoint.\nProvide this cursor to retrieve the next page of results for your original request.\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "type": "string", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListCustomerCustomAttributeDefinitionsResponse" } } } }, "post": { "tags": [ "CustomerCustomAttributes" ], "summary": "CreateCustomerCustomAttributeDefinition", "operationId": "CreateCustomerCustomAttributeDefinition", "description": "Creates a customer-related [custom attribute definition](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttributeDefinition) for a Square seller account.\nUse this endpoint to define a custom attribute that can be associated with customer profiles.\n\nA custom attribute definition specifies the `key`, `visibility`, `schema`, and other properties\nfor a custom attribute. After the definition is created, you can call\n[UpsertCustomerCustomAttribute](https://developer.squareup.com/reference/square_2024-10-17/customer-custom-attributes-api/upsert-customer-custom-attribute) or\n[BulkUpsertCustomerCustomAttributes](https://developer.squareup.com/reference/square_2024-10-17/customer-custom-attributes-api/bulk-upsert-customer-custom-attributes)\nto set the custom attribute for customer profiles in the seller\u0027s Customer Directory.\n\nSellers can view all custom attributes in exported customer data, including those set to\n`VISIBILITY_HIDDEN`.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "CUSTOMERS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CUSTOMERS_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CreateCustomerCustomAttributeDefinitionRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CreateCustomerCustomAttributeDefinitionResponse" } } } } }, "/v2/customers/custom-attribute-definitions/{key}": { "delete": { "tags": [ "CustomerCustomAttributes" ], "summary": "DeleteCustomerCustomAttributeDefinition", "operationId": "DeleteCustomerCustomAttributeDefinition", "description": "Deletes a customer-related [custom attribute definition](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttributeDefinition) from a Square seller account.\n\nDeleting a custom attribute definition also deletes the corresponding custom attribute from\nall customer profiles in the seller\u0027s Customer Directory.\n\nOnly the definition owner can delete a custom attribute definition.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "CUSTOMERS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CUSTOMERS_WRITE" ] } ], "parameters": [ { "name": "key", "description": "The key of the custom attribute definition to delete.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/DeleteCustomerCustomAttributeDefinitionResponse" } } } }, "get": { "tags": [ "CustomerCustomAttributes" ], "summary": "RetrieveCustomerCustomAttributeDefinition", "operationId": "RetrieveCustomerCustomAttributeDefinition", "description": "Retrieves a customer-related [custom attribute definition](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttributeDefinition) from a Square seller account.\n\nTo retrieve a custom attribute definition created by another application, the `visibility`\nsetting must be `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined custom attributes\n(also known as custom fields) are always set to `VISIBILITY_READ_WRITE_VALUES`.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "CUSTOMERS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CUSTOMERS_READ" ] } ], "parameters": [ { "name": "key", "description": "The key of the custom attribute definition to retrieve. If the requesting application\nis not the definition owner, you must use the qualified key.", "type": "string", "in": "path", "required": true }, { "name": "version", "description": "The current version of the custom attribute definition, which is used for strongly consistent\nreads to guarantee that you receive the most up-to-date data. When included in the request,\nSquare returns the specified version or a higher version if one exists. If the specified version\nis higher than the current version, Square returns a `BAD_REQUEST` error.", "type": "integer", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveCustomerCustomAttributeDefinitionResponse" } } } }, "put": { "tags": [ "CustomerCustomAttributes" ], "summary": "UpdateCustomerCustomAttributeDefinition", "operationId": "UpdateCustomerCustomAttributeDefinition", "description": "Updates a customer-related [custom attribute definition](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttributeDefinition) for a Square seller account.\n\nUse this endpoint to update the following fields: `name`, `description`, `visibility`, or the\n`schema` for a `Selection` data type.\n\nOnly the definition owner can update a custom attribute definition. Note that sellers can view\nall custom attributes in exported customer data, including those set to `VISIBILITY_HIDDEN`.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "CUSTOMERS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CUSTOMERS_WRITE" ] } ], "parameters": [ { "name": "key", "description": "The key of the custom attribute definition to update.", "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/UpdateCustomerCustomAttributeDefinitionRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/UpdateCustomerCustomAttributeDefinitionResponse" } } } } }, "/v2/customers/custom-attributes/bulk-upsert": { "post": { "tags": [ "CustomerCustomAttributes" ], "summary": "BulkUpsertCustomerCustomAttributes", "operationId": "BulkUpsertCustomerCustomAttributes", "description": "Creates or updates [custom attributes](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttribute) for customer profiles as a bulk operation.\n\nUse this endpoint to set the value of one or more custom attributes for one or more customer profiles.\nA custom attribute is based on a custom attribute definition in a Square seller account, which is\ncreated using the [CreateCustomerCustomAttributeDefinition](https://developer.squareup.com/reference/square_2024-10-17/customer-custom-attributes-api/create-customer-custom-attribute-definition) endpoint.\n\nThis `BulkUpsertCustomerCustomAttributes` endpoint accepts a map of 1 to 25 individual upsert\nrequests and returns a map of individual upsert responses. Each upsert request has a unique ID\nand provides a customer ID and custom attribute. Each upsert response is returned with the ID\nof the corresponding request.\n\nTo create or update a custom attribute owned by another application, the `visibility` setting\nmust be `VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined custom attributes\n(also known as custom fields) are always set to `VISIBILITY_READ_WRITE_VALUES`.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "CUSTOMERS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CUSTOMERS_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/BulkUpsertCustomerCustomAttributesRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/BulkUpsertCustomerCustomAttributesResponse" } } } } }, "/v2/customers/groups": { "get": { "tags": [ "CustomerGroups" ], "summary": "ListCustomerGroups", "operationId": "ListCustomerGroups", "description": "Retrieves the list of customer groups of a business.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "CUSTOMERS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CUSTOMERS_READ" ] } ], "parameters": [ { "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).", "type": "string", "in": "query", "required": false }, { "name": "limit", "description": "The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results.\nIf the limit is less than 1 or greater than 50, Square returns a `400 VALUE_TOO_LOW` or `400 VALUE_TOO_HIGH` error. The default value is 50.\n\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "type": "integer", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListCustomerGroupsResponse" } } } }, "post": { "tags": [ "CustomerGroups" ], "summary": "CreateCustomerGroup", "operationId": "CreateCustomerGroup", "description": "Creates a new customer group for a business.\n\nThe request must include the `name` value of the group.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "CUSTOMERS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CUSTOMERS_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CreateCustomerGroupRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CreateCustomerGroupResponse" } } } } }, "/v2/customers/groups/{group_id}": { "delete": { "tags": [ "CustomerGroups" ], "summary": "DeleteCustomerGroup", "operationId": "DeleteCustomerGroup", "description": "Deletes a customer group as identified by the `group_id` value.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "CUSTOMERS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CUSTOMERS_WRITE" ] } ], "parameters": [ { "name": "group_id", "description": "The ID of the customer group to delete.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/DeleteCustomerGroupResponse" } } } }, "get": { "tags": [ "CustomerGroups" ], "summary": "RetrieveCustomerGroup", "operationId": "RetrieveCustomerGroup", "description": "Retrieves a specific customer group as identified by the `group_id` value.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "CUSTOMERS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CUSTOMERS_READ" ] } ], "parameters": [ { "name": "group_id", "description": "The ID of the customer group to retrieve.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveCustomerGroupResponse" } } } }, "put": { "tags": [ "CustomerGroups" ], "summary": "UpdateCustomerGroup", "operationId": "UpdateCustomerGroup", "description": "Updates a customer group as identified by the `group_id` value.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "CUSTOMERS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CUSTOMERS_WRITE" ] } ], "parameters": [ { "name": "group_id", "description": "The ID of the customer group to update.", "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/UpdateCustomerGroupRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/UpdateCustomerGroupResponse" } } } } }, "/v2/customers/search": { "post": { "tags": [ "Customers" ], "summary": "SearchCustomers", "operationId": "SearchCustomers", "description": "Searches the customer profiles associated with a Square account using one or more supported query filters.\n\nCalling `SearchCustomers` without any explicit query filter returns all\ncustomer profiles ordered alphabetically based on `given_name` and\n`family_name`.\n\nUnder normal operating conditions, newly created or updated customer profiles become available\nfor the search operation in well under 30 seconds. Occasionally, propagation of the new or updated\nprofiles can take closer to one minute or longer, especially during network incidents and outages.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "CUSTOMERS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CUSTOMERS_READ" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/SearchCustomersRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/SearchCustomersResponse" } } } } }, "/v2/customers/segments": { "get": { "tags": [ "CustomerSegments" ], "summary": "ListCustomerSegments", "operationId": "ListCustomerSegments", "description": "Retrieves the list of customer segments of a business.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "CUSTOMERS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CUSTOMERS_READ" ] } ], "parameters": [ { "name": "cursor", "description": "A pagination cursor returned by previous calls to `ListCustomerSegments`.\nThis cursor is used to retrieve the next set of query results.\n\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "type": "string", "in": "query", "required": false }, { "name": "limit", "description": "The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results.\nIf the specified limit is less than 1 or greater than 50, Square returns a `400 VALUE_TOO_LOW` or `400 VALUE_TOO_HIGH` error. The default value is 50.\n\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "type": "integer", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListCustomerSegmentsResponse" } } } } }, "/v2/customers/segments/{segment_id}": { "get": { "tags": [ "CustomerSegments" ], "summary": "RetrieveCustomerSegment", "operationId": "RetrieveCustomerSegment", "description": "Retrieves a specific customer segment as identified by the `segment_id` value.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "CUSTOMERS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CUSTOMERS_READ" ] } ], "parameters": [ { "name": "segment_id", "description": "The Square-issued ID of the customer segment.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveCustomerSegmentResponse" } } } } }, "/v2/customers/{customer_id}": { "delete": { "tags": [ "Customers" ], "summary": "DeleteCustomer", "operationId": "DeleteCustomer", "description": "Deletes a customer profile from a business. This operation also unlinks any associated cards on file.\n\nTo delete a customer profile that was created by merging existing profiles, you must use the ID of the newly created profile.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "CUSTOMERS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CUSTOMERS_WRITE" ] } ], "parameters": [ { "name": "customer_id", "description": "The ID of the customer to delete.", "type": "string", "in": "path", "required": true }, { "name": "version", "description": "The current version of the customer profile.\n\nAs a best practice, you should include this parameter to enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) control. For more information, see [Delete a customer profile](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#delete-customer-profile).", "type": "integer", "format": "int64", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/DeleteCustomerResponse" } } } }, "get": { "tags": [ "Customers" ], "summary": "RetrieveCustomer", "operationId": "RetrieveCustomer", "description": "Returns details for a single customer.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "CUSTOMERS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CUSTOMERS_READ" ] } ], "parameters": [ { "name": "customer_id", "description": "The ID of the customer to retrieve.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveCustomerResponse" } } } }, "put": { "tags": [ "Customers" ], "summary": "UpdateCustomer", "operationId": "UpdateCustomer", "description": "Updates a customer profile. This endpoint supports sparse updates, so only new or changed fields are required in the request.\nTo add or update a field, specify the new value. To remove a field, specify `null`.\n\nTo update a customer profile that was created by merging existing profiles, you must use the ID of the newly created profile.\n\nYou cannot use this endpoint to change cards on file. To make changes, use the [Cards API](https://developer.squareup.com/reference/square_2024-10-17/cards-api) or [Gift Cards API](https://developer.squareup.com/reference/square_2024-10-17/gift-cards-api).", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "CUSTOMERS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CUSTOMERS_WRITE" ] } ], "parameters": [ { "name": "customer_id", "description": "The ID of the customer to update.", "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/UpdateCustomerRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/UpdateCustomerResponse" } } } } }, "/v2/customers/{customer_id}/cards": { "post": { "tags": [ "Customers" ], "summary": "CreateCustomerCard", "operationId": "CreateCustomerCard", "description": "Adds a card on file to an existing customer.\n\nAs with charges, calls to `CreateCustomerCard` are idempotent. Multiple\ncalls with the same card nonce return the same card record that was created\nwith the provided nonce during the _first_ call.", "x-release-status": "DEPRECATED", "x-is-deprecated": true, "x-oauthpermissions": [ "CUSTOMERS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CUSTOMERS_WRITE" ] } ], "parameters": [ { "name": "customer_id", "description": "The Square ID of the customer profile the card is linked to.", "x-is-deprecated": true, "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CreateCustomerCardRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CreateCustomerCardResponse" } } } } }, "/v2/customers/{customer_id}/cards/{card_id}": { "delete": { "tags": [ "Customers" ], "summary": "DeleteCustomerCard", "operationId": "DeleteCustomerCard", "description": "Removes a card on file from a customer.", "x-release-status": "DEPRECATED", "x-is-deprecated": true, "x-oauthpermissions": [ "CUSTOMERS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CUSTOMERS_WRITE" ] } ], "parameters": [ { "name": "customer_id", "description": "The ID of the customer that the card on file belongs to.", "x-is-deprecated": true, "type": "string", "in": "path", "required": true }, { "name": "card_id", "description": "The ID of the card on file to delete.", "x-is-deprecated": true, "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/DeleteCustomerCardResponse" } } } } }, "/v2/customers/{customer_id}/custom-attributes": { "get": { "tags": [ "CustomerCustomAttributes" ], "summary": "ListCustomerCustomAttributes", "operationId": "ListCustomerCustomAttributes", "description": "Lists the [custom attributes](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttribute) associated with a customer profile.\n\nYou can use the `with_definitions` query parameter to also retrieve custom attribute definitions\nin the same call.\n\nWhen all response pages are retrieved, the results include all custom attributes that are\nvisible to the requesting application, including those that are owned by other applications\nand set to `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "CUSTOMERS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CUSTOMERS_READ" ] } ], "parameters": [ { "name": "customer_id", "description": "The ID of the target [customer profile](https://developer.squareup.com/reference/square_2024-10-17/objects/Customer).", "type": "string", "in": "path", "required": true }, { "name": "limit", "description": "The maximum number of results to return in a single paged response. This limit is advisory.\nThe response might contain more or fewer results. The minimum value is 1 and the maximum value is 100.\nThe default value is 20. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "type": "integer", "in": "query", "required": false }, { "name": "cursor", "description": "The cursor returned in the paged response from the previous call to this endpoint.\nProvide this cursor to retrieve the next page of results for your original request. For more\ninformation, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "type": "string", "in": "query", "required": false }, { "name": "with_definitions", "description": "Indicates whether to return the [custom attribute definition](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttributeDefinition) in the `definition` field of each\ncustom attribute. Set this parameter to `true` to get the name and description of each custom\nattribute, information about the data type, or other definition details. The default value is `false`.", "type": "boolean", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListCustomerCustomAttributesResponse" } } } } }, "/v2/customers/{customer_id}/custom-attributes/{key}": { "delete": { "tags": [ "CustomerCustomAttributes" ], "summary": "DeleteCustomerCustomAttribute", "operationId": "DeleteCustomerCustomAttribute", "description": "Deletes a [custom attribute](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttribute) associated with a customer profile.\n\nTo delete a custom attribute owned by another application, the `visibility` setting must be\n`VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined custom attributes\n(also known as custom fields) are always set to `VISIBILITY_READ_WRITE_VALUES`.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "CUSTOMERS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CUSTOMERS_WRITE" ] } ], "parameters": [ { "name": "customer_id", "description": "The ID of the target [customer profile](https://developer.squareup.com/reference/square_2024-10-17/objects/Customer).", "type": "string", "in": "path", "required": true }, { "name": "key", "description": "The key of the custom attribute to delete. This key must match the `key` of a custom\nattribute definition in the Square seller account. If the requesting application is not the\ndefinition owner, you must use the qualified key.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/DeleteCustomerCustomAttributeResponse" } } } }, "get": { "tags": [ "CustomerCustomAttributes" ], "summary": "RetrieveCustomerCustomAttribute", "operationId": "RetrieveCustomerCustomAttribute", "description": "Retrieves a [custom attribute](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttribute) associated with a customer profile.\n\nYou can use the `with_definition` query parameter to also retrieve the custom attribute definition\nin the same call.\n\nTo retrieve a custom attribute owned by another application, the `visibility` setting must be\n`VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined custom attributes\n(also known as custom fields) are always set to `VISIBILITY_READ_WRITE_VALUES`.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "CUSTOMERS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CUSTOMERS_READ" ] } ], "parameters": [ { "name": "customer_id", "description": "The ID of the target [customer profile](https://developer.squareup.com/reference/square_2024-10-17/objects/Customer).", "type": "string", "in": "path", "required": true }, { "name": "key", "description": "The key of the custom attribute to retrieve. This key must match the `key` of a custom\nattribute definition in the Square seller account. If the requesting application is not the\ndefinition owner, you must use the qualified key.", "type": "string", "in": "path", "required": true }, { "name": "with_definition", "description": "Indicates whether to return the [custom attribute definition](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttributeDefinition) in the `definition` field of\nthe custom attribute. Set this parameter to `true` to get the name and description of the custom\nattribute, information about the data type, or other definition details. The default value is `false`.", "type": "boolean", "in": "query", "required": false }, { "name": "version", "description": "The current version of the custom attribute, which is used for strongly consistent reads to\nguarantee that you receive the most up-to-date data. When included in the request, Square\nreturns the specified version or a higher version if one exists. If the specified version is\nhigher than the current version, Square returns a `BAD_REQUEST` error.", "type": "integer", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveCustomerCustomAttributeResponse" } } } }, "post": { "tags": [ "CustomerCustomAttributes" ], "summary": "UpsertCustomerCustomAttribute", "operationId": "UpsertCustomerCustomAttribute", "description": "Creates or updates a [custom attribute](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttribute) for a customer profile.\n\nUse this endpoint to set the value of a custom attribute for a specified customer profile.\nA custom attribute is based on a custom attribute definition in a Square seller account, which\nis created using the [CreateCustomerCustomAttributeDefinition](https://developer.squareup.com/reference/square_2024-10-17/customer-custom-attributes-api/create-customer-custom-attribute-definition) endpoint.\n\nTo create or update a custom attribute owned by another application, the `visibility` setting\nmust be `VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined custom attributes\n(also known as custom fields) are always set to `VISIBILITY_READ_WRITE_VALUES`.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "CUSTOMERS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CUSTOMERS_WRITE" ] } ], "parameters": [ { "name": "customer_id", "description": "The ID of the target [customer profile](https://developer.squareup.com/reference/square_2024-10-17/objects/Customer).", "type": "string", "in": "path", "required": true }, { "name": "key", "description": "The key of the custom attribute to create or update. This key must match the `key` of a\ncustom attribute definition in the Square seller account. If the requesting application is not\nthe definition owner, you must use the qualified key.", "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/UpsertCustomerCustomAttributeRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/UpsertCustomerCustomAttributeResponse" } } } } }, "/v2/customers/{customer_id}/groups/{group_id}": { "delete": { "tags": [ "Customers" ], "summary": "RemoveGroupFromCustomer", "operationId": "RemoveGroupFromCustomer", "description": "Removes a group membership from a customer.\n\nThe customer is identified by the `customer_id` value\nand the customer group is identified by the `group_id` value.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "CUSTOMERS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CUSTOMERS_WRITE" ] } ], "parameters": [ { "name": "customer_id", "description": "The ID of the customer to remove from the group.", "type": "string", "in": "path", "required": true }, { "name": "group_id", "description": "The ID of the customer group to remove the customer from.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RemoveGroupFromCustomerResponse" } } } }, "put": { "tags": [ "Customers" ], "summary": "AddGroupToCustomer", "operationId": "AddGroupToCustomer", "description": "Adds a group membership to a customer.\n\nThe customer is identified by the `customer_id` value\nand the customer group is identified by the `group_id` value.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "CUSTOMERS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CUSTOMERS_WRITE" ] } ], "parameters": [ { "name": "customer_id", "description": "The ID of the customer to add to a group.", "type": "string", "in": "path", "required": true }, { "name": "group_id", "description": "The ID of the customer group to add the customer to.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/AddGroupToCustomerResponse" } } } } }, "/v2/devices": { "get": { "tags": [ "Devices" ], "summary": "ListDevices", "operationId": "ListDevices", "description": "List devices associated with the merchant. Currently, only Terminal API\ndevices are supported.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "DEVICES_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "DEVICES_READ" ] } ], "parameters": [ { "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 the original query.\nSee [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination) for more information.", "x-is-beta": true, "type": "string", "in": "query", "required": false }, { "name": "sort_order", "description": "The order in which results are listed.\n- `ASC` - Oldest to newest.\n- `DESC` - Newest to oldest (default).", "x-is-beta": true, "type": "string", "in": "query", "required": false }, { "name": "limit", "description": "The number of results to return in a single page.", "x-is-beta": true, "type": "integer", "in": "query", "required": false }, { "name": "location_id", "description": "If present, only returns devices at the target location.", "x-is-beta": true, "type": "string", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListDevicesResponse" } } } } }, "/v2/devices/codes": { "get": { "tags": [ "Devices" ], "summary": "ListDeviceCodes", "operationId": "ListDeviceCodes", "description": "Lists all DeviceCodes associated with the merchant.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "DEVICE_CREDENTIAL_MANAGEMENT" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "DEVICE_CREDENTIAL_MANAGEMENT" ] } ], "parameters": [ { "name": "cursor", "description": "A pagination cursor returned by a previous call to this endpoint.\nProvide this to retrieve the next set of results for your original query.\n\nSee [Paginating results](https://developer.squareup.com/docs/working-with-apis/pagination) for more information.", "type": "string", "in": "query", "required": false }, { "name": "location_id", "description": "If specified, only returns DeviceCodes of the specified location.\nReturns DeviceCodes of all locations if empty.", "type": "string", "in": "query", "required": false }, { "name": "product_type", "description": "If specified, only returns DeviceCodes targeting the specified product type.\nReturns DeviceCodes of all product types if empty.", "type": "string", "in": "query", "required": false }, { "name": "status", "description": "If specified, returns DeviceCodes with the specified statuses.\nReturns DeviceCodes of status `PAIRED` and `UNPAIRED` if empty.", "type": "string", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListDeviceCodesResponse" } } } }, "post": { "tags": [ "Devices" ], "summary": "CreateDeviceCode", "operationId": "CreateDeviceCode", "description": "Creates a DeviceCode that can be used to login to a Square Terminal device to enter the connected\nterminal mode.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "DEVICE_CREDENTIAL_MANAGEMENT" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "DEVICE_CREDENTIAL_MANAGEMENT" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CreateDeviceCodeRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CreateDeviceCodeResponse" } } } } }, "/v2/devices/codes/{id}": { "get": { "tags": [ "Devices" ], "summary": "GetDeviceCode", "operationId": "GetDeviceCode", "description": "Retrieves DeviceCode with the associated ID.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "DEVICE_CREDENTIAL_MANAGEMENT" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "DEVICE_CREDENTIAL_MANAGEMENT" ] } ], "parameters": [ { "name": "id", "description": "The unique identifier for the device code.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/GetDeviceCodeResponse" } } } } }, "/v2/devices/{device_id}": { "get": { "tags": [ "Devices" ], "summary": "GetDevice", "operationId": "GetDevice", "description": "Retrieves Device with the associated `device_id`.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "DEVICES_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "DEVICES_READ" ] } ], "parameters": [ { "name": "device_id", "description": "The unique ID for the desired `Device`.", "x-is-beta": true, "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/GetDeviceResponse" } } } } }, "/v2/disputes": { "get": { "tags": [ "Disputes" ], "summary": "ListDisputes", "operationId": "ListDisputes", "description": "Returns a list of disputes associated with a particular account.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "DISPUTES_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "DISPUTES_READ" ] } ], "parameters": [ { "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 the original query.\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "type": "string", "in": "query", "required": false }, { "name": "states", "description": "The dispute states used to filter the result. If not specified, the endpoint returns all disputes.", "type": "string", "in": "query", "required": false }, { "name": "location_id", "description": "The ID of the location for which to return a list of disputes.\nIf not specified, the endpoint returns disputes associated with all locations.", "type": "string", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListDisputesResponse" } } } } }, "/v2/disputes/{dispute_id}": { "get": { "tags": [ "Disputes" ], "summary": "RetrieveDispute", "operationId": "RetrieveDispute", "description": "Returns details about a specific dispute.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "DISPUTES_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "DISPUTES_READ" ] } ], "parameters": [ { "name": "dispute_id", "description": "The ID of the dispute you want more details about.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveDisputeResponse" } } } } }, "/v2/disputes/{dispute_id}/accept": { "post": { "tags": [ "Disputes" ], "summary": "AcceptDispute", "operationId": "AcceptDispute", "description": "Accepts the loss on a dispute. Square returns the disputed amount to the cardholder and\nupdates the dispute state to ACCEPTED.\n\nSquare debits the disputed amount from the seller’s Square account. If the Square account\ndoes not have sufficient funds, Square debits the associated bank account.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "DISPUTES_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "DISPUTES_WRITE" ] } ], "parameters": [ { "name": "dispute_id", "description": "The ID of the dispute you want to accept.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/AcceptDisputeResponse" } } } } }, "/v2/disputes/{dispute_id}/evidence": { "get": { "tags": [ "Disputes" ], "summary": "ListDisputeEvidence", "operationId": "ListDisputeEvidence", "description": "Returns a list of evidence associated with a dispute.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "DISPUTES_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "DISPUTES_READ" ] } ], "parameters": [ { "name": "dispute_id", "description": "The ID of the dispute.", "type": "string", "in": "path", "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 the original query.\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "type": "string", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListDisputeEvidenceResponse" } } } } }, "/v2/disputes/{dispute_id}/evidence-text": { "post": { "tags": [ "Disputes" ], "summary": "CreateDisputeEvidenceText", "operationId": "CreateDisputeEvidenceText", "description": "Uploads text to use as evidence for a dispute challenge.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "DISPUTES_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "DISPUTES_WRITE" ] } ], "parameters": [ { "name": "dispute_id", "description": "The ID of the dispute for which you want to upload evidence.", "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CreateDisputeEvidenceTextRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CreateDisputeEvidenceTextResponse" } } } } }, "/v2/disputes/{dispute_id}/evidence/{evidence_id}": { "delete": { "tags": [ "Disputes" ], "summary": "DeleteDisputeEvidence", "operationId": "DeleteDisputeEvidence", "description": "Removes specified evidence from a dispute.\nSquare does not send the bank any evidence that is removed.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "DISPUTES_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "DISPUTES_WRITE" ] } ], "parameters": [ { "name": "dispute_id", "description": "The ID of the dispute from which you want to remove evidence.", "type": "string", "in": "path", "required": true }, { "name": "evidence_id", "description": "The ID of the evidence you want to remove.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/DeleteDisputeEvidenceResponse" } } } }, "get": { "tags": [ "Disputes" ], "summary": "RetrieveDisputeEvidence", "operationId": "RetrieveDisputeEvidence", "description": "Returns the metadata for the evidence specified in the request URL path.\n\nYou must maintain a copy of any evidence uploaded if you want to reference it later. Evidence cannot be downloaded after you upload it.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "DISPUTES_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "DISPUTES_READ" ] } ], "parameters": [ { "name": "dispute_id", "description": "The ID of the dispute from which you want to retrieve evidence metadata.", "type": "string", "in": "path", "required": true }, { "name": "evidence_id", "description": "The ID of the evidence to retrieve.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveDisputeEvidenceResponse" } } } } }, "/v2/disputes/{dispute_id}/submit-evidence": { "post": { "tags": [ "Disputes" ], "summary": "SubmitEvidence", "operationId": "SubmitEvidence", "description": "Submits evidence to the cardholder\u0027s bank.\n\nThe evidence submitted by this endpoint includes evidence uploaded\nusing the [CreateDisputeEvidenceFile](https://developer.squareup.com/reference/square_2024-10-17/disputes-api/create-dispute-evidence-file) and\n[CreateDisputeEvidenceText](https://developer.squareup.com/reference/square_2024-10-17/disputes-api/create-dispute-evidence-text) endpoints and\nevidence automatically provided by Square, when available. Evidence cannot be removed from\na dispute after submission.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "DISPUTES_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "DISPUTES_WRITE" ] } ], "parameters": [ { "name": "dispute_id", "description": "The ID of the dispute for which you want to submit evidence.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/SubmitEvidenceResponse" } } } } }, "/v2/employees": { "get": { "tags": [ "Employees" ], "summary": "ListEmployees", "operationId": "ListEmployees", "description": "", "x-release-status": "DEPRECATED", "x-is-deprecated": true, "x-oauthpermissions": [ "EMPLOYEES_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "EMPLOYEES_READ" ] } ], "parameters": [ { "name": "location_id", "description": "", "x-is-deprecated": true, "type": "string", "in": "query", "required": false }, { "name": "status", "description": "Specifies the EmployeeStatus to filter the employee by.", "x-is-deprecated": true, "type": "string", "in": "query", "required": false }, { "name": "limit", "description": "The number of employees to be returned on each page.", "x-is-deprecated": true, "type": "integer", "in": "query", "required": false }, { "name": "cursor", "description": "The token required to retrieve the specified page of results.", "x-is-deprecated": true, "type": "string", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListEmployeesResponse" } } } } }, "/v2/employees/{id}": { "get": { "tags": [ "Employees" ], "summary": "RetrieveEmployee", "operationId": "RetrieveEmployee", "description": "", "x-release-status": "DEPRECATED", "x-is-deprecated": true, "x-oauthpermissions": [ "EMPLOYEES_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "EMPLOYEES_READ" ] } ], "parameters": [ { "name": "id", "description": "UUID for the employee that was requested.", "x-is-deprecated": true, "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveEmployeeResponse" } } } } }, "/v2/events": { "post": { "tags": [ "Events" ], "summary": "SearchEvents", "operationId": "SearchEvents", "description": "Search for Square API events that occur within a 28-day timeframe.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/SearchEventsRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/SearchEventsResponse" } } } } }, "/v2/events/disable": { "put": { "tags": [ "Events" ], "summary": "DisableEvents", "operationId": "DisableEvents", "description": "Disables events to prevent them from being searchable.\nAll events are disabled by default. You must enable events to make them searchable.\nDisabling events for a specific time period prevents them from being searchable, even if you re-enable them later.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [] } ], "parameters": [], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/DisableEventsResponse" } } } } }, "/v2/events/enable": { "put": { "tags": [ "Events" ], "summary": "EnableEvents", "operationId": "EnableEvents", "description": "Enables events to make them searchable. Only events that occur while in the enabled state are searchable.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [] } ], "parameters": [], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/EnableEventsResponse" } } } } }, "/v2/events/types": { "get": { "tags": [ "Events" ], "summary": "ListEventTypes", "operationId": "ListEventTypes", "description": "Lists all event types that you can subscribe to as webhooks or query using the Events API.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [] } ], "parameters": [ { "name": "api_version", "description": "The API version for which to list event types. Setting this field overrides the default version used by the application.", "x-is-beta": true, "type": "string", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListEventTypesResponse" } } } } }, "/v2/gift-cards": { "get": { "tags": [ "GiftCards" ], "summary": "ListGiftCards", "operationId": "ListGiftCards", "description": "Lists all gift cards. You can specify optional filters to retrieve \na subset of the gift cards. Results are sorted by `created_at` in ascending order.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "GIFTCARDS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "GIFTCARDS_READ" ] } ], "parameters": [ { "name": "type", "description": "If a [type](https://developer.squareup.com/reference/square_2024-10-17/enums/GiftCardType) is provided, the endpoint returns gift cards of the specified type.\nOtherwise, the endpoint returns gift cards of all types.", "type": "string", "in": "query", "required": false }, { "name": "state", "description": "If a [state](https://developer.squareup.com/reference/square_2024-10-17/enums/GiftCardStatus) is provided, the endpoint returns the gift cards in the specified state.\nOtherwise, the endpoint returns the gift cards of all states.", "type": "string", "in": "query", "required": false }, { "name": "limit", "description": "If a limit is provided, the endpoint returns only the specified number of results per page.\nThe maximum value is 200. The default value is 30.\nFor more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).", "type": "integer", "in": "query", "required": false }, { "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 the original query.\nIf a cursor is not provided, the endpoint returns the first page of the results. \nFor more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).", "type": "string", "in": "query", "required": false }, { "name": "customer_id", "description": "If a customer ID is provided, the endpoint returns only the gift cards linked to the specified customer.", "type": "string", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListGiftCardsResponse" } } } }, "post": { "tags": [ "GiftCards" ], "summary": "CreateGiftCard", "operationId": "CreateGiftCard", "description": "Creates a digital gift card or registers a physical (plastic) gift card. The resulting gift card\nhas a `PENDING` state. To activate a gift card so that it can be redeemed for purchases, call\n[CreateGiftCardActivity](https://developer.squareup.com/reference/square_2024-10-17/gift-card-activities-api/create-gift-card-activity) and create an `ACTIVATE`\nactivity with the initial balance. Alternatively, you can use [RefundPayment](https://developer.squareup.com/reference/square_2024-10-17/refunds-api/refund-payment)\nto refund a payment to the new gift card.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "GIFTCARDS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "GIFTCARDS_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CreateGiftCardRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CreateGiftCardResponse" } } } } }, "/v2/gift-cards/activities": { "get": { "tags": [ "GiftCardActivities" ], "summary": "ListGiftCardActivities", "operationId": "ListGiftCardActivities", "description": "Lists gift card activities. By default, you get gift card activities for all\ngift cards in the seller\u0027s account. You can optionally specify query parameters to\nfilter the list. For example, you can get a list of gift card activities for a gift card,\nfor all gift cards in a specific region, or for activities within a time window.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "GIFTCARDS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "GIFTCARDS_READ" ] } ], "parameters": [ { "name": "gift_card_id", "description": "If a gift card ID is provided, the endpoint returns activities related \nto the specified gift card. Otherwise, the endpoint returns all gift card activities for \nthe seller.", "type": "string", "in": "query", "required": false }, { "name": "type", "description": "If a [type](https://developer.squareup.com/reference/square_2024-10-17/objects/GiftCardActivityType) is provided, the endpoint returns gift card activities of the specified type. \nOtherwise, the endpoint returns all types of gift card activities.", "type": "string", "in": "query", "required": false }, { "name": "location_id", "description": "If a location ID is provided, the endpoint returns gift card activities for the specified location. \nOtherwise, the endpoint returns gift card activities for all locations.", "type": "string", "in": "query", "required": false }, { "name": "begin_time", "description": "The timestamp for the beginning of the reporting period, in RFC 3339 format.\nThis start time is inclusive. The default value is the current time minus one year.", "type": "string", "in": "query", "required": false }, { "name": "end_time", "description": "The timestamp for the end of the reporting period, in RFC 3339 format.\nThis end time is inclusive. The default value is the current time.", "type": "string", "in": "query", "required": false }, { "name": "limit", "description": "If a limit is provided, the endpoint returns the specified number \nof results (or fewer) per page. The maximum value is 100. The default value is 50.\nFor more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).", "type": "integer", "in": "query", "required": false }, { "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 the original query.\nIf a cursor is not provided, the endpoint returns the first page of the results.\nFor more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).", "type": "string", "in": "query", "required": false }, { "name": "sort_order", "description": "The order in which the endpoint returns the activities, based on `created_at`.\n- `ASC` - Oldest to newest.\n- `DESC` - Newest to oldest (default).", "type": "string", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListGiftCardActivitiesResponse" } } } }, "post": { "tags": [ "GiftCardActivities" ], "summary": "CreateGiftCardActivity", "operationId": "CreateGiftCardActivity", "description": "Creates a gift card activity to manage the balance or state of a [gift card](https://developer.squareup.com/reference/square_2024-10-17/objects/GiftCard).\nFor example, create an `ACTIVATE` activity to activate a gift card with an initial balance before first use.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "GIFTCARDS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "GIFTCARDS_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CreateGiftCardActivityRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CreateGiftCardActivityResponse" } } } } }, "/v2/gift-cards/from-gan": { "post": { "tags": [ "GiftCards" ], "summary": "RetrieveGiftCardFromGAN", "operationId": "RetrieveGiftCardFromGAN", "description": "Retrieves a gift card using the gift card account number (GAN).", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "GIFTCARDS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "GIFTCARDS_READ" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/RetrieveGiftCardFromGANRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveGiftCardFromGANResponse" } } } } }, "/v2/gift-cards/from-nonce": { "post": { "tags": [ "GiftCards" ], "summary": "RetrieveGiftCardFromNonce", "operationId": "RetrieveGiftCardFromNonce", "description": "Retrieves a gift card using a secure payment token that represents the gift card.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "GIFTCARDS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "GIFTCARDS_READ" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/RetrieveGiftCardFromNonceRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveGiftCardFromNonceResponse" } } } } }, "/v2/gift-cards/{gift_card_id}/link-customer": { "post": { "tags": [ "GiftCards" ], "summary": "LinkCustomerToGiftCard", "operationId": "LinkCustomerToGiftCard", "description": "Links a customer to a gift card, which is also referred to as adding a card on file.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "GIFTCARDS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "GIFTCARDS_WRITE" ] } ], "parameters": [ { "name": "gift_card_id", "description": "The ID of the gift card to be linked.", "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/LinkCustomerToGiftCardRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/LinkCustomerToGiftCardResponse" } } } } }, "/v2/gift-cards/{gift_card_id}/unlink-customer": { "post": { "tags": [ "GiftCards" ], "summary": "UnlinkCustomerFromGiftCard", "operationId": "UnlinkCustomerFromGiftCard", "description": "Unlinks a customer from a gift card, which is also referred to as removing a card on file.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "GIFTCARDS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "GIFTCARDS_WRITE" ] } ], "parameters": [ { "name": "gift_card_id", "description": "The ID of the gift card to be unlinked.", "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/UnlinkCustomerFromGiftCardRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/UnlinkCustomerFromGiftCardResponse" } } } } }, "/v2/gift-cards/{id}": { "get": { "tags": [ "GiftCards" ], "summary": "RetrieveGiftCard", "operationId": "RetrieveGiftCard", "description": "Retrieves a gift card using the gift card ID.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "GIFTCARDS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "GIFTCARDS_READ" ] } ], "parameters": [ { "name": "id", "description": "The ID of the gift card to retrieve.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveGiftCardResponse" } } } } }, "/v2/inventory/adjustment/{adjustment_id}": { "get": { "tags": [ "Inventory" ], "summary": "DeprecatedRetrieveInventoryAdjustment", "operationId": "DeprecatedRetrieveInventoryAdjustment", "description": "Deprecated version of [RetrieveInventoryAdjustment](https://developer.squareup.com/reference/square_2024-10-17/inventory-api/retrieve-inventory-adjustment) after the endpoint URL\nis updated to conform to the standard convention.", "x-release-status": "DEPRECATED", "x-is-deprecated": true, "x-oauthpermissions": [ "INVENTORY_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "INVENTORY_READ" ] } ], "parameters": [ { "name": "adjustment_id", "description": "ID of the [InventoryAdjustment](https://developer.squareup.com/reference/square_2024-10-17/objects/InventoryAdjustment) to retrieve.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveInventoryAdjustmentResponse" } } } } }, "/v2/inventory/adjustments/{adjustment_id}": { "get": { "tags": [ "Inventory" ], "summary": "RetrieveInventoryAdjustment", "operationId": "RetrieveInventoryAdjustment", "description": "Returns the [InventoryAdjustment](https://developer.squareup.com/reference/square_2024-10-17/objects/InventoryAdjustment) object\nwith the provided `adjustment_id`.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "INVENTORY_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "INVENTORY_READ" ] } ], "parameters": [ { "name": "adjustment_id", "description": "ID of the [InventoryAdjustment](https://developer.squareup.com/reference/square_2024-10-17/objects/InventoryAdjustment) to retrieve.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveInventoryAdjustmentResponse" } } } } }, "/v2/inventory/batch-change": { "post": { "tags": [ "Inventory" ], "summary": "DeprecatedBatchChangeInventory", "operationId": "DeprecatedBatchChangeInventory", "description": "Deprecated version of [BatchChangeInventory](https://developer.squareup.com/reference/square_2024-10-17/inventory-api/batch-change-inventory) after the endpoint URL\nis updated to conform to the standard convention.", "x-release-status": "DEPRECATED", "x-is-deprecated": true, "x-oauthpermissions": [ "INVENTORY_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "INVENTORY_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/BatchChangeInventoryRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/BatchChangeInventoryResponse" } } } } }, "/v2/inventory/batch-retrieve-changes": { "post": { "tags": [ "Inventory" ], "summary": "DeprecatedBatchRetrieveInventoryChanges", "operationId": "DeprecatedBatchRetrieveInventoryChanges", "description": "Deprecated version of [BatchRetrieveInventoryChanges](https://developer.squareup.com/reference/square_2024-10-17/inventory-api/batch-retrieve-inventory-changes) after the endpoint URL\nis updated to conform to the standard convention.", "x-release-status": "DEPRECATED", "x-is-deprecated": true, "x-oauthpermissions": [ "INVENTORY_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "INVENTORY_READ" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/BatchRetrieveInventoryChangesRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/BatchRetrieveInventoryChangesResponse" } } } } }, "/v2/inventory/batch-retrieve-counts": { "post": { "tags": [ "Inventory" ], "summary": "DeprecatedBatchRetrieveInventoryCounts", "operationId": "DeprecatedBatchRetrieveInventoryCounts", "description": "Deprecated version of [BatchRetrieveInventoryCounts](https://developer.squareup.com/reference/square_2024-10-17/inventory-api/batch-retrieve-inventory-counts) after the endpoint URL\nis updated to conform to the standard convention.", "x-release-status": "DEPRECATED", "x-is-deprecated": true, "x-oauthpermissions": [ "INVENTORY_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "INVENTORY_READ" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/BatchRetrieveInventoryCountsRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/BatchRetrieveInventoryCountsResponse" } } } } }, "/v2/inventory/changes/batch-create": { "post": { "tags": [ "Inventory" ], "summary": "BatchChangeInventory", "operationId": "BatchChangeInventory", "description": "Applies adjustments and counts to the provided item quantities.\n\nOn success: returns the current calculated counts for all objects\nreferenced in the request.\nOn failure: returns a list of related errors.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "INVENTORY_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "INVENTORY_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/BatchChangeInventoryRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/BatchChangeInventoryResponse" } } } } }, "/v2/inventory/changes/batch-retrieve": { "post": { "tags": [ "Inventory" ], "summary": "BatchRetrieveInventoryChanges", "operationId": "BatchRetrieveInventoryChanges", "description": "Returns historical physical counts and adjustments based on the\nprovided filter criteria.\n\nResults are paginated and sorted in ascending order according their\n`occurred_at` timestamp (oldest first).\n\nBatchRetrieveInventoryChanges is a catch-all query endpoint for queries\nthat cannot be handled by other, simpler endpoints.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "INVENTORY_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "INVENTORY_READ" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/BatchRetrieveInventoryChangesRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/BatchRetrieveInventoryChangesResponse" } } } } }, "/v2/inventory/counts/batch-retrieve": { "post": { "tags": [ "Inventory" ], "summary": "BatchRetrieveInventoryCounts", "operationId": "BatchRetrieveInventoryCounts", "description": "Returns current counts for the provided\n[CatalogObject](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogObject)s at the requested\n[Location](https://developer.squareup.com/reference/square_2024-10-17/objects/Location)s.\n\nResults are paginated and sorted in descending order according to their\n`calculated_at` timestamp (newest first).\n\nWhen `updated_after` is specified, only counts that have changed since that\ntime (based on the server timestamp for the most recent change) are\nreturned. This allows clients to perform a \"sync\" operation, for example\nin response to receiving a Webhook notification.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "INVENTORY_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "INVENTORY_READ" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/BatchRetrieveInventoryCountsRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/BatchRetrieveInventoryCountsResponse" } } } } }, "/v2/inventory/physical-count/{physical_count_id}": { "get": { "tags": [ "Inventory" ], "summary": "DeprecatedRetrieveInventoryPhysicalCount", "operationId": "DeprecatedRetrieveInventoryPhysicalCount", "description": "Deprecated version of [RetrieveInventoryPhysicalCount](https://developer.squareup.com/reference/square_2024-10-17/inventory-api/retrieve-inventory-physical-count) after the endpoint URL\nis updated to conform to the standard convention.", "x-release-status": "DEPRECATED", "x-is-deprecated": true, "x-oauthpermissions": [ "INVENTORY_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "INVENTORY_READ" ] } ], "parameters": [ { "name": "physical_count_id", "description": "ID of the\n[InventoryPhysicalCount](https://developer.squareup.com/reference/square_2024-10-17/objects/InventoryPhysicalCount) to retrieve.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveInventoryPhysicalCountResponse" } } } } }, "/v2/inventory/physical-counts/{physical_count_id}": { "get": { "tags": [ "Inventory" ], "summary": "RetrieveInventoryPhysicalCount", "operationId": "RetrieveInventoryPhysicalCount", "description": "Returns the [InventoryPhysicalCount](https://developer.squareup.com/reference/square_2024-10-17/objects/InventoryPhysicalCount)\nobject with the provided `physical_count_id`.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "INVENTORY_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "INVENTORY_READ" ] } ], "parameters": [ { "name": "physical_count_id", "description": "ID of the\n[InventoryPhysicalCount](https://developer.squareup.com/reference/square_2024-10-17/objects/InventoryPhysicalCount) to retrieve.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveInventoryPhysicalCountResponse" } } } } }, "/v2/inventory/transfers/{transfer_id}": { "get": { "tags": [ "Inventory" ], "summary": "RetrieveInventoryTransfer", "operationId": "RetrieveInventoryTransfer", "description": "Returns the [InventoryTransfer](https://developer.squareup.com/reference/square_2024-10-17/objects/InventoryTransfer) object\nwith the provided `transfer_id`.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "INVENTORY_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "INVENTORY_READ" ] } ], "parameters": [ { "name": "transfer_id", "description": "ID of the [InventoryTransfer](https://developer.squareup.com/reference/square_2024-10-17/objects/InventoryTransfer) to retrieve.", "x-is-beta": true, "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveInventoryTransferResponse" } } } } }, "/v2/inventory/{catalog_object_id}": { "get": { "tags": [ "Inventory" ], "summary": "RetrieveInventoryCount", "operationId": "RetrieveInventoryCount", "description": "Retrieves the current calculated stock count for a given\n[CatalogObject](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogObject) at a given set of\n[Location](https://developer.squareup.com/reference/square_2024-10-17/objects/Location)s. Responses are paginated and unsorted.\nFor more sophisticated queries, use a batch endpoint.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "INVENTORY_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "INVENTORY_READ" ] } ], "parameters": [ { "name": "catalog_object_id", "description": "ID of the [CatalogObject](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogObject) to retrieve.", "type": "string", "in": "path", "required": true }, { "name": "location_ids", "description": "The [Location](https://developer.squareup.com/reference/square_2024-10-17/objects/Location) IDs to look up as a comma-separated\nlist. An empty list queries all locations.", "type": "string", "in": "query", "required": false }, { "name": "cursor", "description": "A pagination cursor returned by a previous call to this endpoint.\nProvide this to retrieve the next set of results for the original query.\n\nSee the [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination) guide for more information.", "type": "string", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveInventoryCountResponse" } } } } }, "/v2/inventory/{catalog_object_id}/changes": { "get": { "tags": [ "Inventory" ], "summary": "RetrieveInventoryChanges", "operationId": "RetrieveInventoryChanges", "description": "Returns a set of physical counts and inventory adjustments for the\nprovided [CatalogObject](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogObject) at the requested\n[Location](https://developer.squareup.com/reference/square_2024-10-17/objects/Location)s.\n\nYou can achieve the same result by calling [BatchRetrieveInventoryChanges](https://developer.squareup.com/reference/square_2024-10-17/inventory-api/batch-retrieve-inventory-changes)\nand having the `catalog_object_ids` list contain a single element of the `CatalogObject` ID.\n\nResults are paginated and sorted in descending order according to their\n`occurred_at` timestamp (newest first).\n\nThere are no limits on how far back the caller can page. This endpoint can be\nused to display recent changes for a specific item. For more\nsophisticated queries, use a batch endpoint.", "x-release-status": "DEPRECATED", "x-is-deprecated": true, "x-oauthpermissions": [ "INVENTORY_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "INVENTORY_READ" ] } ], "parameters": [ { "name": "catalog_object_id", "description": "ID of the [CatalogObject](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogObject) to retrieve.", "type": "string", "in": "path", "required": true }, { "name": "location_ids", "description": "The [Location](https://developer.squareup.com/reference/square_2024-10-17/objects/Location) IDs to look up as a comma-separated\nlist. An empty list queries all locations.", "type": "string", "in": "query", "required": false }, { "name": "cursor", "description": "A pagination cursor returned by a previous call to this endpoint.\nProvide this to retrieve the next set of results for the original query.\n\nSee the [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination) guide for more information.", "type": "string", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveInventoryChangesResponse" } } } } }, "/v2/invoices": { "get": { "tags": [ "Invoices" ], "summary": "ListInvoices", "operationId": "ListInvoices", "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", "x-oauthpermissions": [ "INVOICES_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "INVOICES_READ" ] } ], "parameters": [ { "name": "location_id", "description": "The ID of the location for which to list invoices.", "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).", "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.", "type": "integer", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListInvoicesResponse" } } } }, "post": { "tags": [ "Invoices" ], "summary": "CreateInvoice", "operationId": "CreateInvoice", "description": "Creates a draft [invoice](https://developer.squareup.com/reference/square_2024-10-17/objects/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\u0027s email address or charge the customer’s card on file).", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "ORDERS_WRITE", "INVOICES_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ORDERS_WRITE", "INVOICES_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CreateInvoiceRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CreateInvoiceResponse" } } } } }, "/v2/invoices/search": { "post": { "tags": [ "Invoices" ], "summary": "SearchInvoices", "operationId": "SearchInvoices", "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", "x-oauthpermissions": [ "INVOICES_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "INVOICES_READ" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/SearchInvoicesRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/SearchInvoicesResponse" } } } } }, "/v2/invoices/{invoice_id}": { "delete": { "tags": [ "Invoices" ], "summary": "DeleteInvoice", "operationId": "DeleteInvoice", "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", "x-oauthpermissions": [ "ORDERS_WRITE", "INVOICES_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ORDERS_WRITE", "INVOICES_WRITE" ] } ], "parameters": [ { "name": "invoice_id", "description": "The ID of the invoice to delete.", "type": "string", "in": "path", "required": true }, { "name": "version", "description": "The version of the [invoice](https://developer.squareup.com/reference/square_2024-10-17/objects/Invoice) to delete.\nIf you do not know the version, you can call [GetInvoice](https://developer.squareup.com/reference/square_2024-10-17/invoices-api/get-invoice) or \n[ListInvoices](https://developer.squareup.com/reference/square_2024-10-17/invoices-api/list-invoices).", "type": "integer", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/DeleteInvoiceResponse" } } } }, "get": { "tags": [ "Invoices" ], "summary": "GetInvoice", "operationId": "GetInvoice", "description": "Retrieves an invoice by invoice ID.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "INVOICES_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "INVOICES_READ" ] } ], "parameters": [ { "name": "invoice_id", "description": "The ID of the invoice to retrieve.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/GetInvoiceResponse" } } } }, "put": { "tags": [ "Invoices" ], "summary": "UpdateInvoice", "operationId": "UpdateInvoice", "description": "Updates an invoice. This endpoint supports sparse updates, so you only need\nto specify the fields you want to change along with the required `version` field.\nSome restrictions apply to updating invoices. For example, you cannot change the\n`order_id` or `location_id` field.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "ORDERS_WRITE", "INVOICES_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ORDERS_WRITE", "INVOICES_WRITE" ] } ], "parameters": [ { "name": "invoice_id", "description": "The ID of the invoice to update.", "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/UpdateInvoiceRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/UpdateInvoiceResponse" } } } } }, "/v2/invoices/{invoice_id}/attachments/{attachment_id}": { "delete": { "tags": [ "Invoices" ], "summary": "DeleteInvoiceAttachment", "operationId": "DeleteInvoiceAttachment", "description": "Removes an attachment from an invoice and permanently deletes the file. Attachments can be removed only\nfrom invoices in the `DRAFT`, `SCHEDULED`, `UNPAID`, or `PARTIALLY_PAID` state.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "INVOICES_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "INVOICES_WRITE" ] } ], "parameters": [ { "name": "invoice_id", "description": "The ID of the [invoice](https://developer.squareup.com/reference/square_2024-10-17/objects/Invoice) to delete the attachment from.", "type": "string", "in": "path", "required": true }, { "name": "attachment_id", "description": "The ID of the [attachment](https://developer.squareup.com/reference/square_2024-10-17/objects/InvoiceAttachment) to delete.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/DeleteInvoiceAttachmentResponse" } } } } }, "/v2/invoices/{invoice_id}/cancel": { "post": { "tags": [ "Invoices" ], "summary": "CancelInvoice", "operationId": "CancelInvoice", "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", "x-oauthpermissions": [ "ORDERS_WRITE", "INVOICES_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ORDERS_WRITE", "INVOICES_WRITE" ] } ], "parameters": [ { "name": "invoice_id", "description": "The ID of the [invoice](https://developer.squareup.com/reference/square_2024-10-17/objects/Invoice) to cancel.", "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CancelInvoiceRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CancelInvoiceResponse" } } } } }, "/v2/invoices/{invoice_id}/publish": { "post": { "tags": [ "Invoices" ], "summary": "PublishInvoice", "operationId": "PublishInvoice", "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\u0027s email address, charges the customer\u0027s 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", "x-oauthpermissions": [ "ORDERS_WRITE", "INVOICES_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ORDERS_WRITE", "INVOICES_WRITE" ] } ], "parameters": [ { "name": "invoice_id", "description": "The ID of the invoice to publish.", "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/PublishInvoiceRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/PublishInvoiceResponse" } } } } }, "/v2/labor/break-types": { "get": { "tags": [ "Labor" ], "summary": "ListBreakTypes", "operationId": "ListBreakTypes", "description": "Returns a paginated list of `BreakType` instances for a business.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "TIMECARDS_SETTINGS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "TIMECARDS_SETTINGS_READ" ] } ], "parameters": [ { "name": "location_id", "description": "Filter the returned `BreakType` results to only those that are associated with the\nspecified location.", "type": "string", "in": "query", "required": false }, { "name": "limit", "description": "The maximum number of `BreakType` results to return per page. The number can range between 1\nand 200. The default is 200.", "type": "integer", "in": "query", "required": false }, { "name": "cursor", "description": "A pointer to the next page of `BreakType` results to fetch.", "type": "string", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListBreakTypesResponse" } } } }, "post": { "tags": [ "Labor" ], "summary": "CreateBreakType", "operationId": "CreateBreakType", "description": "Creates a new `BreakType`.\n\nA `BreakType` is a template for creating `Break` objects.\nYou must provide the following values in your request to this\nendpoint:\n\n- `location_id`\n- `break_name`\n- `expected_duration`\n- `is_paid`\n\nYou can only have three `BreakType` instances per location. If you attempt to add a fourth\n`BreakType` for a location, an `INVALID_REQUEST_ERROR` \"Exceeded limit of 3 breaks per location.\"\nis returned.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "TIMECARDS_SETTINGS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "TIMECARDS_SETTINGS_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CreateBreakTypeRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CreateBreakTypeResponse" } } } } }, "/v2/labor/break-types/{id}": { "delete": { "tags": [ "Labor" ], "summary": "DeleteBreakType", "operationId": "DeleteBreakType", "description": "Deletes an existing `BreakType`.\n\nA `BreakType` can be deleted even if it is referenced from a `Shift`.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "TIMECARDS_SETTINGS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "TIMECARDS_SETTINGS_WRITE" ] } ], "parameters": [ { "name": "id", "description": "The UUID for the `BreakType` being deleted.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/DeleteBreakTypeResponse" } } } }, "get": { "tags": [ "Labor" ], "summary": "GetBreakType", "operationId": "GetBreakType", "description": "Returns a single `BreakType` specified by `id`.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "TIMECARDS_SETTINGS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "TIMECARDS_SETTINGS_READ" ] } ], "parameters": [ { "name": "id", "description": "The UUID for the `BreakType` being retrieved.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/GetBreakTypeResponse" } } } }, "put": { "tags": [ "Labor" ], "summary": "UpdateBreakType", "operationId": "UpdateBreakType", "description": "Updates an existing `BreakType`.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "TIMECARDS_SETTINGS_WRITE", "TIMECARDS_SETTINGS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "TIMECARDS_SETTINGS_WRITE", "TIMECARDS_SETTINGS_READ" ] } ], "parameters": [ { "name": "id", "description": " The UUID for the `BreakType` being updated.", "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/UpdateBreakTypeRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/UpdateBreakTypeResponse" } } } } }, "/v2/labor/employee-wages": { "get": { "tags": [ "Labor" ], "summary": "ListEmployeeWages", "operationId": "ListEmployeeWages", "description": "Returns a paginated list of `EmployeeWage` instances for a business.", "x-release-status": "DEPRECATED", "x-is-deprecated": true, "x-oauthpermissions": [ "EMPLOYEES_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "EMPLOYEES_READ" ] } ], "parameters": [ { "name": "employee_id", "description": "Filter the returned wages to only those that are associated with the specified employee.", "x-is-deprecated": true, "type": "string", "in": "query", "required": false }, { "name": "limit", "description": "The maximum number of `EmployeeWage` results to return per page. The number can range between\n1 and 200. The default is 200.", "x-is-deprecated": true, "type": "integer", "in": "query", "required": false }, { "name": "cursor", "description": "A pointer to the next page of `EmployeeWage` results to fetch.", "x-is-deprecated": true, "type": "string", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListEmployeeWagesResponse" } } } } }, "/v2/labor/employee-wages/{id}": { "get": { "tags": [ "Labor" ], "summary": "GetEmployeeWage", "operationId": "GetEmployeeWage", "description": "Returns a single `EmployeeWage` specified by `id`.", "x-release-status": "DEPRECATED", "x-is-deprecated": true, "x-oauthpermissions": [ "EMPLOYEES_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "EMPLOYEES_READ" ] } ], "parameters": [ { "name": "id", "description": "The UUID for the `EmployeeWage` being retrieved.", "x-is-deprecated": true, "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/GetEmployeeWageResponse" } } } } }, "/v2/labor/shifts": { "post": { "tags": [ "Labor" ], "summary": "CreateShift", "operationId": "CreateShift", "description": "Creates a new `Shift`.\n\nA `Shift` represents a complete workday for a single team member.\nYou must provide the following values in your request to this\nendpoint:\n\n- `location_id`\n- `team_member_id`\n- `start_at`\n\nAn attempt to create a new `Shift` can result in a `BAD_REQUEST` error when:\n- The `status` of the new `Shift` is `OPEN` and the team member has another\nshift with an `OPEN` status.\n- The `start_at` date is in the future.\n- The `start_at` or `end_at` date overlaps another shift for the same team member.\n- The `Break` instances are set in the request and a break `start_at`\nis before the `Shift.start_at`, a break `end_at` is after\nthe `Shift.end_at`, or both.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "TIMECARDS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "TIMECARDS_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CreateShiftRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CreateShiftResponse" } } } } }, "/v2/labor/shifts/search": { "post": { "tags": [ "Labor" ], "summary": "SearchShifts", "operationId": "SearchShifts", "description": "Returns a paginated list of `Shift` records for a business.\nThe list to be returned can be filtered by:\n- Location IDs\n- Team member IDs\n- Shift status (`OPEN` or `CLOSED`)\n- Shift start\n- Shift end\n- Workday details\n\nThe list can be sorted by:\n- `START_AT`\n- `END_AT`\n- `CREATED_AT`\n- `UPDATED_AT`", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "TIMECARDS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "TIMECARDS_READ" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/SearchShiftsRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/SearchShiftsResponse" } } } } }, "/v2/labor/shifts/{id}": { "delete": { "tags": [ "Labor" ], "summary": "DeleteShift", "operationId": "DeleteShift", "description": "Deletes a `Shift`.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "TIMECARDS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "TIMECARDS_WRITE" ] } ], "parameters": [ { "name": "id", "description": "The UUID for the `Shift` being deleted.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/DeleteShiftResponse" } } } }, "get": { "tags": [ "Labor" ], "summary": "GetShift", "operationId": "GetShift", "description": "Returns a single `Shift` specified by `id`.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "TIMECARDS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "TIMECARDS_READ" ] } ], "parameters": [ { "name": "id", "description": "The UUID for the `Shift` being retrieved.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/GetShiftResponse" } } } }, "put": { "tags": [ "Labor" ], "summary": "UpdateShift", "operationId": "UpdateShift", "description": "Updates an existing `Shift`.\n\nWhen adding a `Break` to a `Shift`, any earlier `Break` instances in the `Shift` have\nthe `end_at` property set to a valid RFC-3339 datetime string.\n\nWhen closing a `Shift`, all `Break` instances in the `Shift` must be complete with `end_at`\nset on each `Break`.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "TIMECARDS_WRITE", "TIMECARDS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "TIMECARDS_WRITE", "TIMECARDS_READ" ] } ], "parameters": [ { "name": "id", "description": "The ID of the object being updated.", "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/UpdateShiftRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/UpdateShiftResponse" } } } } }, "/v2/labor/team-member-wages": { "get": { "tags": [ "Labor" ], "summary": "ListTeamMemberWages", "operationId": "ListTeamMemberWages", "description": "Returns a paginated list of `TeamMemberWage` instances for a business.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "EMPLOYEES_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "EMPLOYEES_READ" ] } ], "parameters": [ { "name": "team_member_id", "description": "Filter the returned wages to only those that are associated with the\nspecified team member.", "type": "string", "in": "query", "required": false }, { "name": "limit", "description": "The maximum number of `TeamMemberWage` results to return per page. The number can range between\n1 and 200. The default is 200.", "type": "integer", "in": "query", "required": false }, { "name": "cursor", "description": "A pointer to the next page of `EmployeeWage` results to fetch.", "type": "string", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListTeamMemberWagesResponse" } } } } }, "/v2/labor/team-member-wages/{id}": { "get": { "tags": [ "Labor" ], "summary": "GetTeamMemberWage", "operationId": "GetTeamMemberWage", "description": "Returns a single `TeamMemberWage` specified by `id`.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "EMPLOYEES_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "EMPLOYEES_READ" ] } ], "parameters": [ { "name": "id", "description": "The UUID for the `TeamMemberWage` being retrieved.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/GetTeamMemberWageResponse" } } } } }, "/v2/labor/workweek-configs": { "get": { "tags": [ "Labor" ], "summary": "ListWorkweekConfigs", "operationId": "ListWorkweekConfigs", "description": "Returns a list of `WorkweekConfig` instances for a business.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "TIMECARDS_SETTINGS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "TIMECARDS_SETTINGS_READ" ] } ], "parameters": [ { "name": "limit", "description": "The maximum number of `WorkweekConfigs` results to return per page.", "type": "integer", "in": "query", "required": false }, { "name": "cursor", "description": "A pointer to the next page of `WorkweekConfig` results to fetch.", "type": "string", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListWorkweekConfigsResponse" } } } } }, "/v2/labor/workweek-configs/{id}": { "put": { "tags": [ "Labor" ], "summary": "UpdateWorkweekConfig", "operationId": "UpdateWorkweekConfig", "description": "Updates a `WorkweekConfig`.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "TIMECARDS_SETTINGS_WRITE", "TIMECARDS_SETTINGS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "TIMECARDS_SETTINGS_WRITE", "TIMECARDS_SETTINGS_READ" ] } ], "parameters": [ { "name": "id", "description": "The UUID for the `WorkweekConfig` object being updated.", "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/UpdateWorkweekConfigRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/UpdateWorkweekConfigResponse" } } } } }, "/v2/locations": { "get": { "tags": [ "Locations" ], "summary": "ListLocations", "operationId": "ListLocations", "description": "Provides details about all of the seller\u0027s [locations](https://developer.squareup.com/docs/locations-api),\nincluding those with an inactive status. Locations are listed alphabetically by `name`.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "MERCHANT_PROFILE_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "MERCHANT_PROFILE_READ" ] } ], "parameters": [], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListLocationsResponse" } } } }, "post": { "tags": [ "Locations" ], "summary": "CreateLocation", "operationId": "CreateLocation", "description": "Creates a [location](https://developer.squareup.com/docs/locations-api).\nCreating new locations allows for separate configuration of receipt layouts, item prices,\nand sales reports. Developers can use locations to separate sales activity through applications\nthat integrate with Square from sales activity elsewhere in a seller\u0027s account.\nLocations created programmatically with the Locations API last forever and\nare visible to the seller for their own management. Therefore, ensure that\neach location has a sensible and unique name.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "MERCHANT_PROFILE_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "MERCHANT_PROFILE_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CreateLocationRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CreateLocationResponse" } } } } }, "/v2/locations/custom-attribute-definitions": { "get": { "tags": [ "LocationCustomAttributes" ], "summary": "ListLocationCustomAttributeDefinitions", "operationId": "ListLocationCustomAttributeDefinitions", "description": "Lists the location-related [custom attribute definitions](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttributeDefinition) that belong to a Square seller account.\nWhen all response pages are retrieved, the results include all custom attribute definitions\nthat are visible to the requesting application, including those that are created by other\napplications and set to `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "MERCHANT_PROFILE_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "MERCHANT_PROFILE_READ" ] } ], "parameters": [ { "name": "visibility_filter", "description": "Filters the `CustomAttributeDefinition` results by their `visibility` values.", "x-is-beta": true, "type": "string", "in": "query", "required": false }, { "name": "limit", "description": "The maximum number of results to return in a single paged response. This limit is advisory.\nThe response might contain more or fewer results. The minimum value is 1 and the maximum value is 100.\nThe default value is 20. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "x-is-beta": true, "type": "integer", "in": "query", "required": false }, { "name": "cursor", "description": "The cursor returned in the paged response from the previous call to this endpoint.\nProvide this cursor to retrieve the next page of results for your original request.\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "x-is-beta": true, "type": "string", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListLocationCustomAttributeDefinitionsResponse" } } } }, "post": { "tags": [ "LocationCustomAttributes" ], "summary": "CreateLocationCustomAttributeDefinition", "operationId": "CreateLocationCustomAttributeDefinition", "description": "Creates a location-related [custom attribute definition](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttributeDefinition) for a Square seller account.\nUse this endpoint to define a custom attribute that can be associated with locations.\nA custom attribute definition specifies the `key`, `visibility`, `schema`, and other properties\nfor a custom attribute. After the definition is created, you can call\n[UpsertLocationCustomAttribute](https://developer.squareup.com/reference/square_2024-10-17/location-custom-attributes-api/upsert-location-custom-attribute) or\n[BulkUpsertLocationCustomAttributes](https://developer.squareup.com/reference/square_2024-10-17/location-custom-attributes-api/bulk-upsert-location-custom-attributes)\nto set the custom attribute for locations.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "MERCHANT_PROFILE_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "MERCHANT_PROFILE_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CreateLocationCustomAttributeDefinitionRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CreateLocationCustomAttributeDefinitionResponse" } } } } }, "/v2/locations/custom-attribute-definitions/{key}": { "delete": { "tags": [ "LocationCustomAttributes" ], "summary": "DeleteLocationCustomAttributeDefinition", "operationId": "DeleteLocationCustomAttributeDefinition", "description": "Deletes a location-related [custom attribute definition](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttributeDefinition) from a Square seller account.\nDeleting a custom attribute definition also deletes the corresponding custom attribute from\nall locations.\nOnly the definition owner can delete a custom attribute definition.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "MERCHANT_PROFILE_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "MERCHANT_PROFILE_WRITE" ] } ], "parameters": [ { "name": "key", "description": "The key of the custom attribute definition to delete.", "x-is-beta": true, "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/DeleteLocationCustomAttributeDefinitionResponse" } } } }, "get": { "tags": [ "LocationCustomAttributes" ], "summary": "RetrieveLocationCustomAttributeDefinition", "operationId": "RetrieveLocationCustomAttributeDefinition", "description": "Retrieves a location-related [custom attribute definition](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttributeDefinition) from a Square seller account.\nTo retrieve a custom attribute definition created by another application, the `visibility`\nsetting must be `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "MERCHANT_PROFILE_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "MERCHANT_PROFILE_READ" ] } ], "parameters": [ { "name": "key", "description": "The key of the custom attribute definition to retrieve. If the requesting application\nis not the definition owner, you must use the qualified key.", "x-is-beta": true, "type": "string", "in": "path", "required": true }, { "name": "version", "description": "The current version of the custom attribute definition, which is used for strongly consistent\nreads to guarantee that you receive the most up-to-date data. When included in the request,\nSquare returns the specified version or a higher version if one exists. If the specified version\nis higher than the current version, Square returns a `BAD_REQUEST` error.", "x-is-beta": true, "type": "integer", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveLocationCustomAttributeDefinitionResponse" } } } }, "put": { "tags": [ "LocationCustomAttributes" ], "summary": "UpdateLocationCustomAttributeDefinition", "operationId": "UpdateLocationCustomAttributeDefinition", "description": "Updates a location-related [custom attribute definition](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttributeDefinition) for a Square seller account.\nUse this endpoint to update the following fields: `name`, `description`, `visibility`, or the\n`schema` for a `Selection` data type.\nOnly the definition owner can update a custom attribute definition.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "MERCHANT_PROFILE_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "MERCHANT_PROFILE_WRITE" ] } ], "parameters": [ { "name": "key", "description": "The key of the custom attribute definition to update.", "x-is-beta": true, "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/UpdateLocationCustomAttributeDefinitionRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/UpdateLocationCustomAttributeDefinitionResponse" } } } } }, "/v2/locations/custom-attributes/bulk-delete": { "post": { "tags": [ "LocationCustomAttributes" ], "summary": "BulkDeleteLocationCustomAttributes", "operationId": "BulkDeleteLocationCustomAttributes", "description": "Deletes [custom attributes](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttribute) for locations as a bulk operation.\nTo delete a custom attribute owned by another application, the `visibility` setting must be\n`VISIBILITY_READ_WRITE_VALUES`.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "MERCHANT_PROFILE_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "MERCHANT_PROFILE_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/BulkDeleteLocationCustomAttributesRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/BulkDeleteLocationCustomAttributesResponse" } } } } }, "/v2/locations/custom-attributes/bulk-upsert": { "post": { "tags": [ "LocationCustomAttributes" ], "summary": "BulkUpsertLocationCustomAttributes", "operationId": "BulkUpsertLocationCustomAttributes", "description": "Creates or updates [custom attributes](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttribute) for locations as a bulk operation.\nUse this endpoint to set the value of one or more custom attributes for one or more locations.\nA custom attribute is based on a custom attribute definition in a Square seller account, which is\ncreated using the [CreateLocationCustomAttributeDefinition](https://developer.squareup.com/reference/square_2024-10-17/location-custom-attributes-api/create-location-custom-attribute-definition) endpoint.\nThis `BulkUpsertLocationCustomAttributes` endpoint accepts a map of 1 to 25 individual upsert\nrequests and returns a map of individual upsert responses. Each upsert request has a unique ID\nand provides a location ID and custom attribute. Each upsert response is returned with the ID\nof the corresponding request.\nTo create or update a custom attribute owned by another application, the `visibility` setting\nmust be `VISIBILITY_READ_WRITE_VALUES`.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "MERCHANT_PROFILE_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "MERCHANT_PROFILE_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/BulkUpsertLocationCustomAttributesRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/BulkUpsertLocationCustomAttributesResponse" } } } } }, "/v2/locations/{location_id}": { "get": { "tags": [ "Locations" ], "summary": "RetrieveLocation", "operationId": "RetrieveLocation", "description": "Retrieves details of a single location. Specify \"main\"\nas the location ID to retrieve details of the [main location](https://developer.squareup.com/docs/locations-api#about-the-main-location).", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "MERCHANT_PROFILE_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "MERCHANT_PROFILE_READ" ] } ], "parameters": [ { "name": "location_id", "description": "The ID of the location to retrieve. Specify the string\n\"main\" to return the main location.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveLocationResponse" } } } }, "put": { "tags": [ "Locations" ], "summary": "UpdateLocation", "operationId": "UpdateLocation", "description": "Updates a [location](https://developer.squareup.com/docs/locations-api).", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "MERCHANT_PROFILE_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "MERCHANT_PROFILE_WRITE" ] } ], "parameters": [ { "name": "location_id", "description": "The ID of the location to update.", "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/UpdateLocationRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/UpdateLocationResponse" } } } } }, "/v2/locations/{location_id}/checkouts": { "post": { "tags": [ "Checkout" ], "summary": "CreateCheckout", "operationId": "CreateCheckout", "description": "Links a `checkoutId` to a `checkout_page_url` that customers are\ndirected to in order to provide their payment information using a\npayment processing workflow hosted on connect.squareup.com. \n\n\nNOTE: The Checkout API has been updated with new features. \nFor more information, see [Checkout API highlights](https://developer.squareup.com/docs/checkout-api#checkout-api-highlights).", "x-release-status": "DEPRECATED", "x-is-deprecated": true, "x-oauthpermissions": [ "PAYMENTS_WRITE", "ORDERS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "PAYMENTS_WRITE", "ORDERS_WRITE" ] } ], "parameters": [ { "name": "location_id", "description": "The ID of the business location to associate the checkout with.", "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CreateCheckoutRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CreateCheckoutResponse" } } } } }, "/v2/locations/{location_id}/custom-attributes": { "get": { "tags": [ "LocationCustomAttributes" ], "summary": "ListLocationCustomAttributes", "operationId": "ListLocationCustomAttributes", "description": "Lists the [custom attributes](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttribute) associated with a location.\nYou can use the `with_definitions` query parameter to also retrieve custom attribute definitions\nin the same call.\nWhen all response pages are retrieved, the results include all custom attributes that are\nvisible to the requesting application, including those that are owned by other applications\nand set to `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "MERCHANT_PROFILE_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "MERCHANT_PROFILE_READ" ] } ], "parameters": [ { "name": "location_id", "description": "The ID of the target [location](https://developer.squareup.com/reference/square_2024-10-17/objects/Location).", "x-is-beta": true, "type": "string", "in": "path", "required": true }, { "name": "visibility_filter", "description": "Filters the `CustomAttributeDefinition` results by their `visibility` values.", "x-is-beta": true, "type": "string", "in": "query", "required": false }, { "name": "limit", "description": "The maximum number of results to return in a single paged response. This limit is advisory.\nThe response might contain more or fewer results. The minimum value is 1 and the maximum value is 100.\nThe default value is 20. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "x-is-beta": true, "type": "integer", "in": "query", "required": false }, { "name": "cursor", "description": "The cursor returned in the paged response from the previous call to this endpoint.\nProvide this cursor to retrieve the next page of results for your original request. For more\ninformation, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "x-is-beta": true, "type": "string", "in": "query", "required": false }, { "name": "with_definitions", "description": "Indicates whether to return the [custom attribute definition](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttributeDefinition) in the `definition` field of each\ncustom attribute. Set this parameter to `true` to get the name and description of each custom\nattribute, information about the data type, or other definition details. The default value is `false`.", "x-is-beta": true, "type": "boolean", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListLocationCustomAttributesResponse" } } } } }, "/v2/locations/{location_id}/custom-attributes/{key}": { "delete": { "tags": [ "LocationCustomAttributes" ], "summary": "DeleteLocationCustomAttribute", "operationId": "DeleteLocationCustomAttribute", "description": "Deletes a [custom attribute](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttribute) associated with a location.\nTo delete a custom attribute owned by another application, the `visibility` setting must be\n`VISIBILITY_READ_WRITE_VALUES`.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "MERCHANT_PROFILE_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "MERCHANT_PROFILE_WRITE" ] } ], "parameters": [ { "name": "location_id", "description": "The ID of the target [location](https://developer.squareup.com/reference/square_2024-10-17/objects/Location).", "x-is-beta": true, "type": "string", "in": "path", "required": true }, { "name": "key", "description": "The key of the custom attribute to delete. This key must match the `key` of a custom\nattribute definition in the Square seller account. If the requesting application is not the\ndefinition owner, you must use the qualified key.", "x-is-beta": true, "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/DeleteLocationCustomAttributeResponse" } } } }, "get": { "tags": [ "LocationCustomAttributes" ], "summary": "RetrieveLocationCustomAttribute", "operationId": "RetrieveLocationCustomAttribute", "description": "Retrieves a [custom attribute](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttribute) associated with a location.\nYou can use the `with_definition` query parameter to also retrieve the custom attribute definition\nin the same call.\nTo retrieve a custom attribute owned by another application, the `visibility` setting must be\n`VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "MERCHANT_PROFILE_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "MERCHANT_PROFILE_READ" ] } ], "parameters": [ { "name": "location_id", "description": "The ID of the target [location](https://developer.squareup.com/reference/square_2024-10-17/objects/Location).", "x-is-beta": true, "type": "string", "in": "path", "required": true }, { "name": "key", "description": "The key of the custom attribute to retrieve. This key must match the `key` of a custom\nattribute definition in the Square seller account. If the requesting application is not the\ndefinition owner, you must use the qualified key.", "x-is-beta": true, "type": "string", "in": "path", "required": true }, { "name": "with_definition", "description": "Indicates whether to return the [custom attribute definition](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttributeDefinition) in the `definition` field of\nthe custom attribute. Set this parameter to `true` to get the name and description of the custom\nattribute, information about the data type, or other definition details. The default value is `false`.", "x-is-beta": true, "type": "boolean", "in": "query", "required": false }, { "name": "version", "description": "The current version of the custom attribute, which is used for strongly consistent reads to\nguarantee that you receive the most up-to-date data. When included in the request, Square\nreturns the specified version or a higher version if one exists. If the specified version is\nhigher than the current version, Square returns a `BAD_REQUEST` error.", "x-is-beta": true, "type": "integer", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveLocationCustomAttributeResponse" } } } }, "post": { "tags": [ "LocationCustomAttributes" ], "summary": "UpsertLocationCustomAttribute", "operationId": "UpsertLocationCustomAttribute", "description": "Creates or updates a [custom attribute](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttribute) for a location.\nUse this endpoint to set the value of a custom attribute for a specified location.\nA custom attribute is based on a custom attribute definition in a Square seller account, which\nis created using the [CreateLocationCustomAttributeDefinition](https://developer.squareup.com/reference/square_2024-10-17/location-custom-attributes-api/create-location-custom-attribute-definition) endpoint.\nTo create or update a custom attribute owned by another application, the `visibility` setting\nmust be `VISIBILITY_READ_WRITE_VALUES`.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "MERCHANT_PROFILE_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "MERCHANT_PROFILE_WRITE" ] } ], "parameters": [ { "name": "location_id", "description": "The ID of the target [location](https://developer.squareup.com/reference/square_2024-10-17/objects/Location).", "x-is-beta": true, "type": "string", "in": "path", "required": true }, { "name": "key", "description": "The key of the custom attribute to create or update. This key must match the `key` of a\ncustom attribute definition in the Square seller account. If the requesting application is not\nthe definition owner, you must use the qualified key.", "x-is-beta": true, "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/UpsertLocationCustomAttributeRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/UpsertLocationCustomAttributeResponse" } } } } }, "/v2/locations/{location_id}/transactions": { "get": { "tags": [ "Transactions" ], "summary": "ListTransactions", "operationId": "ListTransactions", "description": "Lists transactions for a particular location.\n\nTransactions include payment information from sales and exchanges and refund\ninformation from returns and exchanges.\n\nMax results per [page](https://developer.squareup.com/docs/working-with-apis/pagination): 50", "x-release-status": "DEPRECATED", "x-is-deprecated": true, "x-oauthpermissions": [ "PAYMENTS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "PAYMENTS_READ" ] } ], "parameters": [ { "name": "location_id", "description": "The ID of the location to list transactions for.", "x-is-deprecated": true, "type": "string", "in": "path", "required": true }, { "name": "begin_time", "description": "The beginning of the requested reporting period, in RFC 3339 format.\n\nSee [Date ranges](https://developer.squareup.com/docs/build-basics/working-with-dates) for details on date inclusivity/exclusivity.\n\nDefault value: The current time minus one year.", "x-is-deprecated": true, "type": "string", "in": "query", "required": false }, { "name": "end_time", "description": "The end of the requested reporting period, in RFC 3339 format.\n\nSee [Date ranges](https://developer.squareup.com/docs/build-basics/working-with-dates) for details on date inclusivity/exclusivity.\n\nDefault value: The current time.", "x-is-deprecated": true, "type": "string", "in": "query", "required": false }, { "name": "sort_order", "description": "The order in which results are listed in the response (`ASC` for\noldest first, `DESC` for newest first).\n\nDefault value: `DESC`", "x-is-deprecated": true, "type": "string", "in": "query", "required": false }, { "name": "cursor", "description": "A pagination cursor returned by a previous call to this endpoint.\nProvide this to retrieve the next set of results for your original query.\n\nSee [Paginating results](https://developer.squareup.com/docs/working-with-apis/pagination) for more information.", "x-is-deprecated": true, "type": "string", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListTransactionsResponse" } } } } }, "/v2/locations/{location_id}/transactions/{transaction_id}": { "get": { "tags": [ "Transactions" ], "summary": "RetrieveTransaction", "operationId": "RetrieveTransaction", "description": "Retrieves details for a single transaction.", "x-release-status": "DEPRECATED", "x-is-deprecated": true, "x-oauthpermissions": [ "PAYMENTS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "PAYMENTS_READ" ] } ], "parameters": [ { "name": "location_id", "description": "The ID of the transaction\u0027s associated location.", "x-is-deprecated": true, "type": "string", "in": "path", "required": true }, { "name": "transaction_id", "description": "The ID of the transaction to retrieve.", "x-is-deprecated": true, "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveTransactionResponse" } } } } }, "/v2/locations/{location_id}/transactions/{transaction_id}/capture": { "post": { "tags": [ "Transactions" ], "summary": "CaptureTransaction", "operationId": "CaptureTransaction", "description": "Captures a transaction that was created with the [Charge](https://developer.squareup.com/reference/square_2024-10-17/transactions-api/charge)\nendpoint with a `delay_capture` value of `true`.\n\n\nSee [Delayed capture transactions](https://developer.squareup.com/docs/payments/transactions/overview#delayed-capture)\nfor more information.", "x-release-status": "DEPRECATED", "x-is-deprecated": true, "x-oauthpermissions": [ "PAYMENTS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "PAYMENTS_WRITE" ] } ], "parameters": [ { "name": "location_id", "description": "", "x-is-deprecated": true, "type": "string", "in": "path", "required": true }, { "name": "transaction_id", "description": "", "x-is-deprecated": true, "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CaptureTransactionResponse" } } } } }, "/v2/locations/{location_id}/transactions/{transaction_id}/void": { "post": { "tags": [ "Transactions" ], "summary": "VoidTransaction", "operationId": "VoidTransaction", "description": "Cancels a transaction that was created with the [Charge](https://developer.squareup.com/reference/square_2024-10-17/transactions-api/charge)\nendpoint with a `delay_capture` value of `true`.\n\n\nSee [Delayed capture transactions](https://developer.squareup.com/docs/payments/transactions/overview#delayed-capture)\nfor more information.", "x-release-status": "DEPRECATED", "x-is-deprecated": true, "x-oauthpermissions": [ "PAYMENTS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "PAYMENTS_WRITE" ] } ], "parameters": [ { "name": "location_id", "description": "", "x-is-deprecated": true, "type": "string", "in": "path", "required": true }, { "name": "transaction_id", "description": "", "x-is-deprecated": true, "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/VoidTransactionResponse" } } } } }, "/v2/loyalty/accounts": { "post": { "tags": [ "Loyalty" ], "summary": "CreateLoyaltyAccount", "operationId": "CreateLoyaltyAccount", "description": "Creates a loyalty account. To create a loyalty account, you must provide the `program_id` and a `mapping` with the `phone_number` of the buyer.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "LOYALTY_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "LOYALTY_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CreateLoyaltyAccountRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CreateLoyaltyAccountResponse" } } } } }, "/v2/loyalty/accounts/search": { "post": { "tags": [ "Loyalty" ], "summary": "SearchLoyaltyAccounts", "operationId": "SearchLoyaltyAccounts", "description": "Searches for loyalty accounts in a loyalty program.\n\nYou can search for a loyalty account using the phone number or customer ID associated with the account. To return all loyalty accounts, specify an empty `query` object or omit it entirely.\n\nSearch results are sorted by `created_at` in ascending order.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "LOYALTY_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "LOYALTY_READ" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/SearchLoyaltyAccountsRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/SearchLoyaltyAccountsResponse" } } } } }, "/v2/loyalty/accounts/{account_id}": { "get": { "tags": [ "Loyalty" ], "summary": "RetrieveLoyaltyAccount", "operationId": "RetrieveLoyaltyAccount", "description": "Retrieves a loyalty account.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "LOYALTY_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "LOYALTY_READ" ] } ], "parameters": [ { "name": "account_id", "description": "The ID of the [loyalty account](https://developer.squareup.com/reference/square_2024-10-17/objects/LoyaltyAccount) to retrieve.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveLoyaltyAccountResponse" } } } } }, "/v2/loyalty/accounts/{account_id}/accumulate": { "post": { "tags": [ "Loyalty" ], "summary": "AccumulateLoyaltyPoints", "operationId": "AccumulateLoyaltyPoints", "description": "Adds points earned from a purchase to a [loyalty account](https://developer.squareup.com/reference/square_2024-10-17/objects/LoyaltyAccount).\n\n- If you are using the Orders API to manage orders, provide the `order_id`. Square reads the order\nto compute the points earned from both the base loyalty program and an associated\n[loyalty promotion](https://developer.squareup.com/reference/square_2024-10-17/objects/LoyaltyPromotion). For purchases that qualify for multiple accrual\nrules, Square computes points based on the accrual rule that grants the most points.\nFor purchases that qualify for multiple promotions, Square computes points based on the most\nrecently created promotion. A purchase must first qualify for program points to be eligible for promotion points.\n\n- If you are not using the Orders API to manage orders, provide `points` with the number of points to add.\nYou must first perform a client-side computation of the points earned from the loyalty program and\nloyalty promotion. For spend-based and visit-based programs, you can call [CalculateLoyaltyPoints](https://developer.squareup.com/reference/square_2024-10-17/loyalty-api/calculate-loyalty-points)\nto compute the points earned from the base loyalty program. For information about computing points earned from a loyalty promotion, see\n[Calculating promotion points](https://developer.squareup.com/docs/loyalty-api/loyalty-promotions#calculate-promotion-points).", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "LOYALTY_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "LOYALTY_WRITE" ] } ], "parameters": [ { "name": "account_id", "description": "The ID of the target [loyalty account](https://developer.squareup.com/reference/square_2024-10-17/objects/LoyaltyAccount).", "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/AccumulateLoyaltyPointsRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/AccumulateLoyaltyPointsResponse" } } } } }, "/v2/loyalty/accounts/{account_id}/adjust": { "post": { "tags": [ "Loyalty" ], "summary": "AdjustLoyaltyPoints", "operationId": "AdjustLoyaltyPoints", "description": "Adds points to or subtracts points from a buyer\u0027s account.\n\nUse this endpoint only when you need to manually adjust points. Otherwise, in your application flow, you call\n[AccumulateLoyaltyPoints](https://developer.squareup.com/reference/square_2024-10-17/loyalty-api/accumulate-loyalty-points)\nto add points when a buyer pays for the purchase.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "LOYALTY_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "LOYALTY_WRITE" ] } ], "parameters": [ { "name": "account_id", "description": "The ID of the target [loyalty account](https://developer.squareup.com/reference/square_2024-10-17/objects/LoyaltyAccount).", "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/AdjustLoyaltyPointsRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/AdjustLoyaltyPointsResponse" } } } } }, "/v2/loyalty/events/search": { "post": { "tags": [ "Loyalty" ], "summary": "SearchLoyaltyEvents", "operationId": "SearchLoyaltyEvents", "description": "Searches for loyalty events.\n\nA Square loyalty program maintains a ledger of events that occur during the lifetime of a\nbuyer\u0027s loyalty account. Each change in the point balance\n(for example, points earned, points redeemed, and points expired) is\nrecorded in the ledger. Using this endpoint, you can search the ledger for events.\n\nSearch results are sorted by `created_at` in descending order.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "LOYALTY_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "LOYALTY_READ" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/SearchLoyaltyEventsRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/SearchLoyaltyEventsResponse" } } } } }, "/v2/loyalty/programs": { "get": { "tags": [ "Loyalty" ], "summary": "ListLoyaltyPrograms", "operationId": "ListLoyaltyPrograms", "description": "Returns a list of loyalty programs in the seller\u0027s account.\nLoyalty programs define how buyers can earn points and redeem points for rewards. Square sellers can have only one loyalty program, which is created and managed from the Seller Dashboard. For more information, see [Loyalty Program Overview](https://developer.squareup.com/docs/loyalty/overview).\n\n\nReplaced with [RetrieveLoyaltyProgram](https://developer.squareup.com/reference/square_2024-10-17/loyalty-api/retrieve-loyalty-program) when used with the keyword `main`.", "x-release-status": "DEPRECATED", "x-is-deprecated": true, "x-oauthpermissions": [ "LOYALTY_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "LOYALTY_READ" ] } ], "parameters": [], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListLoyaltyProgramsResponse" } } } } }, "/v2/loyalty/programs/{program_id}": { "get": { "tags": [ "Loyalty" ], "summary": "RetrieveLoyaltyProgram", "operationId": "RetrieveLoyaltyProgram", "description": "Retrieves the loyalty program in a seller\u0027s account, specified by the program ID or the keyword `main`.\n\nLoyalty programs define how buyers can earn points and redeem points for rewards. Square sellers can have only one loyalty program, which is created and managed from the Seller Dashboard. For more information, see [Loyalty Program Overview](https://developer.squareup.com/docs/loyalty/overview).", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "LOYALTY_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "LOYALTY_READ" ] } ], "parameters": [ { "name": "program_id", "description": "The ID of the loyalty program or the keyword `main`. Either value can be used to retrieve the single loyalty program that belongs to the seller.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveLoyaltyProgramResponse" } } } } }, "/v2/loyalty/programs/{program_id}/calculate": { "post": { "tags": [ "Loyalty" ], "summary": "CalculateLoyaltyPoints", "operationId": "CalculateLoyaltyPoints", "description": "Calculates the number of points a buyer can earn from a purchase. Applications might call this endpoint\nto display the points to the buyer.\n\n- If you are using the Orders API to manage orders, provide the `order_id` and (optional) `loyalty_account_id`.\nSquare reads the order to compute the points earned from the base loyalty program and an associated\n[loyalty promotion](https://developer.squareup.com/reference/square_2024-10-17/objects/LoyaltyPromotion).\n\n- If you are not using the Orders API to manage orders, provide `transaction_amount_money` with the\npurchase amount. Square uses this amount to calculate the points earned from the base loyalty program,\nbut not points earned from a loyalty promotion. For spend-based and visit-based programs, the `tax_mode`\nsetting of the accrual rule indicates how taxes should be treated for loyalty points accrual.\nIf the purchase qualifies for program points, call\n[ListLoyaltyPromotions](https://developer.squareup.com/reference/square_2024-10-17/loyalty-api/list-loyalty-promotions) and perform a client-side computation\nto calculate whether the purchase also qualifies for promotion points. For more information, see\n[Calculating promotion points](https://developer.squareup.com/docs/loyalty-api/loyalty-promotions#calculate-promotion-points).", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "LOYALTY_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "LOYALTY_READ" ] } ], "parameters": [ { "name": "program_id", "description": "The ID of the [loyalty program](https://developer.squareup.com/reference/square_2024-10-17/objects/LoyaltyProgram), which defines the rules for accruing points.", "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CalculateLoyaltyPointsRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CalculateLoyaltyPointsResponse" } } } } }, "/v2/loyalty/programs/{program_id}/promotions": { "get": { "tags": [ "Loyalty" ], "summary": "ListLoyaltyPromotions", "operationId": "ListLoyaltyPromotions", "description": "Lists the loyalty promotions associated with a [loyalty program](https://developer.squareup.com/reference/square_2024-10-17/objects/LoyaltyProgram).\nResults are sorted by the `created_at` date in descending order (newest to oldest).", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "LOYALTY_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "LOYALTY_READ" ] } ], "parameters": [ { "name": "program_id", "description": "The ID of the base [loyalty program](https://developer.squareup.com/reference/square_2024-10-17/objects/LoyaltyProgram). To get the program ID,\ncall [RetrieveLoyaltyProgram](https://developer.squareup.com/reference/square_2024-10-17/loyalty-api/retrieve-loyalty-program) using the `main` keyword.", "type": "string", "in": "path", "required": true }, { "name": "status", "description": "The status to filter the results by. If a status is provided, only loyalty promotions\nwith the specified status are returned. Otherwise, all loyalty promotions associated with\nthe loyalty program are returned.", "type": "string", "in": "query", "required": false }, { "name": "cursor", "description": "The cursor returned in the paged response from the previous call to this endpoint.\nProvide this cursor to retrieve the next page of results for your original request.\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "type": "string", "in": "query", "required": false }, { "name": "limit", "description": "The maximum number of results to return in a single paged response.\nThe minimum value is 1 and the maximum value is 30. The default value is 30.\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "type": "integer", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListLoyaltyPromotionsResponse" } } } }, "post": { "tags": [ "Loyalty" ], "summary": "CreateLoyaltyPromotion", "operationId": "CreateLoyaltyPromotion", "description": "Creates a loyalty promotion for a [loyalty program](https://developer.squareup.com/reference/square_2024-10-17/objects/LoyaltyProgram). A loyalty promotion\nenables buyers to earn points in addition to those earned from the base loyalty program.\n\nThis endpoint sets the loyalty promotion to the `ACTIVE` or `SCHEDULED` status, depending on the\n`available_time` setting. A loyalty program can have a maximum of 10 loyalty promotions with an\n`ACTIVE` or `SCHEDULED` status.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "LOYALTY_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "LOYALTY_WRITE" ] } ], "parameters": [ { "name": "program_id", "description": "The ID of the [loyalty program](https://developer.squareup.com/reference/square_2024-10-17/objects/LoyaltyProgram) to associate with the promotion.\nTo get the program ID, call [RetrieveLoyaltyProgram](https://developer.squareup.com/reference/square_2024-10-17/loyalty-api/retrieve-loyalty-program)\nusing the `main` keyword.", "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CreateLoyaltyPromotionRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CreateLoyaltyPromotionResponse" } } } } }, "/v2/loyalty/programs/{program_id}/promotions/{promotion_id}": { "get": { "tags": [ "Loyalty" ], "summary": "RetrieveLoyaltyPromotion", "operationId": "RetrieveLoyaltyPromotion", "description": "Retrieves a loyalty promotion.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "LOYALTY_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "LOYALTY_READ" ] } ], "parameters": [ { "name": "promotion_id", "description": "The ID of the [loyalty promotion](https://developer.squareup.com/reference/square_2024-10-17/objects/LoyaltyPromotion) to retrieve.", "type": "string", "in": "path", "required": true }, { "name": "program_id", "description": "The ID of the base [loyalty program](https://developer.squareup.com/reference/square_2024-10-17/objects/LoyaltyProgram). To get the program ID,\ncall [RetrieveLoyaltyProgram](https://developer.squareup.com/reference/square_2024-10-17/loyalty-api/retrieve-loyalty-program) using the `main` keyword.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveLoyaltyPromotionResponse" } } } } }, "/v2/loyalty/programs/{program_id}/promotions/{promotion_id}/cancel": { "post": { "tags": [ "Loyalty" ], "summary": "CancelLoyaltyPromotion", "operationId": "CancelLoyaltyPromotion", "description": "Cancels a loyalty promotion. Use this endpoint to cancel an `ACTIVE` promotion earlier than the\nend date, cancel an `ACTIVE` promotion when an end date is not specified, or cancel a `SCHEDULED` promotion.\nBecause updating a promotion is not supported, you can also use this endpoint to cancel a promotion before\nyou create a new one.\n\nThis endpoint sets the loyalty promotion to the `CANCELED` state", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "LOYALTY_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "LOYALTY_WRITE" ] } ], "parameters": [ { "name": "promotion_id", "description": "The ID of the [loyalty promotion](https://developer.squareup.com/reference/square_2024-10-17/objects/LoyaltyPromotion) to cancel. You can cancel a\npromotion that has an `ACTIVE` or `SCHEDULED` status.", "type": "string", "in": "path", "required": true }, { "name": "program_id", "description": "The ID of the base [loyalty program](https://developer.squareup.com/reference/square_2024-10-17/objects/LoyaltyProgram).", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CancelLoyaltyPromotionResponse" } } } } }, "/v2/loyalty/rewards": { "post": { "tags": [ "Loyalty" ], "summary": "CreateLoyaltyReward", "operationId": "CreateLoyaltyReward", "description": "Creates a loyalty reward. In the process, the endpoint does following:\n\n- Uses the `reward_tier_id` in the request to determine the number of points\nto lock for this reward.\n- If the request includes `order_id`, it adds the reward and related discount to the order.\n\nAfter a reward is created, the points are locked and\nnot available for the buyer to redeem another reward.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "LOYALTY_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "LOYALTY_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CreateLoyaltyRewardRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CreateLoyaltyRewardResponse" } } } } }, "/v2/loyalty/rewards/search": { "post": { "tags": [ "Loyalty" ], "summary": "SearchLoyaltyRewards", "operationId": "SearchLoyaltyRewards", "description": "Searches for loyalty rewards. This endpoint accepts a request with no query filters and returns results for all loyalty accounts.\nIf you include a `query` object, `loyalty_account_id` is required and `status` is optional.\n\nIf you know a reward ID, use the\n[RetrieveLoyaltyReward](https://developer.squareup.com/reference/square_2024-10-17/loyalty-api/retrieve-loyalty-reward) endpoint.\n\nSearch results are sorted by `updated_at` in descending order.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "LOYALTY_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "LOYALTY_READ" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/SearchLoyaltyRewardsRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/SearchLoyaltyRewardsResponse" } } } } }, "/v2/loyalty/rewards/{reward_id}": { "delete": { "tags": [ "Loyalty" ], "summary": "DeleteLoyaltyReward", "operationId": "DeleteLoyaltyReward", "description": "Deletes a loyalty reward by doing the following:\n\n- Returns the loyalty points back to the loyalty account.\n- If an order ID was specified when the reward was created\n(see [CreateLoyaltyReward](https://developer.squareup.com/reference/square_2024-10-17/loyalty-api/create-loyalty-reward)),\nit updates the order by removing the reward and related\ndiscounts.\n\nYou cannot delete a reward that has reached the terminal state (REDEEMED).", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "LOYALTY_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "LOYALTY_WRITE" ] } ], "parameters": [ { "name": "reward_id", "description": "The ID of the [loyalty reward](https://developer.squareup.com/reference/square_2024-10-17/objects/LoyaltyReward) to delete.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/DeleteLoyaltyRewardResponse" } } } }, "get": { "tags": [ "Loyalty" ], "summary": "RetrieveLoyaltyReward", "operationId": "RetrieveLoyaltyReward", "description": "Retrieves a loyalty reward.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "LOYALTY_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "LOYALTY_READ" ] } ], "parameters": [ { "name": "reward_id", "description": "The ID of the [loyalty reward](https://developer.squareup.com/reference/square_2024-10-17/objects/LoyaltyReward) to retrieve.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveLoyaltyRewardResponse" } } } } }, "/v2/loyalty/rewards/{reward_id}/redeem": { "post": { "tags": [ "Loyalty" ], "summary": "RedeemLoyaltyReward", "operationId": "RedeemLoyaltyReward", "description": "Redeems a loyalty reward.\n\nThe endpoint sets the reward to the `REDEEMED` terminal state.\n\nIf you are using your own order processing system (not using the\nOrders API), you call this endpoint after the buyer paid for the\npurchase.\n\nAfter the reward reaches the terminal state, it cannot be deleted.\nIn other words, points used for the reward cannot be returned\nto the account.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "LOYALTY_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "LOYALTY_WRITE" ] } ], "parameters": [ { "name": "reward_id", "description": "The ID of the [loyalty reward](https://developer.squareup.com/reference/square_2024-10-17/objects/LoyaltyReward) to redeem.", "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/RedeemLoyaltyRewardRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RedeemLoyaltyRewardResponse" } } } } }, "/v2/merchants": { "get": { "tags": [ "Merchants" ], "summary": "ListMerchants", "operationId": "ListMerchants", "description": "Provides details about the merchant associated with a given access token.\n\nThe access token used to connect your application to a Square seller is associated\nwith a single merchant. That means that `ListMerchants` returns a list\nwith a single `Merchant` object. You can specify your personal access token\nto get your own merchant information or specify an OAuth token to get the\ninformation for the merchant that granted your application access.\n\nIf you know the merchant ID, you can also use the [RetrieveMerchant](https://developer.squareup.com/reference/square_2024-10-17/merchants-api/retrieve-merchant)\nendpoint to retrieve the merchant information.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "MERCHANT_PROFILE_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "MERCHANT_PROFILE_READ" ] } ], "parameters": [ { "name": "cursor", "description": "The cursor generated by the previous response.", "type": "integer", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListMerchantsResponse" } } } } }, "/v2/merchants/custom-attribute-definitions": { "get": { "tags": [ "MerchantCustomAttributes" ], "summary": "ListMerchantCustomAttributeDefinitions", "operationId": "ListMerchantCustomAttributeDefinitions", "description": "Lists the merchant-related [custom attribute definitions](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttributeDefinition) that belong to a Square seller account.\nWhen all response pages are retrieved, the results include all custom attribute definitions\nthat are visible to the requesting application, including those that are created by other\napplications and set to `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "MERCHANT_PROFILE_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "MERCHANT_PROFILE_READ" ] } ], "parameters": [ { "name": "visibility_filter", "description": "Filters the `CustomAttributeDefinition` results by their `visibility` values.", "x-is-beta": true, "type": "string", "in": "query", "required": false }, { "name": "limit", "description": "The maximum number of results to return in a single paged response. This limit is advisory.\nThe response might contain more or fewer results. The minimum value is 1 and the maximum value is 100.\nThe default value is 20. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "x-is-beta": true, "type": "integer", "in": "query", "required": false }, { "name": "cursor", "description": "The cursor returned in the paged response from the previous call to this endpoint.\nProvide this cursor to retrieve the next page of results for your original request.\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "x-is-beta": true, "type": "string", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListMerchantCustomAttributeDefinitionsResponse" } } } }, "post": { "tags": [ "MerchantCustomAttributes" ], "summary": "CreateMerchantCustomAttributeDefinition", "operationId": "CreateMerchantCustomAttributeDefinition", "description": "Creates a merchant-related [custom attribute definition](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttributeDefinition) for a Square seller account.\nUse this endpoint to define a custom attribute that can be associated with a merchant connecting to your application.\nA custom attribute definition specifies the `key`, `visibility`, `schema`, and other properties\nfor a custom attribute. After the definition is created, you can call\n[UpsertMerchantCustomAttribute](https://developer.squareup.com/reference/square_2024-10-17/merchant-custom-attributes-api/upsert-merchant-custom-attribute) or\n[BulkUpsertMerchantCustomAttributes](https://developer.squareup.com/reference/square_2024-10-17/merchant-custom-attributes-api/bulk-upsert-merchant-custom-attributes)\nto set the custom attribute for a merchant.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "MERCHANT_PROFILE_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "MERCHANT_PROFILE_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CreateMerchantCustomAttributeDefinitionRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CreateMerchantCustomAttributeDefinitionResponse" } } } } }, "/v2/merchants/custom-attribute-definitions/{key}": { "delete": { "tags": [ "MerchantCustomAttributes" ], "summary": "DeleteMerchantCustomAttributeDefinition", "operationId": "DeleteMerchantCustomAttributeDefinition", "description": "Deletes a merchant-related [custom attribute definition](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttributeDefinition) from a Square seller account.\nDeleting a custom attribute definition also deletes the corresponding custom attribute from\nthe merchant.\nOnly the definition owner can delete a custom attribute definition.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "MERCHANT_PROFILE_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "MERCHANT_PROFILE_WRITE" ] } ], "parameters": [ { "name": "key", "description": "The key of the custom attribute definition to delete.", "x-is-beta": true, "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/DeleteMerchantCustomAttributeDefinitionResponse" } } } }, "get": { "tags": [ "MerchantCustomAttributes" ], "summary": "RetrieveMerchantCustomAttributeDefinition", "operationId": "RetrieveMerchantCustomAttributeDefinition", "description": "Retrieves a merchant-related [custom attribute definition](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttributeDefinition) from a Square seller account.\nTo retrieve a custom attribute definition created by another application, the `visibility`\nsetting must be `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "MERCHANT_PROFILE_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "MERCHANT_PROFILE_READ" ] } ], "parameters": [ { "name": "key", "description": "The key of the custom attribute definition to retrieve. If the requesting application\nis not the definition owner, you must use the qualified key.", "x-is-beta": true, "type": "string", "in": "path", "required": true }, { "name": "version", "description": "The current version of the custom attribute definition, which is used for strongly consistent\nreads to guarantee that you receive the most up-to-date data. When included in the request,\nSquare returns the specified version or a higher version if one exists. If the specified version\nis higher than the current version, Square returns a `BAD_REQUEST` error.", "x-is-beta": true, "type": "integer", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveMerchantCustomAttributeDefinitionResponse" } } } }, "put": { "tags": [ "MerchantCustomAttributes" ], "summary": "UpdateMerchantCustomAttributeDefinition", "operationId": "UpdateMerchantCustomAttributeDefinition", "description": "Updates a merchant-related [custom attribute definition](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttributeDefinition) for a Square seller account.\nUse this endpoint to update the following fields: `name`, `description`, `visibility`, or the\n`schema` for a `Selection` data type.\nOnly the definition owner can update a custom attribute definition.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "MERCHANT_PROFILE_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "MERCHANT_PROFILE_WRITE" ] } ], "parameters": [ { "name": "key", "description": "The key of the custom attribute definition to update.", "x-is-beta": true, "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/UpdateMerchantCustomAttributeDefinitionRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/UpdateMerchantCustomAttributeDefinitionResponse" } } } } }, "/v2/merchants/custom-attributes/bulk-delete": { "post": { "tags": [ "MerchantCustomAttributes" ], "summary": "BulkDeleteMerchantCustomAttributes", "operationId": "BulkDeleteMerchantCustomAttributes", "description": "Deletes [custom attributes](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttribute) for a merchant as a bulk operation.\nTo delete a custom attribute owned by another application, the `visibility` setting must be\n`VISIBILITY_READ_WRITE_VALUES`.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "MERCHANT_PROFILE_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "MERCHANT_PROFILE_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/BulkDeleteMerchantCustomAttributesRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/BulkDeleteMerchantCustomAttributesResponse" } } } } }, "/v2/merchants/custom-attributes/bulk-upsert": { "post": { "tags": [ "MerchantCustomAttributes" ], "summary": "BulkUpsertMerchantCustomAttributes", "operationId": "BulkUpsertMerchantCustomAttributes", "description": "Creates or updates [custom attributes](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttribute) for a merchant as a bulk operation.\nUse this endpoint to set the value of one or more custom attributes for a merchant.\nA custom attribute is based on a custom attribute definition in a Square seller account, which is\ncreated using the [CreateMerchantCustomAttributeDefinition](https://developer.squareup.com/reference/square_2024-10-17/merchant-custom-attributes-api/create-merchant-custom-attribute-definition) endpoint.\nThis `BulkUpsertMerchantCustomAttributes` endpoint accepts a map of 1 to 25 individual upsert\nrequests and returns a map of individual upsert responses. Each upsert request has a unique ID\nand provides a merchant ID and custom attribute. Each upsert response is returned with the ID\nof the corresponding request.\nTo create or update a custom attribute owned by another application, the `visibility` setting\nmust be `VISIBILITY_READ_WRITE_VALUES`.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "MERCHANT_PROFILE_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "MERCHANT_PROFILE_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/BulkUpsertMerchantCustomAttributesRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/BulkUpsertMerchantCustomAttributesResponse" } } } } }, "/v2/merchants/{merchant_id}": { "get": { "tags": [ "Merchants" ], "summary": "RetrieveMerchant", "operationId": "RetrieveMerchant", "description": "Retrieves the `Merchant` object for the given `merchant_id`.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "MERCHANT_PROFILE_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "MERCHANT_PROFILE_READ" ] } ], "parameters": [ { "name": "merchant_id", "description": "The ID of the merchant to retrieve. If the string \"me\" is supplied as the ID,\nthen retrieve the merchant that is currently accessible to this call.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveMerchantResponse" } } } } }, "/v2/merchants/{merchant_id}/custom-attributes": { "get": { "tags": [ "MerchantCustomAttributes" ], "summary": "ListMerchantCustomAttributes", "operationId": "ListMerchantCustomAttributes", "description": "Lists the [custom attributes](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttribute) associated with a merchant.\nYou can use the `with_definitions` query parameter to also retrieve custom attribute definitions\nin the same call.\nWhen all response pages are retrieved, the results include all custom attributes that are\nvisible to the requesting application, including those that are owned by other applications\nand set to `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "MERCHANT_PROFILE_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "MERCHANT_PROFILE_READ" ] } ], "parameters": [ { "name": "merchant_id", "description": "The ID of the target [merchant](https://developer.squareup.com/reference/square_2024-10-17/objects/Merchant).", "x-is-beta": true, "type": "string", "in": "path", "required": true }, { "name": "visibility_filter", "description": "Filters the `CustomAttributeDefinition` results by their `visibility` values.", "x-is-beta": true, "type": "string", "in": "query", "required": false }, { "name": "limit", "description": "The maximum number of results to return in a single paged response. This limit is advisory.\nThe response might contain more or fewer results. The minimum value is 1 and the maximum value is 100.\nThe default value is 20. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "x-is-beta": true, "type": "integer", "in": "query", "required": false }, { "name": "cursor", "description": "The cursor returned in the paged response from the previous call to this endpoint.\nProvide this cursor to retrieve the next page of results for your original request. For more\ninformation, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "x-is-beta": true, "type": "string", "in": "query", "required": false }, { "name": "with_definitions", "description": "Indicates whether to return the [custom attribute definition](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttributeDefinition) in the `definition` field of each\ncustom attribute. Set this parameter to `true` to get the name and description of each custom\nattribute, information about the data type, or other definition details. The default value is `false`.", "x-is-beta": true, "type": "boolean", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListMerchantCustomAttributesResponse" } } } } }, "/v2/merchants/{merchant_id}/custom-attributes/{key}": { "delete": { "tags": [ "MerchantCustomAttributes" ], "summary": "DeleteMerchantCustomAttribute", "operationId": "DeleteMerchantCustomAttribute", "description": "Deletes a [custom attribute](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttribute) associated with a merchant.\nTo delete a custom attribute owned by another application, the `visibility` setting must be\n`VISIBILITY_READ_WRITE_VALUES`.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "MERCHANT_PROFILE_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "MERCHANT_PROFILE_WRITE" ] } ], "parameters": [ { "name": "merchant_id", "description": "The ID of the target [merchant](https://developer.squareup.com/reference/square_2024-10-17/objects/Merchant).", "x-is-beta": true, "type": "string", "in": "path", "required": true }, { "name": "key", "description": "The key of the custom attribute to delete. This key must match the `key` of a custom\nattribute definition in the Square seller account. If the requesting application is not the\ndefinition owner, you must use the qualified key.", "x-is-beta": true, "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/DeleteMerchantCustomAttributeResponse" } } } }, "get": { "tags": [ "MerchantCustomAttributes" ], "summary": "RetrieveMerchantCustomAttribute", "operationId": "RetrieveMerchantCustomAttribute", "description": "Retrieves a [custom attribute](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttribute) associated with a merchant.\nYou can use the `with_definition` query parameter to also retrieve the custom attribute definition\nin the same call.\nTo retrieve a custom attribute owned by another application, the `visibility` setting must be\n`VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "MERCHANT_PROFILE_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "MERCHANT_PROFILE_READ" ] } ], "parameters": [ { "name": "merchant_id", "description": "The ID of the target [merchant](https://developer.squareup.com/reference/square_2024-10-17/objects/Merchant).", "x-is-beta": true, "type": "string", "in": "path", "required": true }, { "name": "key", "description": "The key of the custom attribute to retrieve. This key must match the `key` of a custom\nattribute definition in the Square seller account. If the requesting application is not the\ndefinition owner, you must use the qualified key.", "x-is-beta": true, "type": "string", "in": "path", "required": true }, { "name": "with_definition", "description": "Indicates whether to return the [custom attribute definition](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttributeDefinition) in the `definition` field of\nthe custom attribute. Set this parameter to `true` to get the name and description of the custom\nattribute, information about the data type, or other definition details. The default value is `false`.", "x-is-beta": true, "type": "boolean", "in": "query", "required": false }, { "name": "version", "description": "The current version of the custom attribute, which is used for strongly consistent reads to\nguarantee that you receive the most up-to-date data. When included in the request, Square\nreturns the specified version or a higher version if one exists. If the specified version is\nhigher than the current version, Square returns a `BAD_REQUEST` error.", "x-is-beta": true, "type": "integer", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveMerchantCustomAttributeResponse" } } } }, "post": { "tags": [ "MerchantCustomAttributes" ], "summary": "UpsertMerchantCustomAttribute", "operationId": "UpsertMerchantCustomAttribute", "description": "Creates or updates a [custom attribute](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttribute) for a merchant.\nUse this endpoint to set the value of a custom attribute for a specified merchant.\nA custom attribute is based on a custom attribute definition in a Square seller account, which\nis created using the [CreateMerchantCustomAttributeDefinition](https://developer.squareup.com/reference/square_2024-10-17/merchant-custom-attributes-api/create-merchant-custom-attribute-definition) endpoint.\nTo create or update a custom attribute owned by another application, the `visibility` setting\nmust be `VISIBILITY_READ_WRITE_VALUES`.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "MERCHANT_PROFILE_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "MERCHANT_PROFILE_WRITE" ] } ], "parameters": [ { "name": "merchant_id", "description": "The ID of the target [merchant](https://developer.squareup.com/reference/square_2024-10-17/objects/Merchant).", "x-is-beta": true, "type": "string", "in": "path", "required": true }, { "name": "key", "description": "The key of the custom attribute to create or update. This key must match the `key` of a\ncustom attribute definition in the Square seller account. If the requesting application is not\nthe definition owner, you must use the qualified key.", "x-is-beta": true, "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/UpsertMerchantCustomAttributeRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/UpsertMerchantCustomAttributeResponse" } } } } }, "/v2/online-checkout/location-settings/{location_id}": { "get": { "tags": [ "Checkout" ], "summary": "RetrieveLocationSettings", "operationId": "RetrieveLocationSettings", "description": "Retrieves the location-level settings for a Square-hosted checkout page.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "MERCHANT_PROFILE_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "MERCHANT_PROFILE_READ" ] } ], "parameters": [ { "name": "location_id", "description": "The ID of the location for which to retrieve settings.", "x-is-beta": true, "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveLocationSettingsResponse" } } } }, "put": { "tags": [ "Checkout" ], "summary": "UpdateLocationSettings", "operationId": "UpdateLocationSettings", "description": "Updates the location-level settings for a Square-hosted checkout page.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "MERCHANT_PROFILE_WRITE", "MERCHANT_PROFILE_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "MERCHANT_PROFILE_WRITE", "MERCHANT_PROFILE_READ" ] } ], "parameters": [ { "name": "location_id", "description": "The ID of the location for which to retrieve settings.", "x-is-beta": true, "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/UpdateLocationSettingsRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/UpdateLocationSettingsResponse" } } } } }, "/v2/online-checkout/merchant-settings": { "get": { "tags": [ "Checkout" ], "summary": "RetrieveMerchantSettings", "operationId": "RetrieveMerchantSettings", "description": "Retrieves the merchant-level settings for a Square-hosted checkout page.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "PAYMENT_METHODS_READ", "MERCHANT_PROFILE_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "PAYMENT_METHODS_READ", "MERCHANT_PROFILE_READ" ] } ], "parameters": [], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveMerchantSettingsResponse" } } } }, "put": { "tags": [ "Checkout" ], "summary": "UpdateMerchantSettings", "operationId": "UpdateMerchantSettings", "description": "Updates the merchant-level settings for a Square-hosted checkout page.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "MERCHANT_PROFILE_WRITE", "PAYMENT_METHODS_READ", "MERCHANT_PROFILE_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "MERCHANT_PROFILE_WRITE", "PAYMENT_METHODS_READ", "MERCHANT_PROFILE_READ" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/UpdateMerchantSettingsRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/UpdateMerchantSettingsResponse" } } } } }, "/v2/online-checkout/payment-links": { "get": { "tags": [ "Checkout" ], "summary": "ListPaymentLinks", "operationId": "ListPaymentLinks", "description": "Lists all payment links.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "ORDERS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ORDERS_READ" ] } ], "parameters": [ { "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 the original query.\nIf a cursor is not provided, the endpoint returns the first page of the results.\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "type": "string", "in": "query", "required": false }, { "name": "limit", "description": "A limit on the number of results to return per page. The limit is advisory and\nthe implementation might return more or less results. If the supplied limit is negative, zero, or\ngreater than the maximum limit of 1000, it is ignored.\n\nDefault value: `100`", "type": "integer", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListPaymentLinksResponse" } } } }, "post": { "tags": [ "Checkout" ], "summary": "CreatePaymentLink", "operationId": "CreatePaymentLink", "description": "Creates a Square-hosted checkout page. Applications can share the resulting payment link with their buyer to pay for goods and services.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "PAYMENTS_WRITE", "ORDERS_READ", "ORDERS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "PAYMENTS_WRITE", "ORDERS_READ", "ORDERS_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CreatePaymentLinkRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CreatePaymentLinkResponse" } } } } }, "/v2/online-checkout/payment-links/{id}": { "delete": { "tags": [ "Checkout" ], "summary": "DeletePaymentLink", "operationId": "DeletePaymentLink", "description": "Deletes a payment link.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "ORDERS_READ", "ORDERS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ORDERS_READ", "ORDERS_WRITE" ] } ], "parameters": [ { "name": "id", "description": "The ID of the payment link to delete.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/DeletePaymentLinkResponse" } } } }, "get": { "tags": [ "Checkout" ], "summary": "RetrievePaymentLink", "operationId": "RetrievePaymentLink", "description": "Retrieves a payment link.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "ORDERS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ORDERS_READ" ] } ], "parameters": [ { "name": "id", "description": "The ID of link to retrieve.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrievePaymentLinkResponse" } } } }, "put": { "tags": [ "Checkout" ], "summary": "UpdatePaymentLink", "operationId": "UpdatePaymentLink", "description": "Updates a payment link. You can update the `payment_link` fields such as\n`description`, `checkout_options`, and `pre_populated_data`.\nYou cannot update other fields such as the `order_id`, `version`, `URL`, or `timestamp` field.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "PAYMENTS_WRITE", "ORDERS_READ", "ORDERS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "PAYMENTS_WRITE", "ORDERS_READ", "ORDERS_WRITE" ] } ], "parameters": [ { "name": "id", "description": "The ID of the payment link to update.", "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/UpdatePaymentLinkRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/UpdatePaymentLinkResponse" } } } } }, "/v2/orders": { "post": { "tags": [ "Orders" ], "summary": "CreateOrder", "operationId": "CreateOrder", "description": "Creates a new [order](https://developer.squareup.com/reference/square_2024-10-17/objects/Order) that can include information about products for\npurchase and settings to apply to the purchase.\n\nTo pay for a created order, see\n[Pay for Orders](https://developer.squareup.com/docs/orders-api/pay-for-orders).\n\nYou can modify open orders using the [UpdateOrder](https://developer.squareup.com/reference/square_2024-10-17/orders-api/update-order) endpoint.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "ORDERS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ORDERS_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CreateOrderRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CreateOrderResponse" } } } } }, "/v2/orders/batch-retrieve": { "post": { "tags": [ "Orders" ], "summary": "BatchRetrieveOrders", "operationId": "BatchRetrieveOrders", "description": "Retrieves a set of [orders](https://developer.squareup.com/reference/square_2024-10-17/objects/Order) by their IDs.\n\nIf a given order ID does not exist, the ID is ignored instead of generating an error.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "ORDERS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ORDERS_READ" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/BatchRetrieveOrdersRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/BatchRetrieveOrdersResponse" } } } } }, "/v2/orders/calculate": { "post": { "tags": [ "Orders" ], "summary": "CalculateOrder", "operationId": "CalculateOrder", "description": "Enables applications to preview order pricing without creating an order.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CalculateOrderRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CalculateOrderResponse" } } } } }, "/v2/orders/clone": { "post": { "tags": [ "Orders" ], "summary": "CloneOrder", "operationId": "CloneOrder", "description": "Creates a new order, in the `DRAFT` state, by duplicating an existing order. The newly created order has\nonly the core fields (such as line items, taxes, and discounts) copied from the original order.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "ORDERS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ORDERS_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CloneOrderRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CloneOrderResponse" } } } } }, "/v2/orders/custom-attribute-definitions": { "get": { "tags": [ "OrderCustomAttributes" ], "summary": "ListOrderCustomAttributeDefinitions", "operationId": "ListOrderCustomAttributeDefinitions", "description": "Lists the order-related [custom attribute definitions](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttributeDefinition) that belong to a Square seller account.\n\nWhen all response pages are retrieved, the results include all custom attribute definitions\nthat are visible to the requesting application, including those that are created by other\napplications and set to `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`. Note that\nseller-defined custom attributes (also known as custom fields) are always set to `VISIBILITY_READ_WRITE_VALUES`.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "ORDERS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ORDERS_READ" ] } ], "parameters": [ { "name": "visibility_filter", "description": "Requests that all of the custom attributes be returned, or only those that are read-only or read-write.", "x-is-beta": true, "type": "string", "in": "query", "required": false }, { "name": "cursor", "description": "The cursor returned in the paged response from the previous call to this endpoint. \nProvide this cursor to retrieve the next page of results for your original request. \nFor more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).", "x-is-beta": true, "type": "string", "in": "query", "required": false }, { "name": "limit", "description": "The maximum number of results to return in a single paged response. This limit is advisory. \nThe response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. \nThe default value is 20.\nFor more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).", "x-is-beta": true, "type": "integer", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListOrderCustomAttributeDefinitionsResponse" } } } }, "post": { "tags": [ "OrderCustomAttributes" ], "summary": "CreateOrderCustomAttributeDefinition", "operationId": "CreateOrderCustomAttributeDefinition", "description": "Creates an order-related custom attribute definition. Use this endpoint to\ndefine a custom attribute that can be associated with orders.\n\nAfter creating a custom attribute definition, you can set the custom attribute for orders\nin the Square seller account.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "ORDERS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ORDERS_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CreateOrderCustomAttributeDefinitionRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CreateOrderCustomAttributeDefinitionResponse" } } } } }, "/v2/orders/custom-attribute-definitions/{key}": { "delete": { "tags": [ "OrderCustomAttributes" ], "summary": "DeleteOrderCustomAttributeDefinition", "operationId": "DeleteOrderCustomAttributeDefinition", "description": "Deletes an order-related [custom attribute definition](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttributeDefinition) from a Square seller account.\n\nOnly the definition owner can delete a custom attribute definition.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "ORDERS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ORDERS_WRITE" ] } ], "parameters": [ { "name": "key", "description": "The key of the custom attribute definition to delete.", "x-is-beta": true, "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/DeleteOrderCustomAttributeDefinitionResponse" } } } }, "get": { "tags": [ "OrderCustomAttributes" ], "summary": "RetrieveOrderCustomAttributeDefinition", "operationId": "RetrieveOrderCustomAttributeDefinition", "description": "Retrieves an order-related [custom attribute definition](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttributeDefinition) from a Square seller account.\n\nTo retrieve a custom attribute definition created by another application, the `visibility`\nsetting must be `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined custom attributes\n(also known as custom fields) are always set to `VISIBILITY_READ_WRITE_VALUES`.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "ORDERS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ORDERS_READ" ] } ], "parameters": [ { "name": "key", "description": "The key of the custom attribute definition to retrieve.", "x-is-beta": true, "type": "string", "in": "path", "required": true }, { "name": "version", "description": "To enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)\ncontrol, include this optional field and specify the current version of the custom attribute.", "x-is-beta": true, "type": "integer", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveOrderCustomAttributeDefinitionResponse" } } } }, "put": { "tags": [ "OrderCustomAttributes" ], "summary": "UpdateOrderCustomAttributeDefinition", "operationId": "UpdateOrderCustomAttributeDefinition", "description": "Updates an order-related custom attribute definition for a Square seller account.\n\nOnly the definition owner can update a custom attribute definition. Note that sellers can view all custom attributes in exported customer data, including those set to `VISIBILITY_HIDDEN`.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "ORDERS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ORDERS_WRITE" ] } ], "parameters": [ { "name": "key", "description": "The key of the custom attribute definition to update.", "x-is-beta": true, "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/UpdateOrderCustomAttributeDefinitionRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/UpdateOrderCustomAttributeDefinitionResponse" } } } } }, "/v2/orders/custom-attributes/bulk-delete": { "post": { "tags": [ "OrderCustomAttributes" ], "summary": "BulkDeleteOrderCustomAttributes", "operationId": "BulkDeleteOrderCustomAttributes", "description": "Deletes order [custom attributes](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttribute) as a bulk operation.\n\nUse this endpoint to delete one or more custom attributes from one or more orders.\nA custom attribute is based on a custom attribute definition in a Square seller account. (To create a\ncustom attribute definition, use the [CreateOrderCustomAttributeDefinition](https://developer.squareup.com/reference/square_2024-10-17/order-custom-attributes-api/create-order-custom-attribute-definition) endpoint.)\n\nThis `BulkDeleteOrderCustomAttributes` endpoint accepts a map of 1 to 25 individual delete\nrequests and returns a map of individual delete responses. Each delete request has a unique ID\nand provides an order ID and custom attribute. Each delete response is returned with the ID\nof the corresponding request.\n\nTo delete a custom attribute owned by another application, the `visibility` setting\nmust be `VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined custom attributes\n(also known as custom fields) are always set to `VISIBILITY_READ_WRITE_VALUES`.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "ORDERS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ORDERS_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/BulkDeleteOrderCustomAttributesRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/BulkDeleteOrderCustomAttributesResponse" } } } } }, "/v2/orders/custom-attributes/bulk-upsert": { "post": { "tags": [ "OrderCustomAttributes" ], "summary": "BulkUpsertOrderCustomAttributes", "operationId": "BulkUpsertOrderCustomAttributes", "description": "Creates or updates order [custom attributes](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttribute) as a bulk operation.\n\nUse this endpoint to delete one or more custom attributes from one or more orders.\nA custom attribute is based on a custom attribute definition in a Square seller account. (To create a\ncustom attribute definition, use the [CreateOrderCustomAttributeDefinition](https://developer.squareup.com/reference/square_2024-10-17/order-custom-attributes-api/create-order-custom-attribute-definition) endpoint.)\n\nThis `BulkUpsertOrderCustomAttributes` endpoint accepts a map of 1 to 25 individual upsert\nrequests and returns a map of individual upsert responses. Each upsert request has a unique ID\nand provides an order ID and custom attribute. Each upsert response is returned with the ID\nof the corresponding request.\n\nTo create or update a custom attribute owned by another application, the `visibility` setting\nmust be `VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined custom attributes\n(also known as custom fields) are always set to `VISIBILITY_READ_WRITE_VALUES`.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "ORDERS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ORDERS_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/BulkUpsertOrderCustomAttributesRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/BulkUpsertOrderCustomAttributesResponse" } } } } }, "/v2/orders/search": { "post": { "tags": [ "Orders" ], "summary": "SearchOrders", "operationId": "SearchOrders", "description": "Search all orders for one or more locations. Orders include all sales,\nreturns, and exchanges regardless of how or when they entered the Square\necosystem (such as Point of Sale, Invoices, and Connect APIs).\n\n`SearchOrders` requests need to specify which locations to search and define a\n[SearchOrdersQuery](https://developer.squareup.com/reference/square_2024-10-17/objects/SearchOrdersQuery) object that controls\nhow to sort or filter the results. Your `SearchOrdersQuery` can:\n\n Set filter criteria.\n Set the sort order.\n Determine whether to return results as complete `Order` objects or as\n[OrderEntry](https://developer.squareup.com/reference/square_2024-10-17/objects/OrderEntry) objects.\n\nNote that details for orders processed with Square Point of Sale while in\noffline mode might not be transmitted to Square for up to 72 hours. Offline\norders have a `created_at` value that reflects the time the order was created,\nnot the time it was subsequently transmitted to Square.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "ORDERS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ORDERS_READ" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/SearchOrdersRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/SearchOrdersResponse" } } } } }, "/v2/orders/{order_id}": { "get": { "tags": [ "Orders" ], "summary": "RetrieveOrder", "operationId": "RetrieveOrder", "description": "Retrieves an [Order](https://developer.squareup.com/reference/square_2024-10-17/objects/Order) by ID.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "ORDERS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ORDERS_READ" ] } ], "parameters": [ { "name": "order_id", "description": "The ID of the order to retrieve.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveOrderResponse" } } } }, "put": { "tags": [ "Orders" ], "summary": "UpdateOrder", "operationId": "UpdateOrder", "description": "Updates an open [order](https://developer.squareup.com/reference/square_2024-10-17/objects/Order) by adding, replacing, or deleting\nfields. Orders with a `COMPLETED` or `CANCELED` state cannot be updated.\n\nAn `UpdateOrder` request requires the following:\n\n- The `order_id` in the endpoint path, identifying the order to update.\n- The latest `version` of the order to update.\n- The [sparse order](https://developer.squareup.com/docs/orders-api/manage-orders/update-orders#sparse-order-objects)\ncontaining only the fields to update and the version to which the update is\nbeing applied.\n- If deleting fields, the [dot notation paths](https://developer.squareup.com/docs/orders-api/manage-orders/update-orders#identifying-fields-to-delete)\nidentifying the fields to clear.\n\nTo pay for an order, see\n[Pay for Orders](https://developer.squareup.com/docs/orders-api/pay-for-orders).", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "ORDERS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ORDERS_WRITE" ] } ], "parameters": [ { "name": "order_id", "description": "The ID of the order to update.", "x-is-beta": true, "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/UpdateOrderRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/UpdateOrderResponse" } } } } }, "/v2/orders/{order_id}/custom-attributes": { "get": { "tags": [ "OrderCustomAttributes" ], "summary": "ListOrderCustomAttributes", "operationId": "ListOrderCustomAttributes", "description": "Lists the [custom attributes](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttribute) associated with an order.\n\nYou can use the `with_definitions` query parameter to also retrieve custom attribute definitions\nin the same call.\n\nWhen all response pages are retrieved, the results include all custom attributes that are\nvisible to the requesting application, including those that are owned by other applications\nand set to `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "ORDERS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ORDERS_READ" ] } ], "parameters": [ { "name": "order_id", "description": "The ID of the target [order](https://developer.squareup.com/reference/square_2024-10-17/objects/Order).", "x-is-beta": true, "type": "string", "in": "path", "required": true }, { "name": "visibility_filter", "description": "Requests that all of the custom attributes be returned, or only those that are read-only or read-write.", "x-is-beta": true, "type": "string", "in": "query", "required": false }, { "name": "cursor", "description": "The cursor returned in the paged response from the previous call to this endpoint. \nProvide this cursor to retrieve the next page of results for your original request. \nFor more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).", "x-is-beta": true, "type": "string", "in": "query", "required": false }, { "name": "limit", "description": "The maximum number of results to return in a single paged response. This limit is advisory. \nThe response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. \nThe default value is 20.\nFor more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).", "x-is-beta": true, "type": "integer", "in": "query", "required": false }, { "name": "with_definitions", "description": "Indicates whether to return the [custom attribute definition](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttributeDefinition) in the `definition` field of each\ncustom attribute. Set this parameter to `true` to get the name and description of each custom attribute, \ninformation about the data type, or other definition details. The default value is `false`.", "x-is-beta": true, "type": "boolean", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListOrderCustomAttributesResponse" } } } } }, "/v2/orders/{order_id}/custom-attributes/{custom_attribute_key}": { "delete": { "tags": [ "OrderCustomAttributes" ], "summary": "DeleteOrderCustomAttribute", "operationId": "DeleteOrderCustomAttribute", "description": "Deletes a [custom attribute](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttribute) associated with a customer profile.\n\nTo delete a custom attribute owned by another application, the `visibility` setting must be\n`VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined custom attributes\n(also known as custom fields) are always set to `VISIBILITY_READ_WRITE_VALUES`.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "ORDERS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ORDERS_WRITE" ] } ], "parameters": [ { "name": "order_id", "description": "The ID of the target [order](https://developer.squareup.com/reference/square_2024-10-17/objects/Order).", "x-is-beta": true, "type": "string", "in": "path", "required": true }, { "name": "custom_attribute_key", "description": "The key of the custom attribute to delete. This key must match the key of an\nexisting custom attribute definition.", "x-is-beta": true, "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/DeleteOrderCustomAttributeResponse" } } } }, "get": { "tags": [ "OrderCustomAttributes" ], "summary": "RetrieveOrderCustomAttribute", "operationId": "RetrieveOrderCustomAttribute", "description": "Retrieves a [custom attribute](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttribute) associated with an order.\n\nYou can use the `with_definition` query parameter to also retrieve the custom attribute definition\nin the same call.\n\nTo retrieve a custom attribute owned by another application, the `visibility` setting must be\n`VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined custom attributes\nalso known as custom fields) are always set to `VISIBILITY_READ_WRITE_VALUES`.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "ORDERS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ORDERS_READ" ] } ], "parameters": [ { "name": "order_id", "description": "The ID of the target [order](https://developer.squareup.com/reference/square_2024-10-17/objects/Order).", "x-is-beta": true, "type": "string", "in": "path", "required": true }, { "name": "custom_attribute_key", "description": "The key of the custom attribute to retrieve. This key must match the key of an\nexisting custom attribute definition.", "x-is-beta": true, "type": "string", "in": "path", "required": true }, { "name": "version", "description": "To enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)\ncontrol, include this optional field and specify the current version of the custom attribute.", "x-is-beta": true, "type": "integer", "in": "query", "required": false }, { "name": "with_definition", "description": "Indicates whether to return the [custom attribute definition](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttributeDefinition) in the `definition` field of each \ncustom attribute. Set this parameter to `true` to get the name and description of each custom attribute, \ninformation about the data type, or other definition details. The default value is `false`.", "x-is-beta": true, "type": "boolean", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveOrderCustomAttributeResponse" } } } }, "post": { "tags": [ "OrderCustomAttributes" ], "summary": "UpsertOrderCustomAttribute", "operationId": "UpsertOrderCustomAttribute", "description": "Creates or updates a [custom attribute](https://developer.squareup.com/reference/square_2024-10-17/objects/CustomAttribute) for an order.\n\nUse this endpoint to set the value of a custom attribute for a specific order.\nA custom attribute is based on a custom attribute definition in a Square seller account. (To create a\ncustom attribute definition, use the [CreateOrderCustomAttributeDefinition](https://developer.squareup.com/reference/square_2024-10-17/order-custom-attributes-api/create-order-custom-attribute-definition) endpoint.)\n\nTo create or update a custom attribute owned by another application, the `visibility` setting\nmust be `VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined custom attributes\n(also known as custom fields) are always set to `VISIBILITY_READ_WRITE_VALUES`.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "ORDERS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ORDERS_WRITE" ] } ], "parameters": [ { "name": "order_id", "description": "The ID of the target [order](https://developer.squareup.com/reference/square_2024-10-17/objects/Order).", "x-is-beta": true, "type": "string", "in": "path", "required": true }, { "name": "custom_attribute_key", "description": "The key of the custom attribute to create or update. This key must match the key \nof an existing custom attribute definition.", "x-is-beta": true, "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/UpsertOrderCustomAttributeRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/UpsertOrderCustomAttributeResponse" } } } } }, "/v2/orders/{order_id}/pay": { "post": { "tags": [ "Orders" ], "summary": "PayOrder", "operationId": "PayOrder", "description": "Pay for an [order](https://developer.squareup.com/reference/square_2024-10-17/objects/Order) using one or more approved [payments](https://developer.squareup.com/reference/square_2024-10-17/objects/Payment)\nor settle an order with a total of `0`.\n\nThe total of the `payment_ids` listed in the request must be equal to the order\ntotal. Orders with a total amount of `0` can be marked as paid by specifying an empty\narray of `payment_ids` in the request.\n\nTo be used with `PayOrder`, a payment must:\n\n- Reference the order by specifying the `order_id` when [creating the payment](https://developer.squareup.com/reference/square_2024-10-17/payments-api/create-payment).\nAny approved payments that reference the same `order_id` not specified in the\n`payment_ids` is canceled.\n- Be approved with [delayed capture](https://developer.squareup.com/docs/payments-api/take-payments/card-payments/delayed-capture).\nUsing a delayed capture payment with `PayOrder` completes the approved payment.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "PAYMENTS_WRITE", "ORDERS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "PAYMENTS_WRITE", "ORDERS_WRITE" ] } ], "parameters": [ { "name": "order_id", "description": "The ID of the order being paid.", "x-is-beta": true, "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/PayOrderRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/PayOrderResponse" } } } } }, "/v2/payments": { "get": { "tags": [ "Payments" ], "summary": "ListPayments", "operationId": "ListPayments", "description": "Retrieves a list of payments taken by the account making the request.\n\nResults are eventually consistent, and new payments or changes to payments might take several\nseconds to appear.\n\nThe maximum results per page is 100.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "PAYMENTS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "PAYMENTS_READ" ] } ], "parameters": [ { "name": "begin_time", "description": "Indicates the start of the time range to retrieve payments for, in RFC 3339 format. \nThe range is determined using the `created_at` field for each Payment.\nInclusive. Default: The current time minus one year.", "type": "string", "in": "query", "required": false }, { "name": "end_time", "description": "Indicates the end of the time range to retrieve payments for, in RFC 3339 format. The \nrange is determined using the `created_at` field for each Payment.\n\nDefault: The current time.", "type": "string", "in": "query", "required": false }, { "name": "sort_order", "description": "The order in which results are listed by `Payment.created_at`:\n- `ASC` - Oldest to newest.\n- `DESC` - Newest to oldest (default).", "type": "string", "in": "query", "required": false }, { "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 the original query.\n\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "type": "string", "in": "query", "required": false }, { "name": "location_id", "description": "Limit results to the location supplied. By default, results are returned\nfor the default (main) location associated with the seller.", "type": "string", "in": "query", "required": false }, { "name": "total", "description": "The exact amount in the `total_money` for a payment.", "type": "integer", "format": "int64", "in": "query", "required": false }, { "name": "last_4", "description": "The last four digits of a payment card.", "type": "string", "in": "query", "required": false }, { "name": "card_brand", "description": "The brand of the payment card (for example, VISA).", "type": "string", "in": "query", "required": false }, { "name": "limit", "description": "The maximum number of results to be returned in a single page.\nIt is possible to receive fewer results than the specified limit on a given page.\n\nThe default value of 100 is also the maximum allowed value. If the provided value is \ngreater than 100, it is ignored and the default value is used instead.\n\nDefault: `100`", "type": "integer", "in": "query", "required": false }, { "name": "is_offline_payment", "description": "Whether the payment was taken offline or not.", "type": "boolean", "in": "query", "required": false }, { "name": "offline_begin_time", "description": "Indicates the start of the time range for which to retrieve offline payments, in RFC 3339\nformat for timestamps. The range is determined using the\n`offline_payment_details.client_created_at` field for each Payment. If set, payments without a\nvalue set in `offline_payment_details.client_created_at` will not be returned.\n\nDefault: The current time.", "type": "string", "in": "query", "required": false }, { "name": "offline_end_time", "description": "Indicates the end of the time range for which to retrieve offline payments, in RFC 3339\nformat for timestamps. The range is determined using the\n`offline_payment_details.client_created_at` field for each Payment. If set, payments without a\nvalue set in `offline_payment_details.client_created_at` will not be returned.\n\nDefault: The current time.", "type": "string", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListPaymentsResponse" } } } }, "post": { "tags": [ "Payments" ], "summary": "CreatePayment", "operationId": "CreatePayment", "description": "Creates a payment using the provided source. You can use this endpoint \nto charge a card (credit/debit card or \nSquare gift card) or record a payment that the seller received outside of Square \n(cash payment from a buyer or a payment that an external entity \nprocessed on behalf of the seller).\n\nThe endpoint creates a \n`Payment` object and returns it in the response.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "PAYMENTS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "PAYMENTS_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CreatePaymentRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CreatePaymentResponse" } } } } }, "/v2/payments/cancel": { "post": { "tags": [ "Payments" ], "summary": "CancelPaymentByIdempotencyKey", "operationId": "CancelPaymentByIdempotencyKey", "description": "Cancels (voids) a payment identified by the idempotency key that is specified in the\nrequest.\n\nUse this method when the status of a `CreatePayment` request is unknown (for example, after you send a\n`CreatePayment` request, a network error occurs and you do not get a response). In this case, you can\ndirect Square to cancel the payment using this endpoint. In the request, you provide the same\nidempotency key that you provided in your `CreatePayment` request that you want to cancel. After\ncanceling the payment, you can submit your `CreatePayment` request again.\n\nNote that if no payment with the specified idempotency key is found, no action is taken and the endpoint\nreturns successfully.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "PAYMENTS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "PAYMENTS_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CancelPaymentByIdempotencyKeyRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CancelPaymentByIdempotencyKeyResponse" } } } } }, "/v2/payments/{payment_id}": { "get": { "tags": [ "Payments" ], "summary": "GetPayment", "operationId": "GetPayment", "description": "Retrieves details for a specific payment.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "PAYMENTS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "PAYMENTS_READ" ] } ], "parameters": [ { "name": "payment_id", "description": "A unique ID for the desired payment.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/GetPaymentResponse" } } } }, "put": { "tags": [ "Payments" ], "summary": "UpdatePayment", "operationId": "UpdatePayment", "description": "Updates a payment with the APPROVED status.\nYou can update the `amount_money` and `tip_money` using this endpoint.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "PAYMENTS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "PAYMENTS_WRITE" ] } ], "parameters": [ { "name": "payment_id", "description": "The ID of the payment to update.", "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/UpdatePaymentRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/UpdatePaymentResponse" } } } } }, "/v2/payments/{payment_id}/cancel": { "post": { "tags": [ "Payments" ], "summary": "CancelPayment", "operationId": "CancelPayment", "description": "Cancels (voids) a payment. You can use this endpoint to cancel a payment with \nthe APPROVED `status`.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "PAYMENTS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "PAYMENTS_WRITE" ] } ], "parameters": [ { "name": "payment_id", "description": "The ID of the payment to cancel.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CancelPaymentResponse" } } } } }, "/v2/payments/{payment_id}/complete": { "post": { "tags": [ "Payments" ], "summary": "CompletePayment", "operationId": "CompletePayment", "description": "Completes (captures) a payment.\nBy default, payments are set to complete immediately after they are created.\n\nYou can use this endpoint to complete a payment with the APPROVED `status`.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "PAYMENTS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "PAYMENTS_WRITE" ] } ], "parameters": [ { "name": "payment_id", "description": "The unique ID identifying the payment to be completed.", "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CompletePaymentRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CompletePaymentResponse" } } } } }, "/v2/payouts": { "get": { "tags": [ "Payouts" ], "summary": "ListPayouts", "operationId": "ListPayouts", "description": "Retrieves a list of all payouts for the default location.\nYou can filter payouts by location ID, status, time range, and order them in ascending or descending order.\nTo call this endpoint, set `PAYOUTS_READ` for the OAuth scope.", "x-release-status": "PUBLIC", "x-oauthpermissions": [], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [] } ], "parameters": [ { "name": "location_id", "description": "The ID of the location for which to list the payouts.\nBy default, payouts are returned for the default (main) location associated with the seller.", "type": "string", "in": "query", "required": false }, { "name": "status", "description": "If provided, only payouts with the given status are returned.", "type": "string", "in": "query", "required": false }, { "name": "begin_time", "description": "The timestamp for the beginning of the payout creation time, in RFC 3339 format.\nInclusive. Default: The current time minus one year.", "type": "string", "in": "query", "required": false }, { "name": "end_time", "description": "The timestamp for the end of the payout creation time, in RFC 3339 format.\nDefault: The current time.", "type": "string", "in": "query", "required": false }, { "name": "sort_order", "description": "The order in which payouts are listed.", "type": "string", "in": "query", "required": false }, { "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 the original query.\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).\nIf request parameters change between requests, subsequent results may contain duplicates or missing records.", "type": "string", "in": "query", "required": false }, { "name": "limit", "description": "The maximum number of results to be returned in a single page.\nIt is possible to receive fewer results than the specified limit on a given page.\nThe default value of 100 is also the maximum allowed value. If the provided value is\ngreater than 100, it is ignored and the default value is used instead.\nDefault: `100`", "type": "integer", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListPayoutsResponse" } } } } }, "/v2/payouts/{payout_id}": { "get": { "tags": [ "Payouts" ], "summary": "GetPayout", "operationId": "GetPayout", "description": "Retrieves details of a specific payout identified by a payout ID.\nTo call this endpoint, set `PAYOUTS_READ` for the OAuth scope.", "x-release-status": "PUBLIC", "x-oauthpermissions": [], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [] } ], "parameters": [ { "name": "payout_id", "description": "The ID of the payout to retrieve the information for.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/GetPayoutResponse" } } } } }, "/v2/payouts/{payout_id}/payout-entries": { "get": { "tags": [ "Payouts" ], "summary": "ListPayoutEntries", "operationId": "ListPayoutEntries", "description": "Retrieves a list of all payout entries for a specific payout.\nTo call this endpoint, set `PAYOUTS_READ` for the OAuth scope.", "x-release-status": "PUBLIC", "x-oauthpermissions": [], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [] } ], "parameters": [ { "name": "payout_id", "description": "The ID of the payout to retrieve the information for.", "type": "string", "in": "path", "required": true }, { "name": "sort_order", "description": "The order in which payout entries are listed.", "type": "string", "in": "query", "required": false }, { "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 the original query.\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).\nIf request parameters change between requests, subsequent results may contain duplicates or missing records.", "type": "string", "in": "query", "required": false }, { "name": "limit", "description": "The maximum number of results to be returned in a single page.\nIt is possible to receive fewer results than the specified limit on a given page.\nThe default value of 100 is also the maximum allowed value. If the provided value is\ngreater than 100, it is ignored and the default value is used instead.\nDefault: `100`", "type": "integer", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListPayoutEntriesResponse" } } } } }, "/v2/refunds": { "get": { "tags": [ "Refunds" ], "summary": "ListPaymentRefunds", "operationId": "ListPaymentRefunds", "description": "Retrieves a list of refunds for the account making the request.\n\nResults are eventually consistent, and new refunds or changes to refunds might take several\nseconds to appear.\n\nThe maximum results per page is 100.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "PAYMENTS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "PAYMENTS_READ" ] } ], "parameters": [ { "name": "begin_time", "description": "Indicates the start of the time range to retrieve each `PaymentRefund` for, in RFC 3339 \nformat. The range is determined using the `created_at` field for each `PaymentRefund`. \n\nDefault: The current time minus one year.", "type": "string", "in": "query", "required": false }, { "name": "end_time", "description": "Indicates the end of the time range to retrieve each `PaymentRefund` for, in RFC 3339 \nformat. The range is determined using the `created_at` field for each `PaymentRefund`.\n\nDefault: The current time.", "type": "string", "in": "query", "required": false }, { "name": "sort_order", "description": "The order in which results are listed by `PaymentRefund.created_at`:\n- `ASC` - Oldest to newest.\n- `DESC` - Newest to oldest (default).", "type": "string", "in": "query", "required": false }, { "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 the original query.\n\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "type": "string", "in": "query", "required": false }, { "name": "location_id", "description": "Limit results to the location supplied. By default, results are returned\nfor all locations associated with the seller.", "type": "string", "in": "query", "required": false }, { "name": "status", "description": "If provided, only refunds with the given status are returned.\nFor a list of refund status values, see [PaymentRefund](https://developer.squareup.com/reference/square_2024-10-17/objects/PaymentRefund).\n\nDefault: If omitted, refunds are returned regardless of their status.", "type": "string", "in": "query", "required": false }, { "name": "source_type", "description": "If provided, only returns refunds whose payments have the indicated source type.\nCurrent values include `CARD`, `BANK_ACCOUNT`, `WALLET`, `CASH`, and `EXTERNAL`.\nFor information about these payment source types, see\n[Take Payments](https://developer.squareup.com/docs/payments-api/take-payments).\n\nDefault: If omitted, refunds are returned regardless of the source type.", "type": "string", "in": "query", "required": false }, { "name": "limit", "description": "The maximum number of results to be returned in a single page.\n\nIt is possible to receive fewer results than the specified limit on a given page.\n\nIf the supplied value is greater than 100, no more than 100 results are returned.\n\nDefault: 100", "type": "integer", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListPaymentRefundsResponse" } } } }, "post": { "tags": [ "Refunds" ], "summary": "RefundPayment", "operationId": "RefundPayment", "description": "Refunds a payment. You can refund the entire payment amount or a\nportion of it. You can use this endpoint to refund a card payment or record a \nrefund of a cash or external payment. For more information, see\n[Refund Payment](https://developer.squareup.com/docs/payments-api/refund-payments).", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "PAYMENTS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "PAYMENTS_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/RefundPaymentRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RefundPaymentResponse" } } } } }, "/v2/refunds/{refund_id}": { "get": { "tags": [ "Refunds" ], "summary": "GetPaymentRefund", "operationId": "GetPaymentRefund", "description": "Retrieves a specific refund using the `refund_id`.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "PAYMENTS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "PAYMENTS_READ" ] } ], "parameters": [ { "name": "refund_id", "description": "The unique ID for the desired `PaymentRefund`.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/GetPaymentRefundResponse" } } } } }, "/v2/sites": { "get": { "tags": [ "Sites" ], "summary": "ListSites", "operationId": "ListSites", "description": "Lists the Square Online sites that belong to a seller. Sites are listed in descending order by the `created_at` date.\n\n\n__Note:__ Square Online APIs are publicly available as part of an early access program. For more information, see [Early access program for Square Online APIs](https://developer.squareup.com/docs/online-api#early-access-program-for-square-online-apis).", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "ONLINE_STORE_SITE_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ONLINE_STORE_SITE_READ" ] } ], "parameters": [], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListSitesResponse" } } } } }, "/v2/sites/{site_id}/snippet": { "delete": { "tags": [ "Snippets" ], "summary": "DeleteSnippet", "operationId": "DeleteSnippet", "description": "Removes your snippet from a Square Online site.\n\nYou can call [ListSites](https://developer.squareup.com/reference/square_2024-10-17/sites-api/list-sites) to get the IDs of the sites that belong to a seller.\n\n\n__Note:__ Square Online APIs are publicly available as part of an early access program. For more information, see [Early access program for Square Online APIs](https://developer.squareup.com/docs/online-api#early-access-program-for-square-online-apis).", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "ONLINE_STORE_SNIPPETS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ONLINE_STORE_SNIPPETS_WRITE" ] } ], "parameters": [ { "name": "site_id", "description": "The ID of the site that contains the snippet.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/DeleteSnippetResponse" } } } }, "get": { "tags": [ "Snippets" ], "summary": "RetrieveSnippet", "operationId": "RetrieveSnippet", "description": "Retrieves your snippet from a Square Online site. A site can contain snippets from multiple snippet applications, but you can retrieve only the snippet that was added by your application.\n\nYou can call [ListSites](https://developer.squareup.com/reference/square_2024-10-17/sites-api/list-sites) to get the IDs of the sites that belong to a seller.\n\n\n__Note:__ Square Online APIs are publicly available as part of an early access program. For more information, see [Early access program for Square Online APIs](https://developer.squareup.com/docs/online-api#early-access-program-for-square-online-apis).", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "ONLINE_STORE_SNIPPETS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ONLINE_STORE_SNIPPETS_READ" ] } ], "parameters": [ { "name": "site_id", "description": "The ID of the site that contains the snippet.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveSnippetResponse" } } } }, "post": { "tags": [ "Snippets" ], "summary": "UpsertSnippet", "operationId": "UpsertSnippet", "description": "Adds a snippet to a Square Online site or updates the existing snippet on the site. \nThe snippet code is appended to the end of the `head` element on every page of the site, except checkout pages. A snippet application can add one snippet to a given site. \n\nYou can call [ListSites](https://developer.squareup.com/reference/square_2024-10-17/sites-api/list-sites) to get the IDs of the sites that belong to a seller.\n\n\n__Note:__ Square Online APIs are publicly available as part of an early access program. For more information, see [Early access program for Square Online APIs](https://developer.squareup.com/docs/online-api#early-access-program-for-square-online-apis).", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "ONLINE_STORE_SNIPPETS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "ONLINE_STORE_SNIPPETS_WRITE" ] } ], "parameters": [ { "name": "site_id", "description": "The ID of the site where you want to add or update the snippet.", "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/UpsertSnippetRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/UpsertSnippetResponse" } } } } }, "/v2/subscriptions": { "post": { "tags": [ "Subscriptions" ], "summary": "CreateSubscription", "operationId": "CreateSubscription", "description": "Enrolls a customer in a subscription.\n\nIf you provide a card on file in the request, Square charges the card for\nthe subscription. Otherwise, Square sends an invoice to the customer\u0027s email\naddress. The subscription starts immediately, unless the request includes\nthe optional `start_date`. Each individual subscription is associated with a particular location.\n\nFor more information, see [Create a subscription](https://developer.squareup.com/docs/subscriptions-api/manage-subscriptions#create-a-subscription).", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "CUSTOMERS_READ", "PAYMENTS_WRITE", "SUBSCRIPTIONS_WRITE", "ITEMS_READ", "ORDERS_WRITE", "INVOICES_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CUSTOMERS_READ", "PAYMENTS_WRITE", "SUBSCRIPTIONS_WRITE", "ITEMS_READ", "ORDERS_WRITE", "INVOICES_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CreateSubscriptionRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CreateSubscriptionResponse" } } } } }, "/v2/subscriptions/bulk-swap-plan": { "post": { "tags": [ "Subscriptions" ], "summary": "BulkSwapPlan", "operationId": "BulkSwapPlan", "description": "Schedules a plan variation change for all active subscriptions under a given plan\nvariation. For more information, see [Swap Subscription Plan Variations](https://developer.squareup.com/docs/subscriptions-api/swap-plan-variations).", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "SUBSCRIPTIONS_WRITE", "SUBSCRIPTIONS_READ", "ITEMS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "SUBSCRIPTIONS_WRITE", "SUBSCRIPTIONS_READ", "ITEMS_READ" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/BulkSwapPlanRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/BulkSwapPlanResponse" } } } } }, "/v2/subscriptions/search": { "post": { "tags": [ "Subscriptions" ], "summary": "SearchSubscriptions", "operationId": "SearchSubscriptions", "description": "Searches for subscriptions.\n\nResults are ordered chronologically by subscription creation date. If\nthe request specifies more than one location ID,\nthe endpoint orders the result\nby location ID, and then by creation date within each location. If no locations are given\nin the query, all locations are searched.\n\nYou can also optionally specify `customer_ids` to search by customer.\nIf left unset, all customers\nassociated with the specified locations are returned.\nIf the request specifies customer IDs, the endpoint orders results\nfirst by location, within location by customer ID, and within\ncustomer by subscription creation date.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "SUBSCRIPTIONS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "SUBSCRIPTIONS_READ" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/SearchSubscriptionsRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/SearchSubscriptionsResponse" } } } } }, "/v2/subscriptions/{subscription_id}": { "get": { "tags": [ "Subscriptions" ], "summary": "RetrieveSubscription", "operationId": "RetrieveSubscription", "description": "Retrieves a specific subscription.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "SUBSCRIPTIONS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "SUBSCRIPTIONS_READ" ] } ], "parameters": [ { "name": "subscription_id", "description": "The ID of the subscription to retrieve.", "type": "string", "in": "path", "required": true }, { "name": "include", "description": "A query parameter to specify related information to be included in the response. \n\nThe supported query parameter values are: \n\n- `actions`: to include scheduled actions on the targeted subscription.", "x-is-beta": true, "type": "string", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveSubscriptionResponse" } } } }, "put": { "tags": [ "Subscriptions" ], "summary": "UpdateSubscription", "operationId": "UpdateSubscription", "description": "Updates a subscription by modifying or clearing `subscription` field values.\nTo clear a field, set its value to `null`.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "CUSTOMERS_READ", "PAYMENTS_WRITE", "SUBSCRIPTIONS_WRITE", "ITEMS_READ", "ORDERS_WRITE", "INVOICES_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CUSTOMERS_READ", "PAYMENTS_WRITE", "SUBSCRIPTIONS_WRITE", "ITEMS_READ", "ORDERS_WRITE", "INVOICES_WRITE" ] } ], "parameters": [ { "name": "subscription_id", "description": "The ID of the subscription to update.", "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/UpdateSubscriptionRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/UpdateSubscriptionResponse" } } } } }, "/v2/subscriptions/{subscription_id}/actions/{action_id}": { "delete": { "tags": [ "Subscriptions" ], "summary": "DeleteSubscriptionAction", "operationId": "DeleteSubscriptionAction", "description": "Deletes a scheduled action for a subscription.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "SUBSCRIPTIONS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "SUBSCRIPTIONS_WRITE" ] } ], "parameters": [ { "name": "subscription_id", "description": "The ID of the subscription the targeted action is to act upon.", "x-is-beta": true, "type": "string", "in": "path", "required": true }, { "name": "action_id", "description": "The ID of the targeted action to be deleted.", "x-is-beta": true, "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/DeleteSubscriptionActionResponse" } } } } }, "/v2/subscriptions/{subscription_id}/billing-anchor": { "post": { "tags": [ "Subscriptions" ], "summary": "ChangeBillingAnchorDate", "operationId": "ChangeBillingAnchorDate", "description": "Changes the [billing anchor date](https://developer.squareup.com/docs/subscriptions-api/subscription-billing#billing-dates)\nfor a subscription.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "SUBSCRIPTIONS_WRITE", "SUBSCRIPTIONS_READ", "ITEMS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "SUBSCRIPTIONS_WRITE", "SUBSCRIPTIONS_READ", "ITEMS_READ" ] } ], "parameters": [ { "name": "subscription_id", "description": "The ID of the subscription to update the billing anchor date.", "x-is-beta": true, "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/ChangeBillingAnchorDateRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ChangeBillingAnchorDateResponse" } } } } }, "/v2/subscriptions/{subscription_id}/cancel": { "post": { "tags": [ "Subscriptions" ], "summary": "CancelSubscription", "operationId": "CancelSubscription", "description": "Schedules a `CANCEL` action to cancel an active subscription. This \nsets the `canceled_date` field to the end of the active billing period. After this date, \nthe subscription status changes from ACTIVE to CANCELED.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "SUBSCRIPTIONS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "SUBSCRIPTIONS_WRITE" ] } ], "parameters": [ { "name": "subscription_id", "description": "The ID of the subscription to cancel.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CancelSubscriptionResponse" } } } } }, "/v2/subscriptions/{subscription_id}/events": { "get": { "tags": [ "Subscriptions" ], "summary": "ListSubscriptionEvents", "operationId": "ListSubscriptionEvents", "description": "Lists all [events](https://developer.squareup.com/docs/subscriptions-api/actions-events) for a specific subscription.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "SUBSCRIPTIONS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "SUBSCRIPTIONS_READ" ] } ], "parameters": [ { "name": "subscription_id", "description": "The ID of the subscription to retrieve the events for.", "type": "string", "in": "path", "required": true }, { "name": "cursor", "description": "When the total number of resulting subscription events exceeds the limit of a paged response, \nspecify the cursor returned from a preceding response here to fetch the next set of results.\nIf the cursor is unset, the response contains the last page of the results.\n\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).", "type": "string", "in": "query", "required": false }, { "name": "limit", "description": "The upper limit on the number of subscription events to return\nin a paged response.", "type": "integer", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListSubscriptionEventsResponse" } } } } }, "/v2/subscriptions/{subscription_id}/pause": { "post": { "tags": [ "Subscriptions" ], "summary": "PauseSubscription", "operationId": "PauseSubscription", "description": "Schedules a `PAUSE` action to pause an active subscription.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "CUSTOMERS_READ", "PAYMENTS_WRITE", "SUBSCRIPTIONS_WRITE", "ITEMS_READ", "ORDERS_WRITE", "INVOICES_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CUSTOMERS_READ", "PAYMENTS_WRITE", "SUBSCRIPTIONS_WRITE", "ITEMS_READ", "ORDERS_WRITE", "INVOICES_WRITE" ] } ], "parameters": [ { "name": "subscription_id", "description": "The ID of the subscription to pause.", "x-is-beta": true, "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/PauseSubscriptionRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/PauseSubscriptionResponse" } } } } }, "/v2/subscriptions/{subscription_id}/resume": { "post": { "tags": [ "Subscriptions" ], "summary": "ResumeSubscription", "operationId": "ResumeSubscription", "description": "Schedules a `RESUME` action to resume a paused or a deactivated subscription.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "CUSTOMERS_READ", "PAYMENTS_WRITE", "SUBSCRIPTIONS_WRITE", "ITEMS_READ", "ORDERS_WRITE", "INVOICES_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CUSTOMERS_READ", "PAYMENTS_WRITE", "SUBSCRIPTIONS_WRITE", "ITEMS_READ", "ORDERS_WRITE", "INVOICES_WRITE" ] } ], "parameters": [ { "name": "subscription_id", "description": "The ID of the subscription to resume.", "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/ResumeSubscriptionRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ResumeSubscriptionResponse" } } } } }, "/v2/subscriptions/{subscription_id}/swap-plan": { "post": { "tags": [ "Subscriptions" ], "summary": "SwapPlan", "operationId": "SwapPlan", "description": "Schedules a `SWAP_PLAN` action to swap a subscription plan variation in an existing subscription. \nFor more information, see [Swap Subscription Plan Variations](https://developer.squareup.com/docs/subscriptions-api/swap-plan-variations).", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "CUSTOMERS_READ", "PAYMENTS_WRITE", "SUBSCRIPTIONS_WRITE", "ITEMS_READ", "ORDERS_WRITE", "INVOICES_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "CUSTOMERS_READ", "PAYMENTS_WRITE", "SUBSCRIPTIONS_WRITE", "ITEMS_READ", "ORDERS_WRITE", "INVOICES_WRITE" ] } ], "parameters": [ { "name": "subscription_id", "description": "The ID of the subscription to swap the subscription plan for.", "x-is-beta": true, "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/SwapPlanRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/SwapPlanResponse" } } } } }, "/v2/team-members": { "post": { "tags": [ "Team" ], "summary": "CreateTeamMember", "operationId": "CreateTeamMember", "description": "Creates a single `TeamMember` object. The `TeamMember` object is returned on successful creates.\nYou must provide the following values in your request to this endpoint:\n- `given_name`\n- `family_name`\n\nLearn about [Troubleshooting the Team API](https://developer.squareup.com/docs/team/troubleshooting#createteammember).", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "EMPLOYEES_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "EMPLOYEES_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CreateTeamMemberRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CreateTeamMemberResponse" } } } } }, "/v2/team-members/bulk-create": { "post": { "tags": [ "Team" ], "summary": "BulkCreateTeamMembers", "operationId": "BulkCreateTeamMembers", "description": "Creates multiple `TeamMember` objects. The created `TeamMember` objects are returned on successful creates.\nThis process is non-transactional and processes as much of the request as possible. If one of the creates in\nthe request cannot be successfully processed, the request is not marked as failed, but the body of the response\ncontains explicit error information for the failed create.\n\nLearn about [Troubleshooting the Team API](https://developer.squareup.com/docs/team/troubleshooting#bulk-create-team-members).", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "EMPLOYEES_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "EMPLOYEES_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/BulkCreateTeamMembersRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/BulkCreateTeamMembersResponse" } } } } }, "/v2/team-members/bulk-update": { "post": { "tags": [ "Team" ], "summary": "BulkUpdateTeamMembers", "operationId": "BulkUpdateTeamMembers", "description": "Updates multiple `TeamMember` objects. The updated `TeamMember` objects are returned on successful updates.\nThis process is non-transactional and processes as much of the request as possible. If one of the updates in\nthe request cannot be successfully processed, the request is not marked as failed, but the body of the response\ncontains explicit error information for the failed update.\nLearn about [Troubleshooting the Team API](https://developer.squareup.com/docs/team/troubleshooting#bulk-update-team-members).", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "EMPLOYEES_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "EMPLOYEES_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/BulkUpdateTeamMembersRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/BulkUpdateTeamMembersResponse" } } } } }, "/v2/team-members/search": { "post": { "tags": [ "Team" ], "summary": "SearchTeamMembers", "operationId": "SearchTeamMembers", "description": "Returns a paginated list of `TeamMember` objects for a business.\nThe list can be filtered by the following:\n- location IDs\n- `status`", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "EMPLOYEES_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "EMPLOYEES_READ" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/SearchTeamMembersRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/SearchTeamMembersResponse" } } } } }, "/v2/team-members/{team_member_id}": { "get": { "tags": [ "Team" ], "summary": "RetrieveTeamMember", "operationId": "RetrieveTeamMember", "description": "Retrieves a `TeamMember` object for the given `TeamMember.id`.\nLearn about [Troubleshooting the Team API](https://developer.squareup.com/docs/team/troubleshooting#retrieve-a-team-member).", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "EMPLOYEES_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "EMPLOYEES_READ" ] } ], "parameters": [ { "name": "team_member_id", "description": "The ID of the team member to retrieve.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveTeamMemberResponse" } } } }, "put": { "tags": [ "Team" ], "summary": "UpdateTeamMember", "operationId": "UpdateTeamMember", "description": "Updates a single `TeamMember` object. The `TeamMember` object is returned on successful updates.\nLearn about [Troubleshooting the Team API](https://developer.squareup.com/docs/team/troubleshooting#update-a-team-member).", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "EMPLOYEES_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "EMPLOYEES_WRITE" ] } ], "parameters": [ { "name": "team_member_id", "description": "The ID of the team member to update.", "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/UpdateTeamMemberRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/UpdateTeamMemberResponse" } } } } }, "/v2/team-members/{team_member_id}/wage-setting": { "get": { "tags": [ "Team" ], "summary": "RetrieveWageSetting", "operationId": "RetrieveWageSetting", "description": "Retrieves a `WageSetting` object for a team member specified\nby `TeamMember.id`.\nLearn about [Troubleshooting the Team API](https://developer.squareup.com/docs/team/troubleshooting#retrievewagesetting).", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "EMPLOYEES_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "EMPLOYEES_READ" ] } ], "parameters": [ { "name": "team_member_id", "description": "The ID of the team member for which to retrieve the wage setting.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveWageSettingResponse" } } } }, "put": { "tags": [ "Team" ], "summary": "UpdateWageSetting", "operationId": "UpdateWageSetting", "description": "Creates or updates a `WageSetting` object. The object is created if a\n`WageSetting` with the specified `team_member_id` does not exist. Otherwise,\nit fully replaces the `WageSetting` object for the team member.\nThe `WageSetting` is returned on a successful update.\nLearn about [Troubleshooting the Team API](https://developer.squareup.com/docs/team/troubleshooting#create-or-update-a-wage-setting).", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "EMPLOYEES_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "EMPLOYEES_WRITE" ] } ], "parameters": [ { "name": "team_member_id", "description": "The ID of the team member for which to update the `WageSetting` object.", "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/UpdateWageSettingRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/UpdateWageSettingResponse" } } } } }, "/v2/terminals/actions": { "post": { "tags": [ "Terminal" ], "summary": "CreateTerminalAction", "operationId": "CreateTerminalAction", "description": "Creates a Terminal action request and sends it to the specified device.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "PAYMENTS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "PAYMENTS_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CreateTerminalActionRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CreateTerminalActionResponse" } } } } }, "/v2/terminals/actions/search": { "post": { "tags": [ "Terminal" ], "summary": "SearchTerminalActions", "operationId": "SearchTerminalActions", "description": "Retrieves a filtered list of Terminal action requests created by the account making the request. Terminal action requests are available for 30 days.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "PAYMENTS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "PAYMENTS_READ" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/SearchTerminalActionsRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/SearchTerminalActionsResponse" } } } } }, "/v2/terminals/actions/{action_id}": { "get": { "tags": [ "Terminal" ], "summary": "GetTerminalAction", "operationId": "GetTerminalAction", "description": "Retrieves a Terminal action request by `action_id`. Terminal action requests are available for 30 days.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "PAYMENTS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "PAYMENTS_READ" ] } ], "parameters": [ { "name": "action_id", "description": "Unique ID for the desired `TerminalAction`.", "x-is-beta": true, "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/GetTerminalActionResponse" } } } } }, "/v2/terminals/actions/{action_id}/cancel": { "post": { "tags": [ "Terminal" ], "summary": "CancelTerminalAction", "operationId": "CancelTerminalAction", "description": "Cancels a Terminal action request if the status of the request permits it.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "PAYMENTS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "PAYMENTS_WRITE" ] } ], "parameters": [ { "name": "action_id", "description": "Unique ID for the desired `TerminalAction`.", "x-is-beta": true, "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CancelTerminalActionResponse" } } } } }, "/v2/terminals/actions/{action_id}/dismiss": { "post": { "tags": [ "Terminal" ], "summary": "DismissTerminalAction", "operationId": "DismissTerminalAction", "description": "Dismisses a Terminal action request if the status and type of the request permits it.\n\nSee [Link and Dismiss Actions](https://developer.squareup.com/docs/terminal-api/advanced-features/custom-workflows/link-and-dismiss-actions) for more details.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [] } ], "parameters": [ { "name": "action_id", "description": "Unique ID for the `TerminalAction` associated with the action to be dismissed.", "x-is-beta": true, "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/DismissTerminalActionResponse" } } } } }, "/v2/terminals/checkouts": { "post": { "tags": [ "Terminal" ], "summary": "CreateTerminalCheckout", "operationId": "CreateTerminalCheckout", "description": "Creates a Terminal checkout request and sends it to the specified device to take a payment\nfor the requested amount.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "PAYMENTS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "PAYMENTS_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CreateTerminalCheckoutRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CreateTerminalCheckoutResponse" } } } } }, "/v2/terminals/checkouts/search": { "post": { "tags": [ "Terminal" ], "summary": "SearchTerminalCheckouts", "operationId": "SearchTerminalCheckouts", "description": "Returns a filtered list of Terminal checkout requests created by the application making the request. Only Terminal checkout requests created for the merchant scoped to the OAuth token are returned. Terminal checkout requests are available for 30 days.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "PAYMENTS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "PAYMENTS_READ" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/SearchTerminalCheckoutsRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/SearchTerminalCheckoutsResponse" } } } } }, "/v2/terminals/checkouts/{checkout_id}": { "get": { "tags": [ "Terminal" ], "summary": "GetTerminalCheckout", "operationId": "GetTerminalCheckout", "description": "Retrieves a Terminal checkout request by `checkout_id`. Terminal checkout requests are available for 30 days.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "PAYMENTS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "PAYMENTS_READ" ] } ], "parameters": [ { "name": "checkout_id", "description": "The unique ID for the desired `TerminalCheckout`.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/GetTerminalCheckoutResponse" } } } } }, "/v2/terminals/checkouts/{checkout_id}/cancel": { "post": { "tags": [ "Terminal" ], "summary": "CancelTerminalCheckout", "operationId": "CancelTerminalCheckout", "description": "Cancels a Terminal checkout request if the status of the request permits it.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "PAYMENTS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "PAYMENTS_WRITE" ] } ], "parameters": [ { "name": "checkout_id", "description": "The unique ID for the desired `TerminalCheckout`.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CancelTerminalCheckoutResponse" } } } } }, "/v2/terminals/checkouts/{checkout_id}/dismiss": { "post": { "tags": [ "Terminal" ], "summary": "DismissTerminalCheckout", "operationId": "DismissTerminalCheckout", "description": "Dismisses a Terminal checkout request if the status and type of the request permits it.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [] } ], "parameters": [ { "name": "checkout_id", "description": "Unique ID for the `TerminalCheckout` associated with the checkout to be dismissed.", "x-is-beta": true, "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/DismissTerminalCheckoutResponse" } } } } }, "/v2/terminals/refunds": { "post": { "tags": [ "Terminal" ], "summary": "CreateTerminalRefund", "operationId": "CreateTerminalRefund", "description": "Creates a request to refund an Interac payment completed on a Square Terminal. Refunds for Interac payments on a Square Terminal are supported only for Interac debit cards in Canada. Other refunds for Terminal payments should use the Refunds API. For more information, see [Refunds API](https://developer.squareup.com/reference/square_2024-10-17/refunds-api).", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "PAYMENTS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "PAYMENTS_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CreateTerminalRefundRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CreateTerminalRefundResponse" } } } } }, "/v2/terminals/refunds/search": { "post": { "tags": [ "Terminal" ], "summary": "SearchTerminalRefunds", "operationId": "SearchTerminalRefunds", "description": "Retrieves a filtered list of Interac Terminal refund requests created by the seller making the request. Terminal refund requests are available for 30 days.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "PAYMENTS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "PAYMENTS_READ" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/SearchTerminalRefundsRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/SearchTerminalRefundsResponse" } } } } }, "/v2/terminals/refunds/{terminal_refund_id}": { "get": { "tags": [ "Terminal" ], "summary": "GetTerminalRefund", "operationId": "GetTerminalRefund", "description": "Retrieves an Interac Terminal refund object by ID. Terminal refund objects are available for 30 days.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "PAYMENTS_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "PAYMENTS_READ" ] } ], "parameters": [ { "name": "terminal_refund_id", "description": "The unique ID for the desired `TerminalRefund`.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/GetTerminalRefundResponse" } } } } }, "/v2/terminals/refunds/{terminal_refund_id}/cancel": { "post": { "tags": [ "Terminal" ], "summary": "CancelTerminalRefund", "operationId": "CancelTerminalRefund", "description": "Cancels an Interac Terminal refund request by refund request ID if the status of the request permits it.", "x-release-status": "PUBLIC", "x-oauthpermissions": [ "PAYMENTS_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "PAYMENTS_WRITE" ] } ], "parameters": [ { "name": "terminal_refund_id", "description": "The unique ID for the desired `TerminalRefund`.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CancelTerminalRefundResponse" } } } } }, "/v2/terminals/refunds/{terminal_refund_id}/dismiss": { "post": { "tags": [ "Terminal" ], "summary": "DismissTerminalRefund", "operationId": "DismissTerminalRefund", "description": "Dismisses a Terminal refund request if the status and type of the request permits it.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [] } ], "parameters": [ { "name": "terminal_refund_id", "description": "Unique ID for the `TerminalRefund` associated with the refund to be dismissed.", "x-is-beta": true, "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/DismissTerminalRefundResponse" } } } } }, "/v2/vendors/bulk-create": { "post": { "tags": [ "Vendors" ], "summary": "BulkCreateVendors", "operationId": "BulkCreateVendors", "description": "Creates one or more [Vendor](https://developer.squareup.com/reference/square_2024-10-17/objects/Vendor) objects to represent suppliers to a seller.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "VENDOR_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "VENDOR_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/BulkCreateVendorsRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/BulkCreateVendorsResponse" } } } } }, "/v2/vendors/bulk-retrieve": { "post": { "tags": [ "Vendors" ], "summary": "BulkRetrieveVendors", "operationId": "BulkRetrieveVendors", "description": "Retrieves one or more vendors of specified [Vendor](https://developer.squareup.com/reference/square_2024-10-17/objects/Vendor) IDs.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "VENDOR_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "VENDOR_READ" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/BulkRetrieveVendorsRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/BulkRetrieveVendorsResponse" } } } } }, "/v2/vendors/bulk-update": { "put": { "tags": [ "Vendors" ], "summary": "BulkUpdateVendors", "operationId": "BulkUpdateVendors", "description": "Updates one or more of existing [Vendor](https://developer.squareup.com/reference/square_2024-10-17/objects/Vendor) objects as suppliers to a seller.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "VENDOR_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "VENDOR_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/BulkUpdateVendorsRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/BulkUpdateVendorsResponse" } } } } }, "/v2/vendors/create": { "post": { "tags": [ "Vendors" ], "summary": "CreateVendor", "operationId": "CreateVendor", "description": "Creates a single [Vendor](https://developer.squareup.com/reference/square_2024-10-17/objects/Vendor) object to represent a supplier to a seller.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "VENDOR_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "VENDOR_WRITE" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CreateVendorRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CreateVendorResponse" } } } } }, "/v2/vendors/search": { "post": { "tags": [ "Vendors" ], "summary": "SearchVendors", "operationId": "SearchVendors", "description": "Searches for vendors using a filter against supported [Vendor](https://developer.squareup.com/reference/square_2024-10-17/objects/Vendor) properties and a supported sorter.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "VENDOR_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "VENDOR_READ" ] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/SearchVendorsRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/SearchVendorsResponse" } } } } }, "/v2/vendors/{vendor_id}": { "get": { "tags": [ "Vendors" ], "summary": "RetrieveVendor", "operationId": "RetrieveVendor", "description": "Retrieves the vendor of a specified [Vendor](https://developer.squareup.com/reference/square_2024-10-17/objects/Vendor) ID.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "VENDOR_READ" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "VENDOR_READ" ] } ], "parameters": [ { "name": "vendor_id", "description": "ID of the [Vendor](https://developer.squareup.com/reference/square_2024-10-17/objects/Vendor) to retrieve.", "x-is-beta": true, "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveVendorResponse" } } } }, "put": { "tags": [ "Vendors" ], "summary": "UpdateVendor", "operationId": "UpdateVendor", "description": "Updates an existing [Vendor](https://developer.squareup.com/reference/square_2024-10-17/objects/Vendor) object as a supplier to a seller.", "x-release-status": "BETA", "x-is-beta": true, "x-oauthpermissions": [ "VENDOR_WRITE" ], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [ "VENDOR_WRITE" ] } ], "parameters": [ { "name": "vendor_id", "description": "", "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/UpdateVendorRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/UpdateVendorResponse" } } } } }, "/v2/webhooks/event-types": { "get": { "tags": [ "WebhookSubscriptions" ], "summary": "ListWebhookEventTypes", "operationId": "ListWebhookEventTypes", "description": "Lists all webhook event types that can be subscribed to.", "x-release-status": "PUBLIC", "x-oauthpermissions": [], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [] } ], "parameters": [ { "name": "api_version", "description": "The API version for which to list event types. Setting this field overrides the default version used by the application.", "type": "string", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListWebhookEventTypesResponse" } } } } }, "/v2/webhooks/subscriptions": { "get": { "tags": [ "WebhookSubscriptions" ], "summary": "ListWebhookSubscriptions", "operationId": "ListWebhookSubscriptions", "description": "Lists all webhook subscriptions owned by your application.", "x-release-status": "PUBLIC", "x-oauthpermissions": [], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [] } ], "parameters": [ { "name": "cursor", "description": "A pagination cursor returned by a previous call to this endpoint.\nProvide this 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).", "type": "string", "in": "query", "required": false }, { "name": "include_disabled", "description": "Includes disabled [Subscription](https://developer.squareup.com/reference/square_2024-10-17/objects/WebhookSubscription)s.\nBy default, all enabled [Subscription](https://developer.squareup.com/reference/square_2024-10-17/objects/WebhookSubscription)s are returned.", "type": "boolean", "in": "query", "required": false }, { "name": "sort_order", "description": "Sorts the returned list by when the [Subscription](https://developer.squareup.com/reference/square_2024-10-17/objects/WebhookSubscription) was created with the specified order.\nThis field defaults to ASC.", "type": "string", "in": "query", "required": false }, { "name": "limit", "description": "The maximum number of results to be returned in a single page.\nIt is possible to receive fewer results than the specified limit on a given page.\nThe default value of 100 is also the maximum allowed value.\n\nDefault: 100", "type": "integer", "in": "query", "required": false } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ListWebhookSubscriptionsResponse" } } } }, "post": { "tags": [ "WebhookSubscriptions" ], "summary": "CreateWebhookSubscription", "operationId": "CreateWebhookSubscription", "description": "Creates a webhook subscription.", "x-release-status": "PUBLIC", "x-oauthpermissions": [], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [] } ], "parameters": [ { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/CreateWebhookSubscriptionRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/CreateWebhookSubscriptionResponse" } } } } }, "/v2/webhooks/subscriptions/{subscription_id}": { "delete": { "tags": [ "WebhookSubscriptions" ], "summary": "DeleteWebhookSubscription", "operationId": "DeleteWebhookSubscription", "description": "Deletes a webhook subscription.", "x-release-status": "PUBLIC", "x-oauthpermissions": [], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [] } ], "parameters": [ { "name": "subscription_id", "description": "[REQUIRED] The ID of the [Subscription](https://developer.squareup.com/reference/square_2024-10-17/objects/WebhookSubscription) to delete.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/DeleteWebhookSubscriptionResponse" } } } }, "get": { "tags": [ "WebhookSubscriptions" ], "summary": "RetrieveWebhookSubscription", "operationId": "RetrieveWebhookSubscription", "description": "Retrieves a webhook subscription identified by its ID.", "x-release-status": "PUBLIC", "x-oauthpermissions": [], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [] } ], "parameters": [ { "name": "subscription_id", "description": "[REQUIRED] The ID of the [Subscription](https://developer.squareup.com/reference/square_2024-10-17/objects/WebhookSubscription) to retrieve.", "type": "string", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/RetrieveWebhookSubscriptionResponse" } } } }, "put": { "tags": [ "WebhookSubscriptions" ], "summary": "UpdateWebhookSubscription", "operationId": "UpdateWebhookSubscription", "description": "Updates a webhook subscription.", "x-release-status": "PUBLIC", "x-oauthpermissions": [], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [] } ], "parameters": [ { "name": "subscription_id", "description": "[REQUIRED] The ID of the [Subscription](https://developer.squareup.com/reference/square_2024-10-17/objects/WebhookSubscription) to update.", "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/UpdateWebhookSubscriptionRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/UpdateWebhookSubscriptionResponse" } } } } }, "/v2/webhooks/subscriptions/{subscription_id}/signature-key": { "post": { "tags": [ "WebhookSubscriptions" ], "summary": "UpdateWebhookSubscriptionSignatureKey", "operationId": "UpdateWebhookSubscriptionSignatureKey", "description": "Updates a webhook subscription by replacing the existing signature key with a new one.", "x-release-status": "PUBLIC", "x-oauthpermissions": [], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [] } ], "parameters": [ { "name": "subscription_id", "description": "[REQUIRED] The ID of the [Subscription](https://developer.squareup.com/reference/square_2024-10-17/objects/WebhookSubscription) to update.", "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/UpdateWebhookSubscriptionSignatureKeyRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/UpdateWebhookSubscriptionSignatureKeyResponse" } } } } }, "/v2/webhooks/subscriptions/{subscription_id}/test": { "post": { "tags": [ "WebhookSubscriptions" ], "summary": "TestWebhookSubscription", "operationId": "TestWebhookSubscription", "description": "Tests a webhook subscription by sending a test event to the notification URL.", "x-release-status": "PUBLIC", "x-oauthpermissions": [], "x-sq-version": "2024-10-17", "security": [ { "oauth2": [] } ], "parameters": [ { "name": "subscription_id", "description": "[REQUIRED] The ID of the [Subscription](https://developer.squareup.com/reference/square_2024-10-17/objects/WebhookSubscription) to test.", "type": "string", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", "schema": { "$ref": "#/definitions/TestWebhookSubscriptionRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/TestWebhookSubscriptionResponse" } } } } } }, "definitions": { "ActionCancelReason": { "type": "string", "enum": [ "BUYER_CANCELED", "SELLER_CANCELED", "TIMED_OUT" ], "x-enum-elements": [ { "name": "BUYER_CANCELED", "description": "A person canceled the `TerminalCheckout` from a Square device." }, { "name": "SELLER_CANCELED", "description": "A client canceled the `TerminalCheckout` using the API." }, { "name": "TIMED_OUT", "description": "The `TerminalCheckout` timed out (see `deadline_duration` on the `TerminalCheckout`)." } ], "description": "", "x-release-status": "PUBLIC" }, "ActivityType": { "type": "string", "enum": [ "ADJUSTMENT", "APP_FEE_REFUND", "APP_FEE_REVENUE", "AUTOMATIC_SAVINGS", "AUTOMATIC_SAVINGS_REVERSED", "CHARGE", "DEPOSIT_FEE", "DISPUTE", "ESCHEATMENT", "FEE", "FREE_PROCESSING", "HOLD_ADJUSTMENT", "INITIAL_BALANCE_CHANGE", "MONEY_TRANSFER", "MONEY_TRANSFER_REVERSAL", "OPEN_DISPUTE", "OTHER", "OTHER_ADJUSTMENT", "PAID_SERVICE_FEE", "PAID_SERVICE_FEE_REFUND", "REDEMPTION_CODE", "REFUND", "RELEASE_ADJUSTMENT", "RESERVE_HOLD", "RESERVE_RELEASE", "RETURNED_PAYOUT", "SQUARE_CAPITAL_PAYMENT", "SQUARE_CAPITAL_REVERSED_PAYMENT", "SUBSCRIPTION_FEE", "SUBSCRIPTION_FEE_PAID_REFUND", "SUBSCRIPTION_FEE_REFUND", "TAX_ON_FEE", "THIRD_PARTY_FEE", "THIRD_PARTY_FEE_REFUND", "PAYOUT", "AUTOMATIC_BITCOIN_CONVERSIONS", "AUTOMATIC_BITCOIN_CONVERSIONS_REVERSED", "CREDIT_CARD_REPAYMENT", "CREDIT_CARD_REPAYMENT_REVERSED", "LOCAL_OFFERS_CASHBACK", "LOCAL_OFFERS_FEE", "PERCENTAGE_PROCESSING_ENROLLMENT", "PERCENTAGE_PROCESSING_DEACTIVATION", "PERCENTAGE_PROCESSING_REPAYMENT", "PERCENTAGE_PROCESSING_REPAYMENT_REVERSED", "PROCESSING_FEE", "PROCESSING_FEE_REFUND", "UNDO_PROCESSING_FEE_REFUND", "GIFT_CARD_LOAD_FEE", "GIFT_CARD_LOAD_FEE_REFUND", "UNDO_GIFT_CARD_LOAD_FEE_REFUND", "BALANCE_FOLDERS_TRANSFER", "BALANCE_FOLDERS_TRANSFER_REVERSED", "GIFT_CARD_POOL_TRANSFER", "GIFT_CARD_POOL_TRANSFER_REVERSED" ], "x-enum-elements": [ { "name": "ADJUSTMENT", "description": "A manual adjustment applied to the seller\u0027s account by Square." }, { "name": "APP_FEE_REFUND", "description": "A refund for an application fee on a payment." }, { "name": "APP_FEE_REVENUE", "description": "Revenue generated from an application fee on a payment." }, { "name": "AUTOMATIC_SAVINGS", "description": "An automatic transfer from the payment processing balance to the Square Savings account. These are generally proportional to the seller\u0027s sales." }, { "name": "AUTOMATIC_SAVINGS_REVERSED", "description": "An automatic transfer from the Square Savings account back to the processing balance. These are generally proportional to the seller\u0027s refunds." }, { "name": "CHARGE", "description": "A credit card payment capture." }, { "name": "DEPOSIT_FEE", "description": "Any fees involved with deposits such as instant deposits." }, { "name": "DISPUTE", "description": "The balance change due to a dispute event." }, { "name": "ESCHEATMENT", "description": "An escheatment entry for remittance." }, { "name": "FEE", "description": "The cost plus adjustment fee." }, { "name": "FREE_PROCESSING", "description": "Square offers free payments processing for a variety of business scenarios, including seller\nreferrals or when Square wants to apologize (for example, for a bug, customer service, or repricing complication).\nThis entry represents a credit to the seller for the purposes of free processing." }, { "name": "HOLD_ADJUSTMENT", "description": "An adjustment made by Square related to holding a payment." }, { "name": "INITIAL_BALANCE_CHANGE", "description": "An external change to a seller\u0027s balance (initial, in the sense that it causes the creation of the other activity types, such as a hold and refund)." }, { "name": "MONEY_TRANSFER", "description": "The balance change from a money transfer." }, { "name": "MONEY_TRANSFER_REVERSAL", "description": "The reversal of a money transfer." }, { "name": "OPEN_DISPUTE", "description": "The balance change for a chargeback that\u0027s been filed." }, { "name": "OTHER", "description": "Any other type that doesn\u0027t belong in the rest of the types." }, { "name": "OTHER_ADJUSTMENT", "description": "Any other type of adjustment that doesn\u0027t fall under existing types." }, { "name": "PAID_SERVICE_FEE", "description": "A fee paid to a third-party seller." }, { "name": "PAID_SERVICE_FEE_REFUND", "description": "A fee refunded to a third-party seller." }, { "name": "REDEMPTION_CODE", "description": "Repayment for a redemption code." }, { "name": "REFUND", "description": "A refund for an existing card payment." }, { "name": "RELEASE_ADJUSTMENT", "description": "An adjustment made by Square related to releasing a payment." }, { "name": "RESERVE_HOLD", "description": "Fees paid for a funding risk reserve." }, { "name": "RESERVE_RELEASE", "description": "Fees released from a risk reserve." }, { "name": "RETURNED_PAYOUT", "description": "An entry created when Square receives a response for the ACH file that Square sent indicating that the\nsettlement of the original entry failed." }, { "name": "SQUARE_CAPITAL_PAYMENT", "description": "A capital merchant cash advance (MCA) assessment. These are generally proportional to the merchant\u0027s sales but can be issued for other reasons related to the MCA." }, { "name": "SQUARE_CAPITAL_REVERSED_PAYMENT", "description": "A capital merchant cash advance (MCA) assessment refund. These are generally proportional to the merchant\u0027s refunds but can be issued for other reasons related to the MCA." }, { "name": "SUBSCRIPTION_FEE", "description": "A fee charged for subscription to a Square product." }, { "name": "SUBSCRIPTION_FEE_PAID_REFUND", "description": "A Square subscription fee that\u0027s been refunded." }, { "name": "SUBSCRIPTION_FEE_REFUND", "description": "The refund of a previously charged Square product subscription fee." }, { "name": "TAX_ON_FEE", "description": "The tax paid on fee amounts." }, { "name": "THIRD_PARTY_FEE", "description": "Fees collected by a third-party platform." }, { "name": "THIRD_PARTY_FEE_REFUND", "description": "Refunded fees from a third-party platform." }, { "name": "PAYOUT", "description": "The balance change due to money transfer." }, { "name": "AUTOMATIC_BITCOIN_CONVERSIONS", "description": "Indicates that the portion of each payment withheld by Square was automatically converted into bitcoin using Cash App. The seller manages their bitcoin in their Cash App account." }, { "name": "AUTOMATIC_BITCOIN_CONVERSIONS_REVERSED", "description": "Indicates that a withheld payment, which was scheduled to be converted into bitcoin using Cash App, was deposited back to the Square payments balance." }, { "name": "CREDIT_CARD_REPAYMENT", "description": "Indicates that a repayment toward the outstanding balance on the seller\u0027s Square credit card was made." }, { "name": "CREDIT_CARD_REPAYMENT_REVERSED", "description": "Indicates that a repayment toward the outstanding balance on the seller\u0027s Square credit card was reversed." }, { "name": "LOCAL_OFFERS_CASHBACK", "description": "Cashback amount given by a Square Local Offers seller to their customer for a purchase." }, { "name": "LOCAL_OFFERS_FEE", "description": "A commission fee paid by a Square Local Offers seller to Square for a purchase discovered through Square Local Offers." }, { "name": "PERCENTAGE_PROCESSING_ENROLLMENT", "description": "When activating Percentage Processing, a credit is applied to the seller’s account to offset any negative balance caused by a dispute." }, { "name": "PERCENTAGE_PROCESSING_DEACTIVATION", "description": "Deducting the outstanding Percentage Processing balance from the seller’s account. It\u0027s the final installment in repaying the dispute-induced negative balance through percentage processing." }, { "name": "PERCENTAGE_PROCESSING_REPAYMENT", "description": "Withheld funds from a payment to cover a negative balance. It\u0027s an installment to repay the amount from a dispute that had been offset during Percentage Processing enrollment." }, { "name": "PERCENTAGE_PROCESSING_REPAYMENT_REVERSED", "description": "The reversal of a percentage processing repayment that happens for example when a refund is issued for a payment." }, { "name": "PROCESSING_FEE", "description": "The processing fee for a payment. If sellers opt for Gross Settlement, i.e., direct bank withdrawal instead of deducting fees from daily sales, the processing fee is recorded separately as a new payout entry, not part of the CHARGE payout entry." }, { "name": "PROCESSING_FEE_REFUND", "description": "The processing fee for a payment refund issued by sellers enrolled in Gross Settlement. The refunded processing fee is recorded separately as a new payout entry, not part of the REFUND payout entry." }, { "name": "UNDO_PROCESSING_FEE_REFUND", "description": "When undoing a processing fee refund in a Gross Settlement payment, this payout entry type is used." }, { "name": "GIFT_CARD_LOAD_FEE", "description": "Fee collected during the sale or reload of a gift card. This fee, which is a portion of the amount loaded on the gift card, is deducted from the merchant\u0027s payment balance." }, { "name": "GIFT_CARD_LOAD_FEE_REFUND", "description": "Refund for fee charged during the sale or reload of a gift card." }, { "name": "UNDO_GIFT_CARD_LOAD_FEE_REFUND", "description": "The undo of a refund for a fee charged during the sale or reload of a gift card." }, { "name": "BALANCE_FOLDERS_TRANSFER", "description": "A transfer of funds to a banking folder. In the United States, the folder name is \u0027Checking Folder\u0027; in Canada, it\u0027s \u0027Balance Folder.\u0027" }, { "name": "BALANCE_FOLDERS_TRANSFER_REVERSED", "description": "A reversal of transfer of funds from a banking folder. In the United States, the folder name is \u0027Checking Folder\u0027; in Canada, it\u0027s \u0027Balance Folder.\u0027" }, { "name": "GIFT_CARD_POOL_TRANSFER", "description": "A transfer of gift card funds to a central gift card pool account. In franchises, when gift cards are loaded or reloaded at any location, the money transfers to the franchisor\u0027s account." }, { "name": "GIFT_CARD_POOL_TRANSFER_REVERSED", "description": "A reversal of transfer of gift card funds from a central gift card pool account. In franchises, when gift cards are loaded or reloaded at any location, the money transfers to the franchisor\u0027s account." } ], "description": "", "x-release-status": "PUBLIC" }, "ApplicationDetailsExternalSquareProduct": { "type": "string", "enum": [ "APPOINTMENTS", "ECOMMERCE_API", "INVOICES", "ONLINE_STORE", "OTHER", "RESTAURANTS", "RETAIL", "SQUARE_POS", "TERMINAL_API", "VIRTUAL_TERMINAL" ], "x-enum-elements": [ { "name": "APPOINTMENTS", "description": "" }, { "name": "ECOMMERCE_API", "description": "" }, { "name": "INVOICES", "description": "" }, { "name": "ONLINE_STORE", "description": "" }, { "name": "OTHER", "description": "" }, { "name": "RESTAURANTS", "description": "" }, { "name": "RETAIL", "description": "" }, { "name": "SQUARE_POS", "description": "" }, { "name": "TERMINAL_API", "description": "" }, { "name": "VIRTUAL_TERMINAL", "description": "" } ], "description": "A list of products to return to external callers.", "x-release-status": "PUBLIC" }, "ApplicationType": { "type": "string", "enum": [ "TERMINAL_API" ], "x-enum-elements": [ { "name": "TERMINAL_API", "description": "" } ], "description": "", "x-release-status": "BETA", "x-is-beta": true }, "ArchivedState": { "type": "string", "enum": [ "ARCHIVED_STATE_NOT_ARCHIVED", "ARCHIVED_STATE_ARCHIVED", "ARCHIVED_STATE_ALL" ], "x-enum-elements": [ { "name": "ARCHIVED_STATE_NOT_ARCHIVED", "description": "Requested items are not archived with the `is_archived` attribute set to `false`." }, { "name": "ARCHIVED_STATE_ARCHIVED", "description": "Requested items are archived with the `is_archived` attribute set to `true`." }, { "name": "ARCHIVED_STATE_ALL", "description": "Requested items can be archived or not archived." } ], "description": "Defines the values for the `archived_state` query expression \nused in [SearchCatalogItems](https://developer.squareup.com/reference/square_2024-10-17/catalog-api/search-catalog-items) \nto return the archived, not archived or either type of catalog items.", "x-release-status": "PUBLIC" }, "BankAccountStatus": { "type": "string", "enum": [ "VERIFICATION_IN_PROGRESS", "VERIFIED", "DISABLED" ], "x-enum-elements": [ { "name": "VERIFICATION_IN_PROGRESS", "description": "Indicates that the verification process has started. Some features\n(for example, creditable or debitable) may be provisionally enabled on the bank\naccount." }, { "name": "VERIFIED", "description": "Indicates that the bank account was successfully verified." }, { "name": "DISABLED", "description": "Indicates that the bank account is disabled and is permanently unusable\nfor funds transfer. A bank account can be disabled because of a failed verification\nattempt or a failed deposit attempt." } ], "description": "Indicates the current verification status of a `BankAccount` object.", "x-release-status": "PUBLIC" }, "BankAccountType": { "type": "string", "enum": [ "CHECKING", "SAVINGS", "INVESTMENT", "OTHER", "BUSINESS_CHECKING" ], "x-enum-elements": [ { "name": "CHECKING", "description": "An account at a financial institution against which checks can be\ndrawn by the account depositor." }, { "name": "SAVINGS", "description": "An account at a financial institution that pays interest but cannot be\nused directly as money in the narrow sense of a medium of exchange." }, { "name": "INVESTMENT", "description": "An account at a financial institution that contains a deposit of funds\nand/or securities." }, { "name": "OTHER", "description": "An account at a financial institution which cannot be described by the\nother types." }, { "name": "BUSINESS_CHECKING", "description": "An account at a financial institution against which checks can be\ndrawn specifically for business purposes (non-personal use)." } ], "description": "Indicates the financial purpose of the bank account.", "x-release-status": "PUBLIC" }, "BookingBookingSource": { "type": "string", "enum": [ "FIRST_PARTY_MERCHANT", "FIRST_PARTY_BUYER", "THIRD_PARTY_BUYER", "API" ], "x-enum-elements": [ { "name": "FIRST_PARTY_MERCHANT", "description": "The booking was created by a seller from a Square Appointments application, such as the Square Appointments Dashboard or a Square Appointments mobile app." }, { "name": "FIRST_PARTY_BUYER", "description": "The booking was created by a buyer from a Square Appointments application, such as Square Online Booking Site." }, { "name": "THIRD_PARTY_BUYER", "description": "The booking was created by a buyer created from a third-party application." }, { "name": "API", "description": "The booking was created by a seller or a buyer from the Square Bookings API." } ], "description": "Supported sources a booking was created from.", "x-release-status": "PUBLIC" }, "BookingCreatorDetailsCreatorType": { "type": "string", "enum": [ "TEAM_MEMBER", "CUSTOMER" ], "x-enum-elements": [ { "name": "TEAM_MEMBER", "description": "The creator is of the seller type." }, { "name": "CUSTOMER", "description": "The creator is of the buyer type." } ], "description": "Supported types of a booking creator.", "x-release-status": "PUBLIC" }, "BookingStatus": { "type": "string", "enum": [ "PENDING", "CANCELLED_BY_CUSTOMER", "CANCELLED_BY_SELLER", "DECLINED", "ACCEPTED", "NO_SHOW" ], "x-enum-elements": [ { "name": "PENDING", "description": "An unaccepted booking. It is visible to both sellers and customers." }, { "name": "CANCELLED_BY_CUSTOMER", "description": "A customer-cancelled booking. It is visible to both the seller and the customer." }, { "name": "CANCELLED_BY_SELLER", "description": "A seller-cancelled booking. It is visible to both the seller and the customer." }, { "name": "DECLINED", "description": "A declined booking. It had once been pending, but was then declined by the seller." }, { "name": "ACCEPTED", "description": "An accepted booking agreed to or accepted by the seller." }, { "name": "NO_SHOW", "description": "A no-show booking. The booking was accepted at one time, but have now been marked as a no-show by\nthe seller because the client either missed the booking or cancelled it without enough notice." } ], "description": "Supported booking statuses.", "x-release-status": "PUBLIC" }, "BusinessAppointmentSettingsAlignmentTime": { "type": "string", "enum": [ "SERVICE_DURATION", "QUARTER_HOURLY", "HALF_HOURLY", "HOURLY" ], "x-enum-elements": [ { "name": "SERVICE_DURATION", "description": "The service duration unit is one visit of a fixed time interval specified by the seller." }, { "name": "QUARTER_HOURLY", "description": "The service duration unit is a 15-minute interval. Bookings can be scheduled every quarter hour." }, { "name": "HALF_HOURLY", "description": "The service duration unit is a 30-minute interval. Bookings can be scheduled every half hour." }, { "name": "HOURLY", "description": "The service duration unit is a 60-minute interval. Bookings can be scheduled every hour." } ], "description": "Time units of a service duration for bookings.", "x-release-status": "PUBLIC" }, "BusinessAppointmentSettingsBookingLocationType": { "type": "string", "enum": [ "BUSINESS_LOCATION", "CUSTOMER_LOCATION", "PHONE" ], "x-enum-elements": [ { "name": "BUSINESS_LOCATION", "description": "The service is provided at a seller location." }, { "name": "CUSTOMER_LOCATION", "description": "The service is provided at a customer location." }, { "name": "PHONE", "description": "The service is provided over the phone." } ], "description": "Supported types of location where service is provided.", "x-release-status": "PUBLIC" }, "BusinessAppointmentSettingsCancellationPolicy": { "type": "string", "enum": [ "CANCELLATION_TREATED_AS_NO_SHOW", "CUSTOM_POLICY" ], "x-enum-elements": [ { "name": "CANCELLATION_TREATED_AS_NO_SHOW", "description": "Cancellations are treated as no shows and may incur a fee as specified by `cancellation_fee_money`." }, { "name": "CUSTOM_POLICY", "description": "Cancellations follow the seller-specified policy that is described in free-form text and not enforced automatically by Square." } ], "description": "The category of the seller’s cancellation policy.", "x-release-status": "PUBLIC" }, "BusinessAppointmentSettingsMaxAppointmentsPerDayLimitType": { "type": "string", "enum": [ "PER_TEAM_MEMBER", "PER_LOCATION" ], "x-enum-elements": [ { "name": "PER_TEAM_MEMBER", "description": "The maximum number of daily appointments is set on a per team member basis." }, { "name": "PER_LOCATION", "description": "The maximum number of daily appointments is set on a per location basis." } ], "description": "Types of daily appointment limits.", "x-release-status": "PUBLIC" }, "BusinessBookingProfileBookingPolicy": { "type": "string", "enum": [ "ACCEPT_ALL", "REQUIRES_ACCEPTANCE" ], "x-enum-elements": [ { "name": "ACCEPT_ALL", "description": "The seller accepts all booking requests automatically." }, { "name": "REQUIRES_ACCEPTANCE", "description": "The seller must accept requests to complete bookings." } ], "description": "Policies for accepting bookings.", "x-release-status": "PUBLIC" }, "BusinessBookingProfileCustomerTimezoneChoice": { "type": "string", "enum": [ "BUSINESS_LOCATION_TIMEZONE", "CUSTOMER_CHOICE" ], "x-enum-elements": [ { "name": "BUSINESS_LOCATION_TIMEZONE", "description": "Use the time zone of the business location for bookings." }, { "name": "CUSTOMER_CHOICE", "description": "Use the customer-chosen time zone for bookings." } ], "description": "Choices of customer-facing time zone used for bookings.", "x-release-status": "PUBLIC" }, "CardBrand": { "type": "string", "enum": [ "OTHER_BRAND", "VISA", "MASTERCARD", "AMERICAN_EXPRESS", "DISCOVER", "DISCOVER_DINERS", "JCB", "CHINA_UNIONPAY", "SQUARE_GIFT_CARD", "SQUARE_CAPITAL_CARD", "INTERAC", "EFTPOS", "FELICA", "EBT" ], "x-enum-elements": [ { "name": "OTHER_BRAND", "description": "" }, { "name": "VISA", "description": "" }, { "name": "MASTERCARD", "description": "" }, { "name": "AMERICAN_EXPRESS", "description": "" }, { "name": "DISCOVER", "description": "" }, { "name": "DISCOVER_DINERS", "description": "" }, { "name": "JCB", "description": "" }, { "name": "CHINA_UNIONPAY", "description": "" }, { "name": "SQUARE_GIFT_CARD", "description": "" }, { "name": "SQUARE_CAPITAL_CARD", "description": "" }, { "name": "INTERAC", "description": "" }, { "name": "EFTPOS", "description": "" }, { "name": "FELICA", "description": "" }, { "name": "EBT", "description": "" } ], "description": "Indicates a card\u0027s brand, such as `VISA` or `MASTERCARD`.", "x-release-status": "PUBLIC" }, "CardCoBrand": { "type": "string", "enum": [ "UNKNOWN", "AFTERPAY", "CLEARPAY" ], "x-enum-elements": [ { "name": "UNKNOWN", "description": "" }, { "name": "AFTERPAY", "description": "" }, { "name": "CLEARPAY", "description": "" } ], "description": "Indicates the brand for a co-branded card.", "x-release-status": "PUBLIC" }, "CardPrepaidType": { "type": "string", "enum": [ "UNKNOWN_PREPAID_TYPE", "NOT_PREPAID", "PREPAID" ], "x-enum-elements": [ { "name": "UNKNOWN_PREPAID_TYPE", "description": "" }, { "name": "NOT_PREPAID", "description": "" }, { "name": "PREPAID", "description": "" } ], "description": "Indicates a card\u0027s prepaid type, such as `NOT_PREPAID` or `PREPAID`.", "x-release-status": "PUBLIC" }, "CardType": { "type": "string", "enum": [ "UNKNOWN_CARD_TYPE", "CREDIT", "DEBIT" ], "x-enum-elements": [ { "name": "UNKNOWN_CARD_TYPE", "description": "" }, { "name": "CREDIT", "description": "" }, { "name": "DEBIT", "description": "" } ], "description": "Indicates a card\u0027s type, such as `CREDIT` or `DEBIT`.", "x-release-status": "PUBLIC" }, "CashDrawerEventType": { "type": "string", "enum": [ "NO_SALE", "CASH_TENDER_PAYMENT", "OTHER_TENDER_PAYMENT", "CASH_TENDER_CANCELLED_PAYMENT", "OTHER_TENDER_CANCELLED_PAYMENT", "CASH_TENDER_REFUND", "OTHER_TENDER_REFUND", "PAID_IN", "PAID_OUT" ], "x-enum-elements": [ { "name": "NO_SALE", "description": "Triggered when a no sale occurs on a cash drawer.\nA CashDrawerEvent of this type must have a zero money amount." }, { "name": "CASH_TENDER_PAYMENT", "description": "Triggered when a cash tender payment occurs on a cash drawer.\nA CashDrawerEvent of this type can must not have a negative amount." }, { "name": "OTHER_TENDER_PAYMENT", "description": "Triggered when a check, gift card, or other non-cash payment occurs\non a cash drawer.\nA CashDrawerEvent of this type must have a zero money amount." }, { "name": "CASH_TENDER_CANCELLED_PAYMENT", "description": "Triggered when a split tender bill is cancelled after cash has been\ntendered.\nA CASH_TENDER_CANCELLED_PAYMENT should have a corresponding CASH_TENDER_PAYMENT.\nA CashDrawerEvent of this type must not have a negative amount." }, { "name": "OTHER_TENDER_CANCELLED_PAYMENT", "description": "Triggered when a split tender bill is cancelled after a non-cash tender\nhas been tendered. An OTHER_TENDER_CANCELLED_PAYMENT should have a corresponding\nOTHER_TENDER_PAYMENT. A CashDrawerEvent of this type must have a zero money\namount." }, { "name": "CASH_TENDER_REFUND", "description": "Triggered when a cash tender refund occurs.\nA CashDrawerEvent of this type must not have a negative amount." }, { "name": "OTHER_TENDER_REFUND", "description": "Triggered when an other tender refund occurs.\nA CashDrawerEvent of this type must have a zero money amount." }, { "name": "PAID_IN", "description": "Triggered when money unrelated to a payment is added to the cash drawer.\nFor example, an employee adds coins to the drawer.\nA CashDrawerEvent of this type must not have a negative amount." }, { "name": "PAID_OUT", "description": "Triggered when money is removed from the drawer for other reasons\nthan making change.\nFor example, an employee pays a delivery person with cash from the cash drawer.\nA CashDrawerEvent of this type must not have a negative amount." } ], "description": "The types of events on a CashDrawerShift.\nEach event type represents an employee action on the actual cash drawer\nrepresented by a CashDrawerShift.", "x-release-status": "PUBLIC" }, "CashDrawerShiftState": { "type": "string", "enum": [ "OPEN", "ENDED", "CLOSED" ], "x-enum-elements": [ { "name": "OPEN", "description": "An open cash drawer shift." }, { "name": "ENDED", "description": "A cash drawer shift that is ended but has not yet had an employee content audit." }, { "name": "CLOSED", "description": "An ended cash drawer shift that is closed with a completed employee\ncontent audit and recorded result." } ], "description": "The current state of a cash drawer shift.", "x-release-status": "PUBLIC" }, "CatalogCategoryType": { "type": "string", "enum": [ "REGULAR_CATEGORY", "MENU_CATEGORY", "KITCHEN_CATEGORY" ], "x-enum-elements": [ { "name": "REGULAR_CATEGORY", "description": "The regular category." }, { "name": "MENU_CATEGORY", "description": "The menu category." }, { "name": "KITCHEN_CATEGORY", "description": "Kitchen categories are used by KDS (Kitchen Display System) to route items to specific clients" } ], "description": "Indicates the type of a category.", "x-release-status": "PUBLIC" }, "CatalogCustomAttributeDefinitionAppVisibility": { "type": "string", "enum": [ "APP_VISIBILITY_HIDDEN", "APP_VISIBILITY_READ_ONLY", "APP_VISIBILITY_READ_WRITE_VALUES" ], "x-enum-elements": [ { "name": "APP_VISIBILITY_HIDDEN", "description": "Other applications cannot read this custom attribute." }, { "name": "APP_VISIBILITY_READ_ONLY", "description": "Other applications can read this custom attribute definition and\nvalues." }, { "name": "APP_VISIBILITY_READ_WRITE_VALUES", "description": "Other applications can read and write custom attribute values on objects.\nThey can read but cannot edit the custom attribute definition." } ], "description": "Defines the visibility of a custom attribute to applications other than their\ncreating application.", "x-release-status": "PUBLIC" }, "CatalogCustomAttributeDefinitionSellerVisibility": { "type": "string", "enum": [ "SELLER_VISIBILITY_HIDDEN", "SELLER_VISIBILITY_READ_WRITE_VALUES" ], "x-enum-elements": [ { "name": "SELLER_VISIBILITY_HIDDEN", "description": "Sellers cannot read this custom attribute in Square client\napplications or Square APIs." }, { "name": "SELLER_VISIBILITY_READ_WRITE_VALUES", "description": "Sellers can read and write this custom attribute value in catalog objects,\nbut cannot edit the custom attribute definition." } ], "description": "Defines the visibility of a custom attribute to sellers in Square\nclient applications, Square APIs or in Square UIs (including Square Point\nof Sale applications and Square Dashboard).", "x-release-status": "PUBLIC" }, "CatalogCustomAttributeDefinitionType": { "type": "string", "enum": [ "STRING", "BOOLEAN", "NUMBER", "SELECTION" ], "x-enum-elements": [ { "name": "STRING", "description": "A free-form string containing up to 255 characters." }, { "name": "BOOLEAN", "description": "A `true` or `false` value." }, { "name": "NUMBER", "description": "A decimal string representation of a number. Can support up to 5 digits after the decimal point." }, { "name": "SELECTION", "description": "One or more choices from `allowed_selections`." } ], "description": "Defines the possible types for a custom attribute.", "x-release-status": "PUBLIC" }, "CatalogDiscountModifyTaxBasis": { "type": "string", "enum": [ "MODIFY_TAX_BASIS", "DO_NOT_MODIFY_TAX_BASIS" ], "x-enum-elements": [ { "name": "MODIFY_TAX_BASIS", "description": "Application of the discount will modify the tax basis." }, { "name": "DO_NOT_MODIFY_TAX_BASIS", "description": "Application of the discount will not modify the tax basis." } ], "description": "", "x-release-status": "PUBLIC" }, "CatalogDiscountType": { "type": "string", "enum": [ "FIXED_PERCENTAGE", "FIXED_AMOUNT", "VARIABLE_PERCENTAGE", "VARIABLE_AMOUNT" ], "x-enum-elements": [ { "name": "FIXED_PERCENTAGE", "description": "Apply the discount as a fixed percentage (e.g., 5%) off the item price." }, { "name": "FIXED_AMOUNT", "description": "Apply the discount as a fixed amount (e.g., $1.00) off the item price." }, { "name": "VARIABLE_PERCENTAGE", "description": "Apply the discount as a variable percentage off the item price. The percentage will be specified at the time of sale." }, { "name": "VARIABLE_AMOUNT", "description": "Apply the discount as a variable amount off the item price. The amount will be specified at the time of sale." } ], "description": "How to apply a CatalogDiscount to a CatalogItem.", "x-release-status": "PUBLIC" }, "CatalogItemFoodAndBeverageDetailsDietaryPreferenceStandardDietaryPreference": { "type": "string", "enum": [ "DAIRY_FREE", "GLUTEN_FREE", "HALAL", "KOSHER", "NUT_FREE", "VEGAN", "VEGETARIAN" ], "x-enum-elements": [ { "name": "DAIRY_FREE", "description": "" }, { "name": "GLUTEN_FREE", "description": "" }, { "name": "HALAL", "description": "" }, { "name": "KOSHER", "description": "" }, { "name": "NUT_FREE", "description": "" }, { "name": "VEGAN", "description": "" }, { "name": "VEGETARIAN", "description": "" } ], "description": "Standard dietary preferences for food and beverage items that are recommended on item creation.", "x-release-status": "PUBLIC" }, "CatalogItemFoodAndBeverageDetailsDietaryPreferenceType": { "type": "string", "enum": [ "STANDARD", "CUSTOM" ], "x-enum-elements": [ { "name": "STANDARD", "description": "A standard value from a pre-determined list." }, { "name": "CUSTOM", "description": "A user-defined custom value." } ], "description": "The type of dietary preference for the `FOOD_AND_BEV` type of items and integredients.", "x-release-status": "PUBLIC" }, "CatalogItemFoodAndBeverageDetailsIngredientStandardIngredient": { "type": "string", "enum": [ "CELERY", "CRUSTACEANS", "EGGS", "FISH", "GLUTEN", "LUPIN", "MILK", "MOLLUSCS", "MUSTARD", "PEANUTS", "SESAME", "SOY", "SULPHITES", "TREE_NUTS" ], "x-enum-elements": [ { "name": "CELERY", "description": "" }, { "name": "CRUSTACEANS", "description": "" }, { "name": "EGGS", "description": "" }, { "name": "FISH", "description": "" }, { "name": "GLUTEN", "description": "" }, { "name": "LUPIN", "description": "" }, { "name": "MILK", "description": "" }, { "name": "MOLLUSCS", "description": "" }, { "name": "MUSTARD", "description": "" }, { "name": "PEANUTS", "description": "" }, { "name": "SESAME", "description": "" }, { "name": "SOY", "description": "" }, { "name": "SULPHITES", "description": "" }, { "name": "TREE_NUTS", "description": "" } ], "description": "Standard ingredients for food and beverage items that are recommended on item creation.", "x-release-status": "PUBLIC" }, "CatalogItemProductType": { "type": "string", "enum": [ "REGULAR", "GIFT_CARD", "APPOINTMENTS_SERVICE", "FOOD_AND_BEV", "EVENT", "DIGITAL", "DONATION", "LEGACY_SQUARE_ONLINE_SERVICE", "LEGACY_SQUARE_ONLINE_MEMBERSHIP" ], "x-enum-elements": [ { "name": "REGULAR", "description": "An ordinary item." }, { "name": "GIFT_CARD", "description": "A Square gift card." }, { "name": "APPOINTMENTS_SERVICE", "description": "A service that can be booked using the Square Appointments app." }, { "name": "FOOD_AND_BEV", "description": "A food or beverage item that can be sold by restaurants and other food venues." }, { "name": "EVENT", "description": "An event which tickets can be sold for, including location, address, and times." }, { "name": "DIGITAL", "description": "A digital item like an ebook or song." }, { "name": "DONATION", "description": "A donation which site visitors can send for any cause." }, { "name": "LEGACY_SQUARE_ONLINE_SERVICE", "description": "A legacy Square Online service that is manually fulfilled. This corresponds to the `Other` item type displayed in the Square Seller Dashboard and Square POS apps." }, { "name": "LEGACY_SQUARE_ONLINE_MEMBERSHIP", "description": "A legacy Square Online membership that is manually fulfilled. This corresponds to the `Membership` item type displayed in the Square Seller Dashboard and Square POS apps." } ], "description": "The type of a CatalogItem. Connect V2 only allows the creation of `REGULAR` or `APPOINTMENTS_SERVICE` items.", "x-release-status": "PUBLIC" }, "CatalogModifierListModifierType": { "type": "string", "enum": [ "LIST", "TEXT" ], "x-enum-elements": [ { "name": "LIST", "description": "The `CatalogModifierList` instance is a non-empty list of non text-based modifiers." }, { "name": "TEXT", "description": "The `CatalogModifierList` instance is a single text-based modifier." } ], "description": "Defines the type of `CatalogModifierList`.", "x-release-status": "BETA", "x-is-beta": true }, "CatalogModifierListSelectionType": { "type": "string", "enum": [ "SINGLE", "MULTIPLE" ], "x-enum-elements": [ { "name": "SINGLE", "description": "Indicates that a CatalogModifierList allows only a\nsingle CatalogModifier to be selected." }, { "name": "MULTIPLE", "description": "Indicates that a CatalogModifierList allows multiple\nCatalogModifier to be selected." } ], "description": "Indicates whether a CatalogModifierList supports multiple selections.", "x-release-status": "PUBLIC" }, "CatalogObjectType": { "type": "string", "enum": [ "ITEM", "IMAGE", "CATEGORY", "ITEM_VARIATION", "TAX", "DISCOUNT", "MODIFIER_LIST", "MODIFIER", "PRICING_RULE", "PRODUCT_SET", "TIME_PERIOD", "MEASUREMENT_UNIT", "SUBSCRIPTION_PLAN_VARIATION", "ITEM_OPTION", "ITEM_OPTION_VAL", "CUSTOM_ATTRIBUTE_DEFINITION", "QUICK_AMOUNTS_SETTINGS", "SUBSCRIPTION_PLAN", "AVAILABILITY_PERIOD" ], "x-enum-elements": [ { "name": "ITEM", "description": "The `CatalogObject` instance is of the [CatalogItem](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogItem) type and represents an item. The item-specific data\nmust be set on the `item_data` field." }, { "name": "IMAGE", "description": "The `CatalogObject` instance is of the [CatalogImage](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogImage) type and represents an image. The image-specific data\nmust be set on the `image_data` field." }, { "name": "CATEGORY", "description": "The `CatalogObject` instance is of the [CatalogCategory](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogCategory) type and represents a category. The category-specific data\nmust be set on the `category_data` field." }, { "name": "ITEM_VARIATION", "description": "The `CatalogObject` instance is of the [CatalogItemVariation](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogItemVariation) type and represents an item variation, also referred to as variation.\nThe item variation-specific data must be set on the `item_variation_data` field." }, { "name": "TAX", "description": "The `CatalogObject` instance is of the [CatalogTax](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogTax) type and represents a tax. The tax-specific data\nmust be set on the `tax_data` field." }, { "name": "DISCOUNT", "description": "The `CatalogObject` instance is of the [CatalogDiscount](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogDiscount) type and represents a discount. The discount-specific data\nmust be set on the `discount_data` field." }, { "name": "MODIFIER_LIST", "description": "The `CatalogObject` instance is of the [CatalogModifierList](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogModifierList) type and represents a modifier list.\nThe modifier-list-specific data must be set on the `modifier_list_data` field." }, { "name": "MODIFIER", "description": "The `CatalogObject` instance is of the [CatalogModifier](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogModifier) type and represents a modifier. The modifier-specific data\nmust be set on the `modifier_data` field." }, { "name": "PRICING_RULE", "description": "The `CatalogObject` instance is of the [CatalogPricingRule](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogPricingRule) type and represents a pricing rule. The pricing-rule-specific data\nmust be set on the `pricing_rule_data` field." }, { "name": "PRODUCT_SET", "description": "The `CatalogObject` instance is of the [CatalogProductSet](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogProductSet) type and represents a product set.\nThe product-set-specific data will be stored in the `product_set_data` field." }, { "name": "TIME_PERIOD", "description": "The `CatalogObject` instance is of the [CatalogTimePeriod](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogTimePeriod) type and represents a time period.\nThe time-period-specific data must be set on the `time_period_data` field." }, { "name": "MEASUREMENT_UNIT", "description": "The `CatalogObject` instance is of the [CatalogMeasurementUnit](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogMeasurementUnit) type and represents a measurement unit specifying the unit of\nmeasure and precision in which an item variation is sold. The measurement-unit-specific data must set on the `measurement_unit_data` field." }, { "name": "SUBSCRIPTION_PLAN_VARIATION", "description": "The `CatalogObject` instance is of the [CatalogSubscriptionPlan](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogSubscriptionPlan) type and represents a subscription plan.\nThe subscription-plan-specific data must be stored on the `subscription_plan_data` field." }, { "name": "ITEM_OPTION", "description": "The `CatalogObject` instance is of the [CatalogItemOption](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogItemOption) type and represents a list of options (such as a color or size of a T-shirt)\nthat can be assigned to item variations. The item-option-specific data must be on the `item_option_data` field." }, { "name": "ITEM_OPTION_VAL", "description": "The `CatalogObject` instance is of the [CatalogItemOptionValue](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogItemOptionValue) type and represents a value associated with one or more item options.\nFor example, an item option of \"Size\" may have item option values such as \"Small\" or \"Medium\".\nThe item-option-value-specific data must be on the `item_option_value_data` field." }, { "name": "CUSTOM_ATTRIBUTE_DEFINITION", "description": "The `CatalogObject` instance is of the [CatalogCustomAttributeDefinition](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogCustomAttributeDefinition) type and represents the definition of a custom attribute.\nThe custom-attribute-definition-specific data must be set on the `custom_attribute_definition_data` field." }, { "name": "QUICK_AMOUNTS_SETTINGS", "description": "The `CatalogObject` instance is of the [CatalogQuickAmountsSettings](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogQuickAmountsSettings) type and represents settings to configure preset charges for quick payments at each location.\nFor example, a location may have a list of both AUTO and MANUAL quick amounts that are set to DISABLED.\nThe quick-amounts-settings-specific data must be set on the `quick_amounts_settings_data` field." }, { "name": "SUBSCRIPTION_PLAN", "description": "The `CatalogObject` instance is of the [CatalogSubscriptionPlan](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogSubscriptionPlan) type and represents a subscription plan.\nThe subscription plan specific data must be stored on the `subscription_plan_data` field." }, { "name": "AVAILABILITY_PERIOD", "description": "The `CatalogObject` instance is of the [CatalogAvailabilityPeriod](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogAvailabilityPeriod) type and represents an availability period.\nThe availability period specific data must be stored on the `availability_period_data` field." } ], "description": "Possible types of CatalogObjects returned from the catalog, each\ncontaining type-specific properties in the `*_data` field corresponding to the specified object type.", "x-release-status": "PUBLIC" }, "CatalogPricingType": { "type": "string", "enum": [ "FIXED_PRICING", "VARIABLE_PRICING" ], "x-enum-elements": [ { "name": "FIXED_PRICING", "description": "The catalog item variation\u0027s price is fixed." }, { "name": "VARIABLE_PRICING", "description": "The catalog item variation\u0027s price is entered at the time of sale." } ], "description": "Indicates whether the price of a CatalogItemVariation should be entered manually at the time of sale.", "x-release-status": "PUBLIC" }, "CatalogQuickAmountType": { "type": "string", "enum": [ "QUICK_AMOUNT_TYPE_MANUAL", "QUICK_AMOUNT_TYPE_AUTO" ], "x-enum-elements": [ { "name": "QUICK_AMOUNT_TYPE_MANUAL", "description": "Quick Amount is created manually by the seller." }, { "name": "QUICK_AMOUNT_TYPE_AUTO", "description": "Quick Amount is generated automatically by machine learning algorithms." } ], "description": "Determines the type of a specific Quick Amount.", "x-release-status": "BETA", "x-is-beta": true }, "CatalogQuickAmountsSettingsOption": { "type": "string", "enum": [ "DISABLED", "MANUAL", "AUTO" ], "x-enum-elements": [ { "name": "DISABLED", "description": "Option for seller to disable Quick Amounts." }, { "name": "MANUAL", "description": "Option for seller to choose manually created Quick Amounts." }, { "name": "AUTO", "description": "Option for seller to choose automatically created Quick Amounts." } ], "description": "Determines a seller\u0027s option on Quick Amounts feature.", "x-release-status": "BETA", "x-is-beta": true }, "ChangeTiming": { "type": "string", "enum": [ "IMMEDIATE", "END_OF_BILLING_CYCLE" ], "x-enum-elements": [ { "name": "IMMEDIATE", "description": "The action occurs immediately." }, { "name": "END_OF_BILLING_CYCLE", "description": "The action occurs at the end of the billing cycle." } ], "description": "Supported timings when a pending change, as an action, takes place to a subscription.", "x-release-status": "BETA", "x-is-beta": true }, "CheckoutLocationSettingsBrandingButtonShape": { "type": "string", "enum": [ "SQUARED", "ROUNDED", "PILL" ], "x-enum-elements": [ { "name": "SQUARED", "description": "" }, { "name": "ROUNDED", "description": "" }, { "name": "PILL", "description": "" } ], "description": "", "x-release-status": "BETA", "x-is-beta": true }, "CheckoutLocationSettingsBrandingHeaderType": { "type": "string", "enum": [ "BUSINESS_NAME", "FRAMED_LOGO", "FULL_WIDTH_LOGO" ], "x-enum-elements": [ { "name": "BUSINESS_NAME", "description": "" }, { "name": "FRAMED_LOGO", "description": "" }, { "name": "FULL_WIDTH_LOGO", "description": "" } ], "description": "", "x-release-status": "BETA", "x-is-beta": true }, "CheckoutOptionsPaymentType": { "type": "string", "enum": [ "CARD_PRESENT", "MANUAL_CARD_ENTRY", "FELICA_ID", "FELICA_QUICPAY", "FELICA_TRANSPORTATION_GROUP", "FELICA_ALL", "PAYPAY" ], "x-enum-elements": [ { "name": "CARD_PRESENT", "description": "Accept credit card or debit card payments via tap, dip or swipe." }, { "name": "MANUAL_CARD_ENTRY", "description": "Launches the manual credit or debit card entry screen for the buyer to complete." }, { "name": "FELICA_ID", "description": "Launches the iD checkout screen for the buyer to complete." }, { "name": "FELICA_QUICPAY", "description": "Launches the QUICPay checkout screen for the buyer to complete." }, { "name": "FELICA_TRANSPORTATION_GROUP", "description": "Launches the Transportation Group checkout screen for the buyer to complete." }, { "name": "FELICA_ALL", "description": "Launches a checkout screen for the buyer on the Square Terminal that\nallows them to select a specific FeliCa brand or select the check balance screen." }, { "name": "PAYPAY", "description": "Launches the PayPay checkout screen for the buyer to complete." } ], "description": "", "x-release-status": "PUBLIC" }, "ComponentComponentType": { "type": "string", "enum": [ "APPLICATION", "CARD_READER", "BATTERY", "WIFI", "ETHERNET", "PRINTER" ], "x-enum-elements": [ { "name": "APPLICATION", "description": "" }, { "name": "CARD_READER", "description": "" }, { "name": "BATTERY", "description": "" }, { "name": "WIFI", "description": "" }, { "name": "ETHERNET", "description": "" }, { "name": "PRINTER", "description": "" } ], "description": "An enum for ComponentType.", "x-release-status": "BETA", "x-is-beta": 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\u0027s 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\u0027s Democratic Republic" }, { "name": "LB", "description": "Lebanon" }, { "name": "LC", "description": "Saint Lucia" }, { "name": "LI", "description": "Liechtenstein" }, { "name": "LK", "description": "Sri Lanka" }, { "name": "LR", "description": "Liberia" }, { "name": "LS", "description": "Lesotho" }, { "name": "LT", "description": "Lithuania" }, { "name": "LU", "description": "Luxembourg" }, { "name": "LV", "description": "Latvia" }, { "name": "LY", "description": "Libya" }, { "name": "MA", "description": "Morocco" }, { "name": "MC", "description": "Monaco" }, { "name": "MD", "description": "Moldova" }, { "name": "ME", "description": "Montenegro" }, { "name": "MF", "description": "Saint Martin" }, { "name": "MG", "description": "Madagascar" }, { "name": "MH", "description": "Marshall Islands" }, { "name": "MK", "description": "North Macedonia" }, { "name": "ML", "description": "Mali" }, { "name": "MM", "description": "Myanmar" }, { "name": "MN", "description": "Mongolia" }, { "name": "MO", "description": "Macao" }, { "name": "MP", "description": "Northern Mariana Islands" }, { "name": "MQ", "description": "Martinique" }, { "name": "MR", "description": "Mauritania" }, { "name": "MS", "description": "Montserrat" }, { "name": "MT", "description": "Malta" }, { "name": "MU", "description": "Mauritius" }, { "name": "MV", "description": "Maldives" }, { "name": "MW", "description": "Malawi" }, { "name": "MX", "description": "Mexico" }, { "name": "MY", "description": "Malaysia" }, { "name": "MZ", "description": "Mozambique" }, { "name": "NA", "description": "Namibia" }, { "name": "NC", "description": "New Caledonia" }, { "name": "NE", "description": "Niger" }, { "name": "NF", "description": "Norfolk Island" }, { "name": "NG", "description": "Nigeria" }, { "name": "NI", "description": "Nicaragua" }, { "name": "NL", "description": "Netherlands" }, { "name": "NO", "description": "Norway" }, { "name": "NP", "description": "Nepal" }, { "name": "NR", "description": "Nauru" }, { "name": "NU", "description": "Niue" }, { "name": "NZ", "description": "New Zealand" }, { "name": "OM", "description": "Oman" }, { "name": "PA", "description": "Panama" }, { "name": "PE", "description": "Peru" }, { "name": "PF", "description": "French Polynesia" }, { "name": "PG", "description": "Papua New Guinea" }, { "name": "PH", "description": "Philippines" }, { "name": "PK", "description": "Pakistan" }, { "name": "PL", "description": "Poland" }, { "name": "PM", "description": "Saint Pierre and Miquelon" }, { "name": "PN", "description": "Pitcairn" }, { "name": "PR", "description": "Puerto Rico" }, { "name": "PS", "description": "Palestine" }, { "name": "PT", "description": "Portugal" }, { "name": "PW", "description": "Palau" }, { "name": "PY", "description": "Paraguay" }, { "name": "QA", "description": "Qatar" }, { "name": "RE", "description": "Réunion" }, { "name": "RO", "description": "Romania" }, { "name": "RS", "description": "Serbia" }, { "name": "RU", "description": "Russia" }, { "name": "RW", "description": "Rwanda" }, { "name": "SA", "description": "Saudi Arabia" }, { "name": "SB", "description": "Solomon Islands" }, { "name": "SC", "description": "Seychelles" }, { "name": "SD", "description": "Sudan" }, { "name": "SE", "description": "Sweden" }, { "name": "SG", "description": "Singapore" }, { "name": "SH", "description": "Saint Helena, Ascension and Tristan da Cunha" }, { "name": "SI", "description": "Slovenia" }, { "name": "SJ", "description": "Svalbard and Jan Mayen" }, { "name": "SK", "description": "Slovakia" }, { "name": "SL", "description": "Sierra Leone" }, { "name": "SM", "description": "San Marino" }, { "name": "SN", "description": "Senegal" }, { "name": "SO", "description": "Somalia" }, { "name": "SR", "description": "Suriname" }, { "name": "SS", "description": "South Sudan" }, { "name": "ST", "description": "Sao Tome and Principe" }, { "name": "SV", "description": "El Salvador" }, { "name": "SX", "description": "Sint Maarten" }, { "name": "SY", "description": "Syrian Arab Republic" }, { "name": "SZ", "description": "Eswatini" }, { "name": "TC", "description": "Turks and Caicos Islands" }, { "name": "TD", "description": "Chad" }, { "name": "TF", "description": "French Southern Territories" }, { "name": "TG", "description": "Togo" }, { "name": "TH", "description": "Thailand" }, { "name": "TJ", "description": "Tajikistan" }, { "name": "TK", "description": "Tokelau" }, { "name": "TL", "description": "Timor-Leste" }, { "name": "TM", "description": "Turkmenistan" }, { "name": "TN", "description": "Tunisia" }, { "name": "TO", "description": "Tonga" }, { "name": "TR", "description": "Turkey" }, { "name": "TT", "description": "Trinidad and Tobago" }, { "name": "TV", "description": "Tuvalu" }, { "name": "TW", "description": "Taiwan" }, { "name": "TZ", "description": "Tanzania" }, { "name": "UA", "description": "Ukraine" }, { "name": "UG", "description": "Uganda" }, { "name": "UM", "description": "United States Minor Outlying Islands" }, { "name": "US", "description": "United States of America" }, { "name": "UY", "description": "Uruguay" }, { "name": "UZ", "description": "Uzbekistan" }, { "name": "VA", "description": "Vatican City" }, { "name": "VC", "description": "Saint Vincent and the Grenadines" }, { "name": "VE", "description": "Venezuela" }, { "name": "VG", "description": "British Virgin Islands" }, { "name": "VI", "description": "U.S. Virgin Islands" }, { "name": "VN", "description": "Vietnam" }, { "name": "VU", "description": "Vanuatu" }, { "name": "WF", "description": "Wallis and Futuna" }, { "name": "WS", "description": "Samoa" }, { "name": "YE", "description": "Yemen" }, { "name": "YT", "description": "Mayotte" }, { "name": "ZA", "description": "South Africa" }, { "name": "ZM", "description": "Zambia" }, { "name": "ZW", "description": "Zimbabwe" } ], "description": "Indicates the country associated with another entity, such as a business.\nValues are in [ISO 3166-1-alpha-2 format](http://www.iso.org/iso/home/standards/country_codes.htm).", "x-release-status": "PUBLIC" }, "Currency": { "type": "string", "enum": [ "UNKNOWN_CURRENCY", "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BOV", "BRL", "BSD", "BTN", "BWP", "BYR", "BZD", "CAD", "CDF", "CHE", "CHF", "CHW", "CLF", "CLP", "CNY", "COP", "COU", "CRC", "CUC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "EUR", "FJD", "FKP", "GBP", "GEL", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "INR", "IQD", "IRR", "ISK", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LTL", "LVL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRO", "MUR", "MVR", "MWK", "MXN", "MXV", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLL", "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 złoty" }, { "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 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\u0027anga" }, { "name": "TRY", "description": "Turkish lira" }, { "name": "TTD", "description": "Trinidad and Tobago dollar" }, { "name": "TWD", "description": "New Taiwan dollar" }, { "name": "TZS", "description": "Tanzanian shilling" }, { "name": "UAH", "description": "Ukrainian hryvnia" }, { "name": "UGX", "description": "Ugandan shilling" }, { "name": "USD", "description": "United States dollar" }, { "name": "USN", "description": "United States dollar (next day)" }, { "name": "USS", "description": "United States dollar (same day)" }, { "name": "UYI", "description": "Uruguay Peso en Unidedades Indexadas" }, { "name": "UYU", "description": "Uruguyan peso" }, { "name": "UZS", "description": "Uzbekistan som" }, { "name": "VEF", "description": "Venezuelan bolívar soberano" }, { "name": "VND", "description": "Vietnamese đồng" }, { "name": "VUV", "description": "Vanuatu vatu" }, { "name": "WST", "description": "Samoan tala" }, { "name": "XAF", "description": "CFA franc BEAC" }, { "name": "XAG", "description": "Silver" }, { "name": "XAU", "description": "Gold" }, { "name": "XBA", "description": "European Composite Unit" }, { "name": "XBB", "description": "European Monetary Unit" }, { "name": "XBC", "description": "European Unit of Account 9" }, { "name": "XBD", "description": "European Unit of Account 17" }, { "name": "XCD", "description": "East Caribbean dollar" }, { "name": "XDR", "description": "Special drawing rights (International Monetary Fund)" }, { "name": "XOF", "description": "CFA franc BCEAO" }, { "name": "XPD", "description": "Palladium" }, { "name": "XPF", "description": "CFP franc" }, { "name": "XPT", "description": "Platinum" }, { "name": "XTS", "description": "Code reserved for testing" }, { "name": "XXX", "description": "No currency" }, { "name": "YER", "description": "Yemeni rial" }, { "name": "ZAR", "description": "South African rand" }, { "name": "ZMK", "description": "Zambian kwacha" }, { "name": "ZMW", "description": "Zambian kwacha" }, { "name": "BTC", "description": "Bitcoin" }, { "name": "XUS", "description": "USD Coin" } ], "description": "Indicates the associated currency for an amount of money. Values correspond\nto [ISO 4217](https://wikipedia.org/wiki/ISO_4217).", "x-release-status": "PUBLIC" }, "CustomAttributeDefinitionVisibility": { "type": "string", "enum": [ "VISIBILITY_HIDDEN", "VISIBILITY_READ_ONLY", "VISIBILITY_READ_WRITE_VALUES" ], "x-enum-elements": [ { "name": "VISIBILITY_HIDDEN", "description": "The custom attribute definition and values are hidden from the seller (except on export\nof all seller data) and other developers." }, { "name": "VISIBILITY_READ_ONLY", "description": "The seller and other developers can read the custom attribute definition and values\non resources." }, { "name": "VISIBILITY_READ_WRITE_VALUES", "description": "The seller and other developers can read the custom attribute definition,\nand can read and write values on resources. A custom attribute definition\ncan only be edited or deleted by the application that created it." } ], "description": "The level of permission that a seller or other applications requires to\nview this custom attribute definition.\nThe `Visibility` field controls who can read and write the custom attribute values\nand custom attribute definition.", "x-release-status": "PUBLIC" }, "CustomerCreationSource": { "type": "string", "enum": [ "OTHER", "APPOINTMENTS", "COUPON", "DELETION_RECOVERY", "DIRECTORY", "EGIFTING", "EMAIL_COLLECTION", "FEEDBACK", "IMPORT", "INVOICES", "LOYALTY", "MARKETING", "MERGE", "ONLINE_STORE", "INSTANT_PROFILE", "TERMINAL", "THIRD_PARTY", "THIRD_PARTY_IMPORT", "UNMERGE_RECOVERY" ], "x-enum-elements": [ { "name": "OTHER", "description": "The default creation source. This source is typically used for backward/future\ncompatibility when the original source of a customer profile is\nunrecognized. For example, when older clients do not support newer\nsource types." }, { "name": "APPOINTMENTS", "description": "The customer profile was created automatically when an appointment\nwas scheduled." }, { "name": "COUPON", "description": "The customer profile was created automatically when a coupon was issued\nusing Square Point of Sale." }, { "name": "DELETION_RECOVERY", "description": "The customer profile was restored through Square\u0027s deletion recovery\nprocess." }, { "name": "DIRECTORY", "description": "The customer profile was created manually through Square Seller Dashboard or the \nPoint of Sale application." }, { "name": "EGIFTING", "description": "The customer profile was created automatically when a gift card was\nissued using Square Point of Sale. Customer profiles are created for\nboth the buyer and the recipient of the gift card." }, { "name": "EMAIL_COLLECTION", "description": "The customer profile was created through Square Point of Sale when\nsigning up for marketing emails during checkout." }, { "name": "FEEDBACK", "description": "The customer profile was created automatically when providing feedback\nthrough a digital receipt." }, { "name": "IMPORT", "description": "The customer profile was created automatically when importing customer\ndata through Square Seller Dashboard." }, { "name": "INVOICES", "description": "The customer profile was created automatically during an invoice payment." }, { "name": "LOYALTY", "description": "The customer profile was created automatically when customers provide a\nphone number for loyalty reward programs during checkout." }, { "name": "MARKETING", "description": "The customer profile was created as the result of a campaign managed\nthrough Square’s Facebook integration." }, { "name": "MERGE", "description": "The customer profile was created as the result of explicitly merging\nmultiple customer profiles through the Square Seller Dashboard or the Point of\nSale application." }, { "name": "ONLINE_STORE", "description": "The customer profile was created through Square\u0027s Online Store solution\n(legacy service)." }, { "name": "INSTANT_PROFILE", "description": "The customer profile was created automatically as the result of a successful\ntransaction that did not explicitly link to an existing customer profile." }, { "name": "TERMINAL", "description": "The customer profile was created through Square\u0027s Virtual Terminal." }, { "name": "THIRD_PARTY", "description": "The customer profile was created through a Square API call." }, { "name": "THIRD_PARTY_IMPORT", "description": "The customer profile was created by a third-party product and imported\nthrough an official integration." }, { "name": "UNMERGE_RECOVERY", "description": "The customer profile was restored through Square\u0027s unmerge recovery\nprocess." } ], "description": "Indicates the method used to create the customer profile.", "x-release-status": "PUBLIC" }, "CustomerInclusionExclusion": { "type": "string", "enum": [ "INCLUDE", "EXCLUDE" ], "x-enum-elements": [ { "name": "INCLUDE", "description": "Customers should be included in the result set when they match the\nfiltering criteria." }, { "name": "EXCLUDE", "description": "Customers should be excluded from the result set when they match\nthe filtering criteria." } ], "description": "Indicates whether customers should be included in, or excluded from,\nthe result set when they match the filtering criteria.", "x-release-status": "PUBLIC" }, "CustomerSortField": { "type": "string", "enum": [ "DEFAULT", "CREATED_AT" ], "x-enum-elements": [ { "name": "DEFAULT", "description": "Use the default sort key. By default, customers are sorted\nalphanumerically by concatenating their `given_name` and `family_name`. If\nneither name field is set, string comparison is performed using one of the\nremaining fields in the following order: `company_name`, `email`,\n`phone_number`." }, { "name": "CREATED_AT", "description": "Use the creation date attribute (`created_at`) of customer profiles as the sort key." } ], "description": "Specifies customer attributes as the sort key to customer profiles returned from a search.", "x-release-status": "PUBLIC" }, "DataCollectionOptionsInputType": { "type": "string", "enum": [ "EMAIL", "PHONE_NUMBER" ], "x-enum-elements": [ { "name": "EMAIL", "description": "This value is used to represent an input text that contains a email validation on the\nclient." }, { "name": "PHONE_NUMBER", "description": "This value is used to represent an input text that contains a phone number validation on\nthe client." } ], "description": "Describes the input type of the data.", "x-release-status": "BETA", "x-is-beta": true }, "DayOfWeek": { "type": "string", "enum": [ "SUN", "MON", "TUE", "WED", "THU", "FRI", "SAT" ], "x-enum-elements": [ { "name": "SUN", "description": "Sunday" }, { "name": "MON", "description": "Monday" }, { "name": "TUE", "description": "Tuesday" }, { "name": "WED", "description": "Wednesday" }, { "name": "THU", "description": "Thursday" }, { "name": "FRI", "description": "Friday" }, { "name": "SAT", "description": "Saturday" } ], "description": "Indicates the specific day of the week.", "x-release-status": "PUBLIC" }, "DestinationType": { "type": "string", "enum": [ "BANK_ACCOUNT", "CARD", "SQUARE_BALANCE", "SQUARE_STORED_BALANCE" ], "x-enum-elements": [ { "name": "BANK_ACCOUNT", "description": "An external bank account outside of Square." }, { "name": "CARD", "description": "An external card outside of Square used for the transfer." }, { "name": "SQUARE_BALANCE", "description": "" }, { "name": "SQUARE_STORED_BALANCE", "description": "Square Checking or Savings account (US), Square Card (CA)" } ], "description": "List of possible destinations against which a payout can be made.", "x-release-status": "PUBLIC" }, "DeviceAttributesDeviceType": { "type": "string", "enum": [ "TERMINAL" ], "x-enum-elements": [ { "name": "TERMINAL", "description": "" } ], "description": "An enum identifier of the device type.", "x-release-status": "BETA", "x-is-beta": true }, "DeviceCodeStatus": { "type": "string", "enum": [ "UNKNOWN", "UNPAIRED", "PAIRED", "EXPIRED" ], "x-enum-elements": [ { "name": "UNKNOWN", "description": "The status cannot be determined or does not exist." }, { "name": "UNPAIRED", "description": "The device code is just created and unpaired." }, { "name": "PAIRED", "description": "The device code has been signed in and paired to a device." }, { "name": "EXPIRED", "description": "The device code was unpaired and expired before it was paired." } ], "description": "DeviceCode.Status enum.", "x-release-status": "PUBLIC" }, "DeviceComponentDetailsExternalPower": { "type": "string", "enum": [ "AVAILABLE_CHARGING", "AVAILABLE_NOT_IN_USE", "UNAVAILABLE", "AVAILABLE_INSUFFICIENT" ], "x-enum-elements": [ { "name": "AVAILABLE_CHARGING", "description": "Plugged in and charging." }, { "name": "AVAILABLE_NOT_IN_USE", "description": "Fully charged." }, { "name": "UNAVAILABLE", "description": "On battery power." }, { "name": "AVAILABLE_INSUFFICIENT", "description": "Not providing enough power for the device." } ], "description": "An enum for ExternalPower.", "x-release-status": "BETA", "x-is-beta": true }, "DeviceStatusCategory": { "type": "string", "enum": [ "AVAILABLE", "NEEDS_ATTENTION", "OFFLINE" ], "x-enum-elements": [ { "name": "AVAILABLE", "description": "" }, { "name": "NEEDS_ATTENTION", "description": "" }, { "name": "OFFLINE", "description": "" } ], "description": "", "x-release-status": "BETA", "x-is-beta": true }, "DisputeEvidenceType": { "type": "string", "enum": [ "GENERIC_EVIDENCE", "ONLINE_OR_APP_ACCESS_LOG", "AUTHORIZATION_DOCUMENTATION", "CANCELLATION_OR_REFUND_DOCUMENTATION", "CARDHOLDER_COMMUNICATION", "CARDHOLDER_INFORMATION", "PURCHASE_ACKNOWLEDGEMENT", "DUPLICATE_CHARGE_DOCUMENTATION", "PRODUCT_OR_SERVICE_DESCRIPTION", "RECEIPT", "SERVICE_RECEIVED_DOCUMENTATION", "PROOF_OF_DELIVERY_DOCUMENTATION", "RELATED_TRANSACTION_DOCUMENTATION", "REBUTTAL_EXPLANATION", "TRACKING_NUMBER" ], "x-enum-elements": [ { "name": "GENERIC_EVIDENCE", "description": "Square assumes this evidence type if you do not provide a type when uploading evidence.\n\nUse when uploading evidence as a file or string." }, { "name": "ONLINE_OR_APP_ACCESS_LOG", "description": "Server or activity logs that show proof of the cardholder’s identity and that the\ncardholder successfully ordered and received the goods (digitally or otherwise).\nExample evidence includes IP addresses, corresponding timestamps/dates, cardholder’s name and email\naddress linked to a cardholder profile held by the seller, proof the same device and card (used\nin dispute) were previously used in prior undisputed transaction, and any related detailed activity.\n\nUse when uploading evidence as a file or string." }, { "name": "AUTHORIZATION_DOCUMENTATION", "description": "Evidence that the cardholder did provide authorization for the charge.\nExample evidence includes a signed credit card authorization.\n\nUse when uploading evidence as a file." }, { "name": "CANCELLATION_OR_REFUND_DOCUMENTATION", "description": "Evidence that the cardholder acknowledged your refund or cancellation policy.\nExample evidence includes a signature or checkbox showing the cardholder’s acknowledgement of your\nrefund or cancellation policy.\n\nUse when uploading evidence as a file or string." }, { "name": "CARDHOLDER_COMMUNICATION", "description": "Evidence that shows relevant communication with the cardholder.\nExample evidence includes emails or texts that show the cardholder received goods/services or\ndemonstrate cardholder satisfaction.\n\nUse when uploading evidence as a file." }, { "name": "CARDHOLDER_INFORMATION", "description": "Evidence that validates the customer\u0027s identity.\nExample evidence includes personally identifiable details such as name, email address, purchaser IP\naddress, and a copy of the cardholder ID.\n\nUse when uploading evidence as a file or string." }, { "name": "PURCHASE_ACKNOWLEDGEMENT", "description": "Evidence that shows proof of the sale/transaction.\nExample evidence includes an invoice, contract, or other item showing the customer’s acknowledgement\nof the purchase and your terms.\n\nUse when uploading evidence as a file or string." }, { "name": "DUPLICATE_CHARGE_DOCUMENTATION", "description": "Evidence that shows the charges in question are valid and distinct from one another.\nExample evidence includes receipts, shipping labels, and invoices along with their distinct payment IDs.\n\nUse when uploading evidence as a file." }, { "name": "PRODUCT_OR_SERVICE_DESCRIPTION", "description": "A description of the product or service sold.\n\nUse when uploading evidence as a file or string." }, { "name": "RECEIPT", "description": "A receipt or message sent to the cardholder detailing the charge.\nNote: You do not need to upload the Square receipt; Square submits the receipt on your behalf.\n\nUse when uploading evidence as a file or string." }, { "name": "SERVICE_RECEIVED_DOCUMENTATION", "description": "Evidence that the service was provided to the cardholder or the expected date that services will be rendered.\nExample evidence includes a signed delivery form, work order, expected delivery date, or other written agreements.\n\nUse when uploading evidence as a file or string." }, { "name": "PROOF_OF_DELIVERY_DOCUMENTATION", "description": "Evidence that shows the product was provided to the cardholder or the expected date of delivery.\nExample evidence includes a signed delivery form or written agreement acknowledging receipt of the goods or services.\n\nUse when uploading evidence as a file or string." }, { "name": "RELATED_TRANSACTION_DOCUMENTATION", "description": "Evidence that shows the cardholder previously processed transactions on the same card and did not dispute them.\nNote: Square automatically provides up to five distinct Square receipts for related transactions, when available.\n\nUse when uploading evidence as a file or string." }, { "name": "REBUTTAL_EXPLANATION", "description": "An explanation of why the cardholder’s claim is invalid.\nExample evidence includes an explanation of why each distinct charge is a legitimate purchase, why the cardholder’s claim\nfor credit owed due to their attempt to cancel, return, or refund is invalid per your stated policy and cardholder\nagreement, or an explanation of how the cardholder did not attempt to remedy the issue with you first to receive credit.\n\nUse when uploading evidence as a file or string." }, { "name": "TRACKING_NUMBER", "description": "The tracking number for the order provided by the shipping carrier. If you have multiple numbers, they need to be\nsubmitted individually as separate pieces of evidence.\n\nUse when uploading evidence as a string." } ], "description": "The type of the dispute evidence.", "x-release-status": "PUBLIC" }, "DisputeReason": { "type": "string", "enum": [ "AMOUNT_DIFFERS", "CANCELLED", "DUPLICATE", "NO_KNOWLEDGE", "NOT_AS_DESCRIBED", "NOT_RECEIVED", "PAID_BY_OTHER_MEANS", "CUSTOMER_REQUESTS_CREDIT", "EMV_LIABILITY_SHIFT" ], "x-enum-elements": [ { "name": "AMOUNT_DIFFERS", "description": "The cardholder claims that they were charged the wrong amount for the purchase.\nTo challenge this dispute, provide specific and concrete evidence that the cardholder agreed\nto the amount charged." }, { "name": "CANCELLED", "description": "The cardholder claims that they attempted to return the goods or cancel the service.\nTo challenge this dispute, provide specific and concrete evidence to prove that the cardholder\nis not due a refund and that the cardholder acknowledged your cancellation policy." }, { "name": "DUPLICATE", "description": "The cardholder claims that they were charged twice for the same purchase.\nTo challenge this dispute, provide specific and concrete evidence that shows both charges are\nlegitimate and independent of one another." }, { "name": "NO_KNOWLEDGE", "description": "The cardholder claims that they did not make this purchase nor authorized the charge.\nTo challenge this dispute, provide specific and concrete evidence that proves that the cardholder\nidentity was verified at the time of purchase and that the purchase was authorized." }, { "name": "NOT_AS_DESCRIBED", "description": "The cardholder claims the product or service was provided, but the quality of the deliverable\ndid not align with the expectations of the cardholder based on the description.\nTo challenge this dispute, provide specific and concrete evidence that shows the cardholder is in\npossession of the product as described or received the service as described and agreed on." }, { "name": "NOT_RECEIVED", "description": "The cardholder claims the product or service was not received by the cardholder within the\nstated time frame.\nTo challenge this dispute, provide specific and concrete evidence to prove that the cardholder is\nin possession of or received the product or service sold." }, { "name": "PAID_BY_OTHER_MEANS", "description": "The cardholder claims that they previously paid for this purchase.\nTo challenge this dispute, provide specific and concrete evidence that shows both charges are\nlegitimate and independent of one another or proof that you already provided a credit for the charge." }, { "name": "CUSTOMER_REQUESTS_CREDIT", "description": "The cardholder claims that the purchase was canceled or returned, but they have not yet received\nthe credit.\nTo challenge this dispute, provide specific and concrete evidence to prove that the cardholder is not\ndue a refund and that they acknowledged your cancellation and/or refund policy." }, { "name": "EMV_LIABILITY_SHIFT", "description": "A chip-enabled card was not processed through a compliant chip-card reader (for example, it was swiped\ninstead of dipped into a chip-card reader).\nYou cannot challenge this dispute because the payment did not comply with EMV security requirements.\nFor more information, see [What Is EMV?](https://squareup.com/emv)" } ], "description": "The list of possible reasons why a cardholder might initiate a\ndispute with their bank.", "x-release-status": "PUBLIC" }, "DisputeState": { "type": "string", "enum": [ "INQUIRY_EVIDENCE_REQUIRED", "INQUIRY_PROCESSING", "INQUIRY_CLOSED", "EVIDENCE_REQUIRED", "PROCESSING", "WON", "LOST", "ACCEPTED" ], "x-enum-elements": [ { "name": "INQUIRY_EVIDENCE_REQUIRED", "description": "The initial state of an inquiry with evidence required" }, { "name": "INQUIRY_PROCESSING", "description": "Inquiry evidence has been submitted and the bank is processing the inquiry" }, { "name": "INQUIRY_CLOSED", "description": "The inquiry is complete" }, { "name": "EVIDENCE_REQUIRED", "description": "The initial state of a dispute with evidence required" }, { "name": "PROCESSING", "description": "Dispute evidence has been submitted and the bank is processing the dispute" }, { "name": "WON", "description": "The bank has completed processing the dispute and the seller has won" }, { "name": "LOST", "description": "The bank has completed processing the dispute and the seller has lost" }, { "name": "ACCEPTED", "description": "The seller has accepted the dispute" } ], "description": "The list of possible dispute states.", "x-release-status": "PUBLIC" }, "EcomVisibility": { "type": "string", "enum": [ "UNINDEXED", "UNAVAILABLE", "HIDDEN", "VISIBLE" ], "x-enum-elements": [ { "name": "UNINDEXED", "description": "Item is not synced with Ecom (Weebly). This is the default state" }, { "name": "UNAVAILABLE", "description": "Item is synced but is unavailable within Ecom (Weebly) and Online Checkout" }, { "name": "HIDDEN", "description": "Option for seller to choose manually created Quick Amounts." }, { "name": "VISIBLE", "description": "Item is synced but available within Ecom (Weebly) and Online Checkout but is hidden from Ecom Store." } ], "description": "Determines item visibility in Ecom (Online Store) and Online Checkout.", "x-release-status": "PUBLIC" }, "EmployeeStatus": { "type": "string", "enum": [ "ACTIVE", "INACTIVE" ], "x-enum-elements": [ { "name": "ACTIVE", "description": "Specifies that the employee is in the Active state." }, { "name": "INACTIVE", "description": "Specifies that the employee is in the Inactive state." } ], "description": "The status of the Employee being retrieved.\n\nDEPRECATED at version 2020-08-26. Replaced by [TeamMemberStatus](https://developer.squareup.com/reference/square_2024-10-17/objects/TeamMemberStatus).", "x-release-status": "DEPRECATED", "x-is-deprecated": true }, "ErrorCategory": { "type": "string", "enum": [ "API_ERROR", "AUTHENTICATION_ERROR", "INVALID_REQUEST_ERROR", "RATE_LIMIT_ERROR", "PAYMENT_METHOD_ERROR", "REFUND_ERROR", "MERCHANT_SUBSCRIPTION_ERROR", "EXTERNAL_VENDOR_ERROR" ], "x-enum-elements": [ { "name": "API_ERROR", "description": "An error occurred with the Connect API itself." }, { "name": "AUTHENTICATION_ERROR", "description": "An authentication error occurred. Most commonly, the request had\na missing, malformed, or otherwise invalid `Authorization` header." }, { "name": "INVALID_REQUEST_ERROR", "description": "The request was invalid. Most commonly, a required parameter was\nmissing, or a provided parameter had an invalid value." }, { "name": "RATE_LIMIT_ERROR", "description": "Your application reached the Square API rate limit. You might receive this error if your application sends a high number of requests\nto Square APIs in a short period of time.\n\nYour application should monitor responses for `429 RATE_LIMITED` errors and use a retry mechanism with an [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff)\nschedule to resend the requests at an increasingly slower rate. It is also a good practice to use a randomized delay (jitter) in your retry schedule." }, { "name": "PAYMENT_METHOD_ERROR", "description": "An error occurred while processing a payment method. Most commonly,\nthe details of the payment method were invalid (such as a card\u0027s CVV\nor expiration date)." }, { "name": "REFUND_ERROR", "description": "An error occurred while attempting to process a refund." }, { "name": "MERCHANT_SUBSCRIPTION_ERROR", "description": "An error occurred when checking a merchant subscription status" }, { "name": "EXTERNAL_VENDOR_ERROR", "description": "An error that is returned from an external vendor\u0027s API" } ], "description": "Indicates which high-level category of error has occurred during a\nrequest to the Connect API.", "x-release-status": "PUBLIC" }, "ErrorCode": { "type": "string", "enum": [ "INTERNAL_SERVER_ERROR", "UNAUTHORIZED", "ACCESS_TOKEN_EXPIRED", "ACCESS_TOKEN_REVOKED", "CLIENT_DISABLED", "FORBIDDEN", "INSUFFICIENT_SCOPES", "APPLICATION_DISABLED", "V1_APPLICATION", "V1_ACCESS_TOKEN", "CARD_PROCESSING_NOT_ENABLED", "MERCHANT_SUBSCRIPTION_NOT_FOUND", "BAD_REQUEST", "MISSING_REQUIRED_PARAMETER", "INCORRECT_TYPE", "INVALID_TIME", "INVALID_TIME_RANGE", "INVALID_VALUE", "INVALID_CURSOR", "UNKNOWN_QUERY_PARAMETER", "CONFLICTING_PARAMETERS", "EXPECTED_JSON_BODY", "INVALID_SORT_ORDER", "VALUE_REGEX_MISMATCH", "VALUE_TOO_SHORT", "VALUE_TOO_LONG", "VALUE_TOO_LOW", "VALUE_TOO_HIGH", "VALUE_EMPTY", "ARRAY_LENGTH_TOO_LONG", "ARRAY_LENGTH_TOO_SHORT", "ARRAY_EMPTY", "EXPECTED_BOOLEAN", "EXPECTED_INTEGER", "EXPECTED_FLOAT", "EXPECTED_STRING", "EXPECTED_OBJECT", "EXPECTED_ARRAY", "EXPECTED_MAP", "EXPECTED_BASE64_ENCODED_BYTE_ARRAY", "INVALID_ARRAY_VALUE", "INVALID_ENUM_VALUE", "INVALID_CONTENT_TYPE", "INVALID_FORM_VALUE", "CUSTOMER_NOT_FOUND", "ONE_INSTRUMENT_EXPECTED", "NO_FIELDS_SET", "TOO_MANY_MAP_ENTRIES", "MAP_KEY_LENGTH_TOO_SHORT", "MAP_KEY_LENGTH_TOO_LONG", "CUSTOMER_MISSING_NAME", "CUSTOMER_MISSING_EMAIL", "INVALID_PAUSE_LENGTH", "INVALID_DATE", "UNSUPPORTED_COUNTRY", "UNSUPPORTED_CURRENCY", "APPLE_TTP_PIN_TOKEN", "CARD_EXPIRED", "INVALID_EXPIRATION", "INVALID_EXPIRATION_YEAR", "INVALID_EXPIRATION_DATE", "UNSUPPORTED_CARD_BRAND", "UNSUPPORTED_ENTRY_METHOD", "INVALID_ENCRYPTED_CARD", "INVALID_CARD", "PAYMENT_AMOUNT_MISMATCH", "GENERIC_DECLINE", "CVV_FAILURE", "ADDRESS_VERIFICATION_FAILURE", "INVALID_ACCOUNT", "CURRENCY_MISMATCH", "INSUFFICIENT_FUNDS", "INSUFFICIENT_PERMISSIONS", "CARDHOLDER_INSUFFICIENT_PERMISSIONS", "INVALID_LOCATION", "TRANSACTION_LIMIT", "VOICE_FAILURE", "PAN_FAILURE", "EXPIRATION_FAILURE", "CARD_NOT_SUPPORTED", "INVALID_PIN", "MISSING_PIN", "MISSING_ACCOUNT_TYPE", "INVALID_POSTAL_CODE", "INVALID_FEES", "MANUALLY_ENTERED_PAYMENT_NOT_SUPPORTED", "PAYMENT_LIMIT_EXCEEDED", "GIFT_CARD_AVAILABLE_AMOUNT", "ACCOUNT_UNUSABLE", "BUYER_REFUSED_PAYMENT", "DELAYED_TRANSACTION_EXPIRED", "DELAYED_TRANSACTION_CANCELED", "DELAYED_TRANSACTION_CAPTURED", "DELAYED_TRANSACTION_FAILED", "CARD_TOKEN_EXPIRED", "CARD_TOKEN_USED", "AMOUNT_TOO_HIGH", "UNSUPPORTED_INSTRUMENT_TYPE", "REFUND_AMOUNT_INVALID", "REFUND_ALREADY_PENDING", "PAYMENT_NOT_REFUNDABLE", "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." }, { "name": "UNAUTHORIZED", "description": "A general authorization error occurred." }, { "name": "ACCESS_TOKEN_EXPIRED", "description": "The provided access token has expired." }, { "name": "ACCESS_TOKEN_REVOKED", "description": "The provided access token has been revoked." }, { "name": "CLIENT_DISABLED", "description": "The provided client has been disabled." }, { "name": "FORBIDDEN", "description": "A general access error occurred." }, { "name": "INSUFFICIENT_SCOPES", "description": "The provided access token does not have permission\nto execute the requested action." }, { "name": "APPLICATION_DISABLED", "description": "The calling application was disabled." }, { "name": "V1_APPLICATION", "description": "The calling application was created prior to\n2016-03-30 and is not compatible with v2 Square API calls." }, { "name": "V1_ACCESS_TOKEN", "description": "The calling application is using an access token\ncreated prior to 2016-03-30 and is not compatible with v2 Square API\ncalls." }, { "name": "CARD_PROCESSING_NOT_ENABLED", "description": "The location provided in the API call is not\nenabled for credit card processing." }, { "name": "MERCHANT_SUBSCRIPTION_NOT_FOUND", "description": "A required subscription was not found for the merchant" }, { "name": "BAD_REQUEST", "description": "A general error occurred with the request." }, { "name": "MISSING_REQUIRED_PARAMETER", "description": "The request is missing a required path, query, or\nbody parameter." }, { "name": "INCORRECT_TYPE", "description": "The value provided in the request is the wrong\ntype. For example, a string instead of an integer." }, { "name": "INVALID_TIME", "description": "Formatting for the provided time value is\nincorrect." }, { "name": "INVALID_TIME_RANGE", "description": "The time range provided in the request is invalid.\nFor example, the end time is before the start time." }, { "name": "INVALID_VALUE", "description": "The provided value is invalid. For example,\nincluding `%` in a phone number." }, { "name": "INVALID_CURSOR", "description": "The pagination cursor included in the request is\ninvalid." }, { "name": "UNKNOWN_QUERY_PARAMETER", "description": "The query parameters provided is invalid for the\nrequested endpoint." }, { "name": "CONFLICTING_PARAMETERS", "description": "One or more of the request parameters conflict with\neach other." }, { "name": "EXPECTED_JSON_BODY", "description": "The request body is not a JSON object." }, { "name": "INVALID_SORT_ORDER", "description": "The provided sort order is not a valid key.\nCurrently, sort order must be `ASC` or `DESC`." }, { "name": "VALUE_REGEX_MISMATCH", "description": "The provided value does not match an expected\nregular expression." }, { "name": "VALUE_TOO_SHORT", "description": "The provided string value is shorter than the\nminimum length allowed." }, { "name": "VALUE_TOO_LONG", "description": "The provided string value is longer than the\nmaximum length allowed." }, { "name": "VALUE_TOO_LOW", "description": "The provided value is less than the supported\nminimum." }, { "name": "VALUE_TOO_HIGH", "description": "The provided value is greater than the supported\nmaximum." }, { "name": "VALUE_EMPTY", "description": "The provided value has a default (empty) value\nsuch as a blank string." }, { "name": "ARRAY_LENGTH_TOO_LONG", "description": "The provided array has too many elements." }, { "name": "ARRAY_LENGTH_TOO_SHORT", "description": "The provided array has too few elements." }, { "name": "ARRAY_EMPTY", "description": "The provided array is empty." }, { "name": "EXPECTED_BOOLEAN", "description": "The endpoint expected the provided value to be a\nboolean." }, { "name": "EXPECTED_INTEGER", "description": "The endpoint expected the provided value to be an\ninteger." }, { "name": "EXPECTED_FLOAT", "description": "The endpoint expected the provided value to be a\nfloat." }, { "name": "EXPECTED_STRING", "description": "The endpoint expected the provided value to be a\nstring." }, { "name": "EXPECTED_OBJECT", "description": "The endpoint expected the provided value to be a\nJSON object." }, { "name": "EXPECTED_ARRAY", "description": "The endpoint expected the provided value to be an\narray or list." }, { "name": "EXPECTED_MAP", "description": "The endpoint expected the provided value to be a\nmap or associative array." }, { "name": "EXPECTED_BASE64_ENCODED_BYTE_ARRAY", "description": "The endpoint expected the provided value to be an\narray encoded in base64." }, { "name": "INVALID_ARRAY_VALUE", "description": "One or more objects in the array does not match the\narray type." }, { "name": "INVALID_ENUM_VALUE", "description": "The provided static string is not valid for the\nfield." }, { "name": "INVALID_CONTENT_TYPE", "description": "Invalid content type header." }, { "name": "INVALID_FORM_VALUE", "description": "Only relevant for applications created prior to\n2016-03-30. Indicates there was an error while parsing form values." }, { "name": "CUSTOMER_NOT_FOUND", "description": "The provided customer id can\u0027t be found in the merchant\u0027s customers list." }, { "name": "ONE_INSTRUMENT_EXPECTED", "description": "A general error occurred." }, { "name": "NO_FIELDS_SET", "description": "A general error occurred." }, { "name": "TOO_MANY_MAP_ENTRIES", "description": "Too many entries in the map field." }, { "name": "MAP_KEY_LENGTH_TOO_SHORT", "description": "The length of one of the provided keys in the map is too short." }, { "name": "MAP_KEY_LENGTH_TOO_LONG", "description": "The length of one of the provided keys in the map is too long." }, { "name": "CUSTOMER_MISSING_NAME", "description": "The provided customer does not have a recorded name." }, { "name": "CUSTOMER_MISSING_EMAIL", "description": "The provided customer does not have a recorded email." }, { "name": "INVALID_PAUSE_LENGTH", "description": "The subscription cannot be paused longer than the duration of the current phase." }, { "name": "INVALID_DATE", "description": "The subscription cannot be paused/resumed on the given date." }, { "name": "UNSUPPORTED_COUNTRY", "description": "The API request references an unsupported country." }, { "name": "UNSUPPORTED_CURRENCY", "description": "The API request references an unsupported currency." }, { "name": "APPLE_TTP_PIN_TOKEN", "description": "The payment was declined by the card issuer during an Apple Tap to Pay (TTP)\ntransaction with a request for the card\u0027s PIN. This code will be returned alongside\n`CARD_DECLINED_VERIFICATION_REQUIRED` as a supplemental error, and will include an\nissuer-provided token in the `details` field that is needed to initiate the PIN\ncollection flow on the iOS device." }, { "name": "CARD_EXPIRED", "description": "The card issuer declined the request because the card is expired." }, { "name": "INVALID_EXPIRATION", "description": "The expiration date for the payment card is invalid. For example,\nit indicates a date in the past." }, { "name": "INVALID_EXPIRATION_YEAR", "description": "The expiration year for the payment card is invalid. For example,\nit indicates a year in the past or contains invalid characters." }, { "name": "INVALID_EXPIRATION_DATE", "description": "The expiration date for the payment card is invalid. For example,\nit contains invalid characters." }, { "name": "UNSUPPORTED_CARD_BRAND", "description": "The credit card provided is not from a supported issuer." }, { "name": "UNSUPPORTED_ENTRY_METHOD", "description": "The entry method for the credit card (swipe, dip, tap) is not supported." }, { "name": "INVALID_ENCRYPTED_CARD", "description": "The encrypted card information is invalid." }, { "name": "INVALID_CARD", "description": "The credit card cannot be validated based on the provided details." }, { "name": "PAYMENT_AMOUNT_MISMATCH", "description": "The payment was declined because there was a payment amount mismatch.\nThe money amount Square was expecting does not match the amount provided." }, { "name": "GENERIC_DECLINE", "description": "Square received a decline without any additional information.\nIf the payment information seems correct, the buyer can contact their\nissuer to ask for more information." }, { "name": "CVV_FAILURE", "description": "The card issuer declined the request because the CVV value is invalid." }, { "name": "ADDRESS_VERIFICATION_FAILURE", "description": "The card issuer declined the request because the postal code is invalid." }, { "name": "INVALID_ACCOUNT", "description": "The issuer was not able to locate the account on record." }, { "name": "CURRENCY_MISMATCH", "description": "The currency associated with the payment is not valid for the provided\nfunding source. For example, a gift card funded in USD cannot be used to process\npayments in GBP." }, { "name": "INSUFFICIENT_FUNDS", "description": "The funding source has insufficient funds to cover the payment." }, { "name": "INSUFFICIENT_PERMISSIONS", "description": "The Square account does not have the permissions to accept\nthis payment. For example, Square may limit which merchants are\nallowed to receive gift card payments." }, { "name": "CARDHOLDER_INSUFFICIENT_PERMISSIONS", "description": "The card issuer has declined the transaction due to restrictions on where the card can be used.\nFor example, a gift card is limited to a single merchant." }, { "name": "INVALID_LOCATION", "description": "The Square account cannot take payments in the specified region.\nA Square account can take payments only from the region where the account was created." }, { "name": "TRANSACTION_LIMIT", "description": "The card issuer has determined the payment amount is either too high or too low.\nThe API returns the error code mostly for credit cards (for example, the card reached\nthe credit limit). However, sometimes the issuer bank can indicate the error for debit\nor prepaid cards (for example, card has insufficient funds)." }, { "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." }, { "name": "PAN_FAILURE", "description": "The specified card number is invalid. For example, it is of\nincorrect length or is incorrectly formatted." }, { "name": "EXPIRATION_FAILURE", "description": "The card expiration date is either invalid or indicates that the\ncard is expired." }, { "name": "CARD_NOT_SUPPORTED", "description": "The card is not supported either in the geographic region or by\nthe [merchant category code](https://developer.squareup.com/docs/locations-api#initialize-a-merchant-category-code) (MCC)." }, { "name": "INVALID_PIN", "description": "The card issuer declined the request because the PIN is invalid." }, { "name": "MISSING_PIN", "description": "The payment is missing a required PIN." }, { "name": "MISSING_ACCOUNT_TYPE", "description": "The payment is missing a required ACCOUNT_TYPE parameter." }, { "name": "INVALID_POSTAL_CODE", "description": "The postal code is incorrectly formatted." }, { "name": "INVALID_FEES", "description": "The app_fee_money on a payment is too high." }, { "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." }, { "name": "PAYMENT_LIMIT_EXCEEDED", "description": "Square declined the request because the payment amount exceeded the processing limit for this merchant." }, { "name": "GIFT_CARD_AVAILABLE_AMOUNT", "description": "When a Gift Card is a payment source, you can allow taking a partial payment\nby adding the `accept_partial_authorization` parameter in the request.\nHowever, taking such a partial payment does not work if your request also includes\n`tip_money`, `app_fee_money`, or both. Square declines such payments and returns\nthe `GIFT_CARD_AVAILABLE_AMOUNT` error.\nFor more information, see\n[CreatePayment errors (additional information)](https://developer.squareup.com/docs/payments-api/error-codes#createpayment-errors-additional-information)." }, { "name": "ACCOUNT_UNUSABLE", "description": "The account provided cannot carry out transactions." }, { "name": "BUYER_REFUSED_PAYMENT", "description": "Bank account rejected or was not authorized for the payment." }, { "name": "DELAYED_TRANSACTION_EXPIRED", "description": "The application tried to update a delayed-capture payment that has expired." }, { "name": "DELAYED_TRANSACTION_CANCELED", "description": "The application tried to cancel a delayed-capture payment that was already cancelled." }, { "name": "DELAYED_TRANSACTION_CAPTURED", "description": "The application tried to capture a delayed-capture payment that was already captured." }, { "name": "DELAYED_TRANSACTION_FAILED", "description": "The application tried to update a delayed-capture payment that failed." }, { "name": "CARD_TOKEN_EXPIRED", "description": "The provided card token (nonce) has expired." }, { "name": "CARD_TOKEN_USED", "description": "The provided card token (nonce) was already used to process the payment or refund." }, { "name": "AMOUNT_TOO_HIGH", "description": "The requested payment amount is too high for the provided payment source." }, { "name": "UNSUPPORTED_INSTRUMENT_TYPE", "description": "The API request references an unsupported instrument type." }, { "name": "REFUND_AMOUNT_INVALID", "description": "The requested refund amount exceeds the amount available to refund." }, { "name": "REFUND_ALREADY_PENDING", "description": "The payment already has a pending refund." }, { "name": "PAYMENT_NOT_REFUNDABLE", "description": "The payment is not refundable. For example, the payment has been disputed and is no longer eligible for\nrefunds." }, { "name": "REFUND_DECLINED", "description": "Request failed - The card issuer declined the refund." }, { "name": "INSUFFICIENT_PERMISSIONS_FOR_REFUND", "description": "The Square account does not have the permissions to process this refund." }, { "name": "INVALID_CARD_DATA", "description": "Generic error - the provided card data is invalid." }, { "name": "SOURCE_USED", "description": "The provided source id was already used to create a card." }, { "name": "SOURCE_EXPIRED", "description": "The provided source id has expired." }, { "name": "UNSUPPORTED_LOYALTY_REWARD_TIER", "description": "The referenced loyalty program reward tier is not supported.\nThis could happen if the reward tier created in a first party\napplication is incompatible with the Loyalty API." }, { "name": "LOCATION_MISMATCH", "description": "Generic error - the given location does not matching what is expected." }, { "name": "IDEMPOTENCY_KEY_REUSED", "description": "The provided idempotency key has already been used." }, { "name": "UNEXPECTED_VALUE", "description": "General error - the value provided was unexpected." }, { "name": "SANDBOX_NOT_SUPPORTED", "description": "The API request is not supported in sandbox." }, { "name": "INVALID_EMAIL_ADDRESS", "description": "The provided email address is invalid." }, { "name": "INVALID_PHONE_NUMBER", "description": "The provided phone number is invalid." }, { "name": "CHECKOUT_EXPIRED", "description": "The provided checkout URL has expired." }, { "name": "BAD_CERTIFICATE", "description": "Bad certificate." }, { "name": "INVALID_SQUARE_VERSION_FORMAT", "description": "The provided Square-Version is incorrectly formatted." }, { "name": "API_VERSION_INCOMPATIBLE", "description": "The provided Square-Version is incompatible with the requested action." }, { "name": "CARD_PRESENCE_REQUIRED", "description": "The transaction requires that a card be present." }, { "name": "UNSUPPORTED_SOURCE_TYPE", "description": "The API request references an unsupported source type." }, { "name": "CARD_MISMATCH", "description": "The provided card does not match what is expected." }, { "name": "PLAID_ERROR", "description": "Generic plaid error" }, { "name": "PLAID_ERROR_ITEM_LOGIN_REQUIRED", "description": "Plaid error - ITEM_LOGIN_REQUIRED" }, { "name": "PLAID_ERROR_RATE_LIMIT", "description": "Plaid error - RATE_LIMIT" }, { "name": "CARD_DECLINED", "description": "The card was declined." }, { "name": "VERIFY_CVV_FAILURE", "description": "The CVV could not be verified." }, { "name": "VERIFY_AVS_FAILURE", "description": "The AVS could not be verified." }, { "name": "CARD_DECLINED_CALL_ISSUER", "description": "The payment card was declined with a request\nfor the card holder to call the issuer." }, { "name": "CARD_DECLINED_VERIFICATION_REQUIRED", "description": "The payment card was declined with a request\nfor additional verification." }, { "name": "BAD_EXPIRATION", "description": "The card expiration date is either missing or\nincorrectly formatted." }, { "name": "CHIP_INSERTION_REQUIRED", "description": "The card issuer requires that the card be read\nusing a chip reader." }, { "name": "ALLOWABLE_PIN_TRIES_EXCEEDED", "description": "The card has exhausted its available pin entry\nretries set by the card issuer. Resolving the error typically requires the\ncard holder to contact the card issuer." }, { "name": "RESERVATION_DECLINED", "description": "The card issuer declined the refund." }, { "name": "UNKNOWN_BODY_PARAMETER", "description": "The body parameter is not recognized by the requested endpoint." }, { "name": "NOT_FOUND", "description": "Not Found - a general error occurred." }, { "name": "APPLE_PAYMENT_PROCESSING_CERTIFICATE_HASH_NOT_FOUND", "description": "Square could not find the associated Apple Pay certificate." }, { "name": "METHOD_NOT_ALLOWED", "description": "Method Not Allowed - a general error occurred." }, { "name": "NOT_ACCEPTABLE", "description": "Not Acceptable - a general error occurred." }, { "name": "REQUEST_TIMEOUT", "description": "Request Timeout - a general error occurred." }, { "name": "CONFLICT", "description": "Conflict - a general error occurred." }, { "name": "GONE", "description": "The target resource is no longer available and this\ncondition is likely to be permanent." }, { "name": "REQUEST_ENTITY_TOO_LARGE", "description": "Request Entity Too Large - a general error occurred." }, { "name": "UNSUPPORTED_MEDIA_TYPE", "description": "Unsupported Media Type - a general error occurred." }, { "name": "UNPROCESSABLE_ENTITY", "description": "Unprocessable Entity - a general error occurred." }, { "name": "RATE_LIMITED", "description": "Rate Limited - a general error occurred." }, { "name": "NOT_IMPLEMENTED", "description": "Not Implemented - a general error occurred." }, { "name": "BAD_GATEWAY", "description": "Bad Gateway - a general error occurred." }, { "name": "SERVICE_UNAVAILABLE", "description": "Service Unavailable - a general error occurred." }, { "name": "TEMPORARY_ERROR", "description": "A temporary internal error occurred. You can safely retry your call\nusing the same idempotency key." }, { "name": "GATEWAY_TIMEOUT", "description": "Gateway Timeout - a general error occurred." } ], "description": "Indicates the specific error that occurred during a request to a\nSquare API.", "x-release-status": "PUBLIC" }, "ExcludeStrategy": { "type": "string", "enum": [ "LEAST_EXPENSIVE", "MOST_EXPENSIVE" ], "x-enum-elements": [ { "name": "LEAST_EXPENSIVE", "description": "The least expensive matched products are excluded from the pricing. If\nthe pricing rule is set to exclude one product and multiple products in the\nmatch set qualify as least expensive, then one will be excluded at random.\n\nExcluding the least expensive product gives the best discount value to the buyer." }, { "name": "MOST_EXPENSIVE", "description": "The most expensive matched product is excluded from the pricing rule.\nIf multiple products have the same price and all qualify as least expensive,\none will be excluded at random.\n\nThis guarantees that the most expensive product is purchased at full price." } ], "description": "Indicates which products matched by a CatalogPricingRule\nwill be excluded if the pricing rule uses an exclude set.", "x-release-status": "BETA", "x-is-beta": true }, "FulfillmentDeliveryDetailsOrderFulfillmentDeliveryDetailsScheduleType": { "type": "string", "enum": [ "SCHEDULED", "ASAP" ], "x-enum-elements": [ { "name": "SCHEDULED", "description": "Indicates the fulfillment to deliver at a scheduled deliver time." }, { "name": "ASAP", "description": "Indicates that the fulfillment to deliver as soon as possible and should be prepared\nimmediately." } ], "description": "The schedule type of the delivery fulfillment.", "x-release-status": "BETA", "x-is-beta": true }, "FulfillmentFulfillmentLineItemApplication": { "type": "string", "enum": [ "ALL", "ENTRY_LIST" ], "x-enum-elements": [ { "name": "ALL", "description": "If `ALL`, `entries` must be unset." }, { "name": "ENTRY_LIST", "description": "If `ENTRY_LIST`, supply a list of `entries`." } ], "description": "The `line_item_application` describes what order line items this fulfillment applies\nto. It can be `ALL` or `ENTRY_LIST` with a supplied list of fulfillment entries.", "x-release-status": "BETA", "x-is-beta": true }, "FulfillmentPickupDetailsScheduleType": { "type": "string", "enum": [ "SCHEDULED", "ASAP" ], "x-enum-elements": [ { "name": "SCHEDULED", "description": "Indicates that the fulfillment will be picked up at a scheduled pickup time." }, { "name": "ASAP", "description": "Indicates that the fulfillment will be picked up as soon as possible and\nshould be prepared immediately." } ], "description": "The schedule type of the pickup fulfillment.", "x-release-status": "PUBLIC" }, "FulfillmentState": { "type": "string", "enum": [ "PROPOSED", "RESERVED", "PREPARED", "COMPLETED", "CANCELED", "FAILED" ], "x-enum-elements": [ { "name": "PROPOSED", "description": "Indicates that the fulfillment has been proposed." }, { "name": "RESERVED", "description": "Indicates that the fulfillment has been reserved." }, { "name": "PREPARED", "description": "Indicates that the fulfillment has been prepared." }, { "name": "COMPLETED", "description": "Indicates that the fulfillment was successfully completed." }, { "name": "CANCELED", "description": "Indicates that the fulfillment was canceled." }, { "name": "FAILED", "description": "Indicates that the fulfillment failed to be completed, but was not explicitly\ncanceled." } ], "description": "The current state of this fulfillment.", "x-release-status": "PUBLIC" }, "FulfillmentType": { "type": "string", "enum": [ "PICKUP", "SHIPMENT", "DELIVERY" ], "x-enum-elements": [ { "name": "PICKUP", "description": "A recipient to pick up the fulfillment from a physical [location](https://developer.squareup.com/reference/square_2024-10-17/objects/Location)." }, { "name": "SHIPMENT", "description": "A shipping carrier to ship the fulfillment." }, { "name": "DELIVERY", "description": "A courier to deliver the fulfillment." } ], "description": "The type of fulfillment.", "x-release-status": "PUBLIC" }, "GiftCardActivityAdjustDecrementReason": { "type": "string", "enum": [ "SUSPICIOUS_ACTIVITY", "BALANCE_ACCIDENTALLY_INCREASED", "SUPPORT_ISSUE", "PURCHASE_WAS_REFUNDED" ], "x-enum-elements": [ { "name": "SUSPICIOUS_ACTIVITY", "description": "The balance was decreased because the seller detected suspicious or fraudulent activity\non the gift card." }, { "name": "BALANCE_ACCIDENTALLY_INCREASED", "description": "The balance was decreased to reverse an unintentional balance increase." }, { "name": "SUPPORT_ISSUE", "description": "The balance was decreased to accommodate support issues." }, { "name": "PURCHASE_WAS_REFUNDED", "description": "The balance was decreased because the order used to purchase or reload the\ngift card was refunded." } ], "description": "Indicates the reason for deducting money from a [gift card](https://developer.squareup.com/reference/square_2024-10-17/objects/GiftCard).", "x-release-status": "PUBLIC" }, "GiftCardActivityAdjustIncrementReason": { "type": "string", "enum": [ "COMPLIMENTARY", "SUPPORT_ISSUE", "TRANSACTION_VOIDED" ], "x-enum-elements": [ { "name": "COMPLIMENTARY", "description": "The seller gifted a complimentary gift card balance increase." }, { "name": "SUPPORT_ISSUE", "description": "The seller increased the gift card balance \nto accommodate support issues." }, { "name": "TRANSACTION_VOIDED", "description": "The transaction is voided." } ], "description": "Indicates the reason for adding money to a [gift card](https://developer.squareup.com/reference/square_2024-10-17/objects/GiftCard).", "x-release-status": "PUBLIC" }, "GiftCardActivityBlockReason": { "type": "string", "enum": [ "CHARGEBACK_BLOCK" ], "x-enum-elements": [ { "name": "CHARGEBACK_BLOCK", "description": "The gift card is blocked because the buyer initiated a chargeback on the gift card purchase." } ], "description": "Indicates the reason for blocking a [gift card](https://developer.squareup.com/reference/square_2024-10-17/objects/GiftCard).", "x-release-status": "PUBLIC" }, "GiftCardActivityClearBalanceReason": { "type": "string", "enum": [ "SUSPICIOUS_ACTIVITY", "REUSE_GIFTCARD", "UNKNOWN_REASON" ], "x-enum-elements": [ { "name": "SUSPICIOUS_ACTIVITY", "description": "The seller suspects suspicious activity." }, { "name": "REUSE_GIFTCARD", "description": "The seller cleared the balance to reuse the gift card." }, { "name": "UNKNOWN_REASON", "description": "The gift card balance was cleared for an unknown reason.\n\nThis reason is read-only and cannot be used to create a `CLEAR_BALANCE` activity using the Gift Card Activities API." } ], "description": "Indicates the reason for clearing the balance of a [gift card](https://developer.squareup.com/reference/square_2024-10-17/objects/GiftCard).", "x-release-status": "PUBLIC" }, "GiftCardActivityDeactivateReason": { "type": "string", "enum": [ "SUSPICIOUS_ACTIVITY", "UNKNOWN_REASON", "CHARGEBACK_DEACTIVATE" ], "x-enum-elements": [ { "name": "SUSPICIOUS_ACTIVITY", "description": "The seller suspects suspicious activity." }, { "name": "UNKNOWN_REASON", "description": "The gift card was deactivated for an unknown reason.\n\nThis reason is read-only and cannot be used to create a `DEACTIVATE` activity using the Gift Card Activities API." }, { "name": "CHARGEBACK_DEACTIVATE", "description": "A chargeback on the gift card purchase (or the gift card load) was ruled in favor of the buyer.\n\nThis reason is read-only and cannot be used to create a `DEACTIVATE` activity using the Gift Card Activities API." } ], "description": "Indicates the reason for deactivating a [gift card](https://developer.squareup.com/reference/square_2024-10-17/objects/GiftCard).", "x-release-status": "PUBLIC" }, "GiftCardActivityRedeemStatus": { "type": "string", "enum": [ "PENDING", "COMPLETED", "CANCELED" ], "x-enum-elements": [ { "name": "PENDING", "description": "The gift card redemption is pending. `PENDING` is a temporary status that applies when a \ngift card is redeemed from Square Point of Sale or another Square product. A `PENDING` status is updated to \n`COMPLETED` if the payment is captured or `CANCELED` if the authorization is voided." }, { "name": "COMPLETED", "description": "The gift card redemption is completed." }, { "name": "CANCELED", "description": "The gift card redemption is canceled. A redemption is canceled if the authorization \non the gift card is voided." } ], "description": "Indicates the status of a [gift card](https://developer.squareup.com/reference/square_2024-10-17/objects/GiftCard) redemption. This status is relevant only for\nredemptions made from Square products (such as Square Point of Sale) because Square products use a \ntwo-state process. Gift cards redeemed using the Gift Card Activities API always have a `COMPLETED` status.", "x-release-status": "PUBLIC" }, "GiftCardActivityType": { "type": "string", "enum": [ "ACTIVATE", "LOAD", "REDEEM", "CLEAR_BALANCE", "DEACTIVATE", "ADJUST_INCREMENT", "ADJUST_DECREMENT", "REFUND", "UNLINKED_ACTIVITY_REFUND", "IMPORT", "BLOCK", "UNBLOCK", "IMPORT_REVERSAL", "TRANSFER_BALANCE_FROM", "TRANSFER_BALANCE_TO" ], "x-enum-elements": [ { "name": "ACTIVATE", "description": "Activated a gift card with a balance. When a gift card is activated, Square changes \nthe gift card state from `PENDING` to `ACTIVE`. A gift card must be in the `ACTIVE` state \nto be used for other balance-changing activities." }, { "name": "LOAD", "description": "Loaded a gift card with additional funds." }, { "name": "REDEEM", "description": "Redeemed a gift card for a purchase." }, { "name": "CLEAR_BALANCE", "description": "Set the balance of a gift card to zero." }, { "name": "DEACTIVATE", "description": "Permanently blocked a gift card from balance-changing activities." }, { "name": "ADJUST_INCREMENT", "description": "Added money to a gift card outside of a typical `ACTIVATE`, `LOAD`, or `REFUND` activity flow." }, { "name": "ADJUST_DECREMENT", "description": "Deducted money from a gift card outside of a typical `REDEEM` activity flow." }, { "name": "REFUND", "description": "Added money to a gift card from a refunded transaction. A `REFUND` activity might be linked to \na Square payment, depending on how the payment and refund are processed. For example:\n- A payment processed by Square can be refunded to a `PENDING` or `ACTIVE` gift card using the Square\nSeller Dashboard, Square Point of Sale, or Refunds API.\n- A payment processed using a custom processing system can be refunded to the same gift card." }, { "name": "UNLINKED_ACTIVITY_REFUND", "description": "Added money to a gift card from a refunded transaction that was processed using a custom payment\nprocessing system and not linked to the gift card." }, { "name": "IMPORT", "description": "Imported a third-party gift card with a balance. `IMPORT` activities are managed \nby Square and cannot be created using the Gift Card Activities API." }, { "name": "BLOCK", "description": "Temporarily blocked a gift card from balance-changing activities. `BLOCK` activities \nare managed by Square and cannot be created using the Gift Card Activities API." }, { "name": "UNBLOCK", "description": "Unblocked a gift card, which enables it to resume balance-changing activities. `UNBLOCK` \nactivities are managed by Square and cannot be created using the Gift Card Activities API." }, { "name": "IMPORT_REVERSAL", "description": "Reversed the import of a third-party gift card, which sets the gift card state to \n`PENDING` and clears the balance. `IMPORT_REVERSAL` activities are managed by Square and \ncannot be created using the Gift Card Activities API." }, { "name": "TRANSFER_BALANCE_FROM", "description": "Deducted money from a gift card as the result of a transfer to the balance of another gift card.\n`TRANSFER_BALANCE_FROM` activities are managed by Square and cannot be created using the Gift Card Activities API." }, { "name": "TRANSFER_BALANCE_TO", "description": "Added money to a gift card as the result of a transfer from the balance of another gift card.\n`TRANSFER_BALANCE_TO` activities are managed by Square and cannot be created using the Gift Card Activities API." } ], "description": "Indicates the type of [gift card activity](https://developer.squareup.com/reference/square_2024-10-17/objects/GiftCardActivity).", "x-release-status": "PUBLIC" }, "GiftCardActivityUnblockReason": { "type": "string", "enum": [ "CHARGEBACK_UNBLOCK" ], "x-enum-elements": [ { "name": "CHARGEBACK_UNBLOCK", "description": "The gift card is unblocked because a chargeback was ruled in favor of the seller." } ], "description": "Indicates the reason for unblocking a [gift card](https://developer.squareup.com/reference/square_2024-10-17/objects/GiftCard).", "x-release-status": "PUBLIC" }, "GiftCardGANSource": { "type": "string", "enum": [ "SQUARE", "OTHER" ], "x-enum-elements": [ { "name": "SQUARE", "description": "The GAN is generated by Square." }, { "name": "OTHER", "description": "The GAN is provided by a non-Square system. For more information, see \n[Custom GANs](https://developer.squareup.com/docs/gift-cards/using-gift-cards-api#custom-gans) or \n[Third-party gift cards](https://developer.squareup.com/docs/gift-cards/using-gift-cards-api#third-party-gift-cards)." } ], "description": "Indicates the source that generated the gift card \naccount number (GAN).", "x-release-status": "PUBLIC" }, "GiftCardStatus": { "type": "string", "enum": [ "ACTIVE", "DEACTIVATED", "BLOCKED", "PENDING" ], "x-enum-elements": [ { "name": "ACTIVE", "description": "The gift card is active and can be used as a payment source." }, { "name": "DEACTIVATED", "description": "Any activity that changes the gift card balance is permanently forbidden." }, { "name": "BLOCKED", "description": "Any activity that changes the gift card balance is temporarily forbidden." }, { "name": "PENDING", "description": "The gift card is pending activation.\nThis is the initial state when a gift card is created. Typically, you\u0027ll call\n[CreateGiftCardActivity](https://developer.squareup.com/reference/square_2024-10-17/gift-card-activities-api/create-gift-card-activity) to create an\n`ACTIVATE` activity that activates the gift card with an initial balance before first use." } ], "description": "Indicates the gift card state.", "x-release-status": "PUBLIC" }, "GiftCardType": { "type": "string", "enum": [ "PHYSICAL", "DIGITAL" ], "x-enum-elements": [ { "name": "PHYSICAL", "description": "A plastic gift card." }, { "name": "DIGITAL", "description": "A digital gift card." } ], "description": "Indicates the gift card type.", "x-release-status": "PUBLIC" }, "InventoryAlertType": { "type": "string", "enum": [ "NONE", "LOW_QUANTITY" ], "x-enum-elements": [ { "name": "NONE", "description": "The variation does not display an alert." }, { "name": "LOW_QUANTITY", "description": "The variation generates an alert when its quantity is low." } ], "description": "Indicates whether Square should alert the merchant when the inventory quantity of a CatalogItemVariation is low.", "x-release-status": "PUBLIC" }, "InventoryChangeType": { "type": "string", "enum": [ "PHYSICAL_COUNT", "ADJUSTMENT", "TRANSFER" ], "x-enum-elements": [ { "name": "PHYSICAL_COUNT", "description": "The change occurred as part of a physical count update." }, { "name": "ADJUSTMENT", "description": "The change occurred as part of the normal lifecycle of goods\n(e.g., as an inventory adjustment)." }, { "name": "TRANSFER", "description": "The change occurred as part of an inventory transfer." } ], "description": "Indicates how the inventory change was applied to a tracked product quantity.", "x-release-status": "PUBLIC" }, "InventoryState": { "type": "string", "enum": [ "CUSTOM", "IN_STOCK", "SOLD", "RETURNED_BY_CUSTOMER", "RESERVED_FOR_SALE", "SOLD_ONLINE", "ORDERED_FROM_VENDOR", "RECEIVED_FROM_VENDOR", "IN_TRANSIT_TO", "NONE", "WASTE", "UNLINKED_RETURN", "COMPOSED", "DECOMPOSED", "SUPPORTED_BY_NEWER_VERSION", "IN_TRANSIT" ], "x-enum-elements": [ { "name": "CUSTOM", "description": "The related quantity of items are in a custom state. **READ-ONLY**:\nthe Inventory API cannot move quantities to or from this state." }, { "name": "IN_STOCK", "description": "The related quantity of items are on hand and available for sale." }, { "name": "SOLD", "description": "The related quantity of items were sold as part of an itemized\ntransaction. Quantities in the `SOLD` state are no longer tracked." }, { "name": "RETURNED_BY_CUSTOMER", "description": "The related quantity of items were returned through the Square Point\nof Sale application, but are not yet available for sale. **READ-ONLY**:\nthe Inventory API cannot move quantities to or from this state." }, { "name": "RESERVED_FOR_SALE", "description": "The related quantity of items are on hand, but not currently\navailable for sale. **READ-ONLY**: the Inventory API cannot move\nquantities to or from this state." }, { "name": "SOLD_ONLINE", "description": "The related quantity of items were sold online. **READ-ONLY**: the\nInventory API cannot move quantities to or from this state." }, { "name": "ORDERED_FROM_VENDOR", "description": "The related quantity of items were ordered from a vendor but not yet\nreceived. **READ-ONLY**: the Inventory API cannot move quantities to or\nfrom this state." }, { "name": "RECEIVED_FROM_VENDOR", "description": "The related quantity of items were received from a vendor but are\nnot yet available for sale. **READ-ONLY**: the Inventory API cannot move\nquantities to or from this state." }, { "name": "IN_TRANSIT_TO", "description": "Replaced by `IN_TRANSIT` to represent quantities\nof items that are in transit between locations." }, { "name": "NONE", "description": "A placeholder indicating that the related quantity of items are not\ncurrently tracked in Square. Transferring quantities from the `NONE` state\nto a tracked state (e.g., `IN_STOCK`) introduces stock into the system." }, { "name": "WASTE", "description": "The related quantity of items are lost or damaged and cannot be\nsold." }, { "name": "UNLINKED_RETURN", "description": "The related quantity of items were returned but not linked to a\nprevious transaction. Unlinked returns are not tracked in Square.\nTransferring a quantity from `UNLINKED_RETURN` to a tracked state (e.g.,\n`IN_STOCK`) introduces new stock into the system." }, { "name": "COMPOSED", "description": "The related quantity of items that are part of a composition consisting one or more components." }, { "name": "DECOMPOSED", "description": "The related quantity of items that are part of a component." }, { "name": "SUPPORTED_BY_NEWER_VERSION", "description": "This state is not supported by this version of the Square API. We recommend that you upgrade the client to use the appropriate version of the Square API supporting this state." }, { "name": "IN_TRANSIT", "description": "The related quantity of items are in transit between locations. **READ-ONLY:** the Inventory API cannot currently be used to move quantities to or from this inventory state." } ], "description": "Indicates the state of a tracked item quantity in the lifecycle of goods.", "x-release-status": "PUBLIC" }, "InvoiceAutomaticPaymentSource": { "type": "string", "enum": [ "NONE", "CARD_ON_FILE", "BANK_ON_FILE" ], "x-enum-elements": [ { "name": "NONE", "description": "An automatic payment is not configured for the payment request." }, { "name": "CARD_ON_FILE", "description": "Use a card on file as the automatic payment method. On the due date, Square charges the card\nfor the amount of the payment request.\n\nFor `CARD_ON_FILE` payments, the invoice delivery method must be `EMAIL` and `card_id` must be\nspecified for the payment request before the invoice can be published." }, { "name": "BANK_ON_FILE", "description": "Use a bank account on file as the automatic payment method. On the due date, Square charges the bank\naccount for the amount of the payment request if the buyer has approved the payment. The buyer receives a\nrequest to approve the payment when the invoice is sent or the invoice is updated.\n\nThis payment method applies only to invoices that sellers create in the Seller Dashboard or other\nSquare product. The bank account is provided by the customer during the payment flow. \n\nYou cannot set `BANK_ON_FILE` as a payment method using the Invoices API, but you can change a `BANK_ON_FILE`\npayment method to `NONE` or `CARD_ON_FILE`. For `BANK_ON_FILE` payments, the invoice delivery method must be `EMAIL`." } ], "description": "Indicates the automatic payment method for an [invoice payment request](https://developer.squareup.com/reference/square_2024-10-17/objects/InvoicePaymentRequest).", "x-release-status": "PUBLIC" }, "InvoiceCustomFieldPlacement": { "type": "string", "enum": [ "ABOVE_LINE_ITEMS", "BELOW_LINE_ITEMS" ], "x-enum-elements": [ { "name": "ABOVE_LINE_ITEMS", "description": "Render the custom field above the invoice line items." }, { "name": "BELOW_LINE_ITEMS", "description": "Render the custom field below the invoice line items." } ], "description": "Indicates where to render a custom field on the Square-hosted invoice page and in emailed or PDF \ncopies of the invoice.", "x-release-status": "PUBLIC" }, "InvoiceDeliveryMethod": { "type": "string", "enum": [ "EMAIL", "SHARE_MANUALLY", "SMS" ], "x-enum-elements": [ { "name": "EMAIL", "description": "Directs Square to send invoices, reminders, and receipts to the customer using email." }, { "name": "SHARE_MANUALLY", "description": "Directs Square to take no action on the invoice. In this case, the seller\nor application developer follows up with the customer for payment. For example,\na seller might collect a payment in the Seller Dashboard or Point of Sale (POS) application.\nThe seller might also share the URL of the Square-hosted invoice page (`public_url`) with the customer to request payment." }, { "name": "SMS", "description": "Directs Square to send invoices and receipts to the customer using SMS (text message).\n\nYou cannot set `SMS` as a delivery method using the Invoices API, but you can change an `SMS` delivery method to `EMAIL` or `SHARE_MANUALLY`." } ], "description": "Indicates how Square delivers the [invoice](https://developer.squareup.com/reference/square_2024-10-17/objects/Invoice) to the customer.", "x-release-status": "PUBLIC" }, "InvoicePaymentReminderStatus": { "type": "string", "enum": [ "PENDING", "NOT_APPLICABLE", "SENT" ], "x-enum-elements": [ { "name": "PENDING", "description": "The reminder will be sent on the `relative_scheduled_date` (if the invoice is published)." }, { "name": "NOT_APPLICABLE", "description": "The reminder is not applicable and is not sent. The following are examples\nof when reminders are not applicable and are not sent:\n- You schedule a reminder to be sent before the invoice is published.\n- The invoice is configured with multiple payment requests and a payment request reminder\nis configured to be sent after the next payment request `due_date`.\n- Two reminders (for different payment requests) are configured to be sent on the\nsame date. Therefore, only one reminder is sent.\n- You configure a reminder to be sent on the date that the invoice is scheduled to be sent.\n- The payment request is already paid.\n- The invoice status is `CANCELED` or `FAILED`." }, { "name": "SENT", "description": "The reminder is sent." } ], "description": "The status of a payment request reminder.", "x-release-status": "PUBLIC" }, "InvoiceRequestMethod": { "type": "string", "enum": [ "EMAIL", "CHARGE_CARD_ON_FILE", "SHARE_MANUALLY", "CHARGE_BANK_ON_FILE", "SMS", "SMS_CHARGE_CARD_ON_FILE", "SMS_CHARGE_BANK_ON_FILE" ], "x-enum-elements": [ { "name": "EMAIL", "description": "Directs Square to send invoices, reminders, and receipts to the customer using email.\nSquare sends the invoice after it is published (either immediately or at the `scheduled_at`\ntime, if specified in the [invoice](https://developer.squareup.com/reference/square_2024-10-17/objects/Invoice))." }, { "name": "CHARGE_CARD_ON_FILE", "description": "Directs Square to charge the card on file on the `due_date` specified in the payment request\nand to use email to send invoices, reminders, and receipts." }, { "name": "SHARE_MANUALLY", "description": "Directs Square to take no specific action on the invoice. In this case, the seller \n(or the application developer) follows up with the customer for payment. For example, \na seller might collect a payment in the Seller Dashboard or use the Point of Sale (POS) application. \nThe seller might also share the URL of the Square-hosted invoice page (`public_url`) with the customer requesting payment." }, { "name": "CHARGE_BANK_ON_FILE", "description": "Directs Square to charge the customer\u0027s 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](https://developer.squareup.com/reference/square_2024-10-17/objects/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\u0027s 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\u0027s 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", "x-is-deprecated": 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" }, "InvoiceSortField": { "type": "string", "enum": [ "INVOICE_SORT_DATE" ], "x-enum-elements": [ { "name": "INVOICE_SORT_DATE", "description": "The field works as follows:\n\n- If the invoice is a draft, it uses the invoice `created_at` date.\n- If the invoice is scheduled for publication, it uses the `scheduled_at` date.\n- If the invoice is published, it uses the invoice publication date." } ], "description": "The field to use for sorting.", "x-release-status": "PUBLIC" }, "InvoiceStatus": { "type": "string", "enum": [ "DRAFT", "UNPAID", "SCHEDULED", "PARTIALLY_PAID", "PAID", "PARTIALLY_REFUNDED", "REFUNDED", "CANCELED", "FAILED", "PAYMENT_PENDING" ], "x-enum-elements": [ { "name": "DRAFT", "description": "The invoice is a draft. You must publish a draft invoice before Square can process it.\nA draft invoice has no `public_url`, so it is not available to customers." }, { "name": "UNPAID", "description": "The invoice is published but not yet paid." }, { "name": "SCHEDULED", "description": "The invoice is scheduled to be processed. On the scheduled date,\nSquare sends the invoice, initiates an automatic payment, or takes no action, depending on\nthe delivery method and payment request settings. Square also sets the invoice status to the\nappropriate state: `UNPAID`, `PAID`, `PARTIALLY_PAID`, or `PAYMENT_PENDING`." }, { "name": "PARTIALLY_PAID", "description": "A partial payment is received for the invoice." }, { "name": "PAID", "description": "The customer paid the invoice in full." }, { "name": "PARTIALLY_REFUNDED", "description": "The invoice is paid (or partially paid) and some but not all the amount paid is\nrefunded." }, { "name": "REFUNDED", "description": "The full amount that the customer paid for the invoice is refunded." }, { "name": "CANCELED", "description": "The invoice is canceled. Square no longer requests payments from the customer.\nThe `public_url` page remains and is accessible, but it displays the invoice\nas canceled and does not accept payment." }, { "name": "FAILED", "description": "Square canceled the invoice due to suspicious activity." }, { "name": "PAYMENT_PENDING", "description": "A payment on the invoice was initiated but has not yet been processed.\n\nWhen in this state, invoices cannot be updated and other payments cannot be initiated." } ], "description": "Indicates the status of an invoice.", "x-release-status": "PUBLIC" }, "JobAssignmentPayType": { "type": "string", "enum": [ "NONE", "HOURLY", "SALARY" ], "x-enum-elements": [ { "name": "NONE", "description": "The job does not have a defined pay type." }, { "name": "HOURLY", "description": "The job pays an hourly rate." }, { "name": "SALARY", "description": "The job pays an annual salary." } ], "description": "Enumerates the possible pay types that a job can be assigned.", "x-release-status": "PUBLIC" }, "LocationCapability": { "type": "string", "enum": [ "CREDIT_CARD_PROCESSING", "AUTOMATIC_TRANSFERS", "UNLINKED_REFUNDS" ], "x-enum-elements": [ { "name": "CREDIT_CARD_PROCESSING", "description": "The capability to process credit card transactions with Square." }, { "name": "AUTOMATIC_TRANSFERS", "description": "The capability to receive automatic transfers from Square." }, { "name": "UNLINKED_REFUNDS", "description": "The capability to process unlinked refunds with Square." } ], "description": "The capabilities a location might have.", "x-release-status": "PUBLIC" }, "LocationStatus": { "type": "string", "enum": [ "ACTIVE", "INACTIVE" ], "x-enum-elements": [ { "name": "ACTIVE", "description": "A location that is active for business." }, { "name": "INACTIVE", "description": "A location that is not active for business. Inactive locations provide historical\ninformation. Hide inactive locations unless the user has requested to see them." } ], "description": "A location\u0027s status.", "x-release-status": "PUBLIC" }, "LocationType": { "type": "string", "enum": [ "PHYSICAL", "MOBILE" ], "x-enum-elements": [ { "name": "PHYSICAL", "description": "A place of business with a physical location." }, { "name": "MOBILE", "description": "A place of business that is mobile, such as a food truck or online store." } ], "description": "A location\u0027s type.", "x-release-status": "PUBLIC" }, "LoyaltyAccountMappingType": { "type": "string", "enum": [ "PHONE" ], "x-enum-elements": [ { "name": "PHONE", "description": "The loyalty account is mapped by phone." } ], "description": "The type of mapping.", "x-release-status": "PUBLIC" }, "LoyaltyEventSource": { "type": "string", "enum": [ "SQUARE", "LOYALTY_API" ], "x-enum-elements": [ { "name": "SQUARE", "description": "The event is generated by the Square Point of Sale (POS)." }, { "name": "LOYALTY_API", "description": "The event is generated by something other than the Square Point of Sale that used the Loyalty API." } ], "description": "Defines whether the event was generated by the Square Point of Sale.", "x-release-status": "PUBLIC" }, "LoyaltyEventType": { "type": "string", "enum": [ "ACCUMULATE_POINTS", "CREATE_REWARD", "REDEEM_REWARD", "DELETE_REWARD", "ADJUST_POINTS", "EXPIRE_POINTS", "OTHER", "ACCUMULATE_PROMOTION_POINTS" ], "x-enum-elements": [ { "name": "ACCUMULATE_POINTS", "description": "Points are added to a loyalty account for a purchase that\nqualified for points based on an [accrual rule](https://developer.squareup.com/reference/square_2024-10-17/objects/LoyaltyProgramAccrualRule)." }, { "name": "CREATE_REWARD", "description": "A [loyalty reward](https://developer.squareup.com/reference/square_2024-10-17/objects/LoyaltyReward) is created." }, { "name": "REDEEM_REWARD", "description": "A loyalty reward is redeemed." }, { "name": "DELETE_REWARD", "description": "A loyalty reward is deleted." }, { "name": "ADJUST_POINTS", "description": "Loyalty points are manually adjusted." }, { "name": "EXPIRE_POINTS", "description": "Loyalty points are expired according to the \nexpiration policy of the loyalty program." }, { "name": "OTHER", "description": "Some other loyalty event occurred." }, { "name": "ACCUMULATE_PROMOTION_POINTS", "description": " Points are added to a loyalty account for a purchase that\nqualified for a [loyalty promotion](https://developer.squareup.com/reference/square_2024-10-17/objects/LoyaltyPromotion)." } ], "description": "The type of the loyalty event.", "x-release-status": "PUBLIC" }, "LoyaltyProgramAccrualRuleTaxMode": { "type": "string", "enum": [ "BEFORE_TAX", "AFTER_TAX" ], "x-enum-elements": [ { "name": "BEFORE_TAX", "description": "Exclude taxes from the purchase amount used for loyalty points accrual." }, { "name": "AFTER_TAX", "description": "Include taxes in the purchase amount used for loyalty points accrual." } ], "description": "Indicates how taxes should be treated when calculating the purchase amount used for loyalty points accrual. \nThis setting applies only to `SPEND` accrual rules or `VISIT` accrual rules that have a minimum spend requirement.", "x-release-status": "PUBLIC" }, "LoyaltyProgramAccrualRuleType": { "type": "string", "enum": [ "VISIT", "SPEND", "ITEM_VARIATION", "CATEGORY" ], "x-enum-elements": [ { "name": "VISIT", "description": "A visit-based accrual rule. A buyer earns points for each visit. \nYou can specify the minimum purchase required." }, { "name": "SPEND", "description": "A spend-based accrual rule. A buyer earns points based on the amount \nspent." }, { "name": "ITEM_VARIATION", "description": "An accrual rule based on an item variation. For example, accrue \npoints for purchasing a coffee." }, { "name": "CATEGORY", "description": "An accrual rule based on an item category. For example, accrue points \nfor purchasing any item in the \"hot drink\" category: coffee, tea, or hot cocoa." } ], "description": "The type of the accrual rule that defines how buyers can earn points.", "x-release-status": "PUBLIC" }, "LoyaltyProgramRewardDefinitionScope": { "type": "string", "enum": [ "ORDER", "ITEM_VARIATION", "CATEGORY" ], "x-enum-elements": [ { "name": "ORDER", "description": "The discount applies to the entire order." }, { "name": "ITEM_VARIATION", "description": "The discount applies only to specific item variations." }, { "name": "CATEGORY", "description": "The discount applies only to items in the given categories." } ], "description": "Indicates the scope of the reward tier. DEPRECATED at version 2020-12-16. Discount details\nare now defined using a catalog pricing rule and other catalog objects. For more information, see\n[Getting discount details for a reward tier](https://developer.squareup.com/docs/loyalty-api/loyalty-rewards#get-discount-details).", "x-release-status": "DEPRECATED", "x-is-deprecated": true }, "LoyaltyProgramRewardDefinitionType": { "type": "string", "enum": [ "FIXED_AMOUNT", "FIXED_PERCENTAGE" ], "x-enum-elements": [ { "name": "FIXED_AMOUNT", "description": "The fixed amount discounted." }, { "name": "FIXED_PERCENTAGE", "description": "The fixed percentage discounted." } ], "description": "The type of discount the reward tier offers. DEPRECATED at version 2020-12-16. Discount details\nare now defined using a catalog pricing rule and other catalog objects. For more information, see\n[Getting discount details for a reward tier](https://developer.squareup.com/docs/loyalty-api/loyalty-rewards#get-discount-details).", "x-release-status": "DEPRECATED", "x-is-deprecated": true }, "LoyaltyProgramStatus": { "type": "string", "enum": [ "INACTIVE", "ACTIVE" ], "x-enum-elements": [ { "name": "INACTIVE", "description": "The loyalty program does not have an active subscription. \nLoyalty API requests fail." }, { "name": "ACTIVE", "description": "The program is fully functional. The program has an active subscription." } ], "description": "Indicates whether the program is currently active.", "x-release-status": "PUBLIC" }, "LoyaltyPromotionIncentiveType": { "type": "string", "enum": [ "POINTS_MULTIPLIER", "POINTS_ADDITION" ], "x-enum-elements": [ { "name": "POINTS_MULTIPLIER", "description": "Multiply the number of points earned from the base loyalty program.\nFor example, \"Earn double points.\"" }, { "name": "POINTS_ADDITION", "description": "Add a specified number of points to those earned from the base loyalty program.\nFor example, \"Earn 10 additional points.\"" } ], "description": "Indicates the type of points incentive for a [loyalty promotion](https://developer.squareup.com/reference/square_2024-10-17/objects/LoyaltyPromotion),\nwhich is used to determine how buyers can earn points from the promotion.", "x-release-status": "PUBLIC" }, "LoyaltyPromotionStatus": { "type": "string", "enum": [ "ACTIVE", "ENDED", "CANCELED", "SCHEDULED" ], "x-enum-elements": [ { "name": "ACTIVE", "description": "The loyalty promotion is currently active. Buyers can earn points for purchases\nthat meet the promotion conditions, such as the promotion\u0027s `available_time`." }, { "name": "ENDED", "description": "The loyalty promotion has ended because the specified `end_date` was reached.\n`ENDED` is a terminal status." }, { "name": "CANCELED", "description": "The loyalty promotion was canceled. `CANCELED` is a terminal status." }, { "name": "SCHEDULED", "description": "The loyalty promotion is scheduled to start in the future. Square changes the\npromotion status to `ACTIVE` when the `start_date` is reached." } ], "description": "Indicates the status of a [loyalty promotion](https://developer.squareup.com/reference/square_2024-10-17/objects/LoyaltyPromotion).", "x-release-status": "PUBLIC" }, "LoyaltyPromotionTriggerLimitInterval": { "type": "string", "enum": [ "ALL_TIME", "DAY" ], "x-enum-elements": [ { "name": "ALL_TIME", "description": "The limit applies to the entire time that the promotion is active. For example, if `times`\nis set to 1 and `time_period` is set to `ALL_TIME`, a buyer can earn promotion points a maximum\nof one time during the promotion." }, { "name": "DAY", "description": "The limit applies per day, according to the `available_time` schedule specified for the promotion.\nFor example, if the `times` field of the trigger limit is set to 1, a buyer can trigger the promotion\na maximum of once per day." } ], "description": "Indicates the time period that the [trigger limit](https://developer.squareup.com/reference/square_2024-10-17/objects/LoyaltyPromotionTriggerLimit) applies to,\nwhich is used to determine the number of times a buyer can earn points for a [loyalty promotion](https://developer.squareup.com/reference/square_2024-10-17/objects/LoyaltyPromotion).", "x-release-status": "PUBLIC" }, "LoyaltyRewardStatus": { "type": "string", "enum": [ "ISSUED", "REDEEMED", "DELETED" ], "x-enum-elements": [ { "name": "ISSUED", "description": "The reward is issued." }, { "name": "REDEEMED", "description": "The reward is redeemed." }, { "name": "DELETED", "description": "The reward is deleted." } ], "description": "The status of the loyalty reward.", "x-release-status": "PUBLIC" }, "MeasurementUnitArea": { "type": "string", "enum": [ "IMPERIAL_ACRE", "IMPERIAL_SQUARE_INCH", "IMPERIAL_SQUARE_FOOT", "IMPERIAL_SQUARE_YARD", "IMPERIAL_SQUARE_MILE", "METRIC_SQUARE_CENTIMETER", "METRIC_SQUARE_METER", "METRIC_SQUARE_KILOMETER" ], "x-enum-elements": [ { "name": "IMPERIAL_ACRE", "description": "The area is measured in acres." }, { "name": "IMPERIAL_SQUARE_INCH", "description": "The area is measured in square inches." }, { "name": "IMPERIAL_SQUARE_FOOT", "description": "The area is measured in square feet." }, { "name": "IMPERIAL_SQUARE_YARD", "description": "The area is measured in square yards." }, { "name": "IMPERIAL_SQUARE_MILE", "description": "The area is measured in square miles." }, { "name": "METRIC_SQUARE_CENTIMETER", "description": "The area is measured in square centimeters." }, { "name": "METRIC_SQUARE_METER", "description": "The area is measured in square meters." }, { "name": "METRIC_SQUARE_KILOMETER", "description": "The area is measured in square kilometers." } ], "description": "Unit of area used to measure a quantity.", "x-release-status": "PUBLIC" }, "MeasurementUnitGeneric": { "type": "string", "enum": [ "UNIT" ], "x-enum-elements": [ { "name": "UNIT", "description": "The generic unit." } ], "description": "", "x-release-status": "PUBLIC" }, "MeasurementUnitLength": { "type": "string", "enum": [ "IMPERIAL_INCH", "IMPERIAL_FOOT", "IMPERIAL_YARD", "IMPERIAL_MILE", "METRIC_MILLIMETER", "METRIC_CENTIMETER", "METRIC_METER", "METRIC_KILOMETER" ], "x-enum-elements": [ { "name": "IMPERIAL_INCH", "description": "The length is measured in inches." }, { "name": "IMPERIAL_FOOT", "description": "The length is measured in feet." }, { "name": "IMPERIAL_YARD", "description": "The length is measured in yards." }, { "name": "IMPERIAL_MILE", "description": "The length is measured in miles." }, { "name": "METRIC_MILLIMETER", "description": "The length is measured in millimeters." }, { "name": "METRIC_CENTIMETER", "description": "The length is measured in centimeters." }, { "name": "METRIC_METER", "description": "The length is measured in meters." }, { "name": "METRIC_KILOMETER", "description": "The length is measured in kilometers." } ], "description": "The unit of length used to measure a quantity.", "x-release-status": "PUBLIC" }, "MeasurementUnitTime": { "type": "string", "enum": [ "GENERIC_MILLISECOND", "GENERIC_SECOND", "GENERIC_MINUTE", "GENERIC_HOUR", "GENERIC_DAY" ], "x-enum-elements": [ { "name": "GENERIC_MILLISECOND", "description": "The time is measured in milliseconds." }, { "name": "GENERIC_SECOND", "description": "The time is measured in seconds." }, { "name": "GENERIC_MINUTE", "description": "The time is measured in minutes." }, { "name": "GENERIC_HOUR", "description": "The time is measured in hours." }, { "name": "GENERIC_DAY", "description": "The time is measured in days." } ], "description": "Unit of time used to measure a quantity (a duration).", "x-release-status": "PUBLIC" }, "MeasurementUnitUnitType": { "type": "string", "enum": [ "TYPE_CUSTOM", "TYPE_AREA", "TYPE_LENGTH", "TYPE_VOLUME", "TYPE_WEIGHT", "TYPE_GENERIC" ], "x-enum-elements": [ { "name": "TYPE_CUSTOM", "description": "The unit details are contained in the custom_unit field." }, { "name": "TYPE_AREA", "description": "The unit details are contained in the area_unit field." }, { "name": "TYPE_LENGTH", "description": "The unit details are contained in the length_unit field." }, { "name": "TYPE_VOLUME", "description": "The unit details are contained in the volume_unit field." }, { "name": "TYPE_WEIGHT", "description": "The unit details are contained in the weight_unit field." }, { "name": "TYPE_GENERIC", "description": "The unit details are contained in the generic_unit field." } ], "description": "Describes the type of this unit and indicates which field contains the unit information. This is an ‘open’ enum.", "x-release-status": "PUBLIC" }, "MeasurementUnitVolume": { "type": "string", "enum": [ "GENERIC_FLUID_OUNCE", "GENERIC_SHOT", "GENERIC_CUP", "GENERIC_PINT", "GENERIC_QUART", "GENERIC_GALLON", "IMPERIAL_CUBIC_INCH", "IMPERIAL_CUBIC_FOOT", "IMPERIAL_CUBIC_YARD", "METRIC_MILLILITER", "METRIC_LITER" ], "x-enum-elements": [ { "name": "GENERIC_FLUID_OUNCE", "description": "The volume is measured in ounces." }, { "name": "GENERIC_SHOT", "description": "The volume is measured in shots." }, { "name": "GENERIC_CUP", "description": "The volume is measured in cups." }, { "name": "GENERIC_PINT", "description": "The volume is measured in pints." }, { "name": "GENERIC_QUART", "description": "The volume is measured in quarts." }, { "name": "GENERIC_GALLON", "description": "The volume is measured in gallons." }, { "name": "IMPERIAL_CUBIC_INCH", "description": "The volume is measured in cubic inches." }, { "name": "IMPERIAL_CUBIC_FOOT", "description": "The volume is measured in cubic feet." }, { "name": "IMPERIAL_CUBIC_YARD", "description": "The volume is measured in cubic yards." }, { "name": "METRIC_MILLILITER", "description": "The volume is measured in metric milliliters." }, { "name": "METRIC_LITER", "description": "The volume is measured in metric liters." } ], "description": "The unit of volume used to measure a quantity.", "x-release-status": "PUBLIC" }, "MeasurementUnitWeight": { "type": "string", "enum": [ "IMPERIAL_WEIGHT_OUNCE", "IMPERIAL_POUND", "IMPERIAL_STONE", "METRIC_MILLIGRAM", "METRIC_GRAM", "METRIC_KILOGRAM" ], "x-enum-elements": [ { "name": "IMPERIAL_WEIGHT_OUNCE", "description": "The weight is measured in ounces." }, { "name": "IMPERIAL_POUND", "description": "The weight is measured in pounds." }, { "name": "IMPERIAL_STONE", "description": "The weight is measured in stones." }, { "name": "METRIC_MILLIGRAM", "description": "The weight is measured in milligrams." }, { "name": "METRIC_GRAM", "description": "The weight is measured in grams." }, { "name": "METRIC_KILOGRAM", "description": "The weight is measured in kilograms." } ], "description": "Unit of weight used to measure a quantity.", "x-release-status": "PUBLIC" }, "MerchantStatus": { "type": "string", "enum": [ "ACTIVE", "INACTIVE" ], "x-enum-elements": [ { "name": "ACTIVE", "description": "A fully operational merchant account. The merchant can interact with Square products and APIs." }, { "name": "INACTIVE", "description": "A functionally limited merchant account. The merchant can only have limited interaction\nvia Square APIs. The merchant cannot log in or access the seller dashboard." } ], "description": "", "x-release-status": "PUBLIC" }, "OrderFulfillmentDeliveryDetailsScheduleType": { "type": "string", "enum": [ "SCHEDULED", "ASAP" ], "x-enum-elements": [ { "name": "SCHEDULED", "description": "Indicates the fulfillment to deliver at a scheduled deliver time." }, { "name": "ASAP", "description": "Indicates that the fulfillment to deliver as soon as possible and should be prepared\nimmediately." } ], "description": "The schedule type of the delivery fulfillment.", "x-release-status": "BETA", "x-is-beta": true }, "OrderFulfillmentFulfillmentLineItemApplication": { "type": "string", "enum": [ "ALL", "ENTRY_LIST" ], "x-enum-elements": [ { "name": "ALL", "description": "If `ALL`, `entries` must be unset." }, { "name": "ENTRY_LIST", "description": "If `ENTRY_LIST`, supply a list of `entries`." } ], "description": "The `line_item_application` describes what order line items this fulfillment applies\nto. It can be `ALL` or `ENTRY_LIST` with a supplied list of fulfillment entries.", "x-release-status": "BETA", "x-is-beta": true }, "OrderFulfillmentPickupDetailsScheduleType": { "type": "string", "enum": [ "SCHEDULED", "ASAP" ], "x-enum-elements": [ { "name": "SCHEDULED", "description": "Indicates that the fulfillment will be picked up at a scheduled pickup time." }, { "name": "ASAP", "description": "Indicates that the fulfillment will be picked up as soon as possible and\nshould be prepared immediately." } ], "description": "The schedule type of the pickup fulfillment.", "x-release-status": "PUBLIC" }, "OrderFulfillmentState": { "type": "string", "enum": [ "PROPOSED", "RESERVED", "PREPARED", "COMPLETED", "CANCELED", "FAILED" ], "x-enum-elements": [ { "name": "PROPOSED", "description": "Indicates that the fulfillment has been proposed." }, { "name": "RESERVED", "description": "Indicates that the fulfillment has been reserved." }, { "name": "PREPARED", "description": "Indicates that the fulfillment has been prepared." }, { "name": "COMPLETED", "description": "Indicates that the fulfillment was successfully completed." }, { "name": "CANCELED", "description": "Indicates that the fulfillment was canceled." }, { "name": "FAILED", "description": "Indicates that the fulfillment failed to be completed, but was not explicitly\ncanceled." } ], "description": "The current state of this fulfillment.", "x-release-status": "PUBLIC" }, "OrderFulfillmentType": { "type": "string", "enum": [ "PICKUP", "SHIPMENT", "DELIVERY" ], "x-enum-elements": [ { "name": "PICKUP", "description": "A recipient to pick up the fulfillment from a physical [location](https://developer.squareup.com/reference/square_2024-10-17/objects/Location)." }, { "name": "SHIPMENT", "description": "A shipping carrier to ship the fulfillment." }, { "name": "DELIVERY", "description": "A courier to deliver the fulfillment." } ], "description": "The type of fulfillment.", "x-release-status": "PUBLIC" }, "OrderLineItemDiscountScope": { "type": "string", "enum": [ "OTHER_DISCOUNT_SCOPE", "LINE_ITEM", "ORDER" ], "x-enum-elements": [ { "name": "OTHER_DISCOUNT_SCOPE", "description": "Used for reporting only.\nThe original transaction discount scope is currently not supported by the API." }, { "name": "LINE_ITEM", "description": "The discount should be applied to only line items specified by\n`OrderLineItemAppliedDiscount` reference records." }, { "name": "ORDER", "description": "The discount should be applied to the entire order." } ], "description": "Indicates whether this is a line-item or order-level discount.", "x-release-status": "PUBLIC" }, "OrderLineItemDiscountType": { "type": "string", "enum": [ "UNKNOWN_DISCOUNT", "FIXED_PERCENTAGE", "FIXED_AMOUNT", "VARIABLE_PERCENTAGE", "VARIABLE_AMOUNT" ], "x-enum-elements": [ { "name": "UNKNOWN_DISCOUNT", "description": "Used for reporting only.\nThe original transaction discount type is currently not supported by the API." }, { "name": "FIXED_PERCENTAGE", "description": "Apply the discount as a fixed percentage (such as 5%) off the item price." }, { "name": "FIXED_AMOUNT", "description": "Apply the discount as a fixed monetary value (such as $1.00) off the item price." }, { "name": "VARIABLE_PERCENTAGE", "description": "Apply the discount as a variable percentage based on the item\nprice.\n\nThe specific discount percentage of a `VARIABLE_PERCENTAGE` discount\nis assigned at the time of the purchase." }, { "name": "VARIABLE_AMOUNT", "description": "Apply the discount as a variable amount based on the item price.\n\nThe specific discount amount of a `VARIABLE_AMOUNT` discount\nis assigned at the time of the purchase." } ], "description": "Indicates how the discount is applied to the associated line item or order.", "x-release-status": "PUBLIC" }, "OrderLineItemItemType": { "type": "string", "enum": [ "ITEM", "CUSTOM_AMOUNT", "GIFT_CARD" ], "x-enum-elements": [ { "name": "ITEM", "description": "Indicates that the line item is an itemized sale." }, { "name": "CUSTOM_AMOUNT", "description": "Indicates that the line item is a non-itemized sale." }, { "name": "GIFT_CARD", "description": "Indicates that the line item is a gift card sale. Gift cards sold through\nthe Orders API are sold in an unactivated state and can be activated through the\nGift Cards API using the line item `uid`." } ], "description": "Represents the line item type.", "x-release-status": "BETA", "x-is-beta": true }, "OrderLineItemTaxScope": { "type": "string", "enum": [ "OTHER_TAX_SCOPE", "LINE_ITEM", "ORDER" ], "x-enum-elements": [ { "name": "OTHER_TAX_SCOPE", "description": "Used for reporting only.\nThe original transaction tax scope is currently not supported by the API." }, { "name": "LINE_ITEM", "description": "The tax should be applied only to line items specified by\nthe `OrderLineItemAppliedTax` reference records." }, { "name": "ORDER", "description": "The tax should be applied to the entire order." } ], "description": "Indicates whether this is a line-item or order-level tax.", "x-release-status": "PUBLIC" }, "OrderLineItemTaxType": { "type": "string", "enum": [ "UNKNOWN_TAX", "ADDITIVE", "INCLUSIVE" ], "x-enum-elements": [ { "name": "UNKNOWN_TAX", "description": "Used for reporting only.\nThe original transaction tax type is currently not supported by the API." }, { "name": "ADDITIVE", "description": "The tax is an additive tax. The tax amount is added on top of the price.\nFor example, an item with a cost of 1.00 USD and a 10% additive tax has a total\ncost to the buyer of 1.10 USD." }, { "name": "INCLUSIVE", "description": "The tax is an inclusive tax. Inclusive taxes are already included\nin the line item price or order total. For example, an item with a cost of\n1.00 USD and a 10% inclusive tax has a pretax cost of 0.91 USD\n(91 cents) and a 0.09 (9 cents) tax for a total cost of 1.00 USD to\nthe buyer." } ], "description": "Indicates how the tax is applied to the associated line item or order.", "x-release-status": "PUBLIC" }, "OrderServiceChargeCalculationPhase": { "type": "string", "enum": [ "SUBTOTAL_PHASE", "TOTAL_PHASE", "APPORTIONED_PERCENTAGE_PHASE", "APPORTIONED_AMOUNT_PHASE" ], "x-enum-elements": [ { "name": "SUBTOTAL_PHASE", "description": "The service charge is applied after discounts, but before\ntaxes." }, { "name": "TOTAL_PHASE", "description": "The service charge is applied after all discounts and taxes\nare applied." }, { "name": "APPORTIONED_PERCENTAGE_PHASE", "description": "The service charge is calculated as a compounding adjustment\nafter any discounts, but before amount based apportioned service charges\nand any tax considerations." }, { "name": "APPORTIONED_AMOUNT_PHASE", "description": "The service charge is calculated as a compounding adjustment\nafter any discounts and percentage based apportioned service charges,\nbut before any tax considerations." } ], "description": "Represents a phase in the process of calculating order totals.\nService charges are applied after the indicated phase.\n\n[Read more about how order totals are calculated.](https://developer.squareup.com/docs/orders-api/how-it-works#how-totals-are-calculated)", "x-release-status": "PUBLIC" }, "OrderServiceChargeScope": { "type": "string", "enum": [ "OTHER_SERVICE_CHARGE_SCOPE", "LINE_ITEM", "ORDER" ], "x-enum-elements": [ { "name": "OTHER_SERVICE_CHARGE_SCOPE", "description": "Used for reporting only.\nThe original transaction service charge scope is currently not supported by the API." }, { "name": "LINE_ITEM", "description": "The service charge should be applied to only line items specified by\n`OrderLineItemAppliedServiceCharge` reference records." }, { "name": "ORDER", "description": "The service charge should be applied to the entire order." } ], "description": "Indicates whether this is a line-item or order-level apportioned\nservice charge.", "x-release-status": "BETA", "x-is-beta": true }, "OrderServiceChargeTreatmentType": { "type": "string", "enum": [ "LINE_ITEM_TREATMENT", "APPORTIONED_TREATMENT" ], "x-enum-elements": [ { "name": "LINE_ITEM_TREATMENT", "description": "" }, { "name": "APPORTIONED_TREATMENT", "description": "" } ], "description": "Indicates whether the service charge will be treated as a value-holding line item or\napportioned toward a line item.", "x-release-status": "BETA", "x-is-beta": true }, "OrderServiceChargeType": { "type": "string", "enum": [ "AUTO_GRATUITY", "CUSTOM" ], "x-enum-elements": [ { "name": "AUTO_GRATUITY", "description": "" }, { "name": "CUSTOM", "description": "" } ], "description": "", "x-release-status": "PUBLIC" }, "OrderState": { "type": "string", "enum": [ "OPEN", "COMPLETED", "CANCELED", "DRAFT" ], "x-enum-elements": [ { "name": "OPEN", "description": "Indicates that the order is open. Open orders can be updated." }, { "name": "COMPLETED", "description": "Indicates that the order is completed. Completed orders are fully paid. This is a terminal state." }, { "name": "CANCELED", "description": "Indicates that the order is canceled. Canceled orders are not paid. This is a terminal state." }, { "name": "DRAFT", "description": "Indicates that the order is in a draft state. Draft orders can be updated,\nbut cannot be paid or fulfilled.\nFor more information, see [Create Orders](https://developer.squareup.com/docs/orders-api/create-orders)." } ], "description": "The state of the order.", "x-release-status": "PUBLIC" }, "PaymentOptionsDelayAction": { "type": "string", "enum": [ "CANCEL", "COMPLETE" ], "x-enum-elements": [ { "name": "CANCEL", "description": "Indicates that the payment should be automatically canceled when the delay duration\nelapses." }, { "name": "COMPLETE", "description": "Indicates that the payment should be automatically completed when the delay duration\nelapses." } ], "description": "Describes the action to be applied to a delayed capture payment when the delay_duration\nhas elapsed.", "x-release-status": "BETA", "x-is-beta": true }, "PayoutFeeType": { "type": "string", "enum": [ "TRANSFER_FEE", "TAX_ON_TRANSFER_FEE" ], "x-enum-elements": [ { "name": "TRANSFER_FEE", "description": "Fee type associated with transfers." }, { "name": "TAX_ON_TRANSFER_FEE", "description": "Taxes associated with the transfer fee." } ], "description": "Represents the type of payout fee that can incur as part of a payout.", "x-release-status": "PUBLIC" }, "PayoutStatus": { "type": "string", "enum": [ "SENT", "FAILED", "PAID" ], "x-enum-elements": [ { "name": "SENT", "description": "Indicates that the payout was successfully sent to the banking destination." }, { "name": "FAILED", "description": "Indicates that the payout was rejected by the banking destination." }, { "name": "PAID", "description": "Indicates that the payout has successfully completed." } ], "description": "Payout status types", "x-release-status": "PUBLIC" }, "PayoutType": { "type": "string", "enum": [ "BATCH", "SIMPLE" ], "x-enum-elements": [ { "name": "BATCH", "description": "Payouts that include a list of payout entries that can be considered settled." }, { "name": "SIMPLE", "description": "Payouts that do not have any payout entries associated with them and will\nshow up as one of the payout entries in a future BATCH payout." } ], "description": "The type of payout: “BATCH” or “SIMPLE”.\nBATCH payouts include a list of payout entries that can be considered settled.\nSIMPLE payouts do not have any payout entries associated with them\nand will show up as one of the payout entries in a future BATCH payout.", "x-release-status": "PUBLIC" }, "Product": { "type": "string", "enum": [ "SQUARE_POS", "EXTERNAL_API", "BILLING", "APPOINTMENTS", "INVOICES", "ONLINE_STORE", "PAYROLL", "DASHBOARD", "ITEM_LIBRARY_IMPORT", "OTHER" ], "x-enum-elements": [ { "name": "SQUARE_POS", "description": "Square Point of Sale application." }, { "name": "EXTERNAL_API", "description": "Square Connect APIs (for example, Orders API or Checkout API)." }, { "name": "BILLING", "description": "A Square subscription (various products)." }, { "name": "APPOINTMENTS", "description": "Square Appointments." }, { "name": "INVOICES", "description": "Square Invoices." }, { "name": "ONLINE_STORE", "description": "Square Online Store." }, { "name": "PAYROLL", "description": "Square Payroll." }, { "name": "DASHBOARD", "description": "Square Dashboard." }, { "name": "ITEM_LIBRARY_IMPORT", "description": "Item Library Import." }, { "name": "OTHER", "description": "A Square product that does not match any other value." } ], "description": "Indicates the Square product used to generate a change.", "x-release-status": "PUBLIC" }, "ProductType": { "type": "string", "enum": [ "TERMINAL_API" ], "x-enum-elements": [ { "name": "TERMINAL_API", "description": "" } ], "description": "", "x-release-status": "PUBLIC" }, "RefundStatus": { "type": "string", "enum": [ "PENDING", "APPROVED", "REJECTED", "FAILED" ], "x-enum-elements": [ { "name": "PENDING", "description": "The refund is pending." }, { "name": "APPROVED", "description": "The refund has been approved by Square." }, { "name": "REJECTED", "description": "The refund has been rejected by Square." }, { "name": "FAILED", "description": "The refund failed." } ], "description": "Indicates a refund\u0027s current status.", "x-release-status": "PUBLIC" }, "RegisterDomainResponseStatus": { "type": "string", "enum": [ "PENDING", "VERIFIED" ], "x-enum-elements": [ { "name": "PENDING", "description": "The domain is added, but not verified." }, { "name": "VERIFIED", "description": "The domain is added and verified. It can be used to accept Apple Pay transactions." } ], "description": "The status of the domain registration.", "x-release-status": "PUBLIC" }, "RiskEvaluationRiskLevel": { "type": "string", "enum": [ "PENDING", "NORMAL", "MODERATE", "HIGH" ], "x-enum-elements": [ { "name": "PENDING", "description": "Indicates Square is still evaluating the payment." }, { "name": "NORMAL", "description": "Indicates payment risk is within the normal range." }, { "name": "MODERATE", "description": "Indicates elevated risk level associated with the payment." }, { "name": "HIGH", "description": "Indicates significantly elevated risk level with the payment." } ], "description": "", "x-release-status": "BETA", "x-is-beta": true }, "SearchCatalogItemsRequestStockLevel": { "type": "string", "enum": [ "OUT", "LOW" ], "x-enum-elements": [ { "name": "OUT", "description": "The item inventory is empty." }, { "name": "LOW", "description": "The item inventory is low." } ], "description": "Defines supported stock levels of the item inventory.", "x-release-status": "PUBLIC" }, "SearchEventsSortField": { "type": "string", "enum": [ "DEFAULT" ], "x-enum-elements": [ { "name": "DEFAULT", "description": "Use the default sort key. The default behavior is to sort events by when they were created (`created_at`)." } ], "description": "Specifies the sort key for events returned from a search.", "x-release-status": "BETA", "x-is-beta": true }, "SearchOrdersSortField": { "type": "string", "enum": [ "CREATED_AT", "UPDATED_AT", "CLOSED_AT" ], "x-enum-elements": [ { "name": "CREATED_AT", "description": "The time when the order was created, in RFC-3339 format. If you are also\nfiltering for a time range in this query, you must set the `CREATED_AT`\nfield in your `DateTimeFilter`." }, { "name": "UPDATED_AT", "description": "The time when the order last updated, in RFC-3339 format. If you are also\nfiltering for a time range in this query, you must set the `UPDATED_AT`\nfield in your `DateTimeFilter`." }, { "name": "CLOSED_AT", "description": "The time when the order was closed, in RFC-3339 format. If you use this\nvalue, you must also set a `StateFilter` with closed states. If you are also\nfiltering for a time range in this query, you must set the `CLOSED_AT`\nfield in your `DateTimeFilter`." } ], "description": "Specifies which timestamp to use to sort `SearchOrder` results.", "x-release-status": "PUBLIC" }, "SearchVendorsRequestSortField": { "type": "string", "enum": [ "NAME", "CREATED_AT" ], "x-enum-elements": [ { "name": "NAME", "description": "To sort the result by the name of the [Vendor](https://developer.squareup.com/reference/square_2024-10-17/objects/Vendor) objects." }, { "name": "CREATED_AT", "description": "To sort the result by the creation time of the [Vendor](https://developer.squareup.com/reference/square_2024-10-17/objects/Vendor) objects." } ], "description": "The field to sort the returned [Vendor](https://developer.squareup.com/reference/square_2024-10-17/objects/Vendor) objects by.", "x-release-status": "BETA", "x-is-beta": true }, "ShiftFilterStatus": { "type": "string", "enum": [ "OPEN", "CLOSED" ], "x-enum-elements": [ { "name": "OPEN", "description": "Shifts that have been started and not ended." }, { "name": "CLOSED", "description": "Shifts that have been started and ended." } ], "description": "Specifies the `status` of `Shift` records to be returned.", "x-release-status": "PUBLIC" }, "ShiftSortField": { "type": "string", "enum": [ "START_AT", "END_AT", "CREATED_AT", "UPDATED_AT" ], "x-enum-elements": [ { "name": "START_AT", "description": "The start date/time of a `Shift`" }, { "name": "END_AT", "description": "The end date/time of a `Shift`" }, { "name": "CREATED_AT", "description": "The date/time that a `Shift` is created" }, { "name": "UPDATED_AT", "description": "The most recent date/time that a `Shift` is updated" } ], "description": "Enumerates the `Shift` fields to sort on.", "x-release-status": "PUBLIC" }, "ShiftStatus": { "type": "string", "enum": [ "OPEN", "CLOSED" ], "x-enum-elements": [ { "name": "OPEN", "description": "Employee started a work shift and the shift is not complete" }, { "name": "CLOSED", "description": "Employee started and ended a work shift." } ], "description": "Enumerates the possible status of a `Shift`.", "x-release-status": "PUBLIC" }, "ShiftWorkdayMatcher": { "type": "string", "enum": [ "START_AT", "END_AT", "INTERSECTION" ], "x-enum-elements": [ { "name": "START_AT", "description": "All shifts that start on or after the specified workday" }, { "name": "END_AT", "description": "All shifts that end on or before the specified workday" }, { "name": "INTERSECTION", "description": "All shifts that start between the start and end workdays (inclusive)" } ], "description": "Defines the logic used to apply a workday filter.", "x-release-status": "PUBLIC" }, "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" }, "SubscriptionActionType": { "type": "string", "enum": [ "CANCEL", "PAUSE", "RESUME", "SWAP_PLAN", "CHANGE_BILLING_ANCHOR_DATE" ], "x-enum-elements": [ { "name": "CANCEL", "description": "The action to execute a scheduled cancellation of a subscription." }, { "name": "PAUSE", "description": "The action to execute a scheduled pause of a subscription." }, { "name": "RESUME", "description": "The action to execute a scheduled resumption of a subscription." }, { "name": "SWAP_PLAN", "description": "The action to execute a scheduled swap of a subscription plan in a subscription." }, { "name": "CHANGE_BILLING_ANCHOR_DATE", "description": "A billing anchor date change action." } ], "description": "Supported types of an action as a pending change to a subscription.", "x-release-status": "BETA", "x-is-beta": true }, "SubscriptionCadence": { "type": "string", "enum": [ "DAILY", "WEEKLY", "EVERY_TWO_WEEKS", "THIRTY_DAYS", "SIXTY_DAYS", "NINETY_DAYS", "MONTHLY", "EVERY_TWO_MONTHS", "QUARTERLY", "EVERY_FOUR_MONTHS", "EVERY_SIX_MONTHS", "ANNUAL", "EVERY_TWO_YEARS" ], "x-enum-elements": [ { "name": "DAILY", "description": "Once per day" }, { "name": "WEEKLY", "description": "Once per week" }, { "name": "EVERY_TWO_WEEKS", "description": "Every two weeks" }, { "name": "THIRTY_DAYS", "description": "Once every 30 days" }, { "name": "SIXTY_DAYS", "description": "Once every 60 days" }, { "name": "NINETY_DAYS", "description": "Once every 90 days" }, { "name": "MONTHLY", "description": "Once per month" }, { "name": "EVERY_TWO_MONTHS", "description": "Once every two months" }, { "name": "QUARTERLY", "description": "Once every three months" }, { "name": "EVERY_FOUR_MONTHS", "description": "Once every four months" }, { "name": "EVERY_SIX_MONTHS", "description": "Once every six months" }, { "name": "ANNUAL", "description": "Once per year" }, { "name": "EVERY_TWO_YEARS", "description": "Once every two years" } ], "description": "Determines the billing cadence of a [Subscription](https://developer.squareup.com/reference/square_2024-10-17/objects/Subscription)", "x-release-status": "PUBLIC" }, "SubscriptionEventInfoCode": { "type": "string", "enum": [ "LOCATION_NOT_ACTIVE", "LOCATION_CANNOT_ACCEPT_PAYMENT", "CUSTOMER_DELETED", "CUSTOMER_NO_EMAIL", "CUSTOMER_NO_NAME", "USER_PROVIDED" ], "x-enum-elements": [ { "name": "LOCATION_NOT_ACTIVE", "description": "The location is not active." }, { "name": "LOCATION_CANNOT_ACCEPT_PAYMENT", "description": "The location cannot accept payments." }, { "name": "CUSTOMER_DELETED", "description": "The subscribing customer profile has been deleted." }, { "name": "CUSTOMER_NO_EMAIL", "description": "The subscribing customer does not have an email." }, { "name": "CUSTOMER_NO_NAME", "description": "The subscribing customer does not have a name." }, { "name": "USER_PROVIDED", "description": "User-provided detail." } ], "description": "Supported info codes of a subscription event.", "x-release-status": "PUBLIC" }, "SubscriptionEventSubscriptionEventType": { "type": "string", "enum": [ "START_SUBSCRIPTION", "PLAN_CHANGE", "STOP_SUBSCRIPTION", "DEACTIVATE_SUBSCRIPTION", "RESUME_SUBSCRIPTION", "PAUSE_SUBSCRIPTION", "BILLING_ANCHOR_DATE_CHANGED" ], "x-enum-elements": [ { "name": "START_SUBSCRIPTION", "description": "The subscription was started." }, { "name": "PLAN_CHANGE", "description": "The subscription plan was changed." }, { "name": "STOP_SUBSCRIPTION", "description": "The subscription was stopped." }, { "name": "DEACTIVATE_SUBSCRIPTION", "description": "The subscription was deactivated" }, { "name": "RESUME_SUBSCRIPTION", "description": "The subscription was resumed." }, { "name": "PAUSE_SUBSCRIPTION", "description": "The subscription was paused." }, { "name": "BILLING_ANCHOR_DATE_CHANGED", "description": "The billing anchor date was changed." } ], "description": "Supported types of an event occurred to a subscription.", "x-release-status": "PUBLIC" }, "SubscriptionPricingType": { "type": "string", "enum": [ "STATIC", "RELATIVE" ], "x-enum-elements": [ { "name": "STATIC", "description": "Static pricing" }, { "name": "RELATIVE", "description": "Relative pricing" } ], "description": "Determines the pricing of a [Subscription](https://developer.squareup.com/reference/square_2024-10-17/objects/Subscription)", "x-release-status": "PUBLIC" }, "SubscriptionStatus": { "type": "string", "enum": [ "PENDING", "ACTIVE", "CANCELED", "DEACTIVATED", "PAUSED" ], "x-enum-elements": [ { "name": "PENDING", "description": "The subscription is pending to start in the future." }, { "name": "ACTIVE", "description": "The subscription is active." }, { "name": "CANCELED", "description": "The subscription is canceled." }, { "name": "DEACTIVATED", "description": "The subscription is deactivated." }, { "name": "PAUSED", "description": "The subscription is paused." } ], "description": "Supported subscription statuses.", "x-release-status": "PUBLIC" }, "TaxCalculationPhase": { "type": "string", "enum": [ "TAX_SUBTOTAL_PHASE", "TAX_TOTAL_PHASE" ], "x-enum-elements": [ { "name": "TAX_SUBTOTAL_PHASE", "description": "The fee is calculated based on the payment\u0027s subtotal." }, { "name": "TAX_TOTAL_PHASE", "description": "The fee is calculated based on the payment\u0027s total." } ], "description": "When to calculate the taxes due on a cart.", "x-release-status": "PUBLIC" }, "TaxInclusionType": { "type": "string", "enum": [ "ADDITIVE", "INCLUSIVE" ], "x-enum-elements": [ { "name": "ADDITIVE", "description": "The tax is an additive tax. The tax amount is added on top of the\nCatalogItemVariation price. For example, a $1.00 item with a 10% additive\ntax would have a total cost to the buyer of $1.10." }, { "name": "INCLUSIVE", "description": "The tax is an inclusive tax. The tax amount is included in the\nCatalogItemVariation price. For example, a $1.00 item with a 10% inclusive\ntax would have a total cost to the buyer of $1.00, with $0.91 (91 cents) of\nthat total being the cost of the item and $0.09 (9 cents) being tax." } ], "description": "Whether to the tax amount should be additional to or included in the CatalogItem price.", "x-release-status": "PUBLIC" }, "TeamMemberAssignedLocationsAssignmentType": { "type": "string", "enum": [ "ALL_CURRENT_AND_FUTURE_LOCATIONS", "EXPLICIT_LOCATIONS" ], "x-enum-elements": [ { "name": "ALL_CURRENT_AND_FUTURE_LOCATIONS", "description": "The team member is assigned to all current and future locations. The `location_ids` field\nis empty if the team member has this assignment type." }, { "name": "EXPLICIT_LOCATIONS", "description": "The team member is assigned to an explicit subset of locations. The `location_ids` field\nis the list of locations that the team member is assigned to." } ], "description": "Enumerates the possible assignment types that the team member can have.", "x-release-status": "PUBLIC" }, "TeamMemberInvitationStatus": { "type": "string", "enum": [ "UNINVITED", "PENDING", "ACCEPTED" ], "x-enum-elements": [ { "name": "UNINVITED", "description": "The team member has not received an invitation." }, { "name": "PENDING", "description": "The team member has received an invitation, but had not accepted it." }, { "name": "ACCEPTED", "description": "The team member has both received and accepted an invitation." } ], "description": "Enumerates the possible invitation statuses the team member can have within a business.", "x-release-status": "PUBLIC" }, "TeamMemberStatus": { "type": "string", "enum": [ "ACTIVE", "INACTIVE" ], "x-enum-elements": [ { "name": "ACTIVE", "description": "The team member can sign in to Point of Sale and the Seller Dashboard." }, { "name": "INACTIVE", "description": "The team member can no longer sign in to Point of Sale or the Seller Dashboard,\nbut the team member\u0027s sales reports remain available." } ], "description": "Enumerates the possible statuses the team member can have within a business.", "x-release-status": "PUBLIC" }, "TenderBankAccountDetailsStatus": { "type": "string", "enum": [ "PENDING", "COMPLETED", "FAILED" ], "x-enum-elements": [ { "name": "PENDING", "description": "The bank account payment is in progress." }, { "name": "COMPLETED", "description": "The bank account payment has been completed." }, { "name": "FAILED", "description": "The bank account payment failed." } ], "description": "Indicates the bank account payment\u0027s current status.", "x-release-status": "PUBLIC" }, "TenderBuyNowPayLaterDetailsBrand": { "type": "string", "enum": [ "OTHER_BRAND", "AFTERPAY" ], "x-enum-elements": [ { "name": "OTHER_BRAND", "description": "" }, { "name": "AFTERPAY", "description": "" } ], "description": "", "x-release-status": "PUBLIC" }, "TenderBuyNowPayLaterDetailsStatus": { "type": "string", "enum": [ "AUTHORIZED", "CAPTURED", "VOIDED", "FAILED" ], "x-enum-elements": [ { "name": "AUTHORIZED", "description": "The buy now pay later payment has been authorized but not yet captured." }, { "name": "CAPTURED", "description": "The buy now pay later payment was authorized and subsequently captured (i.e., completed)." }, { "name": "VOIDED", "description": "The buy now pay later payment was authorized and subsequently voided (i.e., canceled)." }, { "name": "FAILED", "description": "The buy now pay later payment failed." } ], "description": "", "x-release-status": "PUBLIC" }, "TenderCardDetailsEntryMethod": { "type": "string", "enum": [ "SWIPED", "KEYED", "EMV", "ON_FILE", "CONTACTLESS" ], "x-enum-elements": [ { "name": "SWIPED", "description": "The card was swiped through a Square reader or Square stand." }, { "name": "KEYED", "description": "The card information was keyed manually into Square Point of Sale or a\nSquare-hosted web form." }, { "name": "EMV", "description": "The card was processed via EMV with a Square reader." }, { "name": "ON_FILE", "description": "The buyer\u0027s card details were already on file with Square." }, { "name": "CONTACTLESS", "description": "The card was processed via a contactless (i.e., NFC) transaction\nwith a Square reader." } ], "description": "Indicates the method used to enter the card\u0027s details.", "x-release-status": "PUBLIC" }, "TenderCardDetailsStatus": { "type": "string", "enum": [ "AUTHORIZED", "CAPTURED", "VOIDED", "FAILED" ], "x-enum-elements": [ { "name": "AUTHORIZED", "description": "The card transaction has been authorized but not yet captured." }, { "name": "CAPTURED", "description": "The card transaction was authorized and subsequently captured (i.e., completed)." }, { "name": "VOIDED", "description": "The card transaction was authorized and subsequently voided (i.e., canceled)." }, { "name": "FAILED", "description": "The card transaction failed." } ], "description": "Indicates the card transaction\u0027s current status.", "x-release-status": "PUBLIC" }, "TenderSquareAccountDetailsStatus": { "type": "string", "enum": [ "AUTHORIZED", "CAPTURED", "VOIDED", "FAILED" ], "x-enum-elements": [ { "name": "AUTHORIZED", "description": "The Square Account payment has been authorized but not yet captured." }, { "name": "CAPTURED", "description": "The Square Account payment was authorized and subsequently captured (i.e., completed)." }, { "name": "VOIDED", "description": "The Square Account payment was authorized and subsequently voided (i.e., canceled)." }, { "name": "FAILED", "description": "The Square Account payment failed." } ], "description": "", "x-release-status": "PUBLIC" }, "TenderType": { "type": "string", "enum": [ "CARD", "CASH", "THIRD_PARTY_CARD", "SQUARE_GIFT_CARD", "NO_SALE", "BANK_ACCOUNT", "WALLET", "BUY_NOW_PAY_LATER", "SQUARE_ACCOUNT", "OTHER" ], "x-enum-elements": [ { "name": "CARD", "description": "A credit card." }, { "name": "CASH", "description": "Cash." }, { "name": "THIRD_PARTY_CARD", "description": "A credit card processed with a card processor other than Square.\n\nThis value applies only to merchants in countries where Square does not\nyet provide card processing." }, { "name": "SQUARE_GIFT_CARD", "description": "A Square gift card." }, { "name": "NO_SALE", "description": "This tender represents the register being opened for a \"no sale\" event." }, { "name": "BANK_ACCOUNT", "description": "A bank account payment." }, { "name": "WALLET", "description": "A payment from a digital wallet, e.g. Cash App, Paypay, Rakuten Pay,\nAu Pay, D Barai, Merpay, Wechat Pay, Alipay.\n\nNote: Some \"digital wallets\", including Google Pay and Apple Pay, facilitate\ncard payments. Those payments have the `CARD` type." }, { "name": "BUY_NOW_PAY_LATER", "description": "A Buy Now Pay Later payment." }, { "name": "SQUARE_ACCOUNT", "description": "A Square House Account payment." }, { "name": "OTHER", "description": "A form of tender that does not match any other value." } ], "description": "Indicates a tender\u0027s type.", "x-release-status": "PUBLIC" }, "TerminalActionActionType": { "type": "string", "enum": [ "QR_CODE", "PING", "SAVE_CARD", "SIGNATURE", "CONFIRMATION", "RECEIPT", "DATA_COLLECTION", "SELECT" ], "x-enum-elements": [ { "name": "QR_CODE", "description": "The action represents a request to display a QR code. Details are contained in\nthe `qr_code_options` object." }, { "name": "PING", "description": "The action represents a request to check if the specific device is\nonline or currently active with the merchant in question. Does not require an action options value." }, { "name": "SAVE_CARD", "description": "Represents a request to save a card for future card-on-file use. Details are contained\nin the `save_card_options` object." }, { "name": "SIGNATURE", "description": "The action represents a request to capture a buyer\u0027s signature. Details are contained\nin the `signature_options` object." }, { "name": "CONFIRMATION", "description": "The action represents a request to collect a buyer\u0027s confirmation decision to the\ndisplayed terms. Details are contained in the `confirmation_options` object." }, { "name": "RECEIPT", "description": "The action represents a request to display the receipt screen options. Details are\ncontained in the `receipt_options` object." }, { "name": "DATA_COLLECTION", "description": "The action represents a request to collect a buyer\u0027s text data. Details\nare contained in the `data_collection_options` object." }, { "name": "SELECT", "description": "The action represents a request to allow the buyer to select from provided options.\nDetails are contained in the `select_options` object." } ], "description": "Describes the type of this unit and indicates which field contains the unit information. This is an ‘open’ enum.", "x-release-status": "BETA", "x-is-beta": true }, "TransactionProduct": { "type": "string", "enum": [ "REGISTER", "EXTERNAL_API", "BILLING", "APPOINTMENTS", "INVOICES", "ONLINE_STORE", "PAYROLL", "OTHER" ], "x-enum-elements": [ { "name": "REGISTER", "description": "Square Point of Sale." }, { "name": "EXTERNAL_API", "description": "The Square Connect API." }, { "name": "BILLING", "description": "A Square subscription for one of multiple products." }, { "name": "APPOINTMENTS", "description": "Square Appointments." }, { "name": "INVOICES", "description": "Square Invoices." }, { "name": "ONLINE_STORE", "description": "Square Online Store." }, { "name": "PAYROLL", "description": "Square Payroll." }, { "name": "OTHER", "description": "A Square product that does not match any other value." } ], "description": "Indicates the Square product used to process a transaction.", "x-release-status": "DEPRECATED", "x-is-deprecated": true }, "TransactionType": { "type": "string", "enum": [ "DEBIT", "CREDIT" ], "x-enum-elements": [ { "name": "DEBIT", "description": "" }, { "name": "CREDIT", "description": "" } ], "description": "The transaction type used in the disputed payment.", "x-release-status": "PUBLIC" }, "V1OrderHistoryEntryAction": { "type": "string", "enum": [ "ORDER_PLACED", "DECLINED", "PAYMENT_RECEIVED", "CANCELED", "COMPLETED", "REFUNDED", "EXPIRED" ], "x-enum-elements": [ { "name": "ORDER_PLACED", "description": "" }, { "name": "DECLINED", "description": "" }, { "name": "PAYMENT_RECEIVED", "description": "" }, { "name": "CANCELED", "description": "" }, { "name": "COMPLETED", "description": "" }, { "name": "REFUNDED", "description": "" }, { "name": "EXPIRED", "description": "" } ], "description": "", "x-release-status": "DEPRECATED", "x-is-deprecated": true, "x-visibility": "SDK_ONLY" }, "V1OrderState": { "type": "string", "enum": [ "PENDING", "OPEN", "COMPLETED", "CANCELED", "REFUNDED", "REJECTED" ], "x-enum-elements": [ { "name": "PENDING", "description": "" }, { "name": "OPEN", "description": "" }, { "name": "COMPLETED", "description": "" }, { "name": "CANCELED", "description": "" }, { "name": "REFUNDED", "description": "" }, { "name": "REJECTED", "description": "" } ], "description": "", "x-release-status": "DEPRECATED", "x-is-deprecated": true, "x-visibility": "SDK_ONLY" }, "V1TenderCardBrand": { "type": "string", "enum": [ "OTHER_BRAND", "VISA", "MASTER_CARD", "AMERICAN_EXPRESS", "DISCOVER", "DISCOVER_DINERS", "JCB", "CHINA_UNIONPAY", "SQUARE_GIFT_CARD" ], "x-enum-elements": [ { "name": "OTHER_BRAND", "description": "" }, { "name": "VISA", "description": "" }, { "name": "MASTER_CARD", "description": "" }, { "name": "AMERICAN_EXPRESS", "description": "" }, { "name": "DISCOVER", "description": "" }, { "name": "DISCOVER_DINERS", "description": "" }, { "name": "JCB", "description": "" }, { "name": "CHINA_UNIONPAY", "description": "" }, { "name": "SQUARE_GIFT_CARD", "description": "" } ], "description": "The brand of a credit card.", "x-release-status": "DEPRECATED", "x-is-deprecated": true }, "V1TenderEntryMethod": { "type": "string", "enum": [ "MANUAL", "SCANNED", "SQUARE_CASH", "SQUARE_WALLET", "SWIPED", "WEB_FORM", "OTHER" ], "x-enum-elements": [ { "name": "MANUAL", "description": "" }, { "name": "SCANNED", "description": "" }, { "name": "SQUARE_CASH", "description": "" }, { "name": "SQUARE_WALLET", "description": "" }, { "name": "SWIPED", "description": "" }, { "name": "WEB_FORM", "description": "" }, { "name": "OTHER", "description": "" } ], "description": "", "x-release-status": "DEPRECATED", "x-is-deprecated": true }, "V1TenderType": { "type": "string", "enum": [ "CREDIT_CARD", "CASH", "THIRD_PARTY_CARD", "NO_SALE", "SQUARE_WALLET", "SQUARE_GIFT_CARD", "UNKNOWN", "OTHER" ], "x-enum-elements": [ { "name": "CREDIT_CARD", "description": "" }, { "name": "CASH", "description": "" }, { "name": "THIRD_PARTY_CARD", "description": "" }, { "name": "NO_SALE", "description": "" }, { "name": "SQUARE_WALLET", "description": "" }, { "name": "SQUARE_GIFT_CARD", "description": "" }, { "name": "UNKNOWN", "description": "" }, { "name": "OTHER", "description": "" } ], "description": "", "x-release-status": "DEPRECATED", "x-is-deprecated": true }, "V1UpdateOrderRequestAction": { "type": "string", "enum": [ "COMPLETE", "CANCEL", "REFUND" ], "x-enum-elements": [ { "name": "COMPLETE", "description": "" }, { "name": "CANCEL", "description": "" }, { "name": "REFUND", "description": "" } ], "description": "", "x-release-status": "DEPRECATED", "x-is-deprecated": true, "x-visibility": "SDK_ONLY" }, "VendorStatus": { "type": "string", "enum": [ "ACTIVE", "INACTIVE" ], "x-enum-elements": [ { "name": "ACTIVE", "description": "Vendor is active and can receive purchase orders." }, { "name": "INACTIVE", "description": "Vendor is inactive and cannot receive purchase orders." } ], "description": "The status of the [Vendor](https://developer.squareup.com/reference/square_2024-10-17/objects/Vendor),\nwhether a [Vendor](https://developer.squareup.com/reference/square_2024-10-17/objects/Vendor) is active or inactive.", "x-release-status": "BETA", "x-is-beta": true }, "VisibilityFilter": { "type": "string", "enum": [ "ALL", "READ", "READ_WRITE" ], "x-enum-elements": [ { "name": "ALL", "description": "All custom attributes or custom attribute definitions." }, { "name": "READ", "description": "All custom attributes or custom attribute definitions with the `visibility` field set to `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`." }, { "name": "READ_WRITE", "description": "All custom attributes or custom attribute definitions with the `visibility` field set to `VISIBILITY_READ_WRITE_VALUES`." } ], "description": "Enumeration of visibility-filter values used to set the ability to view custom attributes or custom attribute definitions.", "x-release-status": "PUBLIC" }, "Weekday": { "type": "string", "enum": [ "MON", "TUE", "WED", "THU", "FRI", "SAT", "SUN" ], "x-enum-elements": [ { "name": "MON", "description": "Monday" }, { "name": "TUE", "description": "Tuesday" }, { "name": "WED", "description": "Wednesday" }, { "name": "THU", "description": "Thursday" }, { "name": "FRI", "description": "Friday" }, { "name": "SAT", "description": "Saturday" }, { "name": "SUN", "description": "Sunday" } ], "description": "The days of the week.", "x-release-status": "PUBLIC" }, "ACHDetails": { "type": "object", "properties": { "routing_number": { "maxLength": 50, "type": "string", "description": "The routing number for the bank account." }, "account_number_suffix": { "minLength": 1, "maxLength": 4, "type": "string", "description": "The last few digits of the bank account number." }, "account_type": { "maxLength": 50, "type": "string", "description": "The type of the bank account performing the transfer. The account type can be `CHECKING`,\n`SAVINGS`, or `UNKNOWN`." } }, "description": "ACH-specific details about `BANK_ACCOUNT` type payments with the `transfer_type` of `ACH`.", "x-release-status": "PUBLIC" }, "AcceptDisputeRequest": { "type": "object", "properties": {}, "description": "Defines the request parameters for the `AcceptDispute` endpoint.", "x-release-status": "PUBLIC", "example": { "request_body": {} } }, "AcceptDisputeResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Information about errors encountered during the request." }, "dispute": { "$ref": "#/definitions/Dispute", "description": "Details about the accepted dispute." } }, "description": "Defines the fields in an `AcceptDispute` response.", "x-release-status": "PUBLIC", "example": { "dispute": { "amount_money": { "amount": 2500, "currency": "USD" }, "reason": "NO_KNOWLEDGE", "state": "ACCEPTED", "due_at": "2022-07-13T00:00:00.000Z", "disputed_payment": { "payment_id": "zhyh1ch64kRBrrlfVhwjCEjZWzNZY" }, "card_brand": "VISA", "created_at": "2022-06-29T18:45:22.265Z", "updated_at": "2022-07-07T19:14:42.650Z", "brand_dispute_id": "100000809947", "version": 2, "location_id": "L1HN3ZMQK64X9", "id": "XDgyFu7yo1E2S5lQGGpYn", "reported_at": "2022-06-29T00:00:00.000Z" } } }, "AcceptedPaymentMethods": { "type": "object", "properties": { "apple_pay": { "type": "boolean", "description": "Whether Apple Pay is accepted at checkout." }, "google_pay": { "type": "boolean", "description": "Whether Google Pay is accepted at checkout." }, "cash_app_pay": { "type": "boolean", "description": "Whether Cash App Pay is accepted at checkout." }, "afterpay_clearpay": { "type": "boolean", "description": "Whether Afterpay/Clearpay is accepted at checkout." } }, "description": "", "x-release-status": "PUBLIC" }, "AccumulateLoyaltyPointsRequest": { "type": "object", "required": [ "accumulate_points", "idempotency_key", "location_id" ], "properties": { "accumulate_points": { "$ref": "#/definitions/LoyaltyEventAccumulatePoints", "description": "The points to add to the account. \nIf you are using the Orders API to manage orders, specify the order ID.\nOtherwise, specify the points to add." }, "idempotency_key": { "minLength": 1, "maxLength": 128, "type": "string", "description": "A unique string that identifies the `AccumulateLoyaltyPoints` request. \nKeys can be any valid string but must be unique for every request." }, "location_id": { "type": "string", "description": "The [location](https://developer.squareup.com/reference/square_2024-10-17/objects/Location) where the purchase was made." } }, "description": "Represents an [AccumulateLoyaltyPoints](https://developer.squareup.com/reference/square_2024-10-17/loyalty-api/accumulate-loyalty-points) request.", "x-release-status": "PUBLIC", "example": { "request_params": "?account_id\u003d5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd", "request_body": { "accumulate_points": { "order_id": "RFZfrdtm3mhO1oGzf5Cx7fEMsmGZY" }, "location_id": "P034NEENMD09F", "idempotency_key": "58b90739-c3e8-4b11-85f7-e636d48d72cb" } } }, "AccumulateLoyaltyPointsResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Any errors that occurred during the request." }, "event": { "$ref": "#/definitions/LoyaltyEvent", "description": "The resulting loyalty event. Starting in Square version 2022-08-17, this field is no longer returned.", "x-release-status": "DEPRECATED", "x-is-deprecated": true }, "events": { "type": "array", "items": { "$ref": "#/definitions/LoyaltyEvent" }, "description": "The resulting loyalty events. If the purchase qualifies for points, the `ACCUMULATE_POINTS` event\nis always included. When using the Orders API, the `ACCUMULATE_PROMOTION_POINTS` event is included\nif the purchase also qualifies for a loyalty promotion." } }, "description": "Represents an [AccumulateLoyaltyPoints](https://developer.squareup.com/reference/square_2024-10-17/loyalty-api/accumulate-loyalty-points) response.", "x-release-status": "PUBLIC", "example": { "events": [ { "id": "ee46aafd-1af6-3695-a385-276e2ef0be26", "type": "ACCUMULATE_POINTS", "created_at": "2020-05-08T21:41:12Z", "accumulate_points": { "loyalty_program_id": "d619f755-2d17-41f3-990d-c04ecedd64dd", "points": 6, "order_id": "RFZfrdtm3mhO1oGzf5Cx7fEMsmGZY" }, "loyalty_account_id": "5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd", "location_id": "P034NEENMD09F", "source": "LOYALTY_API" } ] } }, "AddGroupToCustomerRequest": { "type": "object", "properties": {}, "description": "Defines the fields that are included in the request body of\na request to the [AddGroupToCustomer](https://developer.squareup.com/reference/square_2024-10-17/customers-api/add-group-to-customer) endpoint.", "x-release-status": "PUBLIC", "example": { "request_body": {} } }, "AddGroupToCustomerResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Any errors that occurred during the request." } }, "description": "Defines the fields that are included in the response body of\na request to the [AddGroupToCustomer](https://developer.squareup.com/reference/square_2024-10-17/customers-api/add-group-to-customer) endpoint.", "x-release-status": "PUBLIC", "example": {} }, "AdditionalRecipient": { "type": "object", "required": [ "location_id", "amount_money" ], "properties": { "location_id": { "minLength": 1, "maxLength": 50, "type": "string", "description": "The location ID for a recipient (other than the merchant) receiving a portion of this tender." }, "description": { "maxLength": 100, "type": "string", "description": "The description of the additional recipient." }, "amount_money": { "$ref": "#/definitions/Money", "description": "The amount of money distributed to the recipient." }, "receivable_id": { "maxLength": 192, "type": "string", "description": "The unique ID for the RETIRED `AdditionalRecipientReceivable` object. This field should be empty for any `AdditionalRecipient` objects created after the retirement." } }, "description": "Represents an additional recipient (other than the merchant) receiving a portion of this tender.", "x-release-status": "DEPRECATED", "x-is-deprecated": true }, "Address": { "type": "object", "properties": { "address_line_1": { "type": "string", "description": "The first line of the address.\n\nFields that start with `address_line` provide the address\u0027s most specific\ndetails, like street number, street name, and building name. They do *not*\nprovide less specific details like city, state/province, or country (these\ndetails are provided in other fields)." }, "address_line_2": { "type": "string", "description": "The second line of the address, if any." }, "address_line_3": { "type": "string", "description": "The third line of the address, if any." }, "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)." }, "sublocality": { "type": "string", "description": "A civil region within the address\u0027s `locality`, if any." }, "sublocality_2": { "type": "string", "description": "A civil region within the address\u0027s `sublocality`, if any." }, "sublocality_3": { "type": "string", "description": "A civil region within the address\u0027s `sublocality_2`, if any." }, "administrative_district_level_1": { "type": "string", "description": "A civil entity within the address\u0027s country. In the US, this\nis the state. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses)." }, "administrative_district_level_2": { "type": "string", "description": "A civil entity within the address\u0027s `administrative_district_level_1`.\nIn the US, this is the county." }, "administrative_district_level_3": { "type": "string", "description": "A civil entity within the address\u0027s `administrative_district_level_2`,\nif any." }, "postal_code": { "type": "string", "description": "The address\u0027s postal code. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses)." }, "country": { "type": "string", "description": "The address\u0027s country, in the two-letter format of ISO 3166. For example, `US` or `FR`." }, "first_name": { "type": "string", "description": "Optional first name when it\u0027s representing recipient." }, "last_name": { "type": "string", "description": "Optional last name when it\u0027s representing recipient." } }, "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" }, "AdjustLoyaltyPointsRequest": { "type": "object", "required": [ "idempotency_key", "adjust_points" ], "properties": { "idempotency_key": { "minLength": 1, "maxLength": 128, "type": "string", "description": "A unique string that identifies this `AdjustLoyaltyPoints` request. \nKeys can be any valid string, but must be unique for every request." }, "adjust_points": { "$ref": "#/definitions/LoyaltyEventAdjustPoints", "description": "The points to add or subtract and the reason for the adjustment. To add points, specify a positive integer.\nTo subtract points, specify a negative integer." }, "allow_negative_balance": { "type": "boolean", "description": "Indicates whether to allow a negative adjustment to result in a negative balance. If `true`, a negative\nbalance is allowed when subtracting points. If `false`, Square returns a `BAD_REQUEST` error when subtracting\nthe specified number of points would result in a negative balance. The default value is `false`." } }, "description": "Represents an [AdjustLoyaltyPoints](https://developer.squareup.com/reference/square_2024-10-17/loyalty-api/adjust-loyalty-points) request.", "x-release-status": "PUBLIC", "example": { "request_params": "?account_id\u003d5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd", "request_body": { "adjust_points": { "points": 10, "reason": "Complimentary points" }, "idempotency_key": "bc29a517-3dc9-450e-aa76-fae39ee849d1" } } }, "AdjustLoyaltyPointsResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Any errors that occurred during the request." }, "event": { "$ref": "#/definitions/LoyaltyEvent", "description": "The resulting event data for the adjustment." } }, "description": "Represents an [AdjustLoyaltyPoints](https://developer.squareup.com/reference/square_2024-10-17/loyalty-api/adjust-loyalty-points) request.", "x-release-status": "PUBLIC", "example": { "event": { "id": "613a6fca-8d67-39d0-bad2-3b4bc45c8637", "type": "ADJUST_POINTS", "created_at": "2020-05-08T21:42:32Z", "adjust_points": { "loyalty_program_id": "d619f755-2d17-41f3-990d-c04ecedd64dd", "points": 10, "reason": "Complimentary points" }, "loyalty_account_id": "5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd", "source": "LOYALTY_API" } } }, "AfterpayDetails": { "type": "object", "properties": { "email_address": { "maxLength": 255, "type": "string", "description": "Email address on the buyer\u0027s Afterpay account." } }, "description": "Additional details about Afterpay payments.", "x-release-status": "PUBLIC" }, "ApplicationDetails": { "type": "object", "properties": { "square_product": { "type": "string", "description": "The Square product, such as Square Point of Sale (POS), \nSquare Invoices, or Square Virtual Terminal." }, "application_id": { "type": "string", "description": "The Square ID assigned to the application used to take the payment. \nApplication developers can use this information to identify payments that \ntheir application processed. \nFor example, if a developer uses a custom application to process payments, \nthis field contains the application ID from the Developer Dashboard. \nIf a seller uses a [Square App Marketplace](https://developer.squareup.com/docs/app-marketplace) \napplication to process payments, the field contains the corresponding application ID." } }, "description": "Details about the application that took the payment.", "x-release-status": "PUBLIC" }, "AppointmentSegment": { "type": "object", "required": [ "team_member_id" ], "properties": { "duration_minutes": { "maximum": 1500, "minimum": 0, "type": "integer", "description": "The time span in minutes of an appointment segment." }, "service_variation_id": { "minLength": 0, "maxLength": 36, "type": "string", "description": "The ID of the [CatalogItemVariation](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogItemVariation) object representing the service booked in this segment." }, "team_member_id": { "minLength": 1, "maxLength": 32, "type": "string", "description": "The ID of the [TeamMember](https://developer.squareup.com/reference/square_2024-10-17/objects/TeamMember) object representing the team member booked in this segment." }, "service_variation_version": { "type": "integer", "format": "int64", "description": "The current version of the item variation representing the service booked in this segment." }, "intermission_minutes": { "type": "integer", "description": "Time between the end of this segment and the beginning of the subsequent segment.", "x-read-only": true }, "any_team_member": { "type": "boolean", "description": "Whether the customer accepts any team member, instead of a specific one, to serve this segment.", "x-read-only": true }, "resource_ids": { "type": "array", "items": { "minLength": 0, "maxLength": 65536, "type": "string" }, "description": "The IDs of the seller-accessible resources used for this appointment segment.", "x-read-only": true } }, "description": "Defines an appointment segment of a booking.", "x-release-status": "PUBLIC" }, "Availability": { "type": "object", "properties": { "start_at": { "type": "string", "description": "The RFC 3339 timestamp specifying the beginning time of the slot available for booking." }, "location_id": { "minLength": 0, "maxLength": 32, "type": "string", "description": "The ID of the location available for booking.", "x-read-only": true }, "appointment_segments": { "type": "array", "items": { "$ref": "#/definitions/AppointmentSegment" }, "description": "The list of appointment segments available for booking" } }, "description": "Defines an appointment slot that encapsulates the appointment segments, location and starting time available for booking.", "x-release-status": "PUBLIC" }, "BankAccount": { "type": "object", "required": [ "id", "account_number_suffix", "country", "currency", "account_type", "holder_name", "primary_bank_identification_number", "status", "creditable", "debitable" ], "properties": { "id": { "minLength": 1, "maxLength": 30, "type": "string", "description": "The unique, Square-issued identifier for the bank account." }, "account_number_suffix": { "minLength": 1, "type": "string", "description": "The last few digits of the account number." }, "country": { "type": "string", "description": "The ISO 3166 Alpha-2 country code where the bank account is based." }, "currency": { "type": "string", "description": "The 3-character ISO 4217 currency code indicating the operating\ncurrency of the bank account. For example, the currency code for US dollars\nis `USD`." }, "account_type": { "type": "string", "description": "The financial purpose of the associated bank account." }, "holder_name": { "minLength": 1, "type": "string", "description": "Name of the account holder. This name must match the name \non the targeted bank account record." }, "primary_bank_identification_number": { "maxLength": 40, "type": "string", "description": "Primary identifier for the bank. For more information, see \n[Bank Accounts API](https://developer.squareup.com/docs/bank-accounts-api)." }, "secondary_bank_identification_number": { "maxLength": 40, "type": "string", "description": "Secondary identifier for the bank. For more information, see \n[Bank Accounts API](https://developer.squareup.com/docs/bank-accounts-api)." }, "debit_mandate_reference_id": { "type": "string", "description": "Reference identifier that will be displayed to UK bank account owners\nwhen collecting direct debit authorization. Only required for UK bank accounts." }, "reference_id": { "type": "string", "description": "Client-provided identifier for linking the banking account to an entity\nin a third-party system (for example, a bank account number or a user identifier)." }, "location_id": { "type": "string", "description": "The location to which the bank account belongs." }, "status": { "type": "string", "description": "Read-only. The current verification status of this BankAccount object." }, "creditable": { "type": "boolean", "description": "Indicates whether it is possible for Square to send money to this bank account." }, "debitable": { "type": "boolean", "description": "Indicates whether it is possible for Square to take money from this \nbank account." }, "fingerprint": { "type": "string", "description": "A Square-assigned, unique identifier for the bank account based on the\naccount information. The account fingerprint can be used to compare account\nentries and determine if the they represent the same real-world bank account." }, "version": { "type": "integer", "description": "The current version of the `BankAccount`." }, "bank_name": { "maxLength": 100, "type": "string", "description": "Read only. Name of actual financial institution. \nFor example \"Bank of America\"." } }, "description": "Represents a bank account. For more information about \nlinking a bank account to a Square account, see \n[Bank Accounts API](https://developer.squareup.com/docs/bank-accounts-api).", "x-release-status": "PUBLIC" }, "BankAccountPaymentDetails": { "type": "object", "properties": { "bank_name": { "maxLength": 100, "type": "string", "description": "The name of the bank associated with the bank account." }, "transfer_type": { "maxLength": 50, "type": "string", "description": "The type of the bank transfer. The type can be `ACH` or `UNKNOWN`." }, "account_ownership_type": { "maxLength": 50, "type": "string", "description": "The ownership type of the bank account performing the transfer.\nThe type can be `INDIVIDUAL`, `COMPANY`, or `ACCOUNT_TYPE_UNKNOWN`." }, "fingerprint": { "maxLength": 255, "type": "string", "description": "Uniquely identifies the bank account for this seller and can be used\nto determine if payments are from the same bank account." }, "country": { "minLength": 2, "maxLength": 2, "type": "string", "description": "The two-letter ISO code representing the country the bank account is located in." }, "statement_description": { "maxLength": 1000, "type": "string", "description": "The statement description as sent to the bank." }, "ach_details": { "$ref": "#/definitions/ACHDetails", "description": "ACH-specific information about the transfer. The information is only populated\nif the `transfer_type` is `ACH`." }, "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Information about errors encountered during the request." } }, "description": "Additional details about BANK_ACCOUNT type payments.", "x-release-status": "PUBLIC" }, "BatchChangeInventoryRequest": { "type": "object", "required": [ "idempotency_key" ], "properties": { "idempotency_key": { "minLength": 1, "maxLength": 128, "type": "string", "description": "A client-supplied, universally unique identifier (UUID) for the\nrequest.\n\nSee [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) in the\n[API Development 101](https://developer.squareup.com/docs/buildbasics) section for more\ninformation." }, "changes": { "type": "array", "items": { "$ref": "#/definitions/InventoryChange" }, "description": "The set of physical counts and inventory adjustments to be made.\nChanges are applied based on the client-supplied timestamp and may be sent\nout of order." }, "ignore_unchanged_counts": { "type": "boolean", "description": "Indicates whether the current physical count should be ignored if\nthe quantity is unchanged since the last physical count. Default: `true`." } }, "description": "", "x-release-status": "PUBLIC", "example": { "request_body": { "idempotency_key": "8fc6a5b0-9fe8-4b46-b46b-2ef95793abbe", "changes": [ { "type": "PHYSICAL_COUNT", "physical_count": { "reference_id": "1536bfbf-efed-48bf-b17d-a197141b2a92", "catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI", "state": "IN_STOCK", "location_id": "C6W5YS5QM06F5", "quantity": "53", "team_member_id": "LRK57NSQ5X7PUD05", "occurred_at": "2016-11-16T22:25:24.878Z" } } ], "ignore_unchanged_counts": true } }, "x-sq-sdk-sample-code": { "python": "/sdk_samples/Inventory/BatchChangeInventory/BatchChangeInventoryRequest.python", "csharp": "/sdk_samples/Inventory/BatchChangeInventory/BatchChangeInventoryRequest.csharp", "java": "/sdk_samples/Inventory/BatchChangeInventory/BatchChangeInventoryRequest.java", "php": "/sdk_samples/Inventory/BatchChangeInventory/BatchChangeInventoryRequest.php", "javascript": "/sdk_samples/Inventory/BatchChangeInventory/BatchChangeInventoryRequest.javascript", "ruby": "/sdk_samples/Inventory/BatchChangeInventory/BatchChangeInventoryRequest.ruby" } }, "BatchChangeInventoryResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Any errors that occurred during the request." }, "counts": { "type": "array", "items": { "$ref": "#/definitions/InventoryCount" }, "description": "The current counts for all objects referenced in the request." }, "changes": { "type": "array", "items": { "$ref": "#/definitions/InventoryChange" }, "description": "Changes created for the request.", "x-release-status": "BETA", "x-is-beta": true } }, "description": "", "x-release-status": "PUBLIC", "example": { "errors": [], "counts": [ { "catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI", "catalog_object_type": "ITEM_VARIATION", "state": "IN_STOCK", "location_id": "C6W5YS5QM06F5", "quantity": "53", "calculated_at": "2016-11-16T22:28:01.223Z" } ] } }, "BatchDeleteCatalogObjectsRequest": { "type": "object", "properties": { "object_ids": { "type": "array", "items": { "type": "string" }, "description": "The IDs of the CatalogObjects to be deleted. When an object is deleted, other objects\nin the graph that depend on that object will be deleted as well (for example, deleting a\nCatalogItem will delete its CatalogItemVariation." } }, "description": "", "x-release-status": "PUBLIC", "example": { "request_body": { "object_ids": [ "W62UWFY35CWMYGVWK6TWJDNI", "AA27W3M2GGTF3H6AVPNB77CK" ] } }, "x-sq-sdk-sample-code": { "python": "/sdk_samples/Catalog/BatchDeleteCatalogObjects/BatchDeleteCatalogObjectsRequest.python", "csharp": "/sdk_samples/Catalog/BatchDeleteCatalogObjects/BatchDeleteCatalogObjectsRequest.csharp", "java": "/sdk_samples/Catalog/BatchDeleteCatalogObjects/BatchDeleteCatalogObjectsRequest.java", "php": "/sdk_samples/Catalog/BatchDeleteCatalogObjects/BatchDeleteCatalogObjectsRequest.php", "javascript": "/sdk_samples/Catalog/BatchDeleteCatalogObjects/BatchDeleteCatalogObjectsRequest.javascript", "ruby": "/sdk_samples/Catalog/BatchDeleteCatalogObjects/BatchDeleteCatalogObjectsRequest.ruby" } }, "BatchDeleteCatalogObjectsResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Any errors that occurred during the request." }, "deleted_object_ids": { "type": "array", "items": { "type": "string" }, "description": "The IDs of all CatalogObjects deleted by this request." }, "deleted_at": { "type": "string", "description": "The database [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates) of this deletion in RFC 3339 format, e.g., \"2016-09-04T23:59:33.123Z\"." } }, "description": "", "x-release-status": "PUBLIC", "example": { "deleted_object_ids": [ "W62UWFY35CWMYGVWK6TWJDNI", "AA27W3M2GGTF3H6AVPNB77CK" ], "deleted_at": "2016-11-16T22:25:24.878Z" }, "x-sq-sdk-sample-code": { "python": "/sdk_samples/Catalog/BatchDeleteCatalogObjects/BatchDeleteCatalogObjectsResponse.python", "csharp": "/sdk_samples/Catalog/BatchDeleteCatalogObjects/BatchDeleteCatalogObjectsResponse.csharp", "java": "/sdk_samples/Catalog/BatchDeleteCatalogObjects/BatchDeleteCatalogObjectsResponse.java", "php": "/sdk_samples/Catalog/BatchDeleteCatalogObjects/BatchDeleteCatalogObjectsResponse.php", "javascript": "/sdk_samples/Catalog/BatchDeleteCatalogObjects/BatchDeleteCatalogObjectsResponse.javascript", "ruby": "/sdk_samples/Catalog/BatchDeleteCatalogObjects/BatchDeleteCatalogObjectsResponse.ruby" } }, "BatchRetrieveCatalogObjectsRequest": { "type": "object", "required": [ "object_ids" ], "properties": { "object_ids": { "type": "array", "items": { "type": "string" }, "description": "The IDs of the CatalogObjects to be retrieved." }, "include_related_objects": { "type": "boolean", "description": "If `true`, the response will include additional objects that are related to the\nrequested objects. Related objects are defined as any objects referenced by ID by the results in the `objects` field\nof the response. These objects are put in the `related_objects` field. Setting this to `true` is\nhelpful when the objects are needed for immediate display to a user.\nThis process only goes one level deep. Objects referenced by the related objects will not be included. For example,\n\nif the `objects` field of the response contains a CatalogItem, its associated\nCatalogCategory objects, CatalogTax objects, CatalogImage objects and\nCatalogModifierLists will be returned in the `related_objects` field of the\nresponse. If the `objects` field of the response contains a CatalogItemVariation,\nits parent CatalogItem will be returned in the `related_objects` field of\nthe response.\n\nDefault value: `false`" }, "catalog_version": { "type": "integer", "format": "int64", "description": "The specific version of the catalog objects to be included in the response. \nThis allows you to retrieve historical versions of objects. The specified version value is matched against\nthe [CatalogObject](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogObject)s\u0027 `version` attribute. If not included, results will\nbe from the current version of the catalog.", "x-release-status": "BETA", "x-is-beta": true }, "include_deleted_objects": { "type": "boolean", "description": "Indicates whether to include (`true`) or not (`false`) in the response deleted objects, namely, those with the `is_deleted` attribute set to `true`." }, "include_category_path_to_root": { "type": "boolean", "description": "Specifies whether or not to include the `path_to_root` list for each returned category instance. The `path_to_root` list consists\nof `CategoryPathToRootNode` objects and specifies the path that starts with the immediate parent category of the returned category\nand ends with its root category. If the returned category is a top-level category, the `path_to_root` list is empty and is not returned\nin the response payload." } }, "description": "", "x-release-status": "PUBLIC", "example": { "request_body": { "object_ids": [ "W62UWFY35CWMYGVWK6TWJDNI", "AA27W3M2GGTF3H6AVPNB77CK" ], "include_related_objects": true } }, "x-sq-sdk-sample-code": { "python": "/sdk_samples/Catalog/BatchRetrieveCatalogObjects/BatchRetrieveCatalogObjectsRequest.python", "csharp": "/sdk_samples/Catalog/BatchRetrieveCatalogObjects/BatchRetrieveCatalogObjectsRequest.csharp", "java": "/sdk_samples/Catalog/BatchRetrieveCatalogObjects/BatchRetrieveCatalogObjectsRequest.java", "php": "/sdk_samples/Catalog/BatchRetrieveCatalogObjects/BatchRetrieveCatalogObjectsRequest.php", "javascript": "/sdk_samples/Catalog/BatchRetrieveCatalogObjects/BatchRetrieveCatalogObjectsRequest.javascript", "ruby": "/sdk_samples/Catalog/BatchRetrieveCatalogObjects/BatchRetrieveCatalogObjectsRequest.ruby" } }, "BatchRetrieveCatalogObjectsResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Any errors that occurred during the request." }, "objects": { "type": "array", "items": { "$ref": "#/definitions/CatalogObject" }, "description": "A list of [CatalogObject](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogObject)s returned." }, "related_objects": { "type": "array", "items": { "$ref": "#/definitions/CatalogObject" }, "description": "A list of [CatalogObject](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogObject)s referenced by the object in the `objects` field." } }, "description": "", "x-release-status": "PUBLIC", "example": { "objects": [ { "type": "ITEM", "id": "W62UWFY35CWMYGVWK6TWJDNI", "updated_at": "2016-11-16T22:25:24.878Z", "version": 1479335124878, "is_deleted": false, "present_at_all_locations": true, "item_data": { "name": "Tea", "description": "Hot Leaf Juice", "categories": [ { "id": "BJNQCF2FJ6S6UIDT65ABHLRX", "ordinal": 0 } ], "tax_ids": [ "HURXQOOAIC4IZSI2BEXQRYFY" ], "variations": [ { "type": "ITEM_VARIATION", "id": "2TZFAOHWGG7PAK2QEXWYPZSP", "updated_at": "2016-11-16T22:25:24.878Z", "version": 1479335124878, "is_deleted": false, "present_at_all_locations": true, "item_variation_data": { "item_id": "W62UWFY35CWMYGVWK6TWJDNI", "name": "Mug", "ordinal": 0, "pricing_type": "FIXED_PRICING", "price_money": { "amount": 150, "currency": "USD" } } } ] } }, { "type": "ITEM", "id": "AA27W3M2GGTF3H6AVPNB77CK", "updated_at": "2016-11-16T22:25:24.878Z", "version": 1479335124878, "is_deleted": false, "present_at_all_locations": true, "item_data": { "name": "Coffee", "description": "Hot Bean Juice", "categories": [ { "id": "BJNQCF2FJ6S6UIDT65ABHLRX", "ordinal": 0 } ], "tax_ids": [ "HURXQOOAIC4IZSI2BEXQRYFY" ], "variations": [ { "type": "ITEM_VARIATION", "id": "LBTYIHNHU52WOIHWT7SNRIYH", "updated_at": "2016-11-16T22:25:24.878Z", "version": 1479335124878, "is_deleted": false, "present_at_all_locations": true, "item_variation_data": { "item_id": "AA27W3M2GGTF3H6AVPNB77CK", "name": "Regular", "ordinal": 0, "pricing_type": "FIXED_PRICING", "price_money": { "amount": 250, "currency": "USD" } } }, { "type": "ITEM_VARIATION", "id": "PKYIC7HGGKW5CYVSCVDEIMHY", "updated_at": "2016-11-16T22:25:24.878Z", "version": 1479335124878, "is_deleted": false, "present_at_all_locations": true, "item_variation_data": { "item_id": "AA27W3M2GGTF3H6AVPNB77CK", "name": "Large", "ordinal": 1, "pricing_type": "FIXED_PRICING", "price_money": { "amount": 350, "currency": "USD" } } } ] } } ], "related_objects": [ { "type": "CATEGORY", "id": "BJNQCF2FJ6S6UIDT65ABHLRX", "updated_at": "2016-11-16T22:25:24.878Z", "version": 1479335124878, "is_deleted": false, "present_at_all_locations": true, "category_data": { "name": "Beverages" } }, { "type": "TAX", "id": "HURXQOOAIC4IZSI2BEXQRYFY", "updated_at": "2016-11-16T22:25:24.878Z", "version": 1479335124878, "is_deleted": false, "present_at_all_locations": true, "tax_data": { "name": "Sales Tax", "calculation_phase": "TAX_SUBTOTAL_PHASE", "inclusion_type": "ADDITIVE", "percentage": "5.0", "enabled": true } } ] }, "x-sq-sdk-sample-code": { "python": "/sdk_samples/Catalog/BatchRetrieveCatalogObjects/BatchRetrieveCatalogObjectsResponse.python", "csharp": "/sdk_samples/Catalog/BatchRetrieveCatalogObjects/BatchRetrieveCatalogObjectsResponse.csharp", "java": "/sdk_samples/Catalog/BatchRetrieveCatalogObjects/BatchRetrieveCatalogObjectsResponse.java", "php": "/sdk_samples/Catalog/BatchRetrieveCatalogObjects/BatchRetrieveCatalogObjectsResponse.php", "javascript": "/sdk_samples/Catalog/BatchRetrieveCatalogObjects/BatchRetrieveCatalogObjectsResponse.javascript", "ruby": "/sdk_samples/Catalog/BatchRetrieveCatalogObjects/BatchRetrieveCatalogObjectsResponse.ruby" } }, "BatchRetrieveInventoryChangesRequest": { "type": "object", "properties": { "catalog_object_ids": { "type": "array", "items": { "type": "string" }, "description": "The filter to return results by `CatalogObject` ID.\nThe filter is only applicable when set. The default value is null." }, "location_ids": { "type": "array", "items": { "type": "string" }, "description": "The filter to return results by `Location` ID.\nThe filter is only applicable when set. The default value is null." }, "types": { "type": "array", "items": { "type": "string" }, "description": "The filter to return results by `InventoryChangeType` values other than `TRANSFER`.\nThe default value is `[PHYSICAL_COUNT, ADJUSTMENT]`." }, "states": { "type": "array", "items": { "type": "string" }, "description": "The filter to return `ADJUSTMENT` query results by\n`InventoryState`. This filter is only applied when set.\nThe default value is null." }, "updated_after": { "type": "string", "description": "The filter to return results with their `calculated_at` value\nafter the given time as specified in an RFC 3339 timestamp.\nThe default value is the UNIX epoch of (`1970-01-01T00:00:00Z`)." }, "updated_before": { "type": "string", "description": "The filter to return results with their `created_at` or `calculated_at` value\nstrictly before the given time as specified in an RFC 3339 timestamp.\nThe default value is the UNIX epoch of (`1970-01-01T00:00:00Z`)." }, "cursor": { "type": "string", "description": "A pagination cursor returned by a previous call to this endpoint.\nProvide this to retrieve the next set of results for the original query.\n\nSee the [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination) guide for more information." }, "limit": { "maximum": 1000, "minimum": 1, "type": "integer", "description": "The number of [records](https://developer.squareup.com/reference/square_2024-10-17/objects/InventoryChange) to return." } }, "description": "", "x-release-status": "PUBLIC", "example": { "request_body": { "catalog_object_ids": [ "W62UWFY35CWMYGVWK6TWJDNI" ], "location_ids": [ "C6W5YS5QM06F5" ], "types": [ "PHYSICAL_COUNT" ], "states": [ "IN_STOCK" ], "updated_after": "2016-11-01T00:00:00.000Z", "updated_before": "2016-12-01T00:00:00.000Z" } }, "x-sq-sdk-sample-code": { "python": "/sdk_samples/Inventory/BatchRetrieveInventoryChanges/BatchRetrieveInventoryChangesRequest.python", "csharp": "/sdk_samples/Inventory/BatchRetrieveInventoryChanges/BatchRetrieveInventoryChangesRequest.csharp", "java": "/sdk_samples/Inventory/BatchRetrieveInventoryChanges/BatchRetrieveInventoryChangesRequest.java", "php": "/sdk_samples/Inventory/BatchRetrieveInventoryChanges/BatchRetrieveInventoryChangesRequest.php", "javascript": "/sdk_samples/Inventory/BatchRetrieveInventoryChanges/BatchRetrieveInventoryChangesRequest.javascript", "ruby": "/sdk_samples/Inventory/BatchRetrieveInventoryChanges/BatchRetrieveInventoryChangesRequest.ruby" } }, "BatchRetrieveInventoryChangesResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Any errors that occurred during the request." }, "changes": { "type": "array", "items": { "$ref": "#/definitions/InventoryChange" }, "description": "The current calculated inventory changes for the requested objects\nand locations." }, "cursor": { "type": "string", "description": "The pagination cursor to be used in a subsequent request. If unset,\nthis is the final response.\nSee the [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination) guide for more information." } }, "description": "", "x-release-status": "PUBLIC", "example": { "errors": [], "changes": [ { "type": "PHYSICAL_COUNT", "physical_count": { "id": "46YDTW253DWGGK9HMAE6XCAO", "reference_id": "22c07cf4-5626-4224-89f9-691112019399", "catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI", "catalog_object_type": "ITEM_VARIATION", "state": "IN_STOCK", "location_id": "C6W5YS5QM06F5", "quantity": "86", "source": { "product": "SQUARE_POS", "application_id": "416ff29c-86c4-4feb-b58c-9705f21f3ea0", "name": "Square Point of Sale 4.37" }, "team_member_id": "LRK57NSQ5X7PUD05", "occurred_at": "2016-11-16T22:24:49.028Z", "created_at": "2016-11-16T22:25:24.878Z" } } ] } }, "BatchRetrieveInventoryCountsRequest": { "type": "object", "properties": { "catalog_object_ids": { "type": "array", "items": { "type": "string" }, "description": "The filter to return results by `CatalogObject` ID.\nThe filter is applicable only when set. The default is null." }, "location_ids": { "type": "array", "items": { "type": "string" }, "description": "The filter to return results by `Location` ID.\nThis filter is applicable only when set. The default is null." }, "updated_after": { "type": "string", "description": "The filter to return results with their `calculated_at` value\nafter the given time as specified in an RFC 3339 timestamp.\nThe default value is the UNIX epoch of (`1970-01-01T00:00:00Z`)." }, "cursor": { "type": "string", "description": "A pagination cursor returned by a previous call to this endpoint.\nProvide this to retrieve the next set of results for the original query.\n\nSee the [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination) guide for more information." }, "states": { "type": "array", "items": { "type": "string" }, "description": "The filter to return results by `InventoryState`. The filter is only applicable when set.\nIgnored are untracked states of `NONE`, `SOLD`, and `UNLINKED_RETURN`.\nThe default is null." }, "limit": { "maximum": 1000, "minimum": 1, "type": "integer", "description": "The number of [records](https://developer.squareup.com/reference/square_2024-10-17/objects/InventoryCount) to return." } }, "description": "", "x-release-status": "PUBLIC", "example": { "request_body": { "catalog_object_ids": [ "W62UWFY35CWMYGVWK6TWJDNI" ], "location_ids": [ "59TNP9SA8VGDA" ], "updated_after": "2016-11-16T00:00:00.000Z" } }, "x-sq-sdk-sample-code": { "python": "/sdk_samples/Inventory/BatchRetrieveInventoryCounts/BatchRetrieveInventoryCountsRequest.python", "csharp": "/sdk_samples/Inventory/BatchRetrieveInventoryCounts/BatchRetrieveInventoryCountsRequest.csharp", "java": "/sdk_samples/Inventory/BatchRetrieveInventoryCounts/BatchRetrieveInventoryCountsRequest.java", "php": "/sdk_samples/Inventory/BatchRetrieveInventoryCounts/BatchRetrieveInventoryCountsRequest.php", "javascript": "/sdk_samples/Inventory/BatchRetrieveInventoryCounts/BatchRetrieveInventoryCountsRequest.javascript", "ruby": "/sdk_samples/Inventory/BatchRetrieveInventoryCounts/BatchRetrieveInventoryCountsRequest.ruby" } }, "BatchRetrieveInventoryCountsResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Any errors that occurred during the request." }, "counts": { "type": "array", "items": { "$ref": "#/definitions/InventoryCount" }, "description": "The current calculated inventory counts for the requested objects\nand locations." }, "cursor": { "type": "string", "description": "The pagination cursor to be used in a subsequent request. If unset,\nthis is the final response.\n\nSee the [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination) guide for more information." } }, "description": "", "x-release-status": "PUBLIC", "example": { "errors": [], "counts": [ { "catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI", "catalog_object_type": "ITEM_VARIATION", "state": "IN_STOCK", "location_id": "59TNP9SA8VGDA", "quantity": "79", "calculated_at": "2016-11-16T22:28:01.223Z" } ] } }, "BatchRetrieveOrdersRequest": { "type": "object", "required": [ "order_ids" ], "properties": { "location_id": { "type": "string", "description": "The ID of the location for these orders. This field is optional: omit it to retrieve\norders within the scope of the current authorization\u0027s merchant ID." }, "order_ids": { "type": "array", "items": { "minLength": 1, "type": "string" }, "description": "The IDs of the orders to retrieve. A maximum of 100 orders can be retrieved per request." } }, "description": "Defines the fields that are included in requests to the\n`BatchRetrieveOrders` endpoint.", "x-release-status": "PUBLIC", "example": { "request_body": { "location_id": "057P5VYJ4A5X1", "order_ids": [ "CAISEM82RcpmcFBM0TfOyiHV3es", "CAISENgvlJ6jLWAzERDzjyHVybY" ] } } }, "BatchRetrieveOrdersResponse": { "type": "object", "properties": { "orders": { "type": "array", "items": { "$ref": "#/definitions/Order" }, "description": "The requested orders. This will omit any requested orders that do not exist." }, "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Any errors that occurred during the request." } }, "description": "Defines the fields that are included in the response body of\na request to the `BatchRetrieveOrders` endpoint.", "x-release-status": "PUBLIC", "example": { "orders": [ { "id": "CAISEM82RcpmcFBM0TfOyiHV3es", "location_id": "057P5VYJ4A5X1", "reference_id": "my-order-001", "line_items": [ { "uid": "945986d1-9586-11e6-ad5a-28cfe92138cf", "name": "Awesome product", "quantity": "1", "base_price_money": { "amount": 1599, "currency": "USD" }, "total_money": { "amount": 1599, "currency": "USD" } }, { "uid": "a8f4168c-9586-11e6-bdf0-28cfe92138cf", "name": "Another awesome product", "quantity": "3", "base_price_money": { "amount": 2000, "currency": "USD" }, "total_money": { "amount": 6000, "currency": "USD" } } ], "total_money": { "amount": 7599, "currency": "USD" } } ] } }, "BatchUpsertCatalogObjectsRequest": { "type": "object", "required": [ "idempotency_key", "batches" ], "properties": { "idempotency_key": { "minLength": 1, "type": "string", "description": "A value you specify that uniquely identifies this\nrequest among all your requests. A common way to create\na valid idempotency key is to use a Universally unique\nidentifier (UUID).\n\nIf you\u0027re unsure whether a particular request was successful,\nyou can reattempt it with the same idempotency key without\nworrying about creating duplicate objects.\n\nSee [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) for more information." }, "batches": { "type": "array", "items": { "$ref": "#/definitions/CatalogObjectBatch" }, "description": "A batch of CatalogObjects to be inserted/updated atomically.\nThe objects within a batch will be inserted in an all-or-nothing fashion, i.e., if an error occurs\nattempting to insert or update an object within a batch, the entire batch will be rejected. However, an error\nin one batch will not affect other batches within the same request.\n\nFor each object, its `updated_at` field is ignored and replaced with a current [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates), and its\n`is_deleted` field must not be set to `true`.\n\nTo modify an existing object, supply its ID. To create a new object, use an ID starting\nwith `#`. These IDs may be used to create relationships between an object and attributes of\nother objects that reference it. For example, you can create a CatalogItem with\nID `#ABC` and a CatalogItemVariation with its `item_id` attribute set to\n`#ABC` in order to associate the CatalogItemVariation with its parent\nCatalogItem.\n\nAny `#`-prefixed IDs are valid only within a single atomic batch, and will be replaced by server-generated IDs.\n\nEach batch may contain up to 1,000 objects. The total number of objects across all batches for a single request\nmay not exceed 10,000. If either of these limits is violated, an error will be returned and no objects will\nbe inserted or updated." } }, "description": "", "x-release-status": "PUBLIC", "example": { "request_body": { "idempotency_key": "789ff020-f723-43a9-b4b5-43b5dc1fa3dc", "batches": [ { "objects": [ { "type": "ITEM", "id": "#Tea", "present_at_all_locations": true, "item_data": { "name": "Tea", "description_html": "\u003cp\u003e\u003cstrong\u003eHot\u003c/strong\u003e Leaf Juice\u003c/p\u003e", "categories": [ { "id": "#Beverages" } ], "tax_ids": [ "#SalesTax" ], "variations": [ { "type": "ITEM_VARIATION", "id": "#Tea_Mug", "present_at_all_locations": true, "item_variation_data": { "item_id": "#Tea", "name": "Mug", "pricing_type": "FIXED_PRICING", "price_money": { "amount": 150, "currency": "USD" } } } ] } }, { "type": "ITEM", "id": "#Coffee", "present_at_all_locations": true, "item_data": { "name": "Coffee", "description_html": "\u003cp\u003eHot \u003cem\u003eBean Juice\u003c/em\u003e\u003c/p\u003e", "categories": [ { "id": "#Beverages" } ], "tax_ids": [ "#SalesTax" ], "variations": [ { "type": "ITEM_VARIATION", "id": "#Coffee_Regular", "present_at_all_locations": true, "item_variation_data": { "item_id": "#Coffee", "name": "Regular", "pricing_type": "FIXED_PRICING", "price_money": { "amount": 250, "currency": "USD" } } }, { "type": "ITEM_VARIATION", "id": "#Coffee_Large", "present_at_all_locations": true, "item_variation_data": { "item_id": "#Coffee", "name": "Large", "pricing_type": "FIXED_PRICING", "price_money": { "amount": 350, "currency": "USD" } } } ] } }, { "type": "CATEGORY", "id": "#Beverages", "present_at_all_locations": true, "category_data": { "name": "Beverages" } }, { "type": "TAX", "id": "#SalesTax", "present_at_all_locations": true, "tax_data": { "name": "Sales Tax", "calculation_phase": "TAX_SUBTOTAL_PHASE", "inclusion_type": "ADDITIVE", "percentage": "5.0", "applies_to_custom_amounts": true, "enabled": true } } ] } ] } }, "x-sq-sdk-sample-code": { "python": "/sdk_samples/Catalog/BatchUpsertCatalogObjects/BatchUpsertCatalogObjectsRequest.python", "csharp": "/sdk_samples/Catalog/BatchUpsertCatalogObjects/BatchUpsertCatalogObjectsRequest.csharp", "java": "/sdk_samples/Catalog/BatchUpsertCatalogObjects/BatchUpsertCatalogObjectsRequest.java", "php": "/sdk_samples/Catalog/BatchUpsertCatalogObjects/BatchUpsertCatalogObjectsRequest.php", "javascript": "/sdk_samples/Catalog/BatchUpsertCatalogObjects/BatchUpsertCatalogObjectsRequest.javascript", "ruby": "/sdk_samples/Catalog/BatchUpsertCatalogObjects/BatchUpsertCatalogObjectsRequest.ruby" } }, "BatchUpsertCatalogObjectsResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Any errors that occurred during the request." }, "objects": { "type": "array", "items": { "$ref": "#/definitions/CatalogObject" }, "description": "The created successfully created CatalogObjects." }, "updated_at": { "type": "string", "description": "The database [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates) of this update in RFC 3339 format, e.g., \"2016-09-04T23:59:33.123Z\"." }, "id_mappings": { "type": "array", "items": { "$ref": "#/definitions/CatalogIdMapping" }, "description": "The mapping between client and server IDs for this upsert." } }, "description": "", "x-release-status": "PUBLIC", "example": { "objects": [ { "type": "ITEM", "id": "67GA7XA2FWMRYY2VCONTYZJR", "updated_at": "2023-11-30T19:24:35.4Z", "created_at": "2023-11-30T19:24:35.4Z", "version": 1701372275400, "is_deleted": false, "present_at_all_locations": true, "item_data": { "name": "Tea", "description": "Hot Leaf Juice", "is_taxable": true, "tax_ids": [ "HP5VNYPKZKTNCKZ2Z5NPUH6A" ], "variations": [ { "type": "ITEM_VARIATION", "id": "CAJBHUIQH7ONTSZI2KTVOUP6", "updated_at": "2023-11-30T19:24:35.4Z", "created_at": "2023-11-30T19:24:35.4Z", "version": 1701372275400, "is_deleted": false, "present_at_all_locations": true, "item_variation_data": { "item_id": "67GA7XA2FWMRYY2VCONTYZJR", "name": "Mug", "ordinal": 0, "pricing_type": "FIXED_PRICING", "price_money": { "amount": 150, "currency": "USD" }, "sellable": true, "stockable": true } } ], "product_type": "REGULAR", "categories": [ { "id": "XCS4SCGN4WQYE2VU4U3TKXEH", "ordinal": -2251731094208512 } ], "description_html": "\u003cp\u003e\u003cstrong\u003eHot\u003c/strong\u003e Leaf Juice\u003c/p\u003e", "description_plaintext": "Hot Leaf Juice", "is_archived": false } }, { "type": "ITEM", "id": "MQ4TZKOG3SR2EQI3TWEK4AH7", "updated_at": "2023-11-30T19:24:35.4Z", "created_at": "2023-11-30T19:24:35.4Z", "version": 1701372275400, "is_deleted": false, "present_at_all_locations": true, "item_data": { "name": "Coffee", "description": "Hot Bean Juice", "is_taxable": true, "tax_ids": [ "HP5VNYPKZKTNCKZ2Z5NPUH6A" ], "variations": [ { "type": "ITEM_VARIATION", "id": "GY2GXJTVVPQAPW43GFRR3NG6", "updated_at": "2023-11-30T19:24:35.4Z", "created_at": "2023-11-30T19:24:35.4Z", "version": 1701372275400, "is_deleted": false, "present_at_all_locations": true, "item_variation_data": { "item_id": "MQ4TZKOG3SR2EQI3TWEK4AH7", "name": "Regular", "ordinal": 0, "pricing_type": "FIXED_PRICING", "price_money": { "amount": 250, "currency": "USD" }, "sellable": true, "stockable": true } }, { "type": "ITEM_VARIATION", "id": "JE6VHPSRQL6IWSN26C36CJ7W", "updated_at": "2023-11-30T19:24:35.4Z", "created_at": "2023-11-30T19:24:35.4Z", "version": 1701372275400, "is_deleted": false, "present_at_all_locations": true, "item_variation_data": { "item_id": "MQ4TZKOG3SR2EQI3TWEK4AH7", "name": "Large", "ordinal": 1, "pricing_type": "FIXED_PRICING", "price_money": { "amount": 350, "currency": "USD" }, "sellable": true, "stockable": true } } ], "product_type": "REGULAR", "categories": [ { "id": "XCS4SCGN4WQYE2VU4U3TKXEH", "ordinal": -2251662374731776 } ], "description_html": "\u003cp\u003eHot \u003cem\u003eBean Juice\u003c/em\u003e\u003c/p\u003e", "description_plaintext": "Hot Bean Juice", "is_archived": false } }, { "type": "CATEGORY", "id": "XCS4SCGN4WQYE2VU4U3TKXEH", "updated_at": "2023-11-30T19:24:35.4Z", "created_at": "2023-11-30T19:24:35.4Z", "version": 1701372275400, "is_deleted": false, "present_at_all_locations": true, "category_data": { "name": "Beverages", "category_type": "REGULAR_CATEGORY", "parent_category": { "ordinal": -2250837741010944 }, "is_top_level": true, "online_visibility": true } }, { "type": "TAX", "id": "HP5VNYPKZKTNCKZ2Z5NPUH6A", "updated_at": "2023-11-30T19:24:35.4Z", "created_at": "2023-11-30T19:24:35.4Z", "version": 1701372275400, "is_deleted": false, "present_at_all_locations": true, "tax_data": { "name": "Sales Tax", "calculation_phase": "TAX_SUBTOTAL_PHASE", "inclusion_type": "ADDITIVE", "percentage": "5.0", "applies_to_custom_amounts": true, "enabled": true } } ], "id_mappings": [ { "client_object_id": "#Tea", "object_id": "67GA7XA2FWMRYY2VCONTYZJR" }, { "client_object_id": "#Coffee", "object_id": "MQ4TZKOG3SR2EQI3TWEK4AH7" }, { "client_object_id": "#Beverages", "object_id": "XCS4SCGN4WQYE2VU4U3TKXEH" }, { "client_object_id": "#SalesTax", "object_id": "HP5VNYPKZKTNCKZ2Z5NPUH6A" }, { "client_object_id": "#Tea_Mug", "object_id": "CAJBHUIQH7ONTSZI2KTVOUP6" }, { "client_object_id": "#Coffee_Regular", "object_id": "GY2GXJTVVPQAPW43GFRR3NG6" }, { "client_object_id": "#Coffee_Large", "object_id": "JE6VHPSRQL6IWSN26C36CJ7W" } ] }, "x-sq-sdk-sample-code": { "python": "/sdk_samples/Catalog/BatchUpsertCatalogObjects/BatchUpsertCatalogObjectsResponse.python", "csharp": "/sdk_samples/Catalog/BatchUpsertCatalogObjects/BatchUpsertCatalogObjectsResponse.csharp", "java": "/sdk_samples/Catalog/BatchUpsertCatalogObjects/BatchUpsertCatalogObjectsResponse.java", "php": "/sdk_samples/Catalog/BatchUpsertCatalogObjects/BatchUpsertCatalogObjectsResponse.php", "javascript": "/sdk_samples/Catalog/BatchUpsertCatalogObjects/BatchUpsertCatalogObjectsResponse.javascript", "ruby": "/sdk_samples/Catalog/BatchUpsertCatalogObjects/BatchUpsertCatalogObjectsResponse.ruby" } }, "Booking": { "type": "object", "properties": { "id": { "minLength": 0, "maxLength": 36, "type": "string", "description": "A unique ID of this object representing a booking.", "x-read-only": true }, "version": { "minimum": 0, "type": "integer", "description": "The revision number for the booking used for optimistic concurrency." }, "status": { "type": "string", "description": "The status of the booking, describing where the booking stands with respect to the booking state machine.", "x-read-only": true }, "created_at": { "type": "string", "description": "The RFC 3339 timestamp specifying the creation time of this booking.", "x-read-only": true }, "updated_at": { "type": "string", "description": "The RFC 3339 timestamp specifying the most recent update time of this booking.", "x-read-only": true }, "start_at": { "type": "string", "description": "The RFC 3339 timestamp specifying the starting time of this booking." }, "location_id": { "minLength": 0, "maxLength": 32, "type": "string", "description": "The ID of the [Location](https://developer.squareup.com/reference/square_2024-10-17/objects/Location) object representing the location where the booked service is provided. Once set when the booking is created, its value cannot be changed." }, "customer_id": { "minLength": 0, "maxLength": 192, "type": "string", "description": "The ID of the [Customer](https://developer.squareup.com/reference/square_2024-10-17/objects/Customer) object representing the customer receiving the booked service." }, "customer_note": { "minLength": 0, "maxLength": 4096, "type": "string", "description": "The free-text field for the customer to supply notes about the booking. For example, the note can be preferences that cannot be expressed by supported attributes of a relevant [CatalogObject](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogObject) instance." }, "seller_note": { "minLength": 0, "maxLength": 4096, "type": "string", "description": "The free-text field for the seller to supply notes about the booking. For example, the note can be preferences that cannot be expressed by supported attributes of a specific [CatalogObject](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogObject) instance.\nThis field should not be visible to customers." }, "appointment_segments": { "type": "array", "items": { "$ref": "#/definitions/AppointmentSegment" }, "description": "A list of appointment segments for this booking." }, "transition_time_minutes": { "type": "integer", "description": "Additional time at the end of a booking.\nApplications should not make this field visible to customers of a seller.", "x-read-only": true }, "all_day": { "type": "boolean", "description": "Whether the booking is of a full business day.", "x-read-only": true }, "location_type": { "type": "string", "description": "The type of location where the booking is held." }, "creator_details": { "$ref": "#/definitions/BookingCreatorDetails", "description": "Information about the booking creator.", "x-read-only": true }, "source": { "type": "string", "description": "The source of the booking.\nAccess to this field requires seller-level permissions.", "x-read-only": true }, "address": { "$ref": "#/definitions/Address", "description": "Stores a customer address if the location type is `CUSTOMER_LOCATION`." } }, "description": "Represents a booking as a time-bound service contract for a seller\u0027s staff member to provide a specified service\nat a given location to a requesting customer in one or more appointment segments.", "x-release-status": "PUBLIC" }, "BookingCreatorDetails": { "type": "object", "properties": { "creator_type": { "type": "string", "description": "The seller-accessible type of the creator of the booking.", "x-read-only": true }, "team_member_id": { "minLength": 0, "maxLength": 32, "type": "string", "description": "The ID of the team member who created the booking, when the booking creator is of the `TEAM_MEMBER` type.\nAccess to this field requires seller-level permissions.", "x-read-only": true }, "customer_id": { "minLength": 0, "maxLength": 192, "type": "string", "description": "The ID of the customer who created the booking, when the booking creator is of the `CUSTOMER` type.\nAccess to this field requires seller-level permissions.", "x-read-only": true } }, "description": "Information about a booking creator.", "x-release-status": "PUBLIC" }, "BookingCustomAttributeDeleteRequest": { "type": "object", "required": [ "booking_id", "key" ], "properties": { "booking_id": { "minLength": 1, "maxLength": 36, "type": "string", "description": "The ID of the target [booking](https://developer.squareup.com/reference/square_2024-10-17/objects/Booking)." }, "key": { "minLength": 1, "type": "string", "description": "The key of the custom attribute to delete. This key must match the `key` of a\ncustom attribute definition in the Square seller account. If the requesting application is not\nthe definition owner, you must use the qualified key." } }, "description": "Represents an individual delete request in a [BulkDeleteBookingCustomAttributes](https://developer.squareup.com/reference/square_2024-10-17/booking-custom-attributes-api/bulk-delete-booking-custom-attributes)\nrequest. An individual request contains a booking ID, the custom attribute to delete, and an optional idempotency key.", "x-release-status": "PUBLIC", "example": { "booking_id": "Z57QXKM2FGXEQDV42W8RBZY7BR", "key": "favoriteShampoo" } }, "BookingCustomAttributeDeleteResponse": { "type": "object", "properties": { "booking_id": { "type": "string", "description": "The ID of the [booking](https://developer.squareup.com/reference/square_2024-10-17/objects/Booking) associated with the custom attribute." }, "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Any errors that occurred while processing the individual request." } }, "description": "Represents a response for an individual upsert request in a [BulkDeleteBookingCustomAttributes](https://developer.squareup.com/reference/square_2024-10-17/booking-custom-attributes-api/bulk-delete-booking-custom-attributes) operation.", "x-release-status": "PUBLIC", "example": { "booking_id": "N3NCVYY3WS27HF0HKANA3R9FP8", "errors": [] } }, "BookingCustomAttributeUpsertRequest": { "type": "object", "required": [ "booking_id", "custom_attribute" ], "properties": { "booking_id": { "minLength": 1, "maxLength": 36, "type": "string", "description": "The ID of the target [booking](https://developer.squareup.com/reference/square_2024-10-17/objects/Booking)." }, "custom_attribute": { "$ref": "#/definitions/CustomAttribute", "description": "The custom attribute to create or update, with following fields:\n\n- `key`. This key must match the `key` of a custom attribute definition in the Square seller\naccount. If the requesting application is not the definition owner, you must provide the qualified key.\n\n- `value`. This value must conform to the `schema` specified by the definition.\nFor more information, see [Value data types](https://developer.squareup.com/docs/booking-custom-attributes-api/custom-attributes#value-data-types).\n\n- `version`. To enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)\ncontrol for update operations, include this optional field in the request and set the\nvalue to the current version of the custom attribute." }, "idempotency_key": { "maxLength": 45, "type": "string", "description": "A unique identifier for this individual upsert request, used to ensure idempotency.\nFor more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)." } }, "description": "Represents an individual upsert request in a [BulkUpsertBookingCustomAttributes](https://developer.squareup.com/reference/square_2024-10-17/booking-custom-attributes-api/bulk-upsert-booking-custom-attributes)\nrequest. An individual request contains a booking ID, the custom attribute to create or update,\nand an optional idempotency key.", "x-release-status": "PUBLIC", "example": { "custom_attribute": { "key": "favoriteShampoo", "visibility": "VISIBILITY_READ_WRITE_VALUES", "value": "Spring Fresh" } } }, "BookingCustomAttributeUpsertResponse": { "type": "object", "properties": { "booking_id": { "type": "string", "description": "The ID of the [booking](https://developer.squareup.com/reference/square_2024-10-17/objects/Booking) associated with the custom attribute." }, "custom_attribute": { "$ref": "#/definitions/CustomAttribute", "description": "The new or updated custom attribute." }, "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Any errors that occurred while processing the individual request." } }, "description": "Represents a response for an individual upsert request in a [BulkUpsertBookingCustomAttributes](https://developer.squareup.com/reference/square_2024-10-17/booking-custom-attributes-api/bulk-upsert-booking-custom-attributes) operation.", "x-release-status": "PUBLIC", "example": { "custom_attribute": { "key": "favoriteShampoo", "version": 1, "visibility": "VISIBILITY_READ_WRITE_VALUES", "updated_at": "2022-11-16T00:16:23Z", "value": "Spring Fresh", "created_at": "2022-11-16T00:14:47Z" }, "errors": [] } }, "Break": { "type": "object", "required": [ "start_at", "break_type_id", "name", "expected_duration", "is_paid" ], "properties": { "id": { "type": "string", "description": "The UUID for this object." }, "start_at": { "minLength": 1, "type": "string", "description": "RFC 3339; follows the same timezone information as `Shift`. Precision up to\nthe minute is respected; seconds are truncated." }, "end_at": { "type": "string", "description": "RFC 3339; follows the same timezone information as `Shift`. Precision up to\nthe minute is respected; seconds are truncated." }, "break_type_id": { "minLength": 1, "type": "string", "description": "The `BreakType` that this `Break` was templated on." }, "name": { "minLength": 1, "type": "string", "description": "A human-readable name." }, "expected_duration": { "minLength": 1, "type": "string", "description": "Format: RFC-3339 P[n]Y[n]M[n]DT[n]H[n]M[n]S. The expected length of\nthe break." }, "is_paid": { "type": "boolean", "description": "Whether this break counts towards time worked for compensation\npurposes." } }, "description": "A record of an employee\u0027s break during a shift.", "x-release-status": "PUBLIC" }, "BreakType": { "type": "object", "required": [ "location_id", "break_name", "expected_duration", "is_paid" ], "properties": { "id": { "maxLength": 255, "type": "string", "description": "The UUID for this object." }, "location_id": { "minLength": 1, "type": "string", "description": "The ID of the business location this type of break applies to." }, "break_name": { "minLength": 1, "type": "string", "description": "A human-readable name for this type of break. The name is displayed to\nemployees in Square products." }, "expected_duration": { "minLength": 1, "type": "string", "description": "Format: RFC-3339 P[n]Y[n]M[n]DT[n]H[n]M[n]S. The expected length of\nthis break. Precision less than minutes is truncated.\n\nExample for break expected duration of 15 minutes: T15M" }, "is_paid": { "type": "boolean", "description": "Whether this break counts towards time worked for compensation\npurposes." }, "version": { "type": "integer", "description": "Used for resolving concurrency issues. The request fails if the version\nprovided does not match the server version at the time of the request. If a value is not\nprovided, Square\u0027s servers execute a \"blind\" write; potentially\noverwriting another writer\u0027s data." }, "created_at": { "type": "string", "description": "A read-only timestamp in RFC 3339 format.", "x-read-only": true }, "updated_at": { "type": "string", "description": "A read-only timestamp in RFC 3339 format.", "x-read-only": true } }, "description": "A defined break template that sets an expectation for possible `Break`\ninstances on a `Shift`.", "x-release-status": "PUBLIC" }, "BulkCreateCustomerData": { "type": "object", "properties": { "given_name": { "maxLength": 300, "type": "string", "description": "The given name (that is, the first name) associated with the customer profile." }, "family_name": { "maxLength": 300, "type": "string", "description": "The family name (that is, the last name) associated with the customer profile." }, "company_name": { "maxLength": 500, "type": "string", "description": "A business name associated with the customer profile." }, "nickname": { "maxLength": 100, "type": "string", "description": "A nickname for the customer profile." }, "email_address": { "maxLength": 254, "type": "string", "description": "The email address associated with the customer profile." }, "address": { "$ref": "#/definitions/Address", "description": "The physical address associated with the customer profile. For maximum length constraints,\nsee [Customer addresses](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#address).\nThe `first_name` and `last_name` fields are ignored if they are present in the request." }, "phone_number": { "type": "string", "description": "The phone number associated with the customer profile. The phone number must be valid\nand can contain 9–16 digits, with an optional `+` prefix and country code. For more information,\nsee [Customer phone numbers](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#phone-number)." }, "reference_id": { "maxLength": 100, "type": "string", "description": "An optional second ID used to associate the customer profile with an\nentity in another system." }, "note": { "type": "string", "description": "A custom note associated with the customer profile." }, "birthday": { "type": "string", "description": "The birthday associated with the customer profile, in `YYYY-MM-DD` or `MM-DD` format.\nFor example, specify `1998-09-21` for September 21, 1998, or `09-21` for September 21.\nBirthdays are returned in `YYYY-MM-DD` format, where `YYYY` is the specified birth year or\n`0000` if a birth year is not specified." }, "tax_ids": { "$ref": "#/definitions/CustomerTaxIds", "description": "The tax ID associated with the customer profile. This field is available only for\ncustomers of sellers in EU countries or the United Kingdom. For more information, see\n[Customer tax IDs](https://developer.squareup.com/docs/customers-api/what-it-does#customer-tax-ids)." } }, "description": "Defines the customer data provided in individual create requests for a\n[BulkCreateCustomers](https://developer.squareup.com/reference/square_2024-10-17/customers-api/bulk-create-customers) operation.", "x-release-status": "PUBLIC" }, "BulkCreateCustomersRequest": { "type": "object", "required": [ "customers" ], "properties": { "customers": { "type": "object", "additionalProperties": { "$ref": "#/definitions/BulkCreateCustomerData" }, "description": "A map of 1 to 100 individual create requests, represented by `idempotency key: { customer data }`\nkey-value pairs.\n\nEach key is an [idempotency key](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)\nthat uniquely identifies the create request. Each value contains the customer data used to create the\ncustomer profile." } }, "description": "Defines the body parameters that can be included in requests to the\n[BulkCreateCustomers](https://developer.squareup.com/reference/square_2024-10-17/customers-api/bulk-create-customers) endpoint.", "x-release-status": "PUBLIC", "example": { "request_body": { "customers": { "8bb76c4f-e35d-4c5b-90de-1194cd9179f0": { "given_name": "Amelia", "family_name": "Earhart", "email_address": "Amelia.Earhart@example.com", "address": { "address_line_1": "500 Electric Ave", "address_line_2": "Suite 600", "locality": "New York", "administrative_district_level_1": "NY", "postal_code": "10003", "country": "US" }, "phone_number": "+1-212-555-4240", "reference_id": "YOUR_REFERENCE_ID", "note": "a customer" }, "d1689f23-b25d-4932-b2f0-aed00f5e2029": { "given_name": "Marie", "family_name": "Curie", "email_address": "Marie.Curie@example.com", "address": { "address_line_1": "500 Electric Ave", "address_line_2": "Suite 601", "locality": "New York", "administrative_district_level_1": "NY", "postal_code": "10003", "country": "US" }, "phone_number": "+1-212-444-4240", "reference_id": "YOUR_REFERENCE_ID", "note": "another customer" } } } } }, "BulkCreateCustomersResponse": { "type": "object", "properties": { "responses": { "type": "object", "additionalProperties": { "$ref": "#/definitions/CreateCustomerResponse" }, "description": "A map of responses that correspond to individual create requests, represented by\nkey-value pairs.\n\nEach key is the idempotency key that was provided for a create request and each value\nis the corresponding response.\nIf the request succeeds, the value is the new customer profile.\nIf the request fails, the value contains any errors that occurred during the request." }, "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Any top-level errors that prevented the bulk operation from running." } }, "description": "Defines the fields included in the response body from the\n[BulkCreateCustomers](https://developer.squareup.com/reference/square_2024-10-17/customers-api/bulk-create-customers) endpoint.", "x-release-status": "PUBLIC", "example": { "responses": { "8bb76c4f-e35d-4c5b-90de-1194cd9179f4": { "customer": { "id": "8DDA5NZVBZFGAX0V3HPF81HHE0", "created_at": "2024-03-23T20:21:54.859Z", "updated_at": "2024-03-23T20:21:54.859Z", "given_name": "Amelia", "family_name": "Earhart", "email_address": "Amelia.Earhart@example.com", "address": { "address_line_1": "500 Electric Ave", "address_line_2": "Suite 600", "locality": "New York", "administrative_district_level_1": "NY", "postal_code": "10003", "country": "US" }, "phone_number": "+1-212-555-4240", "reference_id": "YOUR_REFERENCE_ID", "note": "a customer", "preferences": { "email_unsubscribed": false }, "creation_source": "THIRD_PARTY", "version": 0 } }, "d1689f23-b25d-4932-b2f0-aed00f5e2029": { "customer": { "id": "N18CPRVXR5214XPBBA6BZQWF3C", "created_at": "2024-03-23T20:21:54.859Z", "updated_at": "2024-03-23T20:21:54.859Z", "given_name": "Marie", "family_name": "Curie", "email_address": "Marie.Curie@example.com", "address": { "address_line_1": "500 Electric Ave", "address_line_2": "Suite 601", "locality": "New York", "administrative_district_level_1": "NY", "postal_code": "10003", "country": "US" }, "phone_number": "+1-212-444-4240", "reference_id": "YOUR_REFERENCE_ID", "note": "another customer", "preferences": { "email_unsubscribed": false }, "creation_source": "THIRD_PARTY", "version": 0 } } } } }, "BulkCreateTeamMembersRequest": { "type": "object", "required": [ "team_members" ], "properties": { "team_members": { "type": "object", "additionalProperties": { "$ref": "#/definitions/CreateTeamMemberRequest" }, "description": "The data used to create the `TeamMember` objects. Each key is the `idempotency_key` that maps to the `CreateTeamMemberRequest`. The maximum number of create objects is 25." } }, "description": "Represents a bulk create request for `TeamMember` objects.", "x-release-status": "PUBLIC", "example": { "request_body": { "team_members": { "idempotency-key-1": { "team_member": { "given_name": "Joe", "family_name": "Doe", "email_address": "joe_doe@gmail.com", "reference_id": "reference_id_1", "phone_number": "+14159283333", "assigned_locations": { "location_ids": [ "YSGH2WBKG94QZ", "GA2Y9HSJ8KRYT" ], "assignment_type": "EXPLICIT_LOCATIONS" } } }, "idempotency-key-2": { "team_member": { "given_name": "Jane", "family_name": "Smith", "email_address": "jane_smith@gmail.com", "reference_id": "reference_id_2", "phone_number": "+14159223334", "assigned_locations": { "assignment_type": "ALL_CURRENT_AND_FUTURE_LOCATIONS" } } } } } } }, "BulkCreateTeamMembersResponse": { "type": "object", "properties": { "team_members": { "type": "object", "additionalProperties": { "$ref": "#/definitions/CreateTeamMemberResponse" }, "description": "The successfully created `TeamMember` objects. Each key is the `idempotency_key` that maps to the `CreateTeamMemberRequest`." }, "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "The errors that occurred during the request." } }, "description": "Represents a response from a bulk create request containing the created `TeamMember` objects or error messages.", "x-release-status": "PUBLIC", "example": { "team_members": { "idempotency-key-1": { "team_member": { "id": "ywhG1qfIOoqsHfVRubFV", "reference_id": "reference_id_1", "is_owner": false, "status": "ACTIVE", "given_name": "Joe", "family_name": "Doe", "email_address": "joe_doe@gmail.com", "phone_number": "+14159283333", "assigned_locations": { "assignment_type": "EXPLICIT_LOCATIONS", "location_ids": [ "GA2Y9HSJ8KRYT", "YSGH2WBKG94QZ" ] } } }, "idempotency-key-2": { "team_member": { "id": "IF_Ncrg7fHhCqxVI9T6R", "reference_id": "reference_id_2", "is_owner": false, "status": "ACTIVE", "given_name": "Jane", "family_name": "Smith", "email_address": "jane_smith@gmail.com", "phone_number": "+14159223334", "assigned_locations": { "assignment_type": "ALL_CURRENT_AND_FUTURE_LOCATIONS" } } } } } }, "BulkCreateVendorsRequest": { "type": "object", "required": [ "vendors" ], "properties": { "vendors": { "type": "object", "additionalProperties": { "$ref": "#/definitions/Vendor" }, "description": "Specifies a set of new [Vendor](https://developer.squareup.com/reference/square_2024-10-17/objects/Vendor) objects as represented by a collection of idempotency-key/`Vendor`-object pairs." } }, "description": "Represents an input to a call to [BulkCreateVendors](https://developer.squareup.com/reference/square_2024-10-17/vendors-api/bulk-create-vendors).", "x-release-status": "BETA", "x-is-beta": true, "example": { "request_body": { "vendors": { "8fc6a5b0-9fe8-4b46-b46b-2ef95793abbe": { "name": "Joe\u0027s Fresh Seafood", "address": { "address_line_1": "505 Electric Ave", "address_line_2": "Suite 600", "locality": "New York", "administrative_district_level_1": "NY", "postal_code": "10003", "country": "US" }, "contacts": [ { "name": "Joe Burrow", "email_address": "joe@joesfreshseafood.com", "phone_number": "1-212-555-4250" } ], "account_number": "4025391", "note": "a vendor" } }, "47bb76a8-c9fb-4f33-9df8-25ce02ca4505": { "name": "Annie’s Hot Sauce", "contacts": [ { "name": "Annie Thomas", "email_address": "annie@annieshotsauce.com", "phone_number": "1-212-555-4250" } ] } } } }, "BulkCreateVendorsResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Any errors that occurred during the request." }, "responses": { "type": "object", "additionalProperties": { "$ref": "#/definitions/CreateVendorResponse" }, "description": "A set of [CreateVendorResponse](https://developer.squareup.com/reference/square_2024-10-17/objects/CreateVendorResponse) objects encapsulating successfully created [Vendor](https://developer.squareup.com/reference/square_2024-10-17/objects/Vendor)\nobjects or error responses for failed attempts. The set is represented by \na collection of idempotency-key/`Vendor`-object or idempotency-key/error-object pairs. The idempotency keys correspond to those specified\nin the input." } }, "description": "Represents an output from a call to [BulkCreateVendors](https://developer.squareup.com/reference/square_2024-10-17/vendors-api/bulk-create-vendors).", "x-release-status": "BETA", "x-is-beta": true, "example": { "errors": [], "vendors": { "8fc6a5b0-9fe8-4b46-b46b-2ef95793abbe": { "vendor": { "id": "INV_V_JDKYHBWT1D4F8MFH63DBMEN8Y4", "created_at": "2022-03-16T10:21:54.859Z", "updated_at": "2022-03-16T10:21:54.859Z", "name": "Joe\u0027s Fresh Seafood", "address": { "address_line_1": "505 Electric Ave", "address_line_2": "Suite 600", "locality": "New York", "administrative_district_level_1": "NY", "postal_code": "10003", "country": "US" }, "contacts": [ { "id": "INV_VC_FMCYHBWT1TPL8MFH52PBMEN92A", "name": "Joe Burrow", "email_address": "joe@joesfreshseafood.com", "phone_number": "1-212-555-4250" } ], "account_number": "4025391", "note": "a vendor", "version": 0, "status": "ACTIVE" } } }, "47bb76a8-c9fb-4f33-9df8-25ce02ca4505": { "vendor": { "id": "INV_V_FMCYHBWT1TPL8MFH52PBMEN92A", "created_at": "2022-03-16T10:21:54.859Z", "updated_at": "2022-03-16T10:21:54.859Z", "name": "Annie’s Hot Sauce", "contacts": [ { "id": "INV_VC_ABYYHBWT1TPL8MFH52PBMENPJ4", "name": "Annie Thomas", "email_address": "annie@annieshotsauce.com", "phone_number": "1-212-555-4250" } ], "version": 1, "status": "ACTIVE" } } } }, "BulkDeleteBookingCustomAttributesRequest": { "type": "object", "required": [ "values" ], "properties": { "values": { "type": "object", "additionalProperties": { "$ref": "#/definitions/BookingCustomAttributeDeleteRequest" }, "description": "A map containing 1 to 25 individual Delete requests. For each request, provide an\narbitrary ID that is unique for this `BulkDeleteBookingCustomAttributes` request and the\ninformation needed to delete a custom attribute." } }, "description": "Represents a [BulkDeleteBookingCustomAttributes](https://developer.squareup.com/reference/square_2024-10-17/booking-custom-attributes-api/bulk-delete-booking-custom-attributes) request.", "x-release-status": "PUBLIC", "example": { "values": { "id1": { "key": "favoriteShampoo", "booking_id": "N3NCVYY3WS27HF0HKANA3R9FP8" }, "id2": { "key": "ownsShampoo", "booking_id": "SY8EMWRNDN3TQDP2H4KS1QWMMM" }, "id3": { "key": "favoriteShampoo", "booking_id": "SY8EMWRNDN3TQDP2H4KS1QWMMM" } } } }, "BulkDeleteBookingCustomAttributesResponse": { "type": "object", "properties": { "values": { "type": "object", "additionalProperties": { "$ref": "#/definitions/BookingCustomAttributeDeleteResponse" }, "description": "A map of responses that correspond to individual delete requests. Each response has the\nsame ID as the corresponding request and contains `booking_id` and `errors` field." }, "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Any errors that occurred during the request." } }, "description": "Represents a [BulkDeleteBookingCustomAttributes](https://developer.squareup.com/reference/square_2024-10-17/booking-custom-attributes-api/bulk-delete-booking-custom-attributes) response,\nwhich contains a map of responses that each corresponds to an individual delete request.", "x-release-status": "PUBLIC", "example": { "values": { "id1": { "booking_id": "N3NCVYY3WS27HF0HKANA3R9FP8", "errors": [] }, "id2": { "booking_id": "SY8EMWRNDN3TQDP2H4KS1QWMMM", "errors": [] }, "id3": { "booking_id": "SY8EMWRNDN3TQDP2H4KS1QWMMM", "errors": [] } }, "errors": [] } }, "BulkDeleteCustomersRequest": { "type": "object", "required": [ "customer_ids" ], "properties": { "customer_ids": { "type": "array", "items": { "type": "string" }, "description": "The IDs of the [customer profiles](https://developer.squareup.com/reference/square_2024-10-17/objects/Customer) to delete." } }, "description": "Defines the body parameters that can be included in requests to the\n[BulkDeleteCustomers](https://developer.squareup.com/reference/square_2024-10-17/customers-api/bulk-delete-customers) endpoint.", "x-release-status": "PUBLIC", "example": { "request_body": { "customer_ids": [ "8DDA5NZVBZFGAX0V3HPF81HHE0", "N18CPRVXR5214XPBBA6BZQWF3C", "2GYD7WNXF7BJZW1PMGNXZ3Y8M8" ] } } }, "BulkDeleteCustomersResponse": { "type": "object", "properties": { "responses": { "type": "object", "additionalProperties": { "$ref": "#/definitions/DeleteCustomerResponse" }, "description": "A map of responses that correspond to individual delete requests, represented by\nkey-value pairs.\n\nEach key is the customer ID that was specified for a delete request and each value\nis the corresponding response.\nIf the request succeeds, the value is an empty object (`{ }`).\nIf the request fails, the value contains any errors that occurred during the request." }, "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Any top-level errors that prevented the bulk operation from running." } }, "description": "Defines the fields included in the response body from the\n[BulkDeleteCustomers](https://developer.squareup.com/reference/square_2024-10-17/customers-api/bulk-delete-customers) endpoint.", "x-release-status": "PUBLIC", "example": { "responses": { "8DDA5NZVBZFGAX0V3HPF81HHE0": {}, "2GYD7WNXF7BJZW1PMGNXZ3Y8M8": { "errors": [ { "code": "NOT_FOUND", "detail": "Customer with ID `2GYD7WNXF7BJZW1PMGNXZ3Y8M8` not found.", "category": "INVALID_REQUEST_ERROR" } ] }, "N18CPRVXR5214XPBBA6BZQWF3C": {} } } }, "BulkDeleteLocationCustomAttributesRequest": { "type": "object", "required": [ "values" ], "properties": { "values": { "type": "object", "additionalProperties": { "$ref": "#/definitions/LocationCustomAttributeDeleteRequest" }, "description": "The data used to update the `CustomAttribute` objects.\nThe keys must be unique and are used to map to the corresponding response." } }, "description": "Represents a [BulkDeleteLocationCustomAttributes](https://developer.squareup.com/reference/square_2024-10-17/location-custom-attributes-api/bulk-delete-location-custom-attributes) request.", "x-release-status": "BETA", "x-is-beta": true, "example": { "request_body": { "values": { "id1": { "location_id": "L0TBCBTB7P8RQ", "key": "bestseller" }, "id2": { "location_id": "L9XMD04V3STJX", "key": "bestseller" }, "id3": { "location_id": "L0TBCBTB7P8RQ", "key": "phone-number" } } } } }, "BulkDeleteLocationCustomAttributesRequestLocationCustomAttributeDeleteRequest": { "type": "object", "properties": { "key": { "pattern": "^([a-zA-Z0-9_-]+:)?[a-zA-Z0-9_-]{1,60}$", "type": "string", "description": "The key of the associated custom attribute definition.\nRepresented as a qualified key if the requesting app is not the definition owner.", "x-read-only": true } }, "description": "Represents an individual delete request in a [BulkDeleteLocationCustomAttributes](https://developer.squareup.com/reference/square_2024-10-17/location-custom-attributes-api/bulk-delete-location-custom-attributes)\nrequest. An individual request contains an optional ID of the associated custom attribute definition\nand optional key of the associated custom attribute definition.", "x-release-status": "BETA", "x-is-beta": true }, "BulkDeleteLocationCustomAttributesResponse": { "type": "object", "required": [ "values" ], "properties": { "values": { "type": "object", "additionalProperties": { "$ref": "#/definitions/LocationCustomAttributeDeleteResponse" }, "description": "A map of responses that correspond to individual delete requests. Each response has the\nsame key as the corresponding request." }, "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Any errors that occurred during the request." } }, "description": "Represents a [BulkDeleteLocationCustomAttributes](https://developer.squareup.com/reference/square_2024-10-17/location-custom-attributes-api/bulk-delete-location-custom-attributes) response,\nwhich contains a map of responses that each corresponds to an individual delete request.", "x-release-status": "BETA", "x-is-beta": true, "example": { "values": { "id1": { "location_id": "L0TBCBTB7P8RQ", "errors": [] }, "id2": { "location_id": "L9XMD04V3STJX", "errors": [] }, "id3": { "location_id": "L0TBCBTB7P8RQ", "errors": [] } } } }, "BulkDeleteLocationCustomAttributesResponseLocationCustomAttributeDeleteResponse": { "type": "object", "properties": { "location_id": { "type": "string", "description": "The ID of the location associated with the custom attribute." }, "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Errors that occurred while processing the individual LocationCustomAttributeDeleteRequest request" } }, "description": "Represents an individual delete response in a [BulkDeleteLocationCustomAttributes](https://developer.squareup.com/reference/square_2024-10-17/location-custom-attributes-api/bulk-delete-location-custom-attributes)\nrequest.", "x-release-status": "BETA", "x-is-beta": true, "example": { "location_id": "L0TBCBTB7P8RQ", "errors": [] } }, "BulkDeleteMerchantCustomAttributesRequest": { "type": "object", "required": [ "values" ], "properties": { "values": { "type": "object", "additionalProperties": { "$ref": "#/definitions/MerchantCustomAttributeDeleteRequest" }, "description": "The data used to update the `CustomAttribute` objects.\nThe keys must be unique and are used to map to the corresponding response." } }, "description": "Represents a [BulkDeleteMerchantCustomAttributes](https://developer.squareup.com/reference/square_2024-10-17/merchant-custom-attributes-api/bulk-delete-merchant-custom-attributes) request.", "x-release-status": "BETA", "x-is-beta": true, "example": { "request_body": { "values": { "id1": { "merchant_id": "DM7VKY8Q63GNP", "key": "alternative_seller_name" }, "id2": { "merchant_id": "DM7VKY8Q63GNP", "key": "has_seen_tutorial" } } } } }, "BulkDeleteMerchantCustomAttributesRequestMerchantCustomAttributeDeleteRequest": { "type": "object", "properties": { "key": { "pattern": "^([a-zA-Z0-9_-]+:)?[a-zA-Z0-9_-]{1,60}$", "type": "string", "description": "The key of the associated custom attribute definition.\nRepresented as a qualified key if the requesting app is not the definition owner.", "x-read-only": true } }, "description": "Represents an individual delete request in a [BulkDeleteMerchantCustomAttributes](https://developer.squareup.com/reference/square_2024-10-17/merchant-custom-attributes-api/bulk-delete-merchant-custom-attributes)\nrequest. An individual request contains an optional ID of the associated custom attribute definition\nand optional key of the associated custom attribute definition.", "x-release-status": "BETA", "x-is-beta": true }, "BulkDeleteMerchantCustomAttributesResponse": { "type": "object", "required": [ "values" ], "properties": { "values": { "type": "object", "additionalProperties": { "$ref": "#/definitions/MerchantCustomAttributeDeleteResponse" }, "description": "A map of responses that correspond to individual delete requests. Each response has the\nsame key as the corresponding request." }, "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Any errors that occurred during the request." } }, "description": "Represents a [BulkDeleteMerchantCustomAttributes](https://developer.squareup.com/reference/square_2024-10-17/merchant-custom-attributes-api/bulk-delete-merchant-custom-attributes) response,\nwhich contains a map of responses that each corresponds to an individual delete request.", "x-release-status": "BETA", "x-is-beta": true, "example": { "values": { "id1": { "merchant_id": "DM7VKY8Q63GNP", "errors": [] }, "id2": { "merchant_id": "DM7VKY8Q63GNP", "errors": [] } } } }, "BulkDeleteMerchantCustomAttributesResponseMerchantCustomAttributeDeleteResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Errors that occurred while processing the individual MerchantCustomAttributeDeleteRequest request" } }, "description": "Represents an individual delete response in a [BulkDeleteMerchantCustomAttributes](https://developer.squareup.com/reference/square_2024-10-17/merchant-custom-attributes-api/bulk-delete-merchant-custom-attributes)\nrequest.", "x-release-status": "BETA", "x-is-beta": true, "example": { "merchant_id": "DM7VKY8Q63GNP", "errors": [] } }, "BulkDeleteOrderCustomAttributesRequest": { "type": "object", "required": [ "values" ], "properties": { "values": { "type": "object", "additionalProperties": { "$ref": "#/definitions/DeleteCustomAttribute" }, "description": "A map of requests that correspond to individual delete operations for custom attributes." } }, "description": "Represents a bulk delete request for one or more order custom attributes.", "x-release-status": "BETA", "x-is-beta": true, "example": { "request_body": { "values": { "table-number": { "key": "table-number", "order_id": "7BbXGEIWNldxAzrtGf9GPVZTwZ4F" }, "cover-count": { "key": "cover-count", "order_id": "7BbXGEIWNldxAzrtGf9GPVZTwZ4F" } } } } }, "BulkDeleteOrderCustomAttributesRequestDeleteCustomAttribute": { "type": "object", "required": [ "order_id" ], "properties": { "key": { "minLength": 1, "pattern": "^([a-zA-Z0-9_-]+:)?[a-zA-Z0-9_-]{1,60}$", "type": "string", "description": "The key of the custom attribute to delete. This key must match the key \nof an existing custom attribute definition.", "x-read-only": true }, "order_id": { "minLength": 1, "maxLength": 255, "type": "string", "description": "The ID of the target [order](https://developer.squareup.com/reference/square_2024-10-17/objects/Order)." } }, "description": "Represents one delete within the bulk operation.", "x-release-status": "BETA", "x-is-beta": true }, "BulkDeleteOrderCustomAttributesResponse": { "type": "object", "required": [ "values" ], "properties": { "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Any errors that occurred during the request." }, "values": { "type": "object", "additionalProperties": { "$ref": "#/definitions/DeleteOrderCustomAttributeResponse" }, "description": " A map of responses that correspond to individual delete requests. Each response has the same ID \nas the corresponding request and contains either a `custom_attribute` or an `errors` field." } }, "description": "Represents a response from deleting one or more order custom attributes.", "x-release-status": "BETA", "x-is-beta": true, "example": { "values": { "table-number": {}, "cover-count": {} } } }, "BulkRetrieveBookingsRequest": { "type": "object", "required": [ "booking_ids" ], "properties": { "booking_ids": { "type": "array", "items": { "minLength": 1, "maxLength": 36, "type": "string" }, "description": "A non-empty list of [Booking](https://developer.squareup.com/reference/square_2024-10-17/objects/Booking) IDs specifying bookings to retrieve." } }, "description": "Request payload for bulk retrieval of bookings.", "x-release-status": "PUBLIC", "example": { "booking_ids": [ "sc3p3m7dvctfr1", "tdegug1dvctdef", "tdegug1fqni3wh" ] } }, "BulkRetrieveBookingsResponse": { "type": "object", "properties": { "bookings": { "type": "object", "additionalProperties": { "$ref": "#/definitions/RetrieveBookingResponse" }, "description": "Requested bookings returned as a map containing `booking_id` as the key and `RetrieveBookingResponse` as the value." }, "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Errors that occurred during the request." } }, "description": "Response payload for bulk retrieval of bookings.", "x-release-status": "PUBLIC", "example": { "bookings": { "sc3p3m7dvctfr1": { "booking": { "id": "sc3p3m7dvctfr1", "version": 0, "status": "ACCEPTED", "created_at": "2023-04-26T18:19:21Z", "updated_at": "2023-04-26T18:19:21Z", "location_id": "LY6WNBPVM6VGV", "customer_id": "4TDWKN9E8165X8Z77MRS0VFMJM", "start_at": "2023-05-01T14:00:00Z", "all_day": false, "appointment_segments": [ { "duration_minutes": 60, "service_variation_id": "VG4FYBKK3UL6UITOEYQ6MFLS", "team_member_id": "TMjiqI3PxyLMKr4k", "service_variation_version": 1641341724039, "any_team_member": false } ] }, "errors": [] }, "tdegug1dvctdef": { "errors": [ { "category": "INVALID_REQUEST_ERROR", "code": "NOT_FOUND", "detail": "Specified booking was not found.", "field": "booking_id" } ] }, "tdegug1fqni3wh": { "booking": { "id": "tdegug1fqni3wh", "version": 0, "status": "ACCEPTED", "created_at": "2023-04-26T18:19:30Z", "updated_at": "2023-04-26T18:19:30Z", "location_id": "LY6WNBPVM6VGV", "customer_id": "4TDWKN9E8165X8Z77MRS0VFMJM", "start_at": "2023-05-02T14:00:00Z", "all_day": false, "appointment_segments": [ { "duration_minutes": 60, "service_variation_id": "VG4FYBKK3UL6UITOEYQ6MFLS", "team_member_id": "TMjiqI3PxyLMKr4k", "service_variation_version": 1641341724039, "any_team_member": false } ] }, "errors": [] } }, "errors": [] } }, "BulkRetrieveCustomersRequest": { "type": "object", "required": [ "customer_ids" ], "properties": { "customer_ids": { "type": "array", "items": { "type": "string" }, "description": "The IDs of the [customer profiles](https://developer.squareup.com/reference/square_2024-10-17/objects/Customer) to retrieve." } }, "description": "Defines the body parameters that can be included in requests to the\n[BulkRetrieveCustomers](https://developer.squareup.com/reference/square_2024-10-17/customers-api/bulk-retrieve-customers) endpoint.", "x-release-status": "PUBLIC", "example": { "request_body": { "customer_ids": [ "8DDA5NZVBZFGAX0V3HPF81HHE0", "N18CPRVXR5214XPBBA6BZQWF3C", "2GYD7WNXF7BJZW1PMGNXZ3Y8M8" ] } } }, "BulkRetrieveCustomersResponse": { "type": "object", "properties": { "responses": { "type": "object", "additionalProperties": { "$ref": "#/definitions/RetrieveCustomerResponse" }, "description": "A map of responses that correspond to individual retrieve requests, represented by\nkey-value pairs.\n\nEach key is the customer ID that was specified for a retrieve request and each value\nis the corresponding response.\nIf the request succeeds, the value is the requested customer profile.\nIf the request fails, the value contains any errors that occurred during the request." }, "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Any top-level errors that prevented the bulk operation from running." } }, "description": "Defines the fields included in the response body from the\n[BulkRetrieveCustomers](https://developer.squareup.com/reference/square_2024-10-17/customers-api/bulk-retrieve-customers) endpoint.", "x-release-status": "PUBLIC", "example": { "responses": { "8DDA5NZVBZFGAX0V3HPF81HHE0": { "customer": { "id": "8DDA5NZVBZFGAX0V3HPF81HHE0", "created_at": "2024-01-19T00:27:54.59Z", "updated_at": "2024-01-19T00:38:06Z", "given_name": "Amelia", "family_name": "Earhart", "email_address": "New.Amelia.Earhart@example.com", "note": "updated customer note", "preferences": { "email_unsubscribed": false }, "creation_source": "THIRD_PARTY", "birthday": "1897-07-24", "version": 3 } }, "N18CPRVXR5214XPBBA6BZQWF3C": { "customer": { "id": "N18CPRVXR5214XPBBA6BZQWF3C", "created_at": "2024-01-19T00:27:54.59Z", "updated_at": "2024-01-19T00:38:06Z", "given_name": "Marie", "family_name": "Curie", "preferences": { "email_unsubscribed": false }, "creation_source": "THIRD_PARTY", "version": 1 } }, "2GYD7WNXF7BJZW1PMGNXZ3Y8M8": { "errors": [ { "code": "NOT_FOUND", "detail": "Customer with ID `2GYD7WNXF7BJZW1PMGNXZ3Y8M8` not found.", "category": "INVALID_REQUEST_ERROR" } ] } } } }, "BulkRetrieveTeamMemberBookingProfilesRequest": { "type": "object", "required": [ "team_member_ids" ], "properties": { "team_member_ids": { "type": "array", "items": { "minLength": 1, "maxLength": 32, "type": "string" }, "description": "A non-empty list of IDs of team members whose booking profiles you want to retrieve." } }, "description": "Request payload for the [BulkRetrieveTeamMemberBookingProfiles](https://developer.squareup.com/reference/square_2024-10-17/bookings-api/bulk-retrieve-team-member-booking-profiles) endpoint.", "x-release-status": "PUBLIC", "example": { "team_member_ids": [ "TMaJcbiRqPIGZuS9", "TMXUrsBWWcHTt79t", "TMtdegug1fqni3wh" ] } }, "BulkRetrieveTeamMemberBookingProfilesResponse": { "type": "object", "properties": { "team_member_booking_profiles": { "type": "object", "additionalProperties": { "$ref": "#/definitions/RetrieveTeamMemberBookingProfileResponse" }, "description": "The returned team members\u0027 booking profiles, as a map with `team_member_id` as the key and [TeamMemberBookingProfile](https://developer.squareup.com/reference/square_2024-10-17/objects/TeamMemberBookingProfile) the value." }, "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Errors that occurred during the request." } }, "description": "Response payload for the [BulkRetrieveTeamMemberBookingProfiles](https://developer.squareup.com/reference/square_2024-10-17/bookings-api/bulk-retrieve-team-member-booking-profiles) endpoint.", "x-release-status": "PUBLIC", "example": { "team_member_booking_profiles": { "TMaJcbiRqPIGZuS9": { "team_member_booking_profile": { "team_member_id": "TMaJcbiRqPIGZuS9", "display_name": "Sandbox Staff 1", "is_bookable": true }, "errors": [] }, "TMXUrsBWWcHTt79t": { "errors": [ { "category": "INVALID_REQUEST_ERROR", "code": "NOT_FOUND", "detail": "Resource not found." } ] }, "TMtdegug1fqni3wh": { "team_member_booking_profile": { "team_member_id": "TMtdegug1fqni3wh", "display_name": "Sandbox Staff 2", "is_bookable": true }, "errors": [] } }, "errors": [] } }, "BulkRetrieveVendorsRequest": { "type": "object", "properties": { "vendor_ids": { "type": "array", "items": { "type": "string" }, "description": "IDs of the [Vendor](https://developer.squareup.com/reference/square_2024-10-17/objects/Vendor) objects to retrieve." } }, "description": "Represents an input to a call to [BulkRetrieveVendors](https://developer.squareup.com/reference/square_2024-10-17/vendors-api/bulk-retrieve-vendors).", "x-release-status": "BETA", "x-is-beta": true, "example": { "request_body": { "vendor_ids": [ "INV_V_JDKYHBWT1D4F8MFH63DBMEN8Y4" ] } } }, "BulkRetrieveVendorsResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Any errors that occurred during the request." }, "responses": { "type": "object", "additionalProperties": { "$ref": "#/definitions/RetrieveVendorResponse" }, "description": "The set of [RetrieveVendorResponse](https://developer.squareup.com/reference/square_2024-10-17/objects/RetrieveVendorResponse) objects encapsulating successfully retrieved [Vendor](https://developer.squareup.com/reference/square_2024-10-17/objects/Vendor)\nobjects or error responses for failed attempts. The set is represented by \na collection of `Vendor`-ID/`Vendor`-object or `Vendor`-ID/error-object pairs." } }, "description": "Represents an output from a call to [BulkRetrieveVendors](https://developer.squareup.com/reference/square_2024-10-17/vendors-api/bulk-retrieve-vendors).", "x-release-status": "BETA", "x-is-beta": true, "example": { "errors": [], "vendors": { "INV_V_JDKYHBWT1D4F8MFH63DBMEN8Y4": { "vendor": { "id": "INV_V_JDKYHBWT1D4F8MFH63DBMEN8Y4", "created_at": "2022-03-16T10:21:54.859Z", "updated_at": "2022-03-16T10:21:54.859Z", "name": "Joe\u0027s Fresh Seafood", "address": { "address_line_1": "505 Electric Ave", "address_line_2": "Suite 600", "locality": "New York", "administrative_district_level_1": "NY", "postal_code": "10003", "country": "US" }, "contacts": [ { "id": "INV_VC_FMCYHBWT1TPL8MFH52PBMEN92A", "name": "Joe Burrow", "email_address": "joe@joesfreshseafood.com", "phone_number": "1-212-555-4250" } ], "account_number": "4025391", "note": "a vendor", "version": 1, "status": "ACTIVE" } } } } }, "BulkSwapPlanRequest": { "type": "object", "required": [ "new_plan_variation_id", "old_plan_variation_id", "location_id" ], "properties": { "new_plan_variation_id": { "minLength": 1, "type": "string", "description": "The ID of the new subscription plan variation.\n\nThis field is required." }, "old_plan_variation_id": { "minLength": 1, "type": "string", "description": "The ID of the plan variation whose subscriptions should be swapped. Active subscriptions\nusing this plan variation will be subscribed to the new plan variation on their next billing\nday." }, "location_id": { "minLength": 1, "type": "string", "description": "The ID of the location to associate with the swapped subscriptions." } }, "description": "Defines input parameters in a call to the\n[BulkSwapPlan](https://developer.squareup.com/reference/square_2024-10-17/subscriptions-api/bulk-swap-plan) endpoint.", "x-release-status": "BETA", "x-is-beta": true, "example": { "request_body": { "new_plan_variation_id": "FQ7CDXXWSLUJRPM3GFJSJGZ7", "old_plan_variation_id": "6JHXF3B2CW3YKHDV4XEM674H", "location_id": "S8GWD5R9QB376" } } }, "BulkSwapPlanResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Errors encountered during the request." }, "affected_subscriptions": { "type": "integer", "description": "The number of affected subscriptions." } }, "description": "Defines output parameters in a response of the\n[BulkSwapPlan](https://developer.squareup.com/reference/square_2024-10-17/subscriptions-api/bulk-swap-plan) endpoint.", "x-release-status": "BETA", "x-is-beta": true, "example": { "affected_subscriptions": 12 } }, "BulkUpdateCustomerData": { "type": "object", "properties": { "given_name": { "maxLength": 300, "type": "string", "description": "The given name (that is, the first name) associated with the customer profile." }, "family_name": { "maxLength": 300, "type": "string", "description": "The family name (that is, the last name) associated with the customer profile." }, "company_name": { "maxLength": 500, "type": "string", "description": "A business name associated with the customer profile." }, "nickname": { "maxLength": 100, "type": "string", "description": "A nickname for the customer profile." }, "email_address": { "maxLength": 254, "type": "string", "description": "The email address associated with the customer profile." }, "address": { "$ref": "#/definitions/Address", "description": "The physical address associated with the customer profile. For maximum length constraints,\nsee [Customer addresses](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#address).\nThe `first_name` and `last_name` fields are ignored if they are present in the request." }, "phone_number": { "type": "string", "description": "The phone number associated with the customer profile. The phone number must be valid\nand can contain 9–16 digits, with an optional `+` prefix and country code. For more information,\nsee [Customer phone numbers](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#phone-number)." }, "reference_id": { "maxLength": 100, "type": "string", "description": "An optional second ID used to associate the customer profile with an\nentity in another system." }, "note": { "type": "string", "description": "An custom note associates with the customer profile." }, "birthday": { "type": "string", "description": "The birthday associated with the customer profile, in `YYYY-MM-DD` or `MM-DD` format.\nFor example, specify `1998-09-21` for September 21, 1998, or `09-21` for September 21.\nBirthdays are returned in `YYYY-MM-DD` format, where `YYYY` is the specified birth year or\n`0000` if a birth year is not specified." }, "tax_ids": { "$ref": "#/definitions/CustomerTaxIds", "description": "The tax ID associated with the customer profile. This field is available only for\ncustomers of sellers in EU countries or the United Kingdom. For more information, see\n[Customer tax IDs](https://developer.squareup.com/docs/customers-api/what-it-does#customer-tax-ids)." }, "version": { "type": "integer", "format": "int64", "description": "The current version of the customer profile.\n\nAs a best practice, you should include this field to enable\n[optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)\ncontrol." } }, "description": "Defines the customer data provided in individual update requests for a\n[BulkUpdateCustomers](https://developer.squareup.com/reference/square_2024-10-17/customers-api/bulk-update-customers) operation.", "x-release-status": "PUBLIC" }, "BulkUpdateCustomersRequest": { "type": "object", "required": [ "customers" ], "properties": { "customers": { "type": "object", "additionalProperties": { "$ref": "#/definitions/BulkUpdateCustomerData" }, "description": "A map of 1 to 100 individual update requests, represented by `customer ID: { customer data }`\nkey-value pairs.\n\nEach key is the ID of the [customer profile](https://developer.squareup.com/reference/square_2024-10-17/objects/Customer) to update. To update a customer profile\nthat was created by merging existing profiles, provide the ID of the newly created profile.\n\nEach value contains the updated customer data. Only new or changed fields are required. To add or\nupdate a field, specify the new value. To remove a field, specify `null`." } }, "description": "Defines the body parameters that can be included in requests to the\n[BulkUpdateCustomers](https://developer.squareup.com/reference/square_2024-10-17/customers-api/bulk-update-customers) endpoint.", "x-release-status": "PUBLIC", "example": { "request_body": { "customers": { "8DDA5NZVBZFGAX0V3HPF81HHE0": { "phone_number": null, "email_address": "New.Amelia.Earhart@example.com", "note": "updated customer note", "version": 2 }, "N18CPRVXR5214XPBBA6BZQWF3C": { "given_name": "Marie", "family_name": "Curie", "version": 0 } } } } }, "BulkUpdateCustomersResponse": { "type": "object", "properties": { "responses": { "type": "object", "additionalProperties": { "$ref": "#/definitions/UpdateCustomerResponse" }, "description": "A map of responses that correspond to individual update requests, represented by\nkey-value pairs.\n\nEach key is the customer ID that was specified for an update request and each value\nis the corresponding response.\nIf the request succeeds, the value is the updated customer profile.\nIf the request fails, the value contains any errors that occurred during the request." }, "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Any top-level errors that prevented the bulk operation from running." } }, "description": "Defines the fields included in the response body from the\n[BulkUpdateCustomers](https://developer.squareup.com/reference/square_2024-10-17/customers-api/bulk-update-customers) endpoint.", "x-release-status": "PUBLIC", "example": { "responses": { "8DDA5NZVBZFGAX0V3HPF81HHE0": { "customer": { "id": "8DDA5NZVBZFGAX0V3HPF81HHE0", "created_at": "2024-01-19T00:27:54.59Z", "updated_at": "2024-01-19T00:38:06Z", "given_name": "Amelia", "family_name": "Earhart", "email_address": "New.Amelia.Earhart@example.com", "note": "updated customer note", "preferences": { "email_unsubscribed": false }, "creation_source": "THIRD_PARTY", "birthday": "1897-07-24", "version": 3 } }, "N18CPRVXR5214XPBBA6BZQWF3C": { "customer": { "id": "N18CPRVXR5214XPBBA6BZQWF3C", "created_at": "2024-01-19T00:27:54.59Z", "updated_at": "2024-01-19T00:38:06Z", "given_name": "Marie", "family_name": "Curie", "preferences": { "email_unsubscribed": false }, "creation_source": "THIRD_PARTY", "version": 1 } } } } }, "BulkUpdateTeamMembersRequest": { "type": "object", "required": [ "team_members" ], "properties": { "team_members": { "type": "object", "additionalProperties": { "$ref": "#/definitions/UpdateTeamMemberRequest" }, "description": "The data used to update the `TeamMember` objects. Each key is the `team_member_id` that maps to the `UpdateTeamMemberRequest`. The maximum number of update objects is 25." } }, "description": "Represents a bulk update request for `TeamMember` objects.", "x-release-status": "PUBLIC", "example": { "request_body": { "team_members": { "fpgteZNMaf0qOK-a4t6P": { "team_member": { "reference_id": "reference_id_1", "is_owner": false, "status": "ACTIVE", "given_name": "Joe", "family_name": "Doe", "email_address": "joe_doe@gmail.com", "phone_number": "+14159283333", "assigned_locations": { "location_ids": [ "YSGH2WBKG94QZ", "GA2Y9HSJ8KRYT" ], "assignment_type": "EXPLICIT_LOCATIONS" } } }, "AFMwA08kR-MIF-3Vs0OE": { "team_member": { "reference_id": "reference_id_2", "is_owner": false, "status": "ACTIVE", "given_name": "Jane", "family_name": "Smith", "email_address": "jane_smith@gmail.com", "phone_number": "+14159223334", "assigned_locations": { "assignment_type": "ALL_CURRENT_AND_FUTURE_LOCATIONS" } } } } } } }, "BulkUpdateTeamMembersResponse": { "type": "object", "properties": { "team_members": { "type": "object", "additionalProperties": { "$ref": "#/definitions/UpdateTeamMemberResponse" }, "description": "The successfully updated `TeamMember` objects. Each key is the `team_member_id` that maps to the `UpdateTeamMemberRequest`." }, "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "The errors that occurred during the request." } }, "description": "Represents a response from a bulk update request containing the updated `TeamMember` objects or error messages.", "x-release-status": "PUBLIC", "example": { "team_members": { "fpgteZNMaf0qOK-a4t6P": { "team_member": { "id": "fpgteZNMaf0qOK-a4t6P", "reference_id": "reference_id_1", "is_owner": false, "status": "ACTIVE", "given_name": "Joe", "family_name": "Doe", "email_address": "joe_doe@example.com", "phone_number": "+14159283333", "created_at": "2020-03-24T18:14:00Z", "updated_at": "2020-03-24T18:18:00Z", "assigned_locations": { "assignment_type": "EXPLICIT_LOCATIONS", "location_ids": [ "GA2Y9HSJ8KRYT", "YSGH2WBKG94QZ" ] } } }, "AFMwA08kR-MIF-3Vs0OE": { "team_member": { "id": "AFMwA08kR-MIF-3Vs0OE", "reference_id": "reference_id_2", "is_owner": false, "status": "ACTIVE", "given_name": "Jane", "family_name": "Smith", "email_address": "jane_smith@example.com", "phone_number": "+14159223334", "created_at": "2020-03-24T18:14:00Z", "updated_at": "2020-03-24T18:18:00Z", "assigned_locations": { "assignment_type": "ALL_CURRENT_AND_FUTURE_LOCATIONS" } } } } } }, "BulkUpdateVendorsRequest": { "type": "object", "required": [ "vendors" ], "properties": { "vendors": { "type": "object", "additionalProperties": { "$ref": "#/definitions/UpdateVendorRequest" }, "description": "A set of [UpdateVendorRequest](https://developer.squareup.com/reference/square_2024-10-17/objects/UpdateVendorRequest) objects encapsulating to-be-updated [Vendor](https://developer.squareup.com/reference/square_2024-10-17/objects/Vendor)\nobjects. The set is represented by a collection of `Vendor`-ID/`UpdateVendorRequest`-object pairs." } }, "description": "Represents an input to a call to [BulkUpdateVendors](https://developer.squareup.com/reference/square_2024-10-17/vendors-api/bulk-update-vendors).", "x-release-status": "BETA", "x-is-beta": true, "example": { "request_body": { "vendors": { "INV_V_JDKYHBWT1D4F8MFH63DBMEN8Y4": { "note": "favorite vendor", "version": 30, "status": "ACTIVE" }, "FMCYHBWT1TPL8MFH52PBMEN92A": { "address": { "address_line_1": "202 Mill St", "locality": "Moorestown", "administrative_district_level_1": "NJ", "postal_code": "08057", "country": "US" }, "version": 10, "status": "ACTIVE" } } } } }, "BulkUpdateVendorsResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Errors encountered when the request fails." }, "responses": { "type": "object", "additionalProperties": { "$ref": "#/definitions/UpdateVendorResponse" }, "description": "A set of [UpdateVendorResponse](https://developer.squareup.com/reference/square_2024-10-17/objects/UpdateVendorResponse) objects encapsulating successfully created [Vendor](https://developer.squareup.com/reference/square_2024-10-17/objects/Vendor)\nobjects or error responses for failed attempts. The set is represented by a collection of `Vendor`-ID/`UpdateVendorResponse`-object or \n`Vendor`-ID/error-object pairs." } }, "description": "Represents an output from a call to [BulkUpdateVendors](https://developer.squareup.com/reference/square_2024-10-17/vendors-api/bulk-update-vendors).", "x-release-status": "BETA", "x-is-beta": true, "example": { "vendors": { "INV_V_JDKYHBWT1D4F8MFH63DBMEN8Y4": { "id": "INV_V_JDKYHBWT1D4F8MFH63DBMEN8Y4", "created_at": "2022-03-16T10:10:54.859Z", "updated_at": "2022-03-16T20:21:54.859Z", "name": "Joe\u0027s Fresh Seafood", "address": { "address_line_1": "505 Electric Ave", "address_line_2": "Suite 600", "locality": "New York", "administrative_district_level_1": "NY", "postal_code": "10003", "country": "US" }, "contacts": [ { "id": "INV_VC_FMCYHBWT1TPL8MFH52PBMEN92A", "name": "Joe Burrow", "email_address": "joe@joesfreshseafood.com", "phone_number": "1-212-555-4250", "ordinal": 0 } ], "account_number": "4025391", "note": "favorite vendor", "version": 31, "status": "ACTIVE" }, "INV_V_FMCYHBWT1TPL8MFH52PBMEN92A": { "id": "INV_V_FMCYHBWT1TPL8MFH52PBMEN92A", "created_at": "2022-03-16T10:21:54.859Z", "updated_at": "2022-03-16T20:21:54.859Z", "name": "Annie’s Hot Sauce", "contacts": [ { "id": "INV_VC_ABYYHBWT1TPL8MFH52PBMENPJ4", "name": "Annie Thomas", "email_address": "annie@annieshotsauce.com", "phone_number": "1-212-555-4250", "ordinal": 0 } ], "address": { "address_line_1": "202 Mill St", "locality": "Moorestown", "administrative_district_level_1": "NJ", "postal_code": "08057", "country": "US" }, "version": 11, "status": "ACTIVE" } } } }, "BulkUpsertBookingCustomAttributesRequest": { "type": "object", "required": [ "values" ], "properties": { "values": { "type": "object", "additionalProperties": { "$ref": "#/definitions/BookingCustomAttributeUpsertRequest" }, "description": "A map containing 1 to 25 individual upsert requests. For each request, provide an\narbitrary ID that is unique for this `BulkUpsertBookingCustomAttributes` request and the\ninformation needed to create or update a custom attribute." } }, "description": "Represents a [BulkUpsertBookingCustomAttributes](https://developer.squareup.com/reference/square_2024-10-17/booking-custom-attributes-api/bulk-upsert-booking-custom-attributes) request.", "x-release-status": "PUBLIC", "example": { "values": { "id1": { "custom_attribute": { "key": "favoriteShampoo", "value": "Spring Fresh" }, "booking_id": "N3NCVYY3WS27HF0HKANA3R9FP8" }, "id2": { "custom_attribute": { "key": "ownsShampoo", "value": false }, "booking_id": "SY8EMWRNDN3TQDP2H4KS1QWMMM" }, "id3": { "custom_attribute": { "key": "favoriteShampoo", "value": "Hydro-Cool" }, "booking_id": "SY8EMWRNDN3TQDP2H4KS1QWMMM" }, "id4": { "custom_attribute": { "key": "hasShoes", "value": true }, "booking_id": "N3NCVYY3WS27HF0HKANA3R9FP8" }, "id5": { "custom_attribute": { "key": "partySize", "value": "4" }, "booking_id": "70548QG1HN43B05G0KCZ4MMC1G" } } } }, "BulkUpsertBookingCustomAttributesResponse": { "type": "object", "properties": { "values": { "type": "object", "additionalProperties": { "$ref": "#/definitions/BookingCustomAttributeUpsertResponse" }, "description": "A map of responses that correspond to individual upsert requests. Each response has the\nsame ID as the corresponding request and contains either a `booking_id` and `custom_attribute` or an `errors` field." }, "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Any errors that occurred during the request." } }, "description": "Represents a [BulkUpsertBookingCustomAttributes](https://developer.squareup.com/reference/square_2024-10-17/booking-custom-attributes-api/bulk-upsert-booking-custom-attributes) response,\nwhich contains a map of responses that each corresponds to an individual upsert request.", "x-release-status": "PUBLIC", "example": { "values": { "id2": { "booking_id": "SY8EMWRNDN3TQDP2H4KS1QWMMM", "custom_attribute": { "key": "hasShoes", "version": 2, "visibility": "VISIBILITY_READ_WRITE_VALUES", "updated_at": "2022-11-16T00:16:23Z", "value": false, "created_at": "2022-11-16T00:16:20Z" }, "errors": [] }, "id1": { "booking_id": "N3NCVYY3WS27HF0HKANA3R9FP8", "custom_attribute": { "key": "favoriteShampoo", "version": 1, "visibility": "VISIBILITY_READ_WRITE_VALUES", "updated_at": "2022-11-16T00:16:23Z", "value": "Spring Fresh", "created_at": "2022-11-16T23:14:47Z" }, "errors": [] }, "id3": { "booking_id": "SY8EMWRNDN3TQDP2H4KS1QWMMM", "custom_attribute": { "key": "favoriteShampoo", "version": 2, "visibility": "VISIBILITY_READ_WRITE_VALUES", "updated_at": "2022-11-16T00:16:23Z", "value": "Hydro-Cool", "created_at": "2022-11-16T00:16:20Z" }, "errors": [] }, "id4": { "booking_id": "N3NCVYY3WS27HF0HKANA3R9FP8", "custom_attribute": { "key": "partySize", "version": 1, "visibility": "VISIBILITY_READ_WRITE_VALUES", "updated_at": "2022-11-16T00:16:23Z", "value": 4, "created_at": "2022-11-16T23:14:47Z" }, "errors": [] }, "id5": { "booking_id": "70548QG1HN43B05G0KCZ4MMC1G", "custom_attribute": { "key": "celebrating", "version": 2, "visibility": "VISIBILITY_READ_WRITE_VALUES", "updated_at": "2022-11-16T00:16:23Z", "value": "birthday", "created_at": "2022-11-16T00:16:20Z" }, "errors": [] } }, "errors": [] } }, "BulkUpsertCustomerCustomAttributesRequest": { "type": "object", "required": [ "values" ], "properties": { "values": { "type": "object", "additionalProperties": { "$ref": "#/definitions/CustomerCustomAttributeUpsertRequest" }, "description": "A map containing 1 to 25 individual upsert requests. For each request, provide an\narbitrary ID that is unique for this `BulkUpsertCustomerCustomAttributes` request and the\ninformation needed to create or update a custom attribute." } }, "description": "Represents a [BulkUpsertCustomerCustomAttributes](https://developer.squareup.com/reference/square_2024-10-17/customer-custom-attributes-api/bulk-upsert-customer-custom-attributes) request.", "x-release-status": "PUBLIC", "example": { "request_body": { "values": { "id1": { "custom_attribute": { "key": "favoritemovie", "value": "Dune" }, "customer_id": "N3NCVYY3WS27HF0HKANA3R9FP8" }, "id2": { "custom_attribute": { "key": "ownsmovie", "value": false }, "customer_id": "SY8EMWRNDN3TQDP2H4KS1QWMMM" }, "id3": { "custom_attribute": { "key": "favoritemovie", "value": "Star Wars" }, "customer_id": "SY8EMWRNDN3TQDP2H4KS1QWMMM" }, "id4": { "custom_attribute": { "key": "square:a0f1505a-2aa1-490d-91a8-8d31ff181808", "value": "10.5" }, "customer_id": "N3NCVYY3WS27HF0HKANA3R9FP8" }, "id5": { "custom_attribute": { "key": "sq0ids-0evKIskIGaY45fCyNL66aw:backupemail", "value": "fake-email@squareup.com" }, "customer_id": "70548QG1HN43B05G0KCZ4MMC1G" } } } } }, "BulkUpsertCustomerCustomAttributesRequestCustomerCustomAttributeUpsertRequest": { "type": "object", "required": [ "customer_id", "custom_attribute" ], "properties": { "customer_id": { "minLength": 1, "type": "string", "description": "The ID of the target [customer profile](https://developer.squareup.com/reference/square_2024-10-17/objects/Customer)." }, "custom_attribute": { "$ref": "#/definitions/CustomAttribute", "description": "The custom attribute to create or update, with following fields:\n\n- `key`. This key must match the `key` of a custom attribute definition in the Square seller \naccount. If the requesting application is not the definition owner, you must provide the qualified key.\n\n- `value`. This value must conform to the `schema` specified by the definition. \nFor more information, see [Value data types](https://developer.squareup.com/docs/customer-custom-attributes-api/custom-attributes#value-data-types).\n\n- `version`. To enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)\ncontrol for update operations, include this optional field in the request and set the\nvalue to the current version of the custom attribute." }, "idempotency_key": { "maxLength": 45, "type": "string", "description": "A unique identifier for this individual upsert request, used to ensure idempotency.\nFor more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)." } }, "description": "Represents an individual upsert request in a [BulkUpsertCustomerCustomAttributes](https://developer.squareup.com/reference/square_2024-10-17/customer-custom-attributes-api/bulk-upsert-customer-custom-attributes)\nrequest. An individual request contains a customer ID, the custom attribute to create or update,\nand an optional idempotency key.", "x-release-status": "PUBLIC" }, "BulkUpsertCustomerCustomAttributesResponse": { "type": "object", "properties": { "values": { "type": "object", "additionalProperties": { "$ref": "#/definitions/CustomerCustomAttributeUpsertResponse" }, "description": "A map of responses that correspond to individual upsert requests. Each response has the\nsame ID as the corresponding request and contains either a `customer_id` and `custom_attribute` or an `errors` field." }, "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Any errors that occurred during the request." } }, "description": "Represents a [BulkUpsertCustomerCustomAttributes](https://developer.squareup.com/reference/square_2024-10-17/customer-custom-attributes-api/bulk-upsert-customer-custom-attributes) response,\nwhich contains a map of responses that each corresponds to an individual upsert request.", "x-release-status": "PUBLIC", "example": { "values": { "id2": { "customer_id": "SY8EMWRNDN3TQDP2H4KS1QWMMM", "custom_attribute": { "key": "ownsmovie", "version": 2, "visibility": "VISIBILITY_READ_WRITE_VALUES", "updated_at": "2021-12-09T00:16:23Z", "value": false, "created_at": "2021-12-09T00:16:20Z" } }, "id1": { "customer_id": "N3NCVYY3WS27HF0HKANA3R9FP8", "custom_attribute": { "key": "favoritemovie", "version": 1, "visibility": "VISIBILITY_READ_WRITE_VALUES", "updated_at": "2021-12-09T00:16:23Z", "value": "Dune", "created_at": "2021-12-08T23:14:47Z" } }, "id3": { "customer_id": "SY8EMWRNDN3TQDP2H4KS1QWMMM", "custom_attribute": { "key": "favoritemovie", "version": 2, "visibility": "VISIBILITY_READ_WRITE_VALUES", "updated_at": "2021-12-09T00:16:23Z", "value": "Star Wars", "created_at": "2021-12-09T00:16:20Z" } }, "id4": { "customer_id": "N3NCVYY3WS27HF0HKANA3R9FP8", "custom_attribute": { "key": "square:a0f1505a-2aa1-490d-91a8-8d31ff181808", "version": 1, "visibility": "VISIBILITY_READ_WRITE_VALUES", "updated_at": "2021-12-09T00:16:23Z", "value": "10.5", "created_at": "2021-12-08T23:14:47Z" } }, "id5": { "customer_id": "70548QG1HN43B05G0KCZ4MMC1G", "custom_attribute": { "key": "sq0ids-0evKIskIGaY45fCyNL66aw:backupemail", "version": 2, "visibility": "VISIBILITY_READ_WRITE_VALUES", "updated_at": "2021-12-09T00:16:23Z", "value": "fake-email@squareup.com", "created_at": "2021-12-09T00:16:20Z" } } } } }, "BulkUpsertCustomerCustomAttributesResponseCustomerCustomAttributeUpsertResponse": { "type": "object", "properties": { "customer_id": { "type": "string", "description": "The ID of the customer profile associated with the custom attribute." }, "custom_attribute": { "$ref": "#/definitions/CustomAttribute", "description": "The new or updated custom attribute." }, "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Any errors that occurred while processing the individual request." } }, "description": "Represents a response for an individual upsert request in a [BulkUpsertCustomerCustomAttributes](https://developer.squareup.com/reference/square_2024-10-17/customer-custom-attributes-api/bulk-upsert-customer-custom-attributes) operation.", "x-release-status": "PUBLIC", "example": { "customer_id": "N3NCVYY3WS27HF0HKANA3R9FP8", "custom_attribute": { "key": "favoritemovie", "version": 1, "visibility": "VISIBILITY_READ_WRITE_VALUES", "updated_at": "2021-12-09T00:16:23Z", "value": "Dune", "created_at": "2021-12-08T23:14:47Z" } } }, "BulkUpsertLocationCustomAttributesRequest": { "type": "object", "required": [ "values" ], "properties": { "values": { "type": "object", "additionalProperties": { "$ref": "#/definitions/LocationCustomAttributeUpsertRequest" }, "description": "A map containing 1 to 25 individual upsert requests. For each request, provide an\narbitrary ID that is unique for this `BulkUpsertLocationCustomAttributes` request and the\ninformation needed to create or update a custom attribute." } }, "description": "Represents a [BulkUpsertLocationCustomAttributes](https://developer.squareup.com/reference/square_2024-10-17/location-custom-attributes-api/bulk-upsert-location-custom-attributes) request.", "x-release-status": "BETA", "x-is-beta": true, "example": { "request_body": { "values": { "id1": { "custom_attribute": { "key": "bestseller", "value": "hot cocoa" }, "location_id": "L0TBCBTB7P8RQ" }, "id2": { "custom_attribute": { "key": "bestseller", "value": "berry smoothie" }, "location_id": "L9XMD04V3STJX" }, "id3": { "custom_attribute": { "key": "phone-number", "value": "+12223334444" }, "location_id": "L0TBCBTB7P8RQ" } } } } }, "BulkUpsertLocationCustomAttributesRequestLocationCustomAttributeUpsertRequest": { "type": "object", "required": [ "location_id", "custom_attribute" ], "properties": { "location_id": { "minLength": 1, "type": "string", "description": "The ID of the target [location](https://developer.squareup.com/reference/square_2024-10-17/objects/Location)." }, "custom_attribute": { "$ref": "#/definitions/CustomAttribute", "description": "The custom attribute to create or update, with following fields:\n- `key`. This key must match the `key` of a custom attribute definition in the Square seller\naccount. If the requesting application is not the definition owner, you must provide the qualified key.\n- `value`. This value must conform to the `schema` specified by the definition.\nFor more information, see [Supported data types](https://developer.squareup.com/docs/devtools/customattributes/overview#supported-data-types)..\n- `version`. To enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)\ncontrol, specify the current version of the custom attribute. \nIf this is not important for your application, `version` can be set to -1." }, "idempotency_key": { "maxLength": 45, "type": "string", "description": "A unique identifier for this individual upsert request, used to ensure idempotency.\nFor more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)." } }, "description": "Represents an individual upsert request in a [BulkUpsertLocationCustomAttributes](https://developer.squareup.com/reference/square_2024-10-17/location-custom-attributes-api/bulk-upsert-location-custom-attributes)\nrequest. An individual request contains a location ID, the custom attribute to create or update,\nand an optional idempotency key.", "x-release-status": "BETA", "x-is-beta": true }, "BulkUpsertLocationCustomAttributesResponse": { "type": "object", "properties": { "values": { "type": "object", "additionalProperties": { "$ref": "#/definitions/LocationCustomAttributeUpsertResponse" }, "description": "A map of responses that correspond to individual upsert requests. Each response has the\nsame ID as the corresponding request and contains either a `location_id` and `custom_attribute` or an `errors` field." }, "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Any errors that occurred during the request." } }, "description": "Represents a [BulkUpsertLocationCustomAttributes](https://developer.squareup.com/reference/square_2024-10-17/location-custom-attributes-api/bulk-upsert-location-custom-attributes) response,\nwhich contains a map of responses that each corresponds to an individual upsert request.", "x-release-status": "BETA", "x-is-beta": true, "example": { "values": { "id1": { "location_id": "L0TBCBTB7P8RQ", "custom_attribute": { "key": "bestseller", "version": 2, "updated_at": "2023-01-09T19:21:04.551Z", "value": "hot cocoa", "created_at": "2023-01-09T19:02:58.647Z", "visibility": "VISIBILITY_READ_WRITE_VALUES" } }, "id2": { "location_id": "L9XMD04V3STJX", "custom_attribute": { "key": "bestseller", "version": 1, "updated_at": "2023-01-09T19:21:04.551Z", "value": "berry smoothie", "created_at": "2023-01-09T19:02:58.647Z", "visibility": "VISIBILITY_READ_WRITE_VALUES" } }, "id3": { "location_id": "L0TBCBTB7P8RQ", "custom_attribute": { "key": "phone-number", "version": 2, "updated_at": "2023-01-09T19:21:04.563Z", "value": "+12239903892", "created_at": "2023-01-09T19:04:57.985Z", "visibility": "VISIBILITY_READ_WRITE_VALUES" } } } } }, "BulkUpsertLocationCustomAttributesResponseLocationCustomAttributeUpsertResponse": { "type": "object", "properties": { "location_id": { "type": "string", "description": "The ID of the location associated with the custom attribute." }, "custom_attribute": { "$ref": "#/definitions/CustomAttribute", "description": "The new or updated custom attribute." }, "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Any errors that occurred while processing the individual request." } }, "description": "Represents a response for an individual upsert request in a [BulkUpsertLocationCustomAttributes](https://developer.squareup.com/reference/square_2024-10-17/location-custom-attributes-api/bulk-upsert-location-custom-attributes) operation.", "x-release-status": "BETA", "x-is-beta": true, "example": { "location_id": "L0TBCBTB7P8RQ", "custom_attribute": { "key": "bestseller", "version": 2, "updated_at": "2023-01-09T19:21:04.551Z", "value": "hot cocoa", "created_at": "2023-01-09T19:02:58.647Z", "visibility": "VISIBILITY_READ_WRITE_VALUES" } } }, "BulkUpsertMerchantCustomAttributesRequest": { "type": "object", "required": [ "values" ], "properties": { "values": { "type": "object", "additionalProperties": { "$ref": "#/definitions/MerchantCustomAttributeUpsertRequest" }, "description": "A map containing 1 to 25 individual upsert requests. For each request, provide an\narbitrary ID that is unique for this `BulkUpsertMerchantCustomAttributes` request and the\ninformation needed to create or update a custom attribute." } }, "description": "Represents a [BulkUpsertMerchantCustomAttributes](https://developer.squareup.com/reference/square_2024-10-17/merchant-custom-attributes-api/bulk-upsert-merchant-custom-attributes) request.", "x-release-status": "BETA", "x-is-beta": true, "example": { "request_body": { "values": { "id1": { "custom_attribute": { "key": "alternative_seller_name", "value": "Ultimate Sneaker Store" }, "merchant_id": "DM7VKY8Q63GNP" }, "id2": { "custom_attribute": { "key": "has_seen_tutorial", "value": true }, "merchant_id": "DM7VKY8Q63GNP" } } } } }, "BulkUpsertMerchantCustomAttributesRequestMerchantCustomAttributeUpsertRequest": { "type": "object", "required": [ "merchant_id", "custom_attribute" ], "properties": { "merchant_id": { "minLength": 1, "type": "string", "description": "The ID of the target [merchant](https://developer.squareup.com/reference/square_2024-10-17/objects/Merchant)." }, "custom_attribute": { "$ref": "#/definitions/CustomAttribute", "description": "The custom attribute to create or update, with following fields:\n- `key`. This key must match the `key` of a custom attribute definition in the Square seller\naccount. If the requesting application is not the definition owner, you must provide the qualified key.\n- `value`. This value must conform to the `schema` specified by the definition.\nFor more information, see [Supported data types](https://developer.squareup.com/docs/devtools/customattributes/overview#supported-data-types).\n- The version field must match the current version of the custom attribute definition to enable\n[optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)\nIf this is not important for your application, version can be set to -1. For any other values, the request fails with a BAD_REQUEST error." }, "idempotency_key": { "maxLength": 45, "type": "string", "description": "A unique identifier for this individual upsert request, used to ensure idempotency.\nFor more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)." } }, "description": "Represents an individual upsert request in a [BulkUpsertMerchantCustomAttributes](https://developer.squareup.com/reference/square_2024-10-17/merchant-custom-attributes-api/bulk-upsert-merchant-custom-attributes)\nrequest. An individual request contains a merchant ID, the custom attribute to create or update,\nand an optional idempotency key.", "x-release-status": "BETA", "x-is-beta": true }, "BulkUpsertMerchantCustomAttributesResponse": { "type": "object", "properties": { "values": { "type": "object", "additionalProperties": { "$ref": "#/definitions/MerchantCustomAttributeUpsertResponse" }, "description": "A map of responses that correspond to individual upsert requests. Each response has the\nsame ID as the corresponding request and contains either a `merchant_id` and `custom_attribute` or an `errors` field." }, "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Any errors that occurred during the request." } }, "description": "Represents a [BulkUpsertMerchantCustomAttributes](https://developer.squareup.com/reference/square_2024-10-17/merchant-custom-attributes-api/bulk-upsert-merchant-custom-attributes) response,\nwhich contains a map of responses that each corresponds to an individual upsert request.", "x-release-status": "BETA", "x-is-beta": true, "example": { "values": { "id1": { "merchant_id": "DM7VKY8Q63GNP", "custom_attribute": { "key": "alternative_seller_name", "version": 2, "updated_at": "2023-05-06T19:21:04.551Z", "value": "Ultimate Sneaker Store", "created_at": "2023-05-06T19:02:58.647Z", "visibility": "VISIBILITY_READ_ONLY" } }, "id2": { "merchant_id": "DM7VKY8Q63GNP", "custom_attribute": { "key": "has_seen_tutorial", "version": 1, "updated_at": "2023-05-06T19:21:04.551Z", "value": true, "created_at": "2023-05-06T19:02:58.647Z", "visibility": "VISIBILITY_READ_WRITE_VALUES" } } } } }, "BulkUpsertMerchantCustomAttributesResponseMerchantCustomAttributeUpsertResponse": { "type": "object", "properties": { "merchant_id": { "type": "string", "description": "The ID of the merchant associated with the custom attribute." }, "custom_attribute": { "$ref": "#/definitions/CustomAttribute", "description": "The new or updated custom attribute." }, "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Any errors that occurred while processing the individual request." } }, "description": "Represents a response for an individual upsert request in a [BulkUpsertMerchantCustomAttributes](https://developer.squareup.com/reference/square_2024-10-17/merchant-custom-attributes-api/bulk-upsert-merchant-custom-attributes) operation.", "x-release-status": "BETA", "x-is-beta": true, "example": { "merchant_id": "DM7VKY8Q63GNP", "custom_attribute": { "key": "alternative_seller_name", "version": 2, "updated_at": "2023-05-06T19:21:04.551Z", "value": "Ultimate Sneaker Store", "created_at": "2023-05-06T19:02:58.647Z", "visibility": "VISIBILITY_READ_ONLY" } } }, "BulkUpsertOrderCustomAttributesRequest": { "type": "object", "required": [ "values" ], "properties": { "values": { "type": "object", "additionalProperties": { "$ref": "#/definitions/UpsertCustomAttribute" }, "description": "A map of requests that correspond to individual upsert operations for custom attributes." } }, "description": "Represents a bulk upsert request for one or more order custom attributes.", "x-release-status": "BETA", "x-is-beta": true, "example": { "request_body": { "values": { "table-number": { "order_id": "7BbXGEIWNldxAzrtGf9GPVZTwZ4F", "custom_attribute": { "key": "table-number", "value": "11", "version": 4 } }, "cover-count": { "order_id": "7BbXGEIWNldxAzrtGf9GPVZTwZ4F", "custom_attribute": { "key": "cover-count", "value": "6", "version": 2 } } } } } }, "BulkUpsertOrderCustomAttributesRequestUpsertCustomAttribute": { "type": "object", "required": [ "custom_attribute", "order_id" ], "properties": { "custom_attribute": { "$ref": "#/definitions/CustomAttribute", "description": "The custom attribute to create or update, with the following fields:\n\n- `value`. This value must conform to the `schema` specified by the definition. \nFor more information, see [Value data types](https://developer.squareup.com/docs/customer-custom-attributes-api/custom-attributes#value-data-types).\n\n- `version`. To enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)\ncontrol, include this optional field and specify the current version of the custom attribute." }, "idempotency_key": { "minLength": 1, "maxLength": 45, "type": "string", "description": "A unique identifier for this request, used to ensure idempotency. \nFor more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)." }, "order_id": { "minLength": 1, "maxLength": 255, "type": "string", "description": "The ID of the target [order](https://developer.squareup.com/reference/square_2024-10-17/objects/Order)." } }, "description": "Represents one upsert within the bulk operation.", "x-release-status": "BETA", "x-is-beta": true }, "BulkUpsertOrderCustomAttributesResponse": { "type": "object", "required": [ "values" ], "properties": { "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Any errors that occurred during the request." }, "values": { "type": "object", "additionalProperties": { "$ref": "#/definitions/UpsertOrderCustomAttributeResponse" }, "description": " A map of responses that correspond to individual upsert operations for custom attributes." } }, "description": "Represents a response from a bulk upsert of order custom attributes.", "x-release-status": "BETA", "x-is-beta": true, "example": { "values": { "table-number": { "custom_attribute": { "key": "table-number", "updated_at": "2022-11-22T21:28:35.726Z", "value": "11", "created_at": "2022-11-22T21:24:57.823Z", "visibility": "VISIBILITY_HIDDEN" } }, "cover-count": { "custom_attribute": { "key": "cover-count", "updated_at": "2022-11-22T21:28:35.721Z", "value": "6", "created_at": "2022-11-22T21:27:33.429Z", "visibility": "VISIBILITY_READ_WRITE_VALUES" } } } } }, "BusinessAppointmentSettings": { "type": "object", "properties": { "location_types": { "type": "array", "items": { "type": "string" }, "description": "Types of the location allowed for bookings." }, "alignment_time": { "type": "string", "description": "The time unit of the service duration for bookings." }, "min_booking_lead_time_seconds": { "type": "integer", "description": "The minimum lead time in seconds before a service can be booked. A booking must be created at least this amount of time before its starting time." }, "max_booking_lead_time_seconds": { "type": "integer", "description": "The maximum lead time in seconds before a service can be booked. A booking must be created at most this amount of time before its starting time." }, "any_team_member_booking_enabled": { "type": "boolean", "description": "Indicates whether a customer can choose from all available time slots and have a staff member assigned\nautomatically (`true`) or not (`false`)." }, "multiple_service_booking_enabled": { "type": "boolean", "description": "Indicates whether a customer can book multiple services in a single online booking." }, "max_appointments_per_day_limit_type": { "type": "string", "description": "Indicates whether the daily appointment limit applies to team members or to\nbusiness locations." }, "max_appointments_per_day_limit": { "type": "integer", "description": "The maximum number of daily appointments per team member or per location." }, "cancellation_window_seconds": { "type": "integer", "description": "The cut-off time in seconds for allowing clients to cancel or reschedule an appointment." }, "cancellation_fee_money": { "$ref": "#/definitions/Money", "description": "The flat-fee amount charged for a no-show booking." }, "cancellation_policy": { "type": "string", "description": "The cancellation policy adopted by the seller." }, "cancellation_policy_text": { "minLength": 0, "maxLength": 65536, "type": "string", "description": "The free-form text of the seller\u0027s cancellation policy." }, "skip_booking_flow_staff_selection": { "type": "boolean", "description": "Indicates whether customers has an assigned staff member (`true`) or can select s staff member of their choice (`false`)." } }, "description": "The service appointment settings, including where and how the service is provided.", "x-release-status": "PUBLIC" }, "BusinessBookingProfile": { "type": "object", "properties": { "seller_id": { "minLength": 0, "maxLength": 32, "type": "string", "description": "The ID of the seller, obtainable using the Merchants API." }, "created_at": { "type": "string", "description": "The RFC 3339 timestamp specifying the booking\u0027s creation time.", "x-read-only": true }, "booking_enabled": { "type": "boolean", "description": "Indicates whether the seller is open for booking." }, "customer_timezone_choice": { "type": "string", "description": "The choice of customer\u0027s time zone information of a booking.\nThe Square online booking site and all notifications to customers uses either the seller location’s time zone\nor the time zone the customer chooses at booking." }, "booking_policy": { "type": "string", "description": "The policy for the seller to automatically accept booking requests (`ACCEPT_ALL`) or not (`REQUIRES_ACCEPTANCE`)." }, "allow_user_cancel": { "type": "boolean", "description": "Indicates whether customers can cancel or reschedule their own bookings (`true`) or not (`false`)." }, "business_appointment_settings": { "$ref": "#/definitions/BusinessAppointmentSettings", "description": "Settings for appointment-type bookings." }, "support_seller_level_writes": { "type": "boolean", "description": "Indicates whether the seller\u0027s subscription to Square Appointments supports creating, updating or canceling an appointment through the API (`true`) or not (`false`) using seller permission." } }, "description": "A seller\u0027s business booking profile, including booking policy, appointment settings, etc.", "x-release-status": "PUBLIC" }, "BusinessHours": { "type": "object", "properties": { "periods": { "type": "array", "items": { "$ref": "#/definitions/BusinessHoursPeriod" }, "description": "The list of time periods during which the business is open. There can be at most 10 periods per day." } }, "description": "The hours of operation for a location.", "x-release-status": "PUBLIC" }, "BusinessHoursPeriod": { "type": "object", "properties": { "day_of_week": { "type": "string", "description": "The day of the week for this time period." }, "start_local_time": { "type": "string", "description": "The start time of a business hours period, specified in local time using partial-time\nRFC 3339 format. For example, `8:30:00` for a period starting at 8:30 in the morning.\nNote that the seconds value is always :00, but it is appended for conformance to the RFC." }, "end_local_time": { "type": "string", "description": "The end time of a business hours period, specified in local time using partial-time\nRFC 3339 format. For example, `21:00:00` for a period ending at 9:00 in the evening.\nNote that the seconds value is always :00, but it is appended for conformance to the RFC." } }, "description": "Represents a period of time during which a business location is open.", "x-release-status": "PUBLIC" }, "BuyNowPayLaterDetails": { "type": "object", "properties": { "brand": { "maxLength": 50, "type": "string", "description": "The brand used for the Buy Now Pay Later payment.\nThe brand can be `AFTERPAY`, `CLEARPAY` or `UNKNOWN`." }, "afterpay_details": { "$ref": "#/definitions/AfterpayDetails", "description": "Details about an Afterpay payment. These details are only populated if the `brand` is\n`AFTERPAY`." }, "clearpay_details": { "$ref": "#/definitions/ClearpayDetails", "description": "Details about a Clearpay payment. These details are only populated if the `brand` is\n`CLEARPAY`." } }, "description": "Additional details about a Buy Now Pay Later payment type.", "x-release-status": "PUBLIC" }, "CalculateLoyaltyPointsRequest": { "type": "object", "properties": { "order_id": { "type": "string", "description": "The [order](https://developer.squareup.com/reference/square_2024-10-17/objects/Order) ID for which to calculate the points.\nSpecify this field if your application uses the Orders API to process orders.\nOtherwise, specify the `transaction_amount_money`." }, "transaction_amount_money": { "$ref": "#/definitions/Money", "description": "The purchase amount for which to calculate the points. \nSpecify this field if your application does not use the Orders API to process orders.\nOtherwise, specify the `order_id`." }, "loyalty_account_id": { "minLength": 1, "maxLength": 36, "type": "string", "description": "The ID of the target [loyalty account](https://developer.squareup.com/reference/square_2024-10-17/objects/LoyaltyAccount). Optionally specify this field\nif your application uses the Orders API to process orders.\n\nIf specified, the `promotion_points` field in the response shows the number of points the buyer would\nearn from the purchase. In this case, Square uses the account ID to determine whether the promotion\u0027s\n`trigger_limit` (the maximum number of times that a buyer can trigger the promotion) has been reached.\nIf not specified, the `promotion_points` field shows the number of points the purchase qualifies\nfor regardless of the trigger limit." } }, "description": "Represents a [CalculateLoyaltyPoints](https://developer.squareup.com/reference/square_2024-10-17/loyalty-api/calculate-loyalty-points) request.", "x-release-status": "PUBLIC", "example": { "request_params": "?program_id\u003dd619f755-2d17-41f3-990d-c04ecedd64dd", "request_body": { "order_id": "RFZfrdtm3mhO1oGzf5Cx7fEMsmGZY", "loyalty_account_id": "79b807d2-d786-46a9-933b-918028d7a8c5" } } }, "CalculateLoyaltyPointsResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Any errors that occurred during the request." }, "points": { "minimum": 0, "type": "integer", "description": "The number of points that the buyer can earn from the base loyalty program." }, "promotion_points": { "minimum": 0, "type": "integer", "description": "The number of points that the buyer can earn from a loyalty promotion. To be eligible\nto earn promotion points, the purchase must first qualify for program points. When `order_id`\nis not provided in the request, this value is always 0." } }, "description": "Represents a [CalculateLoyaltyPoints](https://developer.squareup.com/reference/square_2024-10-17/loyalty-api/calculate-loyalty-points) response.", "x-release-status": "PUBLIC", "example": { "points": 6, "promotion_points": 12 } }, "CalculateOrderRequest": { "type": "object", "required": [ "order" ], "properties": { "order": { "$ref": "#/definitions/Order", "description": "The order to be calculated. Expects the entire order, not a sparse update." }, "proposed_rewards": { "type": "array", "items": { "$ref": "#/definitions/OrderReward" }, "description": "Identifies one or more loyalty reward tiers to apply during the order calculation.\nThe discounts defined by the reward tiers are added to the order only to preview the\neffect of applying the specified rewards. The rewards do not correspond to actual\nredemptions; that is, no `reward`s are created. Therefore, the reward `id`s are\nrandom strings used only to reference the reward tier." } }, "description": "", "x-release-status": "BETA", "x-is-beta": true, "example": { "request_body": { "idempotency_key": "b3e98fe3-b8de-471c-82f1-545f371e637c", "order": { "location_id": "D7AVYMEAPJ3A3", "discounts": [ { "name": "50% Off", "percentage": "50", "scope": "ORDER" } ], "line_items": [ { "name": "Item 1", "quantity": "1", "base_price_money": { "amount": 500, "currency": "USD" } }, { "name": "Item 2", "quantity": "2", "base_price_money": { "amount": 300, "currency": "USD" } } ] } } } }, "CalculateOrderResponse": { "type": "object", "properties": { "order": { "$ref": "#/definitions/Order", "description": "The calculated version of the order provided in the request." }, "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Any errors that occurred during the request." } }, "description": "", "x-release-status": "BETA", "x-is-beta": true, "example": { "order": { "location_id": "D7AVYMEAPJ3A3", "line_items": [ { "uid": "ULkg0tQTRK2bkU9fNv3IJD", "quantity": "1", "name": "Item 1", "base_price_money": { "amount": 500, "currency": "USD" }, "gross_sales_money": { "amount": 500, "currency": "USD" }, "total_tax_money": { "amount": 0, "currency": "USD" }, "total_service_charge_money": { "amount": 0, "currency": "USD" }, "total_discount_money": { "amount": 250, "currency": "USD" }, "total_money": { "amount": 250, "currency": "USD" }, "variation_total_price_money": { "amount": 500, "currency": "USD" }, "applied_discounts": [ { "uid": "9zr9S4dxvPAixvn0lpa1VC", "discount_uid": "zGsRZP69aqSSR9lq9euSPB", "applied_money": { "amount": 250, "currency": "USD" } } ] }, { "uid": "mumY8Nun4BC5aKe2yyx5a", "quantity": "2", "name": "Item 2", "base_price_money": { "amount": 300, "currency": "USD" }, "gross_sales_money": { "amount": 600, "currency": "USD" }, "total_tax_money": { "amount": 0, "currency": "USD" }, "total_service_charge_money": { "amount": 0, "currency": "USD" }, "total_discount_money": { "amount": 300, "currency": "USD" }, "total_money": { "amount": 300, "currency": "USD" }, "variation_total_price_money": { "amount": 600, "currency": "USD" }, "applied_discounts": [ { "uid": "qa8LwwZK82FgSEkQc2HYVC", "discount_uid": "zGsRZP69aqSSR9lq9euSPB", "applied_money": { "amount": 300, "currency": "USD" } } ] } ], "discounts": [ { "uid": "zGsRZP69aqSSR9lq9euSPB", "name": "50% Off", "percentage": "50", "applied_money": { "amount": 550, "currency": "USD" }, "type": "FIXED_PERCENTAGE", "scope": "ORDER" } ], "created_at": "2020-05-18T16:30:49.614Z", "updated_at": "2020-05-18T16:30:49.614Z", "state": "OPEN", "version": 1, "total_tax_money": { "amount": 0, "currency": "USD" }, "total_discount_money": { "amount": 550, "currency": "USD" }, "total_tip_money": { "amount": 0, "currency": "USD" }, "total_money": { "amount": 550, "currency": "USD" }, "total_service_charge_money": { "amount": 0, "currency": "USD" }, "net_amounts": { "total_money": { "amount": 550, "currency": "USD" }, "tax_money": { "amount": 0, "currency": "USD" }, "discount_money": { "amount": 550, "currency": "USD" }, "tip_money": { "amount": 0, "currency": "USD" }, "service_charge_money": { "amount": 0, "currency": "USD" } } } } }, "CancelBookingRequest": { "type": "object", "properties": { "idempotency_key": { "minLength": 0, "maxLength": 255, "type": "string", "description": "A unique key to make this request an idempotent operation." }, "booking_version": { "minimum": 0, "type": "integer", "description": "The revision number for the booking used for optimistic concurrency." } }, "description": "", "x-release-status": "PUBLIC", "example": { "booking_version": 1 } }, "CancelBookingResponse": { "type": "object", "properties": { "booking": { "$ref": "#/definitions/Booking", "description": "The booking that was cancelled." }, "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Errors that occurred during the request." } }, "description": "", "x-release-status": "PUBLIC", "example": { "booking": { "id": "zkras0xv0xwswx", "version": 1, "status": "CANCELLED_BY_CUSTOMER", "created_at": "2020-10-28T15:47:41Z", "updated_at": "2020-10-28T15:49:25Z", "location_id": "LEQHH0YY8B42M", "customer_id": "EX2QSVGTZN4K1E5QE1CBFNVQ8M", "customer_note": "", "seller_note": "", "start_at": "2020-11-26T13:00:00Z", "appointment_segments": [ { "duration_minutes": 60, "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC", "team_member_id": "TMXUrsBWWcHTt79t", "service_variation_version": 1599775456731 } ] }, "errors": [] } }, "CancelInvoiceRequest": { "type": "object", "required": [ "version" ], "properties": { "version": { "type": "integer", "description": "The version of the [invoice](https://developer.squareup.com/reference/square_2024-10-17/objects/Invoice) to cancel.\nIf you do not know the version, you can call \n[GetInvoice](https://developer.squareup.com/reference/square_2024-10-17/invoices-api/get-invoice) or [ListInvoices](https://developer.squareup.com/reference/square_2024-10-17/invoices-api/list-invoices)." } }, "description": "Describes a `CancelInvoice` request.", "x-release-status": "PUBLIC", "example": { "request_body": { "version": 0 } } }, "CancelInvoiceResponse": { "type": "object", "properties": { "invoice": { "$ref": "#/definitions/Invoice", "description": "The canceled invoice." }, "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Information about errors encountered during the request." } }, "description": "The response returned by the `CancelInvoice` request.", "x-release-status": "PUBLIC", "example": { "invoice": { "id": "inv:0-ChCHu2mZEabLeeHahQnXDjZQECY", "version": 1, "location_id": "ES0RJRZYEC39A", "order_id": "CAISENgvlJ6jLWAzERDzjyHVybY", "payment_requests": [ { "uid": "2da7964f-f3d2-4f43-81e8-5aa220bf3355", "request_type": "BALANCE", "due_date": "2030-01-24", "tipping_enabled": true, "reminders": [ { "uid": "beebd363-e47f-4075-8785-c235aaa7df11", "relative_scheduled_days": -1, "message": "Your invoice is due tomorrow", "status": "PENDING" } ], "computed_amount_money": { "amount": 10000, "currency": "USD" }, "total_completed_amount_money": { "amount": 0, "currency": "USD" }, "automatic_payment_source": "NONE" } ], "invoice_number": "inv-100", "title": "Event Planning Services", "description": "We appreciate your business!", "scheduled_at": "2030-01-13T10:00:00Z", "status": "CANCELED", "timezone": "America/Los_Angeles", "created_at": "2020-06-18T17:45:13Z", "updated_at": "2020-06-18T18:23:11Z", "primary_recipient": { "customer_id": "JDKYHBWT1D4F8MFH63DBMEN8Y4", "given_name": "Amelia", "family_name": "Earhart", "email_address": "Amelia.Earhart@example.com", "phone_number": "1-212-555-4240" }, "accepted_payment_methods": { "card": true, "square_gift_card": false, "bank_account": false, "buy_now_pay_later": false, "cash_app_pay": false }, "custom_fields": [ { "label": "Event Reference Number", "value": "Ref. #1234", "placement": "ABOVE_LINE_ITEMS" }, { "label": "Terms of Service", "value": "The terms of service are...", "placement": "BELOW_LINE_ITEMS" } ], "delivery_method": "EMAIL", "sale_or_service_date": "2030-01-24", "store_payment_method_enabled": false } } }, "CancelLoyaltyPromotionRequest": { "type": "object", "properties": {}, "description": "Represents a [CancelLoyaltyPromotion](https://developer.squareup.com/reference/square_2024-10-17/loyalty-api/cancel-loyalty-promotion) request.", "x-release-status": "PUBLIC", "example": { "request_params": "?program_id\u003dd619f755-2d17-41f3-990d-c04ecedd64dd\u0026promotion_id\u003dloypromo_f0f9b849-725e-378d-b810-511237e07b67", "request_body": {} } }, "CancelLoyaltyPromotionResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Any errors that occurred during the request." }, "loyalty_promotion": { "$ref": "#/definitions/LoyaltyPromotion", "description": "The canceled loyalty promotion." } }, "description": "Represents a [CancelLoyaltyPromotion](https://developer.squareup.com/reference/square_2024-10-17/loyalty-api/cancel-loyalty-promotion) response.\nEither `loyalty_promotion` or `errors` is present in the response.", "x-release-status": "PUBLIC", "example": { "loyalty_promotion": { "id": "loypromo_f0f9b849-725e-378d-b810-511237e07b67", "name": "Tuesday Happy Hour Promo", "incentive": { "type": "POINTS_MULTIPLIER", "points_multiplier_data": { "multiplier": "3.000", "points_multiplier": 3 } }, "available_time": { "start_date": "2022-08-16", "time_periods": [ "BEGIN:VEVENT\nDTSTART:20220816T160000\nDURATION:PT2H\nRRULE:FREQ\u003dWEEKLY;BYDAY\u003dTU\nEND:VEVENT" ] }, "trigger_limit": { "times": 1, "interval": "DAY" }, "minimum_spend_amount_money": { "currency": "USD", "amount": 2000 }, "qualifying_category_ids": [ "XTQPYLR3IIU9C44VRCB3XD12" ], "status": "CANCELED", "created_at": "2022-08-16T08:38:54Z", "canceled_at": "2022-08-17T12:42:49Z", "updated_at": "2022-08-17T12:42:49Z", "loyalty_program_id": "d619f755-2d17-41f3-990d-c04ecedd64dd" } } }, "CancelPaymentByIdempotencyKeyRequest": { "type": "object", "required": [ "idempotency_key" ], "properties": { "idempotency_key": { "minLength": 1, "maxLength": 45, "type": "string", "description": "The `idempotency_key` identifying the payment to be canceled." } }, "description": "Describes a request to cancel a payment using \n[CancelPaymentByIdempotencyKey](https://developer.squareup.com/reference/square_2024-10-17/payments-api/cancel-payment-by-idempotency-key).", "x-release-status": "PUBLIC", "example": { "request_body": { "idempotency_key": "a7e36d40-d24b-11e8-b568-0800200c9a66" } } }, "CancelPaymentByIdempotencyKeyResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Any errors that occurred during the request." } }, "description": "Defines the response returned by \n[CancelPaymentByIdempotencyKey](https://developer.squareup.com/reference/square_2024-10-17/payments-api/cancel-payment-by-idempotency-key).\nOn success, `errors` is empty.", "x-release-status": "PUBLIC", "example": {} }, "CancelPaymentRequest": { "type": "object", "properties": {}, "description": "Describes the request to cancel (void) a payment using\n[CancelPayment](https://developer.squareup.com/reference/square_2024-10-17/payments-api/cancel-payment).\nYou can only cancel a payment that is approved (not completed).\nFor more information, see\n[Delayed capture of a payment](https://developer.squareup.com/docs/payments-api/take-payments/card-payments#delayed-capture-of-a-card-payment).", "x-release-status": "PUBLIC", "example": { "request_body": {} } }, "CancelPaymentResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Information about errors encountered during the request." }, "payment": { "$ref": "#/definitions/Payment", "description": "The successfully canceled `Payment` object." } }, "description": "Defines the response returned by [CancelPayment](https://developer.squareup.com/reference/square_2024-10-17/payments-api/cancel-payment).", "x-release-status": "PUBLIC", "example": { "payment": { "id": "1QjqpBVyrI9S4H9sTGDWU9JeiWdZY", "created_at": "2021-10-13T20:26:44.191Z", "updated_at": "2021-10-13T20:31:21.597Z", "amount_money": { "amount": 1000, "currency": "USD" }, "tip_money": { "amount": 100, "currency": "USD" }, "status": "CANCELED", "delay_duration": "PT168H", "source_type": "CARD", "card_details": { "status": "VOIDED", "card": { "card_brand": "VISA", "last_4": "1111", "exp_month": 11, "exp_year": 2022, "fingerprint": "sq-1-Hxim77tbdcbGejOejnoAklBVJed2YFLTmirfl8Q5XZzObTc8qY_U8RkwzoNL8dCEcQ", "card_type": "DEBIT", "prepaid_type": "NOT_PREPAID", "bin": "411111" }, "entry_method": "ON_FILE", "cvv_status": "CVV_ACCEPTED", "avs_status": "AVS_ACCEPTED", "auth_result_code": "68aLBM", "statement_description": "SQ *EXAMPLE TEST GOSQ.C", "card_payment_timeline": { "authorized_at": "2021-10-13T20:26:44.364Z", "voided_at": "2021-10-13T20:31:21.597Z" } }, "location_id": "L88917AVBK2S5", "order_id": "nUSN9TdxpiK3SrQg3wzmf6r8LP9YY", "risk_evaluation": { "created_at": "2021-10-13T20:26:45.271Z", "risk_level": "NORMAL" }, "note": "Example Note", "customer_id": "W92WH6P11H4Z77CTET0RNTGFW8", "total_money": { "amount": 1100, "currency": "USD" }, "approved_money": { "amount": 1000, "currency": "USD" }, "delay_action": "CANCEL", "delayed_until": "2021-10-20T20:26:44.191Z", "application_details": { "square_product": "ECOMMERCE_API", "application_id": "sq0ids-TcgftTEtKxJTRF1lCFJ9TA" }, "version_token": "N8AGYgEjCiY9Q57Jw7aVHEpBq8bzGCDCQMRX8Vs56N06o" } } }, "CancelSubscriptionRequest": { "type": "object", "properties": {}, "description": "Defines input parameters in a request to the \n[CancelSubscription](https://developer.squareup.com/reference/square_2024-10-17/subscriptions-api/cancel-subscription) endpoint.", "x-release-status": "PUBLIC" }, "CancelSubscriptionResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Errors encountered during the request." }, "subscription": { "$ref": "#/definitions/Subscription", "description": "The specified subscription scheduled for cancellation according to the action created by the request." }, "actions": { "type": "array", "items": { "$ref": "#/definitions/SubscriptionAction" }, "description": "A list of a single `CANCEL` action scheduled for the subscription.", "x-release-status": "BETA", "x-is-beta": true } }, "description": "Defines output parameters in a response from the \n[CancelSubscription](https://developer.squareup.com/reference/square_2024-10-17/subscriptions-api/cancel-subscription) endpoint.", "x-release-status": "PUBLIC", "example": { "subscription": { "id": "910afd30-464a-4e00-a8d8-2296e", "location_id": "S8GWD5R9QB376", "plan_variation_id": "6JHXF3B2CW3YKHDV4XEM674H", "customer_id": "CHFGVKYY8RSV93M5KCYTG4PN0G", "card_id": "ccof:qy5x8hHGYsgLrp4Q4GB", "start_date": "2022-01-19", "canceled_date": "2023-06-05", "paid_until_date": "2023-12-31", "status": "ACTIVE", "invoice_ids": [ "inv:0-ChCHu2mZEabLeeHahQnXDjZQECY", "inv:0-ChrcX_i3sNmfsHTGKhI4Wg2mceA" ], "created_at": "2022-01-19T21:53:10Z", "version": 3, "timezone": "America/Los_Angeles", "source": { "name": "My Application" } } } }, "CancelTerminalActionRequest": { "type": "object", "properties": {}, "description": "", "x-release-status": "BETA", "x-is-beta": true, "example": { "request_body": {} } }, "CancelTerminalActionResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Information on errors encountered during the request." }, "action": { "$ref": "#/definitions/TerminalAction", "description": "The canceled `TerminalAction`" } }, "description": "", "x-release-status": "BETA", "x-is-beta": true, "example": { "action": { "id": "termapia:jveJIAkkAjILHkdCE", "device_id": "DEVICE_ID", "deadline_duration": "PT5M", "created_at": "2021-07-28T23:22:07.476Z", "updated_at": "2021-07-28T23:22:29.511Z", "status": "CANCELED", "cancel_reason": "SELLER_CANCELED", "location_id": "LOCATION_ID", "type": "SAVE_CARD", "app_id": "APP_ID", "save_card_options": { "customer_id": "CUSTOMER_ID", "reference_id": "user-id-1" } } } }, "CancelTerminalCheckoutRequest": { "type": "object", "properties": {}, "description": "", "x-release-status": "PUBLIC", "example": { "request_body": {} } }, "CancelTerminalCheckoutResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Information about errors encountered during the request." }, "checkout": { "$ref": "#/definitions/TerminalCheckout", "description": "The canceled `TerminalCheckout`." } }, "description": "", "x-release-status": "PUBLIC", "example": { "checkout": { "id": "S1yDlPQx7slqO", "amount_money": { "amount": 123, "currency": "USD" }, "reference_id": "id36815", "device_options": { "device_id": "dbb5d83a-7838-11ea-bc55-0242ac130003", "tip_settings": { "allow_tipping": true }, "skip_receipt_screen": true }, "location_id": "LOCATION_ID", "status": "CANCELED", "cancel_reason": "SELLER_CANCELED", "created_at": "2020-03-16T15:31:19.934Z", "updated_at": "2020-03-16T15:31:45.787Z", "app_id": "APP_ID", "deadline_duration": "PT5M" } } }, "CancelTerminalRefundRequest": { "type": "object", "properties": {}, "description": "", "x-release-status": "PUBLIC", "example": { "request_body": {} } }, "CancelTerminalRefundResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Information about errors encountered during the request." }, "refund": { "$ref": "#/definitions/TerminalRefund", "description": "The updated `TerminalRefund`." } }, "description": "", "x-release-status": "PUBLIC", "example": { "refund": { "id": "g6ycb6HD-5O5OvgkcNUhl7JBuINflcjKqUzXZY", "payment_id": "5O5OvgkcNUhl7JBuINflcjKqUzXZY", "amount_money": { "amount": 100, "currency": "CAD" }, "reason": "reason", "device_id": "42690809-faa2-4701-a24b-19d3d34c9aaa", "deadline_duration": "PT5M", "status": "CANCELED", "cancel_reason": "SELLER_CANCELED", "created_at": "2020-10-21T22:47:23.241Z", "updated_at": "2020-10-21T22:47:30.096Z", "app_id": "sandbox-sq0idb-c2OuYt13YaCAeJq_2cd8OQ", "card": { "card_brand": "INTERAC", "last_4": "1111", "exp_month": 1, "exp_year": 2022, "fingerprint": "sq-1-B1fP9MNNmZgVVaPKRND6oDKYbz25S2cTvg9Mzwg3RMTK1zT1PiGRT-AE3nTA8vSmmw", "card_type": "CREDIT", "bin": "411111" }, "order_id": "kcuKDKreRaI4gF4TjmEgZjHk8Z7YY", "location_id": "76C9W6K8CNNQ5" } } }, "CaptureTransactionRequest": { "type": "object", "properties": {}, "description": "", "x-release-status": "DEPRECATED", "x-is-deprecated": true, "example": {}, "x-sq-sdk-sample-code": { "python": "/sdk_samples/CaptureTransaction/CaptureTransactionRequest.python", "csharp": "/sdk_samples/CaptureTransaction/CaptureTransactionRequest.csharp", "java": "/sdk_samples/CaptureTransaction/CaptureTransactionRequest.java", "php": "/sdk_samples/CaptureTransaction/CaptureTransactionRequest.php", "javascript": "/sdk_samples/CaptureTransaction/CaptureTransactionRequest.javascript", "ruby": "/sdk_samples/CaptureTransaction/CaptureTransactionRequest.ruby" } }, "CaptureTransactionResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Any errors that occurred during the request." } }, "description": "Defines the fields that are included in the response body of\na request to the [CaptureTransaction](https://developer.squareup.com/reference/square_2024-10-17/transactions-api/capture-transaction) endpoint.", "x-release-status": "DEPRECATED", "x-is-deprecated": true, "example": {}, "x-sq-sdk-sample-code": { "python": "/sdk_samples/CaptureTransaction/CaptureTransactionResponse.python", "csharp": "/sdk_samples/CaptureTransaction/CaptureTransactionResponse.csharp", "java": "/sdk_samples/CaptureTransaction/CaptureTransactionResponse.java", "php": "/sdk_samples/CaptureTransaction/CaptureTransactionResponse.php", "javascript": "/sdk_samples/CaptureTransaction/CaptureTransactionResponse.javascript", "ruby": "/sdk_samples/CaptureTransaction/CaptureTransactionResponse.ruby" } }, "Card": { "type": "object", "properties": { "id": { "maxLength": 64, "type": "string", "description": "Unique ID for this card. Generated by Square.", "x-read-only": true }, "card_brand": { "type": "string", "description": "The card\u0027s brand.", "x-read-only": true }, "last_4": { "maxLength": 4, "type": "string", "description": "The last 4 digits of the card number.", "x-read-only": true }, "exp_month": { "type": "integer", "format": "int64", "description": "The expiration month of the associated card as an integer between 1 and 12." }, "exp_year": { "type": "integer", "format": "int64", "description": "The four-digit year of the card\u0027s expiration date." }, "cardholder_name": { "maxLength": 96, "type": "string", "description": "The name of the cardholder." }, "billing_address": { "$ref": "#/definitions/Address", "description": "The billing address for this card." }, "fingerprint": { "maxLength": 255, "type": "string", "description": "Intended as a Square-assigned identifier, based\non the card number, to identify the card across multiple locations within a\nsingle application.", "x-read-only": true }, "customer_id": { "type": "string", "description": "**Required** The ID of a customer created using the Customers API to be associated with the card." }, "merchant_id": { "type": "string", "description": "The ID of the merchant associated with the card.", "x-read-only": true }, "reference_id": { "maxLength": 128, "type": "string", "description": "An optional user-defined reference ID that associates this card with\nanother entity in an external system. For example, a customer ID from an\nexternal customer management system." }, "enabled": { "type": "boolean", "description": "Indicates whether or not a card can be used for payments.", "x-read-only": true }, "card_type": { "type": "string", "description": "The type of the card.\nThe Card object includes this field only in response to Payments API calls.", "x-read-only": true }, "prepaid_type": { "type": "string", "description": "Indicates whether the Card is prepaid or not.\nThe Card object includes this field only in response to Payments API calls.", "x-read-only": true }, "bin": { "maxLength": 6, "type": "string", "description": "The first six digits of the card number, known as the Bank Identification Number (BIN). Only the Payments API\nreturns this field.", "x-read-only": true }, "version": { "type": "integer", "format": "int64", "description": "Current version number of the card. Increments with each card update. Requests to update an\nexisting Card object will be rejected unless the version in the request matches the current\nversion for the Card." }, "card_co_brand": { "type": "string", "description": "The card\u0027s co-brand if available. For example, an Afterpay virtual card would have a\nco-brand of AFTERPAY.", "x-read-only": true } }, "description": "Represents the payment details of a card to be used for payments. These\ndetails are determined by the payment token generated by Web Payments SDK.", "x-release-status": "PUBLIC" }, "CardPaymentDetails": { "type": "object", "properties": { "status": { "maxLength": 50, "type": "string", "description": "The card payment\u0027s current state. The state can be AUTHORIZED, CAPTURED, VOIDED, or\nFAILED." }, "card": { "$ref": "#/definitions/Card", "description": "The credit card\u0027s non-confidential details." }, "entry_method": { "maxLength": 50, "type": "string", "description": "The method used to enter the card\u0027s details for the payment. The method can be\n`KEYED`, `SWIPED`, `EMV`, `ON_FILE`, or `CONTACTLESS`." }, "cvv_status": { "maxLength": 50, "type": "string", "description": "The status code returned from the Card Verification Value (CVV) check. The code can be\n`CVV_ACCEPTED`, `CVV_REJECTED`, or `CVV_NOT_CHECKED`." }, "avs_status": { "maxLength": 50, "type": "string", "description": "The status code returned from the Address Verification System (AVS) check. The code can be\n`AVS_ACCEPTED`, `AVS_REJECTED`, or `AVS_NOT_CHECKED`." }, "auth_result_code": { "maxLength": 10, "type": "string", "description": "The status code returned by the card issuer that describes the payment\u0027s\nauthorization status." }, "application_identifier": { "maxLength": 32, "type": "string", "description": "For EMV payments, the application ID identifies the EMV application used for the payment." }, "application_name": { "maxLength": 16, "type": "string", "description": "For EMV payments, the human-readable name of the EMV application used for the payment." }, "application_cryptogram": { "maxLength": 16, "type": "string", "description": "For EMV payments, the cryptogram generated for the payment." }, "verification_method": { "maxLength": 50, "type": "string", "description": "For EMV payments, the method used to verify the cardholder\u0027s identity. The method can be\n`PIN`, `SIGNATURE`, `PIN_AND_SIGNATURE`, `ON_DEVICE`, or `NONE`." }, "verification_results": { "maxLength": 50, "type": "string", "description": "For EMV payments, the results of the cardholder verification. The result can be\n`SUCCESS`, `FAILURE`, or `UNKNOWN`." }, "statement_description": { "maxLength": 50, "type": "string", "description": "The statement description sent to the card networks.\n\nNote: The actual statement description varies and is likely to be truncated and appended with\nadditional information on a per issuer basis." }, "device_details": { "$ref": "#/definitions/DeviceDetails", "description": "__Deprecated__: Use `Payment.device_details` instead.\n\nDetails about the device that took the payment.", "x-release-status": "DEPRECATED", "x-is-deprecated": true }, "card_payment_timeline": { "$ref": "#/definitions/CardPaymentTimeline", "description": "The timeline for card payments." }, "refund_requires_card_presence": { "type": "boolean", "description": "Whether the card must be physically present for the payment to\nbe refunded. If set to `true`, the card must be present.", "x-release-status": "BETA", "x-is-beta": true }, "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Information about errors encountered during the request." } }, "description": "Reflects the current status of a card payment. Contains only non-confidential information.", "x-release-status": "PUBLIC" }, "CardPaymentTimeline": { "type": "object", "properties": { "authorized_at": { "type": "string", "description": "The timestamp when the payment was authorized, in RFC 3339 format." }, "captured_at": { "type": "string", "description": "The timestamp when the payment was captured, in RFC 3339 format." }, "voided_at": { "type": "string", "description": "The timestamp when the payment was voided, in RFC 3339 format." } }, "description": "The timeline for card payments.", "x-release-status": "PUBLIC" }, "CashAppDetails": { "type": "object", "properties": { "buyer_full_name": { "maxLength": 255, "type": "string", "description": "The name of the Cash App account holder." }, "buyer_country_code": { "minLength": 2, "maxLength": 2, "type": "string", "description": "The country of the Cash App account holder, in ISO 3166-1-alpha-2 format.\n\nFor possible values, see [Country](https://developer.squareup.com/reference/square_2024-10-17/enums/Country)." }, "buyer_cashtag": { "minLength": 1, "maxLength": 21, "type": "string", "description": "$Cashtag of the Cash App account holder.", "x-read-only": true } }, "description": "Additional details about `WALLET` type payments with the `brand` of `CASH_APP`.", "x-release-status": "PUBLIC" }, "CashDrawerDevice": { "type": "object", "properties": { "id": { "type": "string", "description": "The device Square-issued ID" }, "name": { "type": "string", "description": "The device merchant-specified name." } }, "description": "", "x-release-status": "PUBLIC" }, "CashDrawerShift": { "type": "object", "properties": { "id": { "type": "string", "description": "The shift unique ID." }, "state": { "type": "string", "description": "The shift current state." }, "opened_at": { "type": "string", "description": "The time when the shift began, in ISO 8601 format." }, "ended_at": { "type": "string", "description": "The time when the shift ended, in ISO 8601 format." }, "closed_at": { "type": "string", "description": "The time when the shift was closed, in ISO 8601 format." }, "description": { "type": "string", "description": "The free-form text description of a cash drawer by an employee." }, "opened_cash_money": { "$ref": "#/definitions/Money", "description": "The amount of money in the cash drawer at the start of the shift.\nThe amount must be greater than or equal to zero." }, "cash_payment_money": { "$ref": "#/definitions/Money", "description": "The amount of money added to the cash drawer from cash payments.\nThis is computed by summing all events with the types CASH_TENDER_PAYMENT and\nCASH_TENDER_CANCELED_PAYMENT. The amount is always greater than or equal to\nzero." }, "cash_refunds_money": { "$ref": "#/definitions/Money", "description": "The amount of money removed from the cash drawer from cash refunds.\nIt is computed by summing the events of type CASH_TENDER_REFUND. The amount\nis always greater than or equal to zero." }, "cash_paid_in_money": { "$ref": "#/definitions/Money", "description": "The amount of money added to the cash drawer for reasons other than cash\npayments. It is computed by summing the events of type PAID_IN. The amount is\nalways greater than or equal to zero." }, "cash_paid_out_money": { "$ref": "#/definitions/Money", "description": "The amount of money removed from the cash drawer for reasons other than\ncash refunds. It is computed by summing the events of type PAID_OUT. The amount\nis always greater than or equal to zero." }, "expected_cash_money": { "$ref": "#/definitions/Money", "description": "The amount of money that should be in the cash drawer at the end of the\nshift, based on the shift\u0027s other money amounts.\nThis can be negative if employees have not correctly recorded all the events\non the cash drawer.\ncash_paid_out_money is a summation of amounts from cash_payment_money (zero\nor positive), cash_refunds_money (zero or negative), cash_paid_in_money (zero\nor positive), and cash_paid_out_money (zero or negative) event types." }, "closed_cash_money": { "$ref": "#/definitions/Money", "description": "The amount of money found in the cash drawer at the end of the shift\nby an auditing employee. The amount should be positive." }, "device": { "$ref": "#/definitions/CashDrawerDevice", "description": "The device running Square Point of Sale that was connected to the cash drawer." }, "created_at": { "type": "string", "description": "The shift start time in RFC 3339 format.", "x-read-only": true }, "updated_at": { "type": "string", "description": "The shift updated at time in RFC 3339 format.", "x-read-only": true }, "location_id": { "type": "string", "description": "The ID of the location the cash drawer shift belongs to.", "x-read-only": true }, "team_member_ids": { "type": "array", "items": { "type": "string" }, "description": "The IDs of all team members that were logged into Square Point of Sale at any\npoint while the cash drawer shift was open.", "x-read-only": true }, "opening_team_member_id": { "type": "string", "description": "The ID of the team member that started the cash drawer shift.", "x-read-only": true }, "ending_team_member_id": { "type": "string", "description": "The ID of the team member that ended the cash drawer shift.", "x-read-only": true }, "closing_team_member_id": { "type": "string", "description": "The ID of the team member that closed the cash drawer shift by auditing\nthe cash drawer contents.", "x-read-only": true } }, "description": "This model gives the details of a cash drawer shift.\nThe cash_payment_money, cash_refund_money, cash_paid_in_money,\nand cash_paid_out_money fields are all computed by summing their respective\nevent types.", "x-release-status": "PUBLIC" }, "CashDrawerShiftEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique ID of the event." }, "event_type": { "type": "string", "description": "The type of cash drawer shift event." }, "event_money": { "$ref": "#/definitions/Money", "description": "The amount of money that was added to or removed from the cash drawer\nin the event. The amount can be positive (for added money)\nor zero (for other tender type payments). The addition or removal of money can be determined by\nby the event type." }, "created_at": { "type": "string", "description": "The event time in RFC 3339 format.", "x-read-only": true }, "description": { "type": "string", "description": "An optional description of the event, entered by the employee that\ncreated the event." }, "team_member_id": { "type": "string", "description": "The ID of the team member that created the event.", "x-read-only": true } }, "description": "", "x-release-status": "PUBLIC" }, "CashDrawerShiftSummary": { "type": "object", "properties": { "id": { "type": "string", "description": "The shift unique ID." }, "state": { "type": "string", "description": "The shift current state." }, "opened_at": { "type": "string", "description": "The shift start time in ISO 8601 format." }, "ended_at": { "type": "string", "description": "The shift end time in ISO 8601 format." }, "closed_at": { "type": "string", "description": "The shift close time in ISO 8601 format." }, "description": { "type": "string", "description": "An employee free-text description of a cash drawer shift." }, "opened_cash_money": { "$ref": "#/definitions/Money", "description": "The amount of money in the cash drawer at the start of the shift. This\nmust be a positive amount." }, "expected_cash_money": { "$ref": "#/definitions/Money", "description": "The amount of money that should be in the cash drawer at the end of the\nshift, based on the cash drawer events on the shift.\nThe amount is correct if all shift employees accurately recorded their\ncash drawer shift events. Unrecorded events and events with the wrong amount\nresult in an incorrect expected_cash_money amount that can be negative." }, "closed_cash_money": { "$ref": "#/definitions/Money", "description": "The amount of money found in the cash drawer at the end of the shift by\nan auditing employee. The amount must be greater than or equal to zero." }, "created_at": { "type": "string", "description": "The shift start time in RFC 3339 format.", "x-read-only": true }, "updated_at": { "type": "string", "description": "The shift updated at time in RFC 3339 format.", "x-read-only": true }, "location_id": { "type": "string", "description": "The ID of the location the cash drawer shift belongs to.", "x-read-only": true } }, "description": "The summary of a closed cash drawer shift.\nThis model contains only the money counted to start a cash drawer shift, counted\nat the end of the shift, and the amount that should be in the drawer at shift\nend based on summing all cash drawer shift events.", "x-release-status": "PUBLIC" }, "CashPaymentDetails": { "type": "object", "required": [ "buyer_supplied_money" ], "properties": { "buyer_supplied_money": { "$ref": "#/definitions/Money", "description": "The amount and currency of the money supplied by the buyer." }, "change_back_money": { "$ref": "#/definitions/Money", "description": "The amount of change due back to the buyer. \nThis read-only field is calculated\nfrom the `amount_money` and `buyer_supplied_money` fields." } }, "description": "Stores details about a cash payment. Contains only non-confidential information. For more information, see \n[Take Cash Payments](https://developer.squareup.com/docs/payments-api/take-payments/cash-payments).", "x-release-status": "PUBLIC" }, "CatalogAvailabilityPeriod": { "type": "object", "properties": { "start_local_time": { "type": "string", "description": "The start time of an availability period, specified in local time using partial-time\nRFC 3339 format. For example, `8:30:00` for a period starting at 8:30 in the morning.\nNote that the seconds value is always :00, but it is appended for conformance to the RFC." }, "end_local_time": { "type": "string", "description": "The end time of an availability period, specified in local time using partial-time\nRFC 3339 format. For example, `21:00:00` for a period ending at 9:00 in the evening.\nNote that the seconds value is always :00, but it is appended for conformance to the RFC." }, "day_of_week": { "type": "string", "description": "The day of the week for this availability period." } }, "description": "Represents a time period of availability.", "x-release-status": "BETA", "x-is-beta": true }, "CatalogCategory": { "type": "object", "properties": { "name": { "maxLength": 255, "type": "string", "description": "The category name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points." }, "image_ids": { "type": "array", "items": { "type": "string" }, "description": "The IDs of images associated with this `CatalogCategory` instance.\nCurrently these images are not displayed by Square, but are free to be displayed in 3rd party applications." }, "category_type": { "type": "string", "description": "The type of the category." }, "parent_category": { "$ref": "#/definitions/CatalogObjectCategory", "description": "The ID of the parent category of this category instance." }, "is_top_level": { "type": "boolean", "description": "Indicates whether a category is a top level category, which does not have any parent_category." }, "channels": { "type": "array", "items": { "type": "string" }, "description": "A list of IDs representing channels, such as a Square Online site, where the category can be made visible." }, "availability_period_ids": { "type": "array", "items": { "type": "string" }, "description": "The IDs of the `CatalogAvailabilityPeriod` objects associated with the category." }, "online_visibility": { "type": "boolean", "description": "Indicates whether the category is visible (`true`) or hidden (`false`) on all of the seller\u0027s Square Online sites." }, "root_category": { "type": "string", "description": "The top-level category in a category hierarchy.", "x-read-only": true }, "ecom_seo_data": { "$ref": "#/definitions/CatalogEcomSeoData", "description": "The SEO data for a seller\u0027s Square Online store." }, "path_to_root": { "type": "array", "items": { "$ref": "#/definitions/CategoryPathToRootNode" }, "description": "The path from the category to its root category. The first node of the path is the parent of the category\nand the last is the root category. The path is empty if the category is a root category." } }, "description": "A category to which a `CatalogItem` instance belongs.", "x-release-status": "PUBLIC", "example": { "object": { "type": "CATEGORY", "id": "#Beverages", "present_at_all_locations": true, "category_data": { "name": "Beverages" } } } }, "CatalogCustomAttributeDefinition": { "type": "object", "required": [ "type", "name", "allowed_object_types" ], "properties": { "type": { "type": "string", "description": "The type of this custom attribute. Cannot be modified after creation.\nRequired." }, "name": { "minLength": 1, "maxLength": 255, "type": "string", "description": " The name of this definition for API and seller-facing UI purposes.\nThe name must be unique within the (merchant, application) pair. Required.\nMay not be empty and may not exceed 255 characters. Can be modified after creation." }, "description": { "maxLength": 255, "type": "string", "description": "Seller-oriented description of the meaning of this Custom Attribute,\nany constraints that the seller should observe, etc. May be displayed as a tooltip in Square UIs." }, "source_application": { "$ref": "#/definitions/SourceApplication", "description": "__Read only.__ Contains information about the application that\ncreated this custom attribute definition." }, "allowed_object_types": { "type": "array", "items": { "type": "string" }, "description": "The set of `CatalogObject` types that this custom atttribute may be applied to.\nCurrently, only `ITEM`, `ITEM_VARIATION`, `MODIFIER`, `MODIFIER_LIST`, and `CATEGORY` are allowed. At least one type must be included." }, "seller_visibility": { "type": "string", "description": "The visibility of a custom attribute in seller-facing UIs (including Square Point\nof Sale applications and Square Dashboard). May be modified." }, "app_visibility": { "type": "string", "description": "The visibility of a custom attribute to applications other than the application\nthat created the attribute." }, "string_config": { "$ref": "#/definitions/CatalogCustomAttributeDefinitionStringConfig", "description": "Optionally, populated when `type` \u003d `STRING`, unset otherwise." }, "number_config": { "$ref": "#/definitions/CatalogCustomAttributeDefinitionNumberConfig", "description": "Optionally, populated when `type` \u003d `NUMBER`, unset otherwise." }, "selection_config": { "$ref": "#/definitions/CatalogCustomAttributeDefinitionSelectionConfig", "description": "Populated when `type` is set to `SELECTION`, unset otherwise." }, "custom_attribute_usage_count": { "type": "integer", "description": "The number of custom attributes that reference this\ncustom attribute definition. Set by the server in response to a ListCatalog\nrequest with `include_counts` set to `true`. If the actual count is greater\nthan 100, `custom_attribute_usage_count` will be set to `100`.", "x-read-only": true }, "key": { "minLength": 1, "pattern": "^[a-zA-Z0-9_-]*$", "maxLength": 60, "type": "string", "description": "The name of the desired custom attribute key that can be used to access\nthe custom attribute value on catalog objects. Cannot be modified after the\ncustom attribute definition has been created.\nMust be between 1 and 60 characters, and may only contain the characters `[a-zA-Z0-9_-]`." } }, "description": "Contains information defining a custom attribute. Custom attributes are\nintended to store additional information about a catalog object or to associate a\ncatalog object with an entity in another system. Do not use custom attributes\nto store any sensitive information (personally identifiable information, card details, etc.).\n[Read more about custom attributes](https://developer.squareup.com/docs/catalog-api/add-custom-attributes)", "x-release-status": "PUBLIC" }, "CatalogCustomAttributeDefinitionNumberConfig": { "type": "object", "properties": { "precision": { "maximum": 5, "minimum": 0, "type": "integer", "description": "An integer between 0 and 5 that represents the maximum number of\npositions allowed after the decimal in number custom attribute values\nFor example:\n\n- if the precision is 0, the quantity can be 1, 2, 3, etc.\n- if the precision is 1, the quantity can be 0.1, 0.2, etc.\n- if the precision is 2, the quantity can be 0.01, 0.12, etc.\n\nDefault: 5" } }, "description": "", "x-release-status": "PUBLIC" }, "CatalogCustomAttributeDefinitionSelectionConfig": { "type": "object", "properties": { "max_allowed_selections": { "maximum": 100, "type": "integer", "description": "The maximum number of selections that can be set. The maximum value for this\nattribute is 100. The default value is 1. The value can be modified, but changing the value will not\naffect existing custom attribute values on objects. Clients need to\nhandle custom attributes with more selected values than allowed by this limit." }, "allowed_selections": { "type": "array", "items": { "$ref": "#/definitions/CatalogCustomAttributeDefinitionSelectionConfigCustomAttributeSelection" }, "description": "The set of valid `CatalogCustomAttributeSelections`. Up to a maximum of 100\nselections can be defined. Can be modified." } }, "description": "Configuration associated with `SELECTION`-type custom attribute definitions.", "x-release-status": "PUBLIC" }, "CatalogCustomAttributeDefinitionSelectionConfigCustomAttributeSelection": { "type": "object", "required": [ "name" ], "properties": { "uid": { "type": "string", "description": "Unique ID set by Square." }, "name": { "minLength": 1, "maxLength": 255, "type": "string", "description": "Selection name, unique within `allowed_selections`." } }, "description": "A named selection for this `SELECTION`-type custom attribute definition.", "x-release-status": "PUBLIC" }, "CatalogCustomAttributeDefinitionStringConfig": { "type": "object", "properties": { "enforce_uniqueness": { "type": "boolean", "description": "If true, each Custom Attribute instance associated with this Custom Attribute\nDefinition must have a unique value within the seller\u0027s catalog. For\nexample, this may be used for a value like a SKU that should not be\nduplicated within a seller\u0027s catalog. May not be modified after the\ndefinition has been created." } }, "description": "Configuration associated with Custom Attribute Definitions of type `STRING`.", "x-release-status": "PUBLIC" }, "CatalogCustomAttributeValue": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom attribute." }, "string_value": { "type": "string", "description": "The string value of the custom attribute. Populated if `type` \u003d `STRING`." }, "custom_attribute_definition_id": { "type": "string", "description": "The id of the [CatalogCustomAttributeDefinition](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogCustomAttributeDefinition) this value belongs to.", "x-read-only": true }, "type": { "type": "string", "description": "A copy of type from the associated `CatalogCustomAttributeDefinition`.", "x-read-only": true }, "number_value": { "type": "string", "description": "Populated if `type` \u003d `NUMBER`. Contains a string\nrepresentation of a decimal number, using a `.` as the decimal separator." }, "boolean_value": { "type": "boolean", "description": "A `true` or `false` value. Populated if `type` \u003d `BOOLEAN`." }, "selection_uid_values": { "type": "array", "items": { "type": "string" }, "description": "One or more choices from `allowed_selections`. Populated if `type` \u003d `SELECTION`." }, "key": { "type": "string", "description": "If the associated `CatalogCustomAttributeDefinition` object is defined by another application, this key is prefixed by the defining application ID.\nFor example, if the CatalogCustomAttributeDefinition has a key attribute of \"cocoa_brand\" and the defining application ID is \"abcd1234\", this key is \"abcd1234:cocoa_brand\"\nwhen the application making the request is different from the application defining the custom attribute definition. Otherwise, the key is simply \"cocoa_brand\".", "x-read-only": true } }, "description": "An instance of a custom attribute. Custom attributes can be defined and\nadded to `ITEM` and `ITEM_VARIATION` type catalog objects.\n[Read more about custom attributes](https://developer.squareup.com/docs/catalog-api/add-custom-attributes).", "x-release-status": "PUBLIC" }, "CatalogDiscount": { "type": "object", "properties": { "name": { "maxLength": 255, "type": "string", "description": "The discount name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points." }, "discount_type": { "type": "string", "description": "Indicates whether the discount is a fixed amount or percentage, or entered at the time of sale." }, "percentage": { "type": "string", "description": "The percentage of the discount as a string representation of a decimal number, using a `.` as the decimal\nseparator and without a `%` sign. A value of `7.5` corresponds to `7.5%`. Specify a percentage of `0` if `discount_type`\nis `VARIABLE_PERCENTAGE`.\n\nDo not use this field for amount-based or variable discounts." }, "amount_money": { "$ref": "#/definitions/Money", "description": "The amount of the discount. Specify an amount of `0` if `discount_type` is `VARIABLE_AMOUNT`.\n\nDo not use this field for percentage-based or variable discounts." }, "pin_required": { "type": "boolean", "description": "Indicates whether a mobile staff member needs to enter their PIN to apply the\ndiscount to a payment in the Square Point of Sale app." }, "label_color": { "type": "string", "description": "The color of the discount display label in the Square Point of Sale app. This must be a valid hex color code." }, "modify_tax_basis": { "type": "string", "description": "Indicates whether this discount should reduce the price used to calculate tax.\n\nMost discounts should use `MODIFY_TAX_BASIS`. However, in some circumstances taxes must\nbe calculated based on an item\u0027s price, ignoring a particular discount. For example,\nin many US jurisdictions, a manufacturer coupon or instant rebate reduces the price a\ncustomer pays but does not reduce the sale price used to calculate how much sales tax is\ndue. In this case, the discount representing that manufacturer coupon should have\n`DO_NOT_MODIFY_TAX_BASIS` for this field.\n\nIf you are unsure whether you need to use this field, consult your tax professional." }, "maximum_amount_money": { "$ref": "#/definitions/Money", "description": "For a percentage discount, the maximum absolute value of the discount. For example, if a\n50% discount has a `maximum_amount_money` of $20, a $100 purchase will yield a $20 discount,\nnot a $50 discount." } }, "description": "A discount applicable to items.", "x-release-status": "PUBLIC", "example": { "object": { "type": "DISCOUNT", "id": "#Maythe4th", "present_at_all_locations": true, "discount_data": { "name": "Welcome to the Dark(Roast) Side!", "discount_type": "FIXED_PERCENTAGE", "percentage": "5.4", "pin_required": false, "label_color": "red" } } } }, "CatalogEcomSeoData": { "type": "object", "properties": { "page_title": { "type": "string", "description": "The SEO title used for the Square Online store." }, "page_description": { "type": "string", "description": "The SEO description used for the Square Online store." }, "permalink": { "type": "string", "description": "The SEO permalink used for the Square Online store." } }, "description": "SEO data for for a seller\u0027s Square Online store.", "x-release-status": "PUBLIC" }, "CatalogIdMapping": { "type": "object", "properties": { "client_object_id": { "type": "string", "description": "The client-supplied temporary `#`-prefixed ID for a new `CatalogObject`." }, "object_id": { "type": "string", "description": "The permanent ID for the CatalogObject created by the server." } }, "description": "A mapping between a temporary client-supplied ID and a permanent server-generated ID.\n\nWhen calling [UpsertCatalogObject](https://developer.squareup.com/reference/square_2024-10-17/catalog-api/upsert-catalog-object) or\n[BatchUpsertCatalogObjects](https://developer.squareup.com/reference/square_2024-10-17/catalog-api/batch-upsert-catalog-objects) to\ncreate a [CatalogObject](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogObject) instance, you can supply\na temporary ID for the to-be-created object, especially when the object is to be referenced\nelsewhere in the same request body. This temporary ID can be any string unique within\nthe call, but must be prefixed by \"#\".\n\nAfter the request is submitted and the object created, a permanent server-generated ID is assigned\nto the new object. The permanent ID is unique across the Square catalog.", "x-release-status": "PUBLIC" }, "CatalogImage": { "type": "object", "properties": { "name": { "type": "string", "description": "The internal name to identify this image in calls to the Square API.\nThis is a searchable attribute for use in applicable query filters\nusing the [SearchCatalogObjects](https://developer.squareup.com/reference/square_2024-10-17/catalog-api/search-catalog-objects).\nIt is not unique and should not be shown in a buyer facing context." }, "url": { "type": "string", "description": "The URL of this image, generated by Square after an image is uploaded\nusing the [CreateCatalogImage](https://developer.squareup.com/reference/square_2024-10-17/catalog-api/create-catalog-image) endpoint.\nTo modify the image, use the UpdateCatalogImage endpoint. Do not change the URL field." }, "caption": { "type": "string", "description": "A caption that describes what is shown in the image. Displayed in the\nSquare Online Store. This is a searchable attribute for use in applicable query filters\nusing the [SearchCatalogObjects](https://developer.squareup.com/reference/square_2024-10-17/catalog-api/search-catalog-objects)." }, "photo_studio_order_id": { "type": "string", "description": "The immutable order ID for this image object created by the Photo Studio service in Square Online Store." } }, "description": "An image file to use in Square catalogs. It can be associated with\n`CatalogItem`, `CatalogItemVariation`, `CatalogCategory`, and `CatalogModifierList` objects.\nOnly the images on items and item variations are exposed in Dashboard.\nOnly the first image on an item is displayed in Square Point of Sale (SPOS).\nImages on items and variations are displayed through Square Online Store.\nImages on other object types are for use by 3rd party application developers.", "x-release-status": "PUBLIC" }, "CatalogInfoRequest": { "type": "object", "properties": {}, "description": "", "x-release-status": "PUBLIC", "example": {}, "x-sq-sdk-sample-code": { "python": "/sdk_samples/Catalog/CatalogInfo/CatalogInfoRequest.python", "csharp": "/sdk_samples/Catalog/CatalogInfo/CatalogInfoRequest.csharp", "java": "/sdk_samples/Catalog/CatalogInfo/CatalogInfoRequest.java", "php": "/sdk_samples/Catalog/CatalogInfo/CatalogInfoRequest.php", "javascript": "/sdk_samples/Catalog/CatalogInfo/CatalogInfoRequest.javascript", "ruby": "/sdk_samples/Catalog/CatalogInfo/CatalogInfoRequest.ruby" } }, "CatalogInfoResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" }, "description": "Any errors that occurred during the request." }, "limits": { "$ref": "#/definitions/CatalogInfoResponseLimits", "description": "Limits that apply to this API." }, "standard_unit_description_group": { "$ref": "#/definitions/StandardUnitDescriptionGroup", "description": "Names and abbreviations for standard units." } }, "description": "", "x-release-status": "PUBLIC", "example": { "limits": { "batch_upsert_max_objects_per_batch": 1000, "batch_upsert_max_total_objects": 10000, "batch_retrieve_max_object_ids": 1000, "search_max_page_limit": 1000, "batch_delete_max_object_ids": 200, "update_item_taxes_max_item_ids": 1000, "update_item_taxes_max_taxes_to_enable": 1000, "update_item_taxes_max_taxes_to_disable": 1000, "update_item_modifier_lists_max_item_ids": 1000, "update_item_modifier_lists_max_modifier_lists_to_enable": 1000, "update_item_modifier_lists_max_modifier_lists_to_disable": 1000 } }, "x-sq-sdk-sample-code": { "python": "/sdk_samples/Catalog/CatalogInfo/CatalogInfoResponse.python", "csharp": "/sdk_samples/Catalog/CatalogInfo/CatalogInfoResponse.csharp", "java": "/sdk_samples/Catalog/CatalogInfo/CatalogInfoResponse.java", "php": "/sdk_samples/Catalog/CatalogInfo/CatalogInfoResponse.php", "javascript": "/sdk_samples/Catalog/CatalogInfo/CatalogInfoResponse.javascript", "ruby": "/sdk_samples/Catalog/CatalogInfo/CatalogInfoResponse.ruby" } }, "CatalogInfoResponseLimits": { "type": "object", "properties": { "batch_upsert_max_objects_per_batch": { "type": "integer", "description": "The maximum number of objects that may appear within a single batch in a\n`/v2/catalog/batch-upsert` request." }, "batch_upsert_max_total_objects": { "type": "integer", "description": "The maximum number of objects that may appear across all batches in a\n`/v2/catalog/batch-upsert` request." }, "batch_retrieve_max_object_ids": { "type": "integer", "description": "The maximum number of object IDs that may appear in a `/v2/catalog/batch-retrieve`\nrequest." }, "search_max_page_limit": { "type": "integer", "description": "The maximum number of results that may be returned in a page of a\n`/v2/catalog/search` response." }, "batch_delete_max_object_ids": { "type": "integer", "description": "The maximum number of object IDs that may be included in a single\n`/v2/catalog/batch-delete` request." }, "update_item_taxes_max_item_ids": { "type": "integer", "description": "The maximum number of item IDs that may be included in a single\n`/v2/catalog/update-item-taxes` request." }, "update_item_taxes_max_taxes_to_enable": { "type": "integer", "description": "The maximum number of tax IDs to be enabled that may be included in a single\n`/v2/catalog/update-item-taxes` request." }, "update_item_taxes_max_taxes_to_disable": { "type": "integer", "description": "The maximum number of tax IDs to be disabled that may be included in a single\n`/v2/catalog/update-item-taxes` request." }, "update_item_modifier_lists_max_item_ids": { "type": "integer", "description": "The maximum number of item IDs that may be included in a single\n`/v2/catalog/update-item-modifier-lists` request." }, "update_item_modifier_lists_max_modifier_lists_to_enable": { "type": "integer", "description": "The maximum number of modifier list IDs to be enabled that may be included in\na single `/v2/catalog/update-item-modifier-lists` request." }, "update_item_modifier_lists_max_modifier_lists_to_disable": { "type": "integer", "description": "The maximum number of modifier list IDs to be disabled that may be included in\na single `/v2/catalog/update-item-modifier-lists` request." } }, "description": "", "x-release-status": "PUBLIC" }, "CatalogItem": { "type": "object", "properties": { "name": { "maxLength": 512, "type": "string", "description": "The item\u0027s name. This is a searchable attribute for use in applicable query filters, its value must not be empty, and the length is of Unicode code points." }, "description": { "maxLength": 4096, "type": "string", "description": "The item\u0027s description. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.\n\nDeprecated at 2022-07-20, this field is planned to retire in 6 months. You should migrate to use `description_html` to set the description\nof the [CatalogItem](https://developer.squareup.com/reference/square_2024-10-17/objects/CatalogItem) instance. The `description` and `description_html` field values are kept in sync. If you try to\nset the both fields, the `description_html` text value overwrites the `description` value. Updates in one field are also reflected in the other,\ne