Square integration summary

Stitch’s Square integration replicates data using the Square API version 2023-06-08. Refer to the Schema section for a list of objects available for replication.

Square feature snapshot

A high-level look at Stitch's Square (v2) integration, including release status, useful links, and the features supported in Stitch.

STITCH
Release status

Released on July 19, 2023

Supported by

Stitch

Stitch plan

Standard

API availability

Available

Singer GitHub repository

singer-io/tap-square

REPLICATION SETTINGS
Anchor Scheduling

Supported

Advanced Scheduling

Supported

Table-level reset

Unsupported

Configurable Replication Methods

Unsupported

DATA SELECTION
Table selection

Supported

Column selection

Supported

Select all

Supported

TRANSPARENCY
Extraction Logs

Supported

Loading Reports

Supported

Connecting Square

Square setup requirements

To set up Square in Stitch, you need:

  • To log into your Square sandbox environment, if you’re connecting a sandbox. To allow Stitch to successfully access the sandbox, you must be logged into it prior to setting up the Square integration in Stitch.

    If you’re connecting a production environment, start with Step 2 of this guide.


Step 1: Login to your Square sandbox environment

To connect to your Square sandbox environment, you’ll need to login to your sandbox environment before completing the next step. This is required to grant Stitch authorization to access the sandbox environment. For more info, refer to the Square documentation.

Step 2: Add Square as a Stitch data source

  1. Sign into your Stitch account.
  2. On the Stitch Dashboard page, click the Add Integration button.

  3. Click the Square icon.

  4. Enter a name for the integration. This is the name that will display on the Stitch Dashboard for the integration; it’ll also be used to create the schema in your destination.

    For example, the name “Stitch Square” would create a schema called stitch_square in the destination. Note: Schema names cannot be changed after you save the integration.

  5. Check the Connect to a sandbox environment if choosing to connect to your Square sandbox. Note: Make sure you completed Step 1 before continuing.

Step 3: Define the historical replication start date

The Sync Historical Data setting defines the starting date for your Square integration. This means that:

  • For tables using Key-based Incremental Replication, data equal to or newer than this date will be replicated to your destination.
  • For tables using Full Table Replication, all data - including records that are older, equal to, or newer than this date - will be replicated to your destination.

Change this setting if you want to replicate data beyond Square’s default setting of 1 year. For a detailed look at historical replication jobs, check out the Syncing Historical SaaS Data guide.

Step 4: Create a replication schedule

In the Replication Frequency section, you’ll create the integration’s replication schedule. An integration’s replication schedule determines how often Stitch runs a replication job, and the time that job begins.

Square integrations support the following replication scheduling methods:

To keep your row usage low, consider setting the integration to replicate less frequently. See the Understanding and Reducing Your Row Usage guide for tips on reducing your usage.

Step 5: Authorizing Stitch to Access Square

Lastly, you’ll be directed to Square’s website to complete the setup.

  1. Enter your Square credentials and click Login.
  2. After the authorization process successfully completes, you’ll be redirected back to Stitch.
  3. Click All Done.

Step 6: Set objects to replicate

The last step is to select the tables and columns you want to replicate. Learn about the available tables for this integration.

Note: If a replication job is currently in progress, new selections won’t be used until the next job starts.

For Square integrations, you can select:

  1. Individual tables and columns

  2. All tables and columns

Click the tabs to view instructions for each selection method.

  1. In the integration’s Tables to Replicate tab, locate a table you want to replicate.
  2. To track a table, click the checkbox next to the table’s name. A blue checkmark means the table is set to replicate.

  3. To track a column, click the checkbox next to the column’s name. A blue checkmark means the column is set to replicate.

  4. Repeat this process for all the tables and columns you want to replicate.
  5. When finished, click the Finalize Your Selections button at the bottom of the screen to save your selections.
  1. Click into the integration from the Stitch Dashboard page.
  2. Click the Tables to Replicate tab.

  3. In the list of tables, click the box next to the Table Names column.
  4. In the menu that displays, click Track all Tables and Fields:

    The Track all Tables and Fields menu in the Tables to Replicate tab

  5. Click the Finalize Your Selections button at the bottom of the page to save your data selections.

Initial and historical replication jobs

After you finish setting up Square, its Sync Status may show as Pending on either the Stitch Dashboard or in the Integration Details page.

For a new integration, a Pending status indicates that Stitch is in the process of scheduling the initial replication job for the integration. This may take some time to complete.

Free historical data loads

The first seven days of replication, beginning when data is first replicated, are free. Rows replicated from the new integration during this time won’t count towards your quota. Stitch offers this as a way of testing new integrations, measuring usage, and ensuring historical data volumes don’t quickly consume your quota.


Square table reference

Replication Method :

Full Table

Primary Key :

id

API endpoint :

List bank accounts (v2)

The bank_accounts contains information about a merchant’s bank account in Square.

Note: This table can’t be replicated if the Connect to a sandbox environment box is checked in the integration’s settings due to limits imposed by Square.

id
STRING

The bank account ID.

Reference:

account_number_suffix
STRING

account_type
STRING

bank_name
STRING

country
STRING

creditable
BOOLEAN

currency
STRING

debitable
BOOLEAN

debit_mandate_reference_id
STRING

Reference identifier that will be displayed to UK bank account owners when collecting direct debit authorization. Only required for UK bank accounts.

holder_name
STRING

location_id
STRING

The ID of the location associated with the bank account.

Reference:

primary_bank_identification_number
STRING

Primary identifier for the bank

secondary_bank_identification_number
STRING

Secondary identifier for the bank

reference_id
STRING

Client-provided identifier for linking the banking account to an entity in a third-party system (for example, a bank account number or a user identifier).

status
STRING

version
INTEGER


cash_drawer_shifts

Replication Method :

Full Table

Primary Key :

None

API endpoint :

Retrieve cash drawer shift (V2)

The cash_drawer_shifts table contains infomration about cash transactions in Square.

closed_at
DATE-TIME

closed_cash_money
OBJECT

amount
INTEGER

currency
STRING

cash_drawer_shifts (table), closed_cash_money (attribute)

created_at
DATE-TIME

description
STRING

ended_at
DATE-TIME

expected_cash_money
OBJECT

amount
INTEGER

currency
STRING

cash_drawer_shifts (table), expected_cash_money (attribute)

id
STRING

location_id
STRING

opened_at
DATE-TIME

opened_cash_money
OBJECT

amount
INTEGER

currency
STRING

cash_drawer_shifts (table), opened_cash_money (attribute)

state
STRING

updated_at
DATE-TIME


Replication Method :

Key-based Incremental

Replication Key :

updated_at

Primary Key :

id

API endpoint :

List catalog (type: category) (V2)

The categories table contains information about item categories for a given location in Square.


Replication Method :

Key-based Incremental

Replication Key :

updated_at

Primary Key :

None

API endpoint :

List customers (v2)

The customers contains information about customer profiles associated with your Square account.

address
OBJECT

locality
STRING

sublocality
STRING

sublocality_2
STRING

sublocality_3
STRING

administrative_district_level_1
STRING

administrative_district_level_2
STRING

administrative_district_level_3
STRING

country
STRING

address_line_1
STRING

address_line_2
STRING

address_line_3
STRING

postal_code
STRING

first_name
STRING

last_name
STRING

customers (table), address (attribute)

birthday
DATE-TIME

birthday
STRING

company_name
STRING

created_at
DATE-TIME

creation_source
STRING

email_address
STRING

family_name
STRING

given_name
STRING

group_ids
ARRAY

items
STRING

customers (table), group_ids (attribute)

id
STRING

nickname
STRING

note
STRING

phone_number
STRING

preferences
OBJECT

email_unsubscribed
BOOLEAN

customers (table), preferences (attribute)

reference_id
STRING

segment_ids
ARRAY

items
STRING

customers (table), segment_ids (attribute)

tax_ids
OBJECT

eu_vat
STRING

customers (table), tax_ids (attribute)

updated_at
DATE-TIME

version
INTEGER


Replication Method :

Key-based Incremental

Replication Key :

updated_at

Primary Key :

id

API endpoint :

List catalog (type: discount) (V2)

The discounts table contains information about discounts for a given location in Square.

id
STRING

The discount ID.

updated_at
DATE-TIME

The time the location was last updated.

absent_at_location_ids
ARRAY

discount_data
OBJECT

amount_money
OBJECT

amount
INTEGER

currency
STRING

discounts (table), amount_money (attribute)

application_method
STRING

discount_type
STRING

label_color
STRING

modify_tax_basis
STRING

name
STRING

percentage
STRING

pin_required
BOOLEAN

discounts (table), discount_data (attribute)

is_deleted
BOOLEAN

present_at_all_locations
BOOLEAN

type
STRING

version
INTEGER


Replication Method :

Full Table

Primary Key :

None

API endpoint :

Retrieve inventory count (V2)

Loading Behavior:

Append-Only

The inventories table contains info about the current calculated stock count for a Square location.


Replication Method :

Key-based Incremental

Replication Key :

updated_at

Primary Key :

id

API endpoint :

List catalog (type: item) (V2)

The items table contains information about items for a given location in Square.

id
STRING

The item ID.

Reference:

updated_at
DATE-TIME

The time the item was last updated.

absent_at_location_ids
ARRAY

A list of locations where the item is unavailable.

is_deleted
BOOLEAN

item_data
OBJECT

abbreviation
STRING

available_electronically
BOOLEAN

available_for_pickup
BOOLEAN

available_online
BOOLEAN

category_id
STRING

Reference:

description
STRING

item_options
ARRAY

item_option_id
STRING

items (table), item_options (attribute)

label_color
STRING

modifier_list_info
ARRAY

name
STRING

product_type
STRING

skip_modifier_screen
BOOLEAN

tax_ids
ARRAY

A list of taxes enabled for the item.

value
STRING

The ID of the tax enabled for the item.

Reference:

items (table), tax_ids (attribute)

variations
ARRAY

id
STRING

is_deleted
BOOLEAN

item_variation_data
OBJECT

present_at_all_locations
BOOLEAN

present_at_location_ids
ARRAY

A list of locations where the item is available.

type
STRING

updated_at
DATE-TIME

version
INTEGER

items (table), variations (attribute)

visibility
STRING

items (table), item_data (attribute)

present_at_all_locations
BOOLEAN

present_at_location_ids
ARRAY

A list of locations where the item is available.

type
STRING

version
INTEGER


Replication Method :

Full Table

Primary Key :

None

API endpoint :

List locations (V2)

The locations table contains information about all of your business locations in Square.

address
OBJECT

address_line_1
STRING

address_line_2
STRING

address_line_3
STRING

postal_code
STRING

locality
STRING

administrative_district_level_1
STRING

administrative_district_level_2
STRING

administrative_district_level_3
STRING

country
STRING

first_name
STRING

last_name
STRING

sublocality
STRING

sublocality_2
STRING

sublocality_3
STRING

locations (table), address (attribute)

business_email
STRING

business_hours
OBJECT

periods
ARRAY

start_local_time
STRING

end_local_time
STRING

day_of_week
STRING

locations (table), periods (attribute)
locations (table), business_hours (attribute)

business_name
STRING

capabilities
ARRAY

items
STRING

locations (table), capabilities (attribute)

coordinates
OBJECT

latitude
STRING

longitude
STRING

locations (table), coordinates (attribute)

country
STRING

created_at
DATE-TIME

currency
STRING

description
STRING

facebook_url
STRING

full_format_logo_url
STRING

id
STRING

instagram_username
STRING

language_code
STRING

logo_url
STRING

mcc
STRING

merchant_id
STRING

name
STRING

phone_number
STRING

pos_background_url
STRING

status
STRING

timezone
STRING

twitter_username
STRING

type
STRING

website_url
STRING


Replication Method :

Key-based Incremental

Replication Key :

updated_at

Primary Key :

id

API endpoint :

List catalog (type: modifier_list) (V2)

The modifier_lists table contains information about modifier lists for a given location in Square.

id
STRING

The modifier list ID.

Reference:

updated_at
DATE-TIME

The time the modifier list was last updated.

absent_at_location_ids
ARRAY

A list of locations where the modifier list is unavailable.

is_deleted
BOOLEAN

modifier_list_data
OBJECT

modifiers
ARRAY

id
STRING

is_deleted
BOOLEAN

modifier_data
OBJECT

modifier_list_id
STRING

The modifier list ID.

Reference:

name
STRING

on_by_default
BOOLEAN

ordinal
INTEGER

price_money
OBJECT

amount
INTEGER

currency
STRING

modifier_lists (table), price_money (attribute)
modifier_lists (table), modifier_data (attribute)

present_at_all_locations
BOOLEAN

type
STRING

updated_at
DATE-TIME

version
INTEGER

modifier_lists (table), modifiers (attribute)

name
STRING

ordinal
INTEGER

selection_type
STRING

modifier_lists (table), modifier_list_data (attribute)

present_at_all_locations
BOOLEAN

type
STRING

version
INTEGER


Replication Method :

Key-based Incremental

Replication Key :

updated_at

Primary Key :

None

API endpoint :

Search orders (V2)

The orders table contains information about order updates in Square.

closed_at
DATE-TIME

created_at
DATE-TIME

discounts
ARRAY

catalog_object_id
STRING

catalog_version
INTEGER

name
STRING

type
STRING

percentage
STRING

amount_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), amount_money (attribute)

applied_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), applied_money (attribute)

scope
STRING

pricing_rule_id
STRING

orders (table), discounts (attribute)

fulfillments
ARRAY

type
STRING

pickup_details
OBJECT

placed_at
DATE-TIME

accepted_at
DATE-TIME

rejected_at
DATE-TIME

ready_at
DATE-TIME

picked_up_at
DATE-TIME

canceled_at
DATE-TIME

expired_at
DATE-TIME

expires_at
DATE-TIME

auto_complete_duration
STRING

schedule_type
STRING

cancel_reason
STRING

pickup_at
DATE-TIME

pickup_window_duration
STRING

prep_time_duration
STRING

note
STRING

recipient
OBJECT

customer_id
STRING

display_name
STRING

email_address
STRING

phone_number
STRING

orders (table), recipient (attribute)
orders (table), pickup_details (attribute)

state
STRING

uid
STRING

orders (table), fulfillments (attribute)

id
STRING

line_items
ARRAY

base_price_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), base_price_money (attribute)

total_discount_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), total_discount_money (attribute)

variation_total_price_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), variation_total_price_money (attribute)

name
STRING

quantity
STRING

quantity_unit
OBJECT

precision
INTEGER

measurement_unit
OBJECT

custom_unit
OBJECT

name
STRING

abbreviation
STRING

orders (table), custom_unit (attribute)

area_unit
STRING

length_unit
STRING

volume_unit
STRING

weight_unit
STRING

generic_unit
STRING

time_unit
STRING

type
STRING

orders (table), measurement_unit (attribute)

catalog_object_id
STRING

catalog_version
INTEGER

orders (table), quantity_unit (attribute)

note
STRING

uid
STRING

gross_sales_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), gross_sales_money (attribute)

total_tax_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), total_tax_money (attribute)

total_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), total_money (attribute)

catalog_object_id
STRING

catalog_version
INTEGER

variation_name
STRING

item_type
STRING

modifiers
ARRAY

catalog_object_id
STRING

catalog_version
INTEGER

name
STRING

quantity
STRING

base_price_money
OBJECT

amount
INTEGER

currency
STRING

orders (table), base_price_money (attribute)

total_price_money
OBJECT

amount
INTEGER

currency
STRING

orders (table), total_price_money (attribute)
orders (table), modifiers (attribute)
orders (table), line_items (attribute)

location_id
STRING

net_amount_due_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), net_amount_due_money (attribute)

net_amounts
OBJECT

tip_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), tip_money (attribute)

service_charge_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), service_charge_money (attribute)

tax_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), tax_money (attribute)

discount_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), discount_money (attribute)

total_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), total_money (attribute)
orders (table), net_amounts (attribute)

pricing_options
OBJECT

auto_apply_discounts
BOOLEAN

orders (table), pricing_options (attribute)

reference_id
STRING

refunds
ARRAY

location_id
STRING

transaction_id
STRING

created_at
DATE-TIME

tender_id
STRING

amount_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), amount_money (attribute)

processing_fee_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), processing_fee_money (attribute)

status
STRING

id
STRING

reason
STRING

orders (table), refunds (attribute)

return_amounts
OBJECT

tip_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), tip_money (attribute)

service_charge_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), service_charge_money (attribute)

tax_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), tax_money (attribute)

discount_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), discount_money (attribute)

total_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), total_money (attribute)
orders (table), return_amounts (attribute)

returns
ARRAY

source_order_id
STRING

return_line_items
ARRAY

base_price_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), base_price_money (attribute)

catalog_object_id
STRING

catalog_version
INTEGER

name
STRING

note
STRING

quantity_unit
OBJECT

precision
INTEGER

measurement_unit
OBJECT

area_unit
STRING

custom_unit
OBJECT

abbreviation
STRING

name
STRING

orders (table), custom_unit (attribute)

generic_unit
STRING

length_unit
STRING

time_unit
STRING

type
STRING

volume_unit
STRING

weight_unit
STRING

orders (table), measurement_unit (attribute)

catalog_object_id
STRING

catalog_version
INTEGER

orders (table), quantity_unit (attribute)

return_modifiers
ARRAY

base_price_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), base_price_money (attribute)

catalog_object_id
STRING

catalog_version
INTEGER

quantity
STRING

name
STRING

source_modifier_uid
STRING

total_price_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), total_price_money (attribute)

uid
STRING

orders (table), return_modifiers (attribute)

source_line_item_uid
STRING

variation_name
STRING

item_type
STRING

total_tax_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), total_tax_money (attribute)

gross_return_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), gross_return_money (attribute)

total_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), total_money (attribute)

variation_total_price_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), variation_total_price_money (attribute)

quantity
STRING

applied_discounts
ARRAY

discount_uid
STRING

applied_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), applied_money (attribute)

uid
STRING

orders (table), applied_discounts (attribute)

applied_taxes
ARRAY

tax_uid
STRING

applied_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), applied_money (attribute)

uid
STRING

orders (table), applied_taxes (attribute)

total_discount_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), total_discount_money (attribute)

total_service_charge_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), total_service_charge_money (attribute)

applied_service_charges
ARRAY

uid
STRING

service_charge_uid
STRING

applied_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), applied_money (attribute)
orders (table), applied_service_charges (attribute)

uid
STRING

orders (table), return_line_items (attribute)

uid
STRING

return_service_charges
ARRAY

source_service_charge_uid
STRING

name
STRING

catalog_object_id
STRING

catalog_version
INTEGER

percentage
STRING

amount_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), amount_money (attribute)

applied_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), applied_money (attribute)

total_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), total_money (attribute)

total_tax_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), total_tax_money (attribute)

calculation_phase
STRING

taxable
BOOLEAN

orders (table), return_service_charges (attribute)

return_taxes
ARRAY

uid
STRING

source_tax_uid
STRING

catalog_object_id
STRING

catalog_version
INTEGER

name
STRING

type
STRING

percentage
STRING

applied_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), applied_money (attribute)

scope
STRING

orders (table), return_taxes (attribute)

return_discounts
ARRAY

uid
STRING

source_discount_uid
STRING

catalog_object_id
STRING

catalog_version
INTEGER

name
STRING

type
STRING

percentage
STRING

amount_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), amount_money (attribute)

applied_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), applied_money (attribute)

scope
STRING

orders (table), return_discounts (attribute)

rounding_adjustment
OBJECT

uid
STRING

name
STRING

amount_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), amount_money (attribute)
orders (table), rounding_adjustment (attribute)

return_amounts
OBJECT

total_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), total_money (attribute)

tax_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), tax_money (attribute)

discount_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), discount_money (attribute)

tip_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), tip_money (attribute)

service_charge_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), service_charge_money (attribute)
orders (table), return_amounts (attribute)
orders (table), returns (attribute)

service_charges
ARRAY

catalog_object_id
STRING

catalog_version
INTEGER

name
STRING

type
STRING

percentage
STRING

amount_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), amount_money (attribute)

applied_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), applied_money (attribute)

total_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), total_money (attribute)

total_tax_money
OBJECT

currency
STRING

amount
INTEGER

orders (table), total_tax_money (attribute)

calculation_phase
STRING

taxable
BOOLEAN

orders (table), service_charges (attribute)

source
OBJECT

name
STRING

orders (table), source (attribute)

state
STRING

taxes
ARRAY

catalog_object_id
STRING

catalog_version
INTEGER

name
STRING

type
STRING

percentage
STRING

applied_money
OBJECT

currency
STRING

amount