Square Component
Square offers a suite of commerce products for retail stores.
Component key: square
Description
Square: https://squareup.com/ is a comprehensive commerce solution that provides a wide array of services like payments, point-of-sale (POS) system, online store builder, and more. It's trusted by millions of businesses for enabling seamless transactions and providing powerful business tools.
Use the Square component to manage payments, items, orders, customer data, and more in your Square account.
A Note on Square Pagination
Square's API supports pagination. This means that the API will return up to a specific limit of items for any query. If additional results are available, the API response includes a cursor field that can be used to retrieve the next page of data.
{
"objects": [],
"cursor": "next_page_cursor"
}
The cursor can be used in a subsequent query to fetch additional results.
See Square's Docs(https://developer.squareup.com/explorer/square) for information about Square's paginated API, and this quickstart for information on looping over a paginated API in Prismatic.
Connections
Square OAuth 2.0
Access Tokens are necessary for interacting with the Square API. Access tokens are unique to each application you create on Square.
To generate an access token, you should log in to Square and navigate to your application's page. Within the application settings, you can find your access tokens.
Square provides two types of access tokens:
- Application Token: This token is used to send requests and perform other application-related actions in Square.
- Personal Access Token: This token is used to perform account-level actions, such as creating and managing applications.
For your integration, you will need both the Application Token and the Personal Access Token.
For more information about access tokens, refer to the Square Docs.
| Input | Notes | Example |
|---|---|---|
| Authorize URL | The OAuth 2.0 Authorization URL for Square | https://connect.squareup.com/oauth2/authorize |
| Application ID | ||
| Application Secret | ||
| Scopes | A space-delimited set of one or more scopes to get the user's permission to access. | MERCHANT_PROFILE_READ PAYMENTS_READ PAYMENTS_WRITE |
| Token URL | The OAuth 2.0 Token URL for Square | https://connect.squareup.com/oauth2/token |
Triggers
Webhook
Receive and validate webhook requests from Square for webhooks you configure. | key: squareWebhookTrigger
Data Sources
Select Bank Accounts
List and select from all of the bank accounts linked to a Square account. | key: selectBankAccounts | type: picklist
| Input | Notes | Example |
|---|---|---|
| Cursor | A pagination cursor returned by a previous call to this endpoint. | |
| Limit | The maximum number of results to be returned in a single page. | |
| Location ID | The ID of the location to retrieve details for. | |
| Square Connection |
Select Catalog
List and select from all of the catalog objects of the specified types. | key: selectCatalog | type: picklist
| Input | Notes | Example |
|---|---|---|
| Catalog Version | The specific version of the catalog objects to be included in the response. This allows you to retrieve historical versions of objects. The specified version value is matched against the CatalogObjects' version attribute. | |
| Cursor | A pagination cursor returned by a previous call to this endpoint. | |
| Square Connection | ||
| Types | An optional case-insensitive, comma-separated list of object types to retrieve. The valid values are defined in the CatalogObjectType enum, for example, ITEM, ITEM_VARIATION, CATEGORY, DISCOUNT, TAX, MODIFIER, MODIFIER_LIST, IMAGE, etc. | ITEM, ITEM_VARIATION, CATEGORY, DISCOUNT, TAX, MODIFIER, MODIFIER_LIST, IMAGE |
Select Customers
List and select from all customer profiles associated with a Square account. | key: selectCustomers | type: picklist
| Input | Notes | Example |
|---|---|---|
| Cursor | A pagination cursor returned by a previous call to this endpoint. | |
| Limit | The maximum number of results to be returned in a single page. | |
| Sort Field | Field to sort the customers on. | |
| Sort Order | Order to sort the customers. | |
| Square Connection |
Select Locations
List and select from all of the seller's locations. | key: selectLocations | type: picklist
| Input | Notes | Example |
|---|---|---|
| Square Connection |
Select Merchants
List and select from all of the seller's merchants. | key: selectMerchants | type: picklist
| Input | Notes | Example |
|---|---|---|
| Square Connection |
Select Webhook Event Types
List all webhook event types that can be subscribed to. | key: selectWebhookEventTypes | type: picklist
| Input | Notes | Example |
|---|---|---|
| API Version | The API version to be used in the request. | |
| Square Connection |
Actions
Batch Change Inventory
Applies adjustments and counts to the provided item quantities. | key: batchChangeInventory
| Input | Notes | Example |
|---|---|---|
| Inventory Changes | The set of physical counts and inventory adjustments to be made. Changes are applied based on the client-supplied timestamp and may be sent out of order. | |
| Idempotency Key | ||
| Ignore Unchanged Counts | false | |
| Square Connection |
Batch Delete Catalog Objects
Deletes a set of CatalogItems based on the provided list of target IDs and returns a set of successfully deleted IDs in the response. | key: batchDeleteCatalogObjects
| Input | Notes | Example |
|---|---|---|
| Object IDs | The IDs of the CatalogObjects to be retrieved. | |
| Square Connection |
Batch Retrieve Catalog Objects
Returns a set of objects based on the provided ID. | key: batchRetrieveCatalogObjects
| Input | Notes | Example |
|---|---|---|
| Catalog Version | The specific version of the catalog objects to be included in the response. This allows you to retrieve historical versions of objects. The specified version value is matched against the CatalogObjects' version attribute. | |
| Include Deleted Objects | If true, deleted objects will be included in the results. | false |
| Include Related Objects | If true, the response will include additional objects that are related to the requested objects. | false |
| Object IDs | The IDs of the CatalogObjects to be retrieved. | |
| Square Connection |
Batch Retrieve Inventory Counts
Returns current counts for the provided CatalogObjects at the requested Locations. | key: batchRetrieveInventoryCounts
| Input | Notes | Example |
|---|---|---|
| Catalog Object IDs | The filter to return results by CatalogObject ID. | |
| Cursor | A pagination cursor returned by a previous call to this endpoint. | |
| Limit | The maximum number of results to be returned in a single page. | |
| Location IDs | Array of location IDs. These IDs will be used to filter the results to specific locations. | |
| Square Connection | ||
| States | The filter to return results by InventoryState. | |
| Updated After | The filter to return results with their calculated_at value after the given time as specified in an RFC 3339 timestamp. |
Batch Retrieve Orders
Retrieves a set of orders by their IDs. | key: batchRetrieveOrders
| Input | Notes | Example |
|---|---|---|
| Location ID | The ID of the location to retrieve details for. | |
| Order IDs | The IDs of the orders to retrieve. A maximum of 100 orders can be retrieved per request. | |
| Square Connection |
Batch Upsert Catalog Objects
Creates or updates up to 10,000 target objects based on the provided list of objects. | key: batchUpsertCatalogObjects
| Input | Notes | Example |
|---|---|---|
| Batches | A list of batches of CatalogObjects to be inserted/updated atomically. Each batch may contain up to 1,000 objects. The total number of objects across all batches for a single request may not exceed 10,000. If either of these limits is violated, an error will be returned and no objects will be inserted or updated. | |
| Idempotency Key | ||
| Square Connection |
Cancel Invoice
Cancel an invoice. | key: cancelInvoice
| Input | Notes | Example |
|---|---|---|
| Invoice ID | The ID of the invoice to retrieve. | |
| Square Connection | ||
| Version |
Cancel Payment
Cancels (voids) a payment. | key: cancelPayment
| Input | Notes | Example |
|---|---|---|
| Payment ID | A unique ID for the desired payment. | |
| Square Connection |
Clone Order
Creates a new order, in the DRAFT state, by duplicating an existing order. | key: cloneOrder
| Input | Notes | Example |
|---|---|---|
| Idempotency Key | ||
| Order ID | The ID of the order to retrieve. | |
| Square Connection | ||
| Version |
Complete Payment
Completes (captures) a payment. | key: completePayment
| Input | Notes | Example |
|---|---|---|
| Payment ID | A unique ID for the desired payment. | |
| Square Connection | ||
| Version Token | Used for optimistic concurrency. This token identifies the current Payment version. |
Create Customer
Create a new customer profile. | key: createCustomer
| Input | Notes | Example |
|---|---|---|
| Address | Address in JSON format | |
| Birthday | ||
| Company Name | ||
| Email Address | ||
| Family Name | ||
| Given Name | ||
| Idempotency Key | ||
| Nickname | ||
| Note | ||
| Phone Number | ||
| Reference Id | ||
| Square Connection | ||
| Tax IDs | Tax IDs in JSON format |
Create Order
Create a new order. | key: createOrder
| Input | Notes | Example |
|---|---|---|
| Location ID | The ID of the location to retrieve details for. | |
| Order Object | The complete order object. Please refer to the Square API documentation for the structure of this object. | |
| Square Connection |
Create Payment
Creates a payment using the provided source. | key: createPayment
| Input | Notes | Example |
|---|---|---|
| Payment Data | The payment data object containing all necessary information for creating the payment. | |
| Square Connection |
Create Team Member
Create a new team member. | key: createTeamMember
| Input | Notes | Example |
|---|---|---|
| Idempotency Key | ||
| Square Connection | ||
| Team Member | The data which will be used to create the TeamMember object. |
Create Webhook Subscription
Creates a webhook subscription. | key: createWebhookSubscription
| Input | Notes | Example |
|---|---|---|
| Idempotency Key | ||
| Square Connection | ||
| Webhook Subscription | The Subscription to create. |
Delete Catalog Object
Deletes a single CatalogObject based on the provided ID and returns the set of successfully deleted IDs in the response. | key: deleteCatalogObject
| Input | Notes | Example |
|---|---|---|
| Object ID | The object ID of any type of catalog objects to be retrieved. | |
| Square Connection |
Delete Customer
Delete a customer profile from a business. | key: deleteCustomer
| Input | Notes | Example |
|---|---|---|
| Customer ID | The ID of the customer to retrieve details for. | |
| Square Connection | ||
| Version |
Delete Instance Webhooks
Delete all webhooks that point to a flow in this instance | key: deleteInstanceWebhooks
| Input | Notes | Example |
|---|---|---|
| Square Connection |
Delete Invoice
Delete an invoice. | key: deleteInvoice
| Input | Notes | Example |
|---|---|---|
| Invoice ID | The ID of the invoice to retrieve. | |
| Square Connection | ||
| Version |
Delete Webhook Subscription
Deletes a webhook subscription. | key: deleteWebhookSubscription
| Input | Notes | Example |
|---|---|---|
| Subscription ID | The ID of the Subscription to delete. | |
| Square Connection |
Get Invoice
Retrieve an invoice by its ID. | key: getInvoice
| Input | Notes | Example |
|---|---|---|
| Invoice ID | The ID of the invoice to retrieve. | |
| Square Connection |
Get Payment
Retrieves details for a specific payment. | key: getPayment
| Input | Notes | Example |
|---|---|---|
| Payment ID | A unique ID for the desired payment. | |
| Square Connection |
Get Payment Refund
Retrieves a specific refund using the refund_id. | key: getPaymentRefund
| Input | Notes | Example |
|---|---|---|
| Refund ID | The unique ID for the desired PaymentRefund. | |
| Square Connection |
List Catalog
Returns a list of all CatalogObjects of the specified types in the catalog. | key: listCatalog
| Input | Notes | Example |
|---|---|---|
| Catalog Version | The specific version of the catalog objects to be included in the response. This allows you to retrieve historical versions of objects. The specified version value is matched against the CatalogObjects' version attribute. | |
| Cursor | A pagination cursor returned by a previous call to this endpoint. | |
| Square Connection | ||
| Types | An optional case-insensitive, comma-separated list of object types to retrieve. The valid values are defined in the CatalogObjectType enum, for example, ITEM, ITEM_VARIATION, CATEGORY, DISCOUNT, TAX, MODIFIER, MODIFIER_LIST, IMAGE, etc. | ITEM, ITEM_VARIATION, CATEGORY, DISCOUNT, TAX, MODIFIER, MODIFIER_LIST, IMAGE |
List Customers
List customer profiles associated with a Square account. | key: listCustomers
| Input | Notes | Example |
|---|---|---|
| Cursor | A pagination cursor returned by a previous call to this endpoint. | |
| Limit | The maximum number of results to be returned in a single page. | |
| Sort Field | Field to sort the customers on. | |
| Sort Order | Order to sort the customers. | |
| Square Connection |
List Invoices
Returns a list of invoices for a given location. | key: listInvoices
| Input | Notes | Example |
|---|---|---|
| Cursor | A pagination cursor returned by a previous call to this endpoint. | |
| Limit | The maximum number of results to be returned in a single page. | |
| Location ID | The ID of the location to retrieve details for. | |
| Square Connection |
List Locations
List all of the seller's locations, including those with an inactive status. | key: listLocations
| Input | Notes | Example |
|---|---|---|
| Square Connection |
List Payment Refunds
Retrieves a list of refunds for the account making the request. | key: listPaymentRefunds
| Input | Notes | Example |
|---|---|---|
| Begin Time | Return objects modified after this timestamp, in RFC 3339 format. | |
| Cursor | A pagination cursor returned by a previous call to this endpoint. | |
| End Time | Indicates the end of the time range to retrieve payments for, in RFC 3339 format. The range is determined using the created_at field for each Payment. | |
| Limit | The maximum number of results to be returned in a single page. | |
| Location ID | The ID of the location to retrieve details for. | |
| Sort Order | Order to sort the customers. | |
| Source Type | If provided, only returns refunds whose payments have the indicated source type. | |
| Square Connection | ||
| Status | If provided, only refunds with the given status are returned. |
List Payments
Retrieves a list of payments taken by the account making the request. | key: listPayments
| Input | Notes | Example |
|---|---|---|
| Begin Time | Return objects modified after this timestamp, in RFC 3339 format. | |
| Card Brand | The brand of the payment card (for example, VISA). | |
| Cursor | A pagination cursor returned by a previous call to this endpoint. | |
| End Time | Indicates the end of the time range to retrieve payments for, in RFC 3339 format. The range is determined using the created_at field for each Payment. | |
| Last 4 digits of Card | The last four digits of a payment card. | |
| Limit | The maximum number of results to be returned in a single page. | |
| Location ID | The ID of the location to retrieve details for. | |
| Sort Order | Order to sort the customers. | |
| Square Connection | ||
| Total | The exact amount in the total_money for a payment. |
List Webhook Subscriptions
Lists all webhook subscriptions owned by your application. | key: listWebhookSubscriptions
| Input | Notes | Example |
|---|---|---|
| Cursor | A pagination cursor returned by a previous call to this endpoint. | |
| Include Disabled | Includes disabled Subscriptions. By default, all enabled Subscriptions are returned. | false |
| Limit | The maximum number of results to be returned in a single page. | |
| Sort Order | Sorts the returned list by when the Subscription was created with the specified order. Options: ASC, DESC | |
| Square Connection |
Publish Invoice
Publish an invoice. | key: publishInvoice
| Input | Notes | Example |
|---|---|---|
| Idempotency Key | ||
| Invoice ID | The ID of the invoice to retrieve. | |
| Square Connection | ||
| Version |
Raw Request
Send raw HTTP request to Square | key: rawRequest
| Input | Notes | Example |
|---|---|---|
| Data | The HTTP body payload to send to the URL. | {"exampleKey": "Example Data"} |
| Debug Request | Enabling this flag will log out the current request. | false |
| File Data | File Data to be sent as a multipart form upload. | [{key: "example.txt", value: "My File Contents"}] |
| File Data File Names | File names to apply to the file data inputs. Keys must match the file data keys above. | |
| Form Data | The Form Data to be sent as a multipart form upload. | [{"key": "Example Key", "value": new Buffer("Hello World")}] |
| Header | A list of headers to send with the request. | User-Agent: curl/7.64.1 |
| Max Retry Count | The maximum number of retries to attempt. Specify 0 for no retries. | 0 |
| Method | The HTTP method to use. | |
| Query Parameter | A list of query parameters to send with the request. This is the portion at the end of the URL similar to ?key1=value1&key2=value2. | |
| Response Type | The type of data you expect in the response. You can request json, text, or binary data. | json |
| Retry On All Errors | If true, retries on all erroneous responses regardless of type. This is helpful when retrying after HTTP 429 or other 3xx or 4xx errors. Otherwise, only retries on HTTP 5xx and network errors. | false |
| Retry Delay (ms) | The delay in milliseconds between retries. This is used when 'Use Exponential Backoff' is disabled. | 0 |
| Square Connection | ||
| Timeout | The maximum time that a client will await a response to its request | 2000 |
| URL | This is the URL to call. | /v2/locations |
| Use Exponential Backoff | Specifies whether to use a pre-defined exponential backoff strategy for retries. When enabled, 'Retry Delay (ms)' is ignored. | false |
Refund Payment
Refunds a payment. You can refund the entire payment amount or a portion of it. | key: refundPayment
| Input | Notes | Example |
|---|---|---|
| Idempotency Key | ||
| Payment ID | A unique ID for the desired payment. | |
| Reason | A description of the reason for the refund. | |
| Refund Amount | The amount of money to refund. This amount cannot be more than the total_money value of the payment minus the total amount of all previously completed refunds for this payment. | |
| Square Connection |
Retrieve Catalog Object
Returns a single CatalogObject based on the provided ID. | key: retrieveCatalogObject
| Input | Notes | Example |
|---|---|---|
| Catalog Version | The specific version of the catalog objects to be included in the response. This allows you to retrieve historical versions of objects. The specified version value is matched against the CatalogObjects' version attribute. | |
| Include Related Objects | If true, the response will include additional objects that are related to the requested objects. | false |
| Object ID | The object ID of any type of catalog objects to be retrieved. | |
| Square Connection |
Retrieve Customer
Retrieve details for a single customer. | key: retrieveCustomer
| Input | Notes | Example |
|---|---|---|
| Customer ID | The ID of the customer to retrieve details for. | |
| Square Connection |
Retrieve Location
Retrieves details of a specific location. | key: retrieveLocation
| Input | Notes | Example |
|---|---|---|
| Location ID | The ID of the location to retrieve details for. | |
| Square Connection |
Retrieve Order
Retrieves an Order by its ID. | key: retrieveOrder
| Input | Notes | Example |
|---|---|---|
| Order ID | The ID of the order to retrieve. | |
| Square Connection |
Retrieve Team Member
Retrieve a team member based on the provided ID. | key: retrieveTeamMember
| Input | Notes | Example |
|---|---|---|
| Square Connection | ||
| Team Member ID | The ID of the TeamMember to be retrieved. | TMFnLDlvT9Nfwal7 |
Retrieve Webhook Subscription
Retrieves a webhook subscription identified by its ID. | key: retrieveWebhookSubscription
| Input | Notes | Example |
|---|---|---|
| Square Connection | ||
| Subscription ID | The ID of the Subscription to retrieve. |
Search Catalog Items
Searches for catalog items or item variations by matching supported search attribute values, including custom attribute values, against one or more of the specified query filters. | key: searchCatalogItems
| Input | Notes | Example |
|---|---|---|
| Category IDs | The category id query expression to return items containing the specified category IDs. | |
| Cursor | A pagination cursor returned by a previous call to this endpoint. | |
| Custom Attribute Filters | The customer-attribute filter to return items or item variations matching the specified custom attribute expressions. | |
| Enabled Location IDs | The enabled-location query expression to return items and item variations having specified enabled locations. | |
| Limit | The maximum number of results to be returned in a single page. | |
| Product Types | The product types query expression to return items or item variations having the specified product types. | |
| Sort Order | Order to sort the customers. | |
| Square Connection | ||
| Stock Levels | The stock-level query expression to return item variations with the specified stock levels. | |
| Text Filter | The text filter expression to return items or item variations containing specified text. |
Search Catalog Objects
Searches for CatalogObject of any type by matching supported search attribute values, excluding custom attribute values on items or item variations, against one or more of the specified query filters. | key: searchCatalogObjects
| Input | Notes | Example |
|---|---|---|
| Begin Time | Return objects modified after this timestamp, in RFC 3339 format. | |
| Catalog Query | A query to be used to filter or sort the results. If no query is specified, the entire catalog will be returned. | |
| Cursor | A pagination cursor returned by a previous call to this endpoint. | |
| Include Deleted Objects | If true, deleted objects will be included in the results. | false |
| Include Related Objects | If true, the response will include additional objects that are related to the requested objects. | false |
| Limit | The maximum number of results to be returned in a single page. | |
| Object Types | The desired set of object types to appear in the search results. | |
| Square Connection |
Search Customers
Search customer profiles. | key: searchCustomers
| Input | Notes | Example |
|---|---|---|
| Cursor | A pagination cursor returned by a previous call to this endpoint. | |
| Limit | The maximum number of results to be returned in a single page. | |
| Query | The query to search for customers. Please refer to the Square API documentation for the structure and options of this query. | |
| Square Connection |
Search Invoices
Searches for invoices from a location specified in the filter. | key: searchInvoices
| Input | Notes | Example |
|---|---|---|
| Cursor | A pagination cursor returned by a previous call to this endpoint. | |
| Query | The query to search for invoices. Please refer to the Square API documentation for the structure and options of this query. | |
| Limit | The maximum number of results to be returned in a single page. | |
| Square Connection |
Search Orders
Search all orders for one or more locations. | key: searchOrders
| Input | Notes | Example |
|---|---|---|
| Cursor | A pagination cursor returned by a previous call to this endpoint. | |
| Limit | The maximum number of results to be returned in a single page. | |
| Location IDs | Array of location IDs. These IDs will be used to filter the results to specific locations. | |
| Query | The query to search for orders. Please refer to the Square API documentation for the structure and options of this query. | |
| Return Entries | Flag that indicates whether the entries associated with the orders should be returned. | true |
| Square Connection |
Search Team Members
Search for team members based on given filters. | key: searchTeamMembers
| Input | Notes | Example |
|---|---|---|
| Cursor | A pagination cursor returned by a previous call to this endpoint. | |
| Limit | The maximum number of results to be returned in a single page. | |
| Search Query | The query parameters to filter the TeamMember objects. | |
| Square Connection |
Update Customer
Update a customer profile. | key: updateCustomer
| Input | Notes | Example |
|---|---|---|
| Address | Address in JSON format | |
| Birthday | ||
| Company Name | ||
| Customer ID | The ID of the customer to retrieve details for. | |
| Email Address | ||
| Family Name | ||
| Given Name | ||
| Nickname | ||
| Note | ||
| Phone Number | ||
| Reference Id | ||
| Square Connection | ||
| Tax IDs | Tax IDs in JSON format | |
| Version |
Update Invoice
Update an invoice. | key: updateInvoice
| Input | Notes | Example |
|---|---|---|
| Invoice ID | The ID of the invoice to retrieve. | |
| Square Connection | ||
| Update Invoice | The data to update an invoice. Please refer to the Square API documentation for the structure and options of this update. |
Update Location
Updates a location associated with a Square account. | key: updateLocation
| Input | Notes | Example |
|---|---|---|
| Location ID | The ID of the location to retrieve details for. | |
| Location Update | The data which will be used to update the Location object. | |
| Square Connection |
Update Order
Updates an open order by adding, replacing, or deleting fields. | key: updateOrder
| Input | Notes | Example |
|---|---|---|
| Fields to Clear | The dot notation paths of fields to clear. For example, line_items[uid].note. This is optional. | |
| Idempotency Key | ||
| Order ID | The ID of the order to retrieve. | |
| Order Object | The complete order object. Please refer to the Square API documentation for the structure of this object. | |
| Square Connection |
Update Payment
Updates a payment with the APPROVED status. | key: updatePayment
| Input | Notes | Example |
|---|---|---|
| Payment | The payment object containing the amount_money and tip_money to be updated. The amount is specified in the smallest denomination of the applicable currency (for example, US dollar amounts are specified in cents). | |
| Payment ID | A unique ID for the desired payment. | |
| Square Connection |
Update Team Member
Update a team member. | key: updateTeamMember
| Input | Notes | Example |
|---|---|---|
| Square Connection | ||
| Team Member | The data which will be used to create the TeamMember object. | |
| Team Member ID | The ID of the TeamMember to be retrieved. | TMFnLDlvT9Nfwal7 |
Update Webhook Subscription
Updates a webhook subscription. | key: updateWebhookSubscription
| Input | Notes | Example |
|---|---|---|
| Square Connection | ||
| Subscription ID | The ID of the Subscription to retrieve. | |
| Webhook Subscription | The updated webhook subscription object. It should include properties that you want to update. |
Upsert Catalog Object
Creates a new or updates the specified CatalogObject. | key: upsertCatalogObject
| Input | Notes | Example |
|---|---|---|
| Catalog Object | A CatalogObject to be created or updated. | |
| Idempotency Key | ||
| Square Connection |