Skip to main content

Square Connector

Square Square offers a suite of commerce products for retail stores.

Connections

Square OAuth 2.0

Authenticate requests to Square using values obtained from the Developer Console.

This connection uses OAuth 2.0, a common authentication mechanism for integrations. Read about how OAuth 2.0 works here.

InputCommentsDefault
Authorize URLThe OAuth 2.0 Authorization URL for Squarehttps://connect.squareup.com/oauth2/authorize
Token URLThe OAuth 2.0 Token URL for Squarehttps://connect.squareup.com/oauth2/token
ScopesA space-delimited set of one or more scopes to get the user's permission to access.MERCHANT_PROFILE_READ PAYMENTS_READ PAYMENTS_WRITE
Application ID
Application Secret

Triggers

Webhook

Receive and validate webhook requests from Square for webhooks you configure.

Actions

Batch Change Inventory

Applies adjustments and counts to the provided item quantities.

InputCommentsDefault
Square Connection
Idempotency Key
Inventory ChangesThe 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.
[
{
"type": "PHYSICAL_COUNT",
"physical_count": {
"catalog_object_id": "object_id",
"state": "IN_STOCK",
"quantity": "10",
"location_id": "location_id",
"occurred_at": "2023-07-01T00:00:00Z",
"created_at": "2023-07-01T00:00:00Z"
}
},
{
"type": "ADJUSTMENT",
"adjustment": {
"catalog_object_id": "object_id",
"from_state": "IN_STOCK",
"to_state": "SOLD",
"quantity": "-1",
"location_id": "location_id",
"occurred_at": "2023-07-01T00:00:00Z",
"created_at": "2023-07-01T00:00:00Z",
"source": {
"product": "REGISTER",
"application_id": "app_id",
"name": "Register",
"type": "APP"
}
}
}
]
Ignore Unchanged Countsfalse

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.

InputCommentsDefault
Square Connection
Object IDsThe IDs of the CatalogObjects to be retrieved.
[
"obj1",
"obj2",
"obj3"
]

Batch Retrieve Catalog Objects

Returns a set of objects based on the provided ID.

InputCommentsDefault
Square Connection
Object IDsThe IDs of the CatalogObjects to be retrieved.
[
"obj1",
"obj2",
"obj3"
]
Include Related ObjectsIf true, the response will include additional objects that are related to the requested objects.false
Catalog VersionThe 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 ObjectsIf true, deleted objects will be included in the results.false

Batch Retrieve Inventory Counts

Returns current counts for the provided CatalogObjects at the requested Locations.

InputCommentsDefault
Square Connection
Catalog Object IDsThe filter to return results by CatalogObject ID.
[
"object1",
"object2"
]
Location IDsArray of location IDs. These IDs will be used to filter the results to specific locations.
[
"L2D9N2BTY6CDC",
"L3K7N2BTY6CDE"
]
Updated AfterThe filter to return results with their calculated_at value after the given time as specified in an RFC 3339 timestamp.
CursorA pagination cursor returned by a previous call to this endpoint.
StatesThe filter to return results by InventoryState.
[
"IN_STOCK",
"SOLD"
]
LimitThe maximum number of results to be returned in a single page.

Batch Retrieve Orders

Retrieves a set of orders by their IDs.

InputCommentsDefault
Square Connection
Location IDThe ID of the location to retrieve details for.
Order IDsThe IDs of the orders to retrieve. A maximum of 100 orders can be retrieved per request.
[
"OrderID1",
"OrderID2"
]

Batch Upsert Catalog Objects

Creates or updates up to 10,000 target objects based on the provided list of objects.

InputCommentsDefault
Square Connection
Idempotency Key
BatchesA 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.
[
{
"objects": [
{
"type": "exampleType",
"id": "#exampleId"
}
]
}
]

Cancel Invoice

Cancel an invoice.

InputCommentsDefault
Square Connection
Invoice IDThe ID of the invoice to retrieve.
Version

Cancel Payment

Cancels (voids) a payment.

InputCommentsDefault
Square Connection
Payment IDA unique ID for the desired payment.

Clone Order

Creates a new order, in the DRAFT state, by duplicating an existing order.

InputCommentsDefault
Square Connection
Order IDThe ID of the order to retrieve.
Version
Idempotency Key

Complete Payment

Completes (captures) a payment.

InputCommentsDefault
Square Connection
Payment IDA unique ID for the desired payment.
Version TokenUsed for optimistic concurrency. This token identifies the current Payment version.

Create Customer

Create a new customer profile.

InputCommentsDefault
AddressAddress in JSON format
{
"address_line_1": "test",
"address_line_2": "test1",
"address_line_3": "test2",
"locality": "madero",
"sublocality": "one",
"sublocality_2": "two",
"sublocality_3": "three",
"administrative_district_level_1": "test3",
"administrative_district_level_2": "test3",
"administrative_district_level_3": "test4",
"postal_code": "89510",
"country": "MX",
"first_name": "Oscar",
"last_name": "Antonio"
}
Birthday
Company Name
Email Address
Family Name
Given Name
Nickname
Note
Phone Number
Reference Id
Tax IDsTax IDs in JSON format
{
"eu_vat": "IE3426675K"
}
Idempotency Key
Square Connection

Create Order

Create a new order.

InputCommentsDefault
Location IDThe ID of the location to retrieve details for.
Order ObjectThe complete order object. Please refer to the Square API documentation for the structure of this object.
{
"idempotency_key": "example_idempotency_key",
"order": {
"location_id": "example_location_id",
"line_items": [
{
"name": "Example item",
"quantity": "1",
"base_price_money": {
"amount": 100,
"currency": "USD"
}
}
]
}
}
Square Connection

Create Payment

Creates a payment using the provided source.

InputCommentsDefault
Square Connection
Payment DataThe payment data object containing all necessary information for creating the payment.
{
"source_id": "SOURCE_ID",
"idempotency_key": "IDEMPOTENCY_KEY",
"amount_money": {
"amount": 100,
"currency": "USD"
}
}

Create Team Member

Create a new team member.

InputCommentsDefault
Team MemberThe data which will be used to create the TeamMember object.
{
"reference_id": "reference_id_1",
"status": "ACTIVE",
"given_name": "John",
"family_name": "Doe",
"email_address": "john_doe@example.com",
"phone_number": "+14155552671",
"assigned_locations": {
"assignment_type": "EXPLICIT_LOCATIONS",
"location_ids": [
"L2D9N2BTY6CDC"
]
}
}
Idempotency Key
Square Connection

Create Webhook Subscription

Creates a webhook subscription.

InputCommentsDefault
Square Connection
Idempotency Key
Webhook SubscriptionThe Subscription to create.
{
"name": "Subscription Name",
"enabled": true,
"event_types": [
"event_type_1",
"event_type_2"
],
"notification_url": "https://example.com/notifications"
}

Delete Catalog Object

Deletes a single CatalogObject based on the provided ID and returns the set of successfully deleted IDs in the response.

InputCommentsDefault
Square Connection
Object IDThe object ID of any type of catalog objects to be retrieved.

Delete Customer

Delete a customer profile from a business.

InputCommentsDefault
Customer IDThe ID of the customer to retrieve details for.
Version
Square Connection

Delete Instance Webhooks

Delete all webhooks that point to a flow in this instance

InputCommentsDefault
Square Connection

Delete Invoice

Delete an invoice.

InputCommentsDefault
Square Connection
Invoice IDThe ID of the invoice to retrieve.
Version

Delete Webhook Subscription

Deletes a webhook subscription.

InputCommentsDefault
Square Connection
Subscription IDThe ID of the Subscription to delete.

Get Invoice

Retrieve an invoice by its ID.

InputCommentsDefault
Square Connection
Invoice IDThe ID of the invoice to retrieve.

Get Payment

Retrieves details for a specific payment.

InputCommentsDefault
Square Connection
Payment IDA unique ID for the desired payment.

Get Payment Refund

Retrieves a specific refund using the refund_id.

InputCommentsDefault
Square Connection
Refund IDThe unique ID for the desired PaymentRefund.

List Catalog

Returns a list of all CatalogObjects of the specified types in the catalog.

InputCommentsDefault
Square Connection
CursorA pagination cursor returned by a previous call to this endpoint.
TypesAn 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
Catalog VersionThe 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.

List Customers

List customer profiles associated with a Square account.

InputCommentsDefault
CursorA pagination cursor returned by a previous call to this endpoint.
LimitThe maximum number of results to be returned in a single page.
Sort FieldField to sort the customers on.
Sort OrderOrder to sort the customers.
Square Connection

List Invoices

Returns a list of invoices for a given location.

InputCommentsDefault
Location IDThe ID of the location to retrieve details for.
Square Connection
CursorA pagination cursor returned by a previous call to this endpoint.
LimitThe maximum number of results to be returned in a single page.

List Locations

List all of the seller's locations, including those with an inactive status.

InputCommentsDefault
Square Connection

List Payment Refunds

Retrieves a list of refunds for the account making the request.

InputCommentsDefault
Square Connection
Begin TimeReturn objects modified after this timestamp, in RFC 3339 format.
End TimeIndicates 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.
Sort OrderOrder to sort the customers.
CursorA pagination cursor returned by a previous call to this endpoint.
Location IDThe ID of the location to retrieve details for.
StatusIf provided, only refunds with the given status are returned.
Source TypeIf provided, only returns refunds whose payments have the indicated source type.
LimitThe maximum number of results to be returned in a single page.

List Payments

Retrieves a list of payments taken by the account making the request.

InputCommentsDefault
Square Connection
Begin TimeReturn objects modified after this timestamp, in RFC 3339 format.
End TimeIndicates 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.
Sort OrderOrder to sort the customers.
CursorA pagination cursor returned by a previous call to this endpoint.
Location IDThe ID of the location to retrieve details for.
TotalThe exact amount in the total_money for a payment.
Last 4 digits of CardThe last four digits of a payment card.
Card BrandThe brand of the payment card (for example, VISA).
LimitThe maximum number of results to be returned in a single page.

List Webhook Subscriptions

Lists all webhook subscriptions owned by your application.

InputCommentsDefault
Square Connection
CursorA pagination cursor returned by a previous call to this endpoint.
Include DisabledIncludes disabled Subscriptions. By default, all enabled Subscriptions are returned.false
Sort OrderSorts the returned list by when the Subscription was created with the specified order. Options: ASC, DESC
LimitThe maximum number of results to be returned in a single page.

Publish Invoice

Publish an invoice.

InputCommentsDefault
Square Connection
Invoice IDThe ID of the invoice to retrieve.
Version
Idempotency Key

Raw Request

Send raw HTTP request to Square

InputCommentsDefault
URLThis is the URL to call.
MethodThe HTTP method to use.
DataThe HTTP body payload to send to the URL.
Form DataThe Form Data to be sent as a multipart form upload.
File DataFile Data to be sent as a multipart form upload.
File Data File NamesFile names to apply to the file data inputs. Keys must match the file data keys above.
Query ParameterA 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.
HeaderA list of headers to send with the request.
Response TypeThe type of data you expect in the response. You can request json, text, or binary data.json
TimeoutThe maximum time that a client will await a response to its request
Debug RequestEnabling this flag will log out the current request.false
Retry Delay (ms)The delay in milliseconds between retries. This is used when 'Use Exponential Backoff' is disabled.0
Retry On All ErrorsIf 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
Max Retry CountThe maximum number of retries to attempt. Specify 0 for no retries.0
Use Exponential BackoffSpecifies whether to use a pre-defined exponential backoff strategy for retries. When enabled, 'Retry Delay (ms)' is ignored.false
Square Connection

Refund Payment

Refunds a payment. You can refund the entire payment amount or a portion of it.

InputCommentsDefault
Square Connection
Payment IDA unique ID for the desired payment.
Idempotency Key
Refund AmountThe 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.
ReasonA description of the reason for the refund.

Retrieve Catalog Object

Returns a single CatalogObject based on the provided ID.

InputCommentsDefault
Square Connection
Object IDThe object ID of any type of catalog objects to be retrieved.
Include Related ObjectsIf true, the response will include additional objects that are related to the requested objects.false
Catalog VersionThe 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.

Retrieve Customer

Retrieve details for a single customer.

InputCommentsDefault
Customer IDThe ID of the customer to retrieve details for.
Square Connection

Retrieve Location

Retrieves details of a specific location.

InputCommentsDefault
Location IDThe ID of the location to retrieve details for.
Square Connection

Retrieve Order

Retrieves an Order by its ID.

InputCommentsDefault
Square Connection
Order IDThe ID of the order to retrieve.

Retrieve Team Member

Retrieve a team member based on the provided ID.

InputCommentsDefault
Team Member IDThe ID of the TeamMember to be retrieved.TMFnLDlvT9Nfwal7
Square Connection

Retrieve Webhook Subscription

Retrieves a webhook subscription identified by its ID.

InputCommentsDefault
Square Connection
Subscription IDThe 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.

InputCommentsDefault
Square Connection
Text FilterThe text filter expression to return items or item variations containing specified text.
Category IDsThe category id query expression to return items containing the specified category IDs.
[
"categoryId1",
"categoryId2"
]
Stock LevelsThe stock-level query expression to return item variations with the specified stock levels.
[
"OUT",
"LOW"
]
Enabled Location IDsThe enabled-location query expression to return items and item variations having specified enabled locations.
[
"locationId1",
"locationId2"
]
CursorA pagination cursor returned by a previous call to this endpoint.
LimitThe maximum number of results to be returned in a single page.
Sort OrderOrder to sort the customers.
Product TypesThe product types query expression to return items or item variations having the specified product types.
[
"REGULAR",
"APPOINTMENTS_SERVICE"
]
Custom Attribute FiltersThe customer-attribute filter to return items or item variations matching the specified custom attribute expressions.
[
{
"custom_attribute_definition_id": "attributeId",
"key": "exampleKey",
"string_filter": "exampleString",
"bool_filter": true
}
]

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.

InputCommentsDefault
Square Connection
CursorA pagination cursor returned by a previous call to this endpoint.
Object TypesThe desired set of object types to appear in the search results.
Include Deleted ObjectsIf true, deleted objects will be included in the results.false
Include Related ObjectsIf true, the response will include additional objects that are related to the requested objects.false
Begin TimeReturn objects modified after this timestamp, in RFC 3339 format.
Catalog QueryA query to be used to filter or sort the results. If no query is specified, the entire catalog will be returned.
{
"sorted_attribute_query": {
"attribute_name": "exampleAttributeName",
"initial_attribute_value": "exampleInitialValue",
"sort_order": "ASC"
},
"exact_query": {
"attribute_name": "exampleAttributeName",
"attribute_value": "exampleAttributeValue"
}
}
LimitThe maximum number of results to be returned in a single page.

Search Customers

Search customer profiles.

InputCommentsDefault
LimitThe maximum number of results to be returned in a single page.
QueryThe query to search for customers. Please refer to the Square API documentation for the structure and options of this query.
{
"query": {
"filter": {
"creation_source": {
"values": [
"THIRD_PARTY"
],
"rule": "INCLUDE"
},
"created_at": {
"start_at": "2018-01-01T00:00:00-00:00",
"end_at": "2018-02-01T00:00:00-00:00"
},
"email_address": {
"fuzzy": "example.com"
},
"group_ids": {
"all": [
"545AXB44B4XXWMVQ4W8SBT3HHF"
]
}
},
"sort": {
"field": "CREATED_AT",
"order": "ASC"
}
}
}
CursorA pagination cursor returned by a previous call to this endpoint.
Square Connection

Search Invoices

Searches for invoices from a location specified in the filter.

InputCommentsDefault
LimitThe maximum number of results to be returned in a single page.
QueryThe query to search for invoices. Please refer to the Square API documentation for the structure and options of this query.
{
"filter": {
"location_ids": [
"L2D9N2BTY6CDC"
],
"customer_ids": [
"SSRAQAX223WXC422K2443PS494"
]
},
"sort": {
"field": "INVOICE_SORT_DATE",
"order": "DESC"
}
}
CursorA pagination cursor returned by a previous call to this endpoint.
Square Connection

Search Orders

Search all orders for one or more locations.

InputCommentsDefault
Square Connection
Location IDsArray of location IDs. These IDs will be used to filter the results to specific locations.
[
"L2D9N2BTY6CDC",
"L3K7N2BTY6CDE"
]
QueryThe query to search for orders. Please refer to the Square API documentation for the structure and options of this query.
{
"filter": {
"state_filter": {
"states": [
"COMPLETED"
]
},
"date_time_filter": {
"closed_at": {
"start_at": "2023-01-01T00:00:00+00:00",
"end_at": "2023-12-31T23:59:59+00:00"
}
},
"customer_filter": {
"customer_ids": [
"SSRAQAX223WXC422K2443PS494"
]
}
},
"sort": {
"sort_field": "CLOSED_AT",
"sort_order": "DESC"
}
}
LimitThe maximum number of results to be returned in a single page.
Return EntriesFlag that indicates whether the entries associated with the orders should be returned.true
CursorA pagination cursor returned by a previous call to this endpoint.

Search Team Members

Search for team members based on given filters.

InputCommentsDefault
Search QueryThe query parameters to filter the TeamMember objects.
{
"filter": {
"location_ids": [
"L2D9N2BTY6CDC"
],
"status": "ACTIVE",
"is_owner": true
}
}
Square Connection
LimitThe maximum number of results to be returned in a single page.
CursorA pagination cursor returned by a previous call to this endpoint.

Update Customer

Update a customer profile.

InputCommentsDefault
Square Connection
Customer IDThe ID of the customer to retrieve details for.
AddressAddress in JSON format
{
"address_line_1": "test",
"address_line_2": "test1",
"address_line_3": "test2",
"locality": "madero",
"sublocality": "one",
"sublocality_2": "two",
"sublocality_3": "three",
"administrative_district_level_1": "test3",
"administrative_district_level_2": "test3",
"administrative_district_level_3": "test4",
"postal_code": "89510",
"country": "MX",
"first_name": "Oscar",
"last_name": "Antonio"
}
Birthday
Company Name
Email Address
Family Name
Given Name
Nickname
Note
Phone Number
Reference Id
Tax IDsTax IDs in JSON format
{
"eu_vat": "IE3426675K"
}
Version

Update Invoice

Update an invoice.

InputCommentsDefault
Square Connection
Invoice IDThe ID of the invoice to retrieve.
Update InvoiceThe data to update an invoice. Please refer to the Square API documentation for the structure and options of this update.
{
"invoice": {
"version": 1,
"paymentRequests": [
{
"uid": "2da7964f-f3d2-4f43-81e8-5aa220bf3355",
"tippingEnabled": false
}
]
},
"idempotencyKey": "4ee82288-0910-499e-ab4c-5d0071dad1be",
"fieldsToClear": [
"payments_requests[2da7964f-f3d2-4f43-81e8-5aa220bf3355].reminders"
]
}

Update Location

Updates a location associated with a Square account.

InputCommentsDefault
Location IDThe ID of the location to retrieve details for.
Location UpdateThe data which will be used to update the Location object.
{
"id": "L2D9N2BTY6CDC",
"name": "Acme",
"address": {
"address_line_1": "1234 Peachtree St. NE",
"locality": "Atlanta",
"administrative_district_level_1": "GA",
"postal_code": "30309"
},
"timezone": "America/New_York",
"status": "ACTIVE",
"country": "US",
"language_code": "en-US",
"currency": "USD",
"type": "PHYSICAL",
"comments": "Midtown Atlanta store - Open weekends",
"coordinates": {
"latitude": 33.7889,
"longitude": -84.3841
},
"business_hours": {
"periods": [
{
"day_of_week": "FRI",
"start_local_time": "07:00",
"end_local_time": "18:00"
},
{
"day_of_week": "SAT",
"start_local_time": "07:00",
"end_local_time": "18:00"
},
{
"day_of_week": "SUN",
"start_local_time": "09:00",
"end_local_time": "15:00"
}
]
},
"business_name": "Jet Fuel Coffee",
"mcc": "7299"
}
Square Connection

Update Order

Updates an open order by adding, replacing, or deleting fields.

InputCommentsDefault
Order IDThe ID of the order to retrieve.
Order ObjectThe complete order object. Please refer to the Square API documentation for the structure of this object.
{
"idempotency_key": "example_idempotency_key",
"order": {
"location_id": "example_location_id",
"line_items": [
{
"name": "Example item",
"quantity": "1",
"base_price_money": {
"amount": 100,
"currency": "USD"
}
}
]
}
}
Fields to ClearThe dot notation paths of fields to clear. For example, line_items[uid].note. This is optional.
[
"field1",
"field2"
]
Idempotency Key
Square Connection

Update Payment

Updates a payment with the APPROVED status.

InputCommentsDefault
Square Connection
Payment IDA unique ID for the desired payment.
PaymentThe 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).
{
"amount_money": {
"amount": 1000,
"currency": "USD"
},
"tip_money": {
"amount": 200,
"currency": "USD"
}
}

Update Team Member

Update a team member.

InputCommentsDefault
Team Member IDThe ID of the TeamMember to be retrieved.TMFnLDlvT9Nfwal7
Team MemberThe data which will be used to create the TeamMember object.
{
"reference_id": "reference_id_1",
"status": "ACTIVE",
"given_name": "John",
"family_name": "Doe",
"email_address": "john_doe@example.com",
"phone_number": "+14155552671",
"assigned_locations": {
"assignment_type": "EXPLICIT_LOCATIONS",
"location_ids": [
"L2D9N2BTY6CDC"
]
}
}
Square Connection

Update Webhook Subscription

Updates a webhook subscription.

InputCommentsDefault
Square Connection
Subscription IDThe ID of the Subscription to retrieve.
Webhook SubscriptionThe updated webhook subscription object. It should include properties that you want to update.
{
"name": "Updated Subscription Name",
"enabled": true,
"event_types": [
"event_type1",
"event_type2"
],
"notification_url": "http://example.com/notification-url"
}

Upsert Catalog Object

Creates a new or updates the specified CatalogObject.

InputCommentsDefault
Square Connection
Idempotency Key
Catalog ObjectA CatalogObject to be created or updated.
{
"type": "ITEM",
"id": "#temp-item-id",
"item_data": {
"name": "Example Item",
"comments": "This is an example item.",
"abbreviation": "E",
"category_id": "example-category-id",
"variations": [
{
"type": "ITEM_VARIATION",
"id": "#temp-variation-id",
"item_variation_data": {
"item_id": "#temp-item-id",
"name": "Example Variation",
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 100,
"currency": "USD"
}
}
}
]
}
}