Square integration summary

Stitch’s Square integration replicates data using the Square V2 and Connect V1 APIs. Refer to the Schema section for a list of objects available for replication.

Square feature snapshot

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

STITCH
Release status

Released on August 27, 2020

 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

bank_accounts

View table schema on GitHub
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.

cash_drawer_shifts

View table schema on GitHub
Replication Method :

Full Table

 Primary Key :

id
API endpoint :

Retrieve cash drawer shift (V2)

The cash_drawer_shifts table contains infomration about cash transactions in Square.

cash_drawer_shifts table schema

id
STRING

The cash drawer shift ID.

closed_at
DATE-TIME

closed_cash_money
OBJECT

Click to expand closed_cash_money

amount
INTEGER

currency
STRING

cash_drawer_shifts (table), closed_cash_money (attribute)

description
STRING

ended_at
DATE-TIME

expected_cash_money
OBJECT

Click to expand expected_cash_money

amount
INTEGER

currency
STRING

cash_drawer_shifts (table), expected_cash_money (attribute)

opened_at
DATE-TIME

opened_cash_money
OBJECT

Click to expand opened_cash_money

amount
INTEGER

currency
STRING

cash_drawer_shifts (table), opened_cash_money (attribute)

state
STRING

categories

View table schema on GitHub
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.

customers

View table schema on GitHub
Replication Method :

Key-based Incremental

 Replication Key :

updated_at
Primary Key :

id

 API endpoint :

List customers (v2)

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

customers table schema

id
STRING

The customer ID.

updated_at
DATE-TIME

address
OBJECT

Click to expand address

locality
STRING

administrative_district_level_1
STRING

country
STRING

address_line_1
STRING

postal_code
STRING

customers (table), address (attribute)

birthday
DATE-TIME

company_name
STRING

created_at
DATE-TIME

creation_source
STRING

email_address
STRING

family_name
STRING

given_name
STRING

nickname
STRING

note
STRING

phone_number
STRING

preferences
OBJECT

Click to expand preferences

email_unsubscribed
BOOLEAN

customers (table), preferences (attribute)

discounts

View table schema on GitHub
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.

discounts table schema

id
STRING

The discount ID.

updated_at
DATE-TIME

The time the location was last updated.

absent_at_location_ids
ARRAY

discount_data
OBJECT

Click to expand discount_data

amount_money
OBJECT

Click to expand amount_money

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

employees

View table schema on GitHub
Replication Method :

Full Table

 Primary Key :

id
API endpoint :

List employees (V1)

The employees table contains information about your employees in Square.

inventories

View table schema on GitHub
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.

items

View table schema on GitHub
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.

items table schema

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

Click to expand item_data

abbreviation
STRING

available_electronically
BOOLEAN

available_for_pickup
BOOLEAN

available_online
BOOLEAN

category_id
STRING

Reference:

description
STRING

item_options
ARRAY

Click to expand item_options

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.

Click to expand tax_ids

value
STRING

The ID of the tax enabled for the item.

Reference:

items (table), tax_ids (attribute)

variations
ARRAY

Click to expand variations

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

locations

View table schema on GitHub
Replication Method :

Full Table

 Primary Key :

id
API endpoint :

List locations (V2)

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

locations table schema

id
STRING

The location ID.

Reference:

address
OBJECT

Click to expand address

address_line_1
STRING

address_line_2
STRING

address_line_3
STRING

administrative_district_level_1
STRING

administrative_district_level_2
STRING

administrative_district_level_3
STRING

country
STRING

first_name
STRING

last_name
STRING

locality
STRING

organization
STRING

postal_code
STRING

sublocality
STRING

sublocality_2
STRING

sublocality_3
STRING

locations (table), address (attribute)

business_email
STRING

business_hours
OBJECT

Click to expand business_hours

periods
ARRAY

Click to expand periods

day_of_week
STRING

end_local_time
STRING

start_local_time
STRING

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

business_name
STRING

capabilities
ARRAY

Click to expand capabilities

value
STRING

locations (table), capabilities (attribute)

coordinates
OBJECT

Click to expand coordinates

latitude
SINGER-DECIMAL

longitude
SINGER-DECIMAL

locations (table), coordinates (attribute)

country
STRING

created_at
DATE-TIME

currency
STRING

description
STRING

facebook_url
STRING

instagram_username
STRING

language_code
STRING

mcc
STRING

merchant_id
STRING

name
STRING

phone_number
STRING

status
STRING

timezone
STRING

twitter_username
STRING

type
STRING

website_url
STRING

modifier_lists

View table schema on GitHub
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.

modifier_lists table schema

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

Click to expand modifier_list_data

modifiers
ARRAY

Click to expand modifiers

id
STRING

is_deleted
BOOLEAN

modifier_data
OBJECT

Click to expand modifier_data

modifier_list_id
STRING

The modifier list ID.

Reference:

name
STRING

on_by_default
BOOLEAN

ordinal
INTEGER

price_money
OBJECT

Click to expand price_money

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

orders

View table schema on GitHub
Replication Method :

Key-based Incremental

 Replication Key :

updated_at
Primary Key :

id

 API endpoint :

Search orders (V2)

The orders table contains information about order updates in Square.

orders table schema

id
STRING

The order ID.

Reference:

updated_at
DATE-TIME

amount_money
OBJECT

Click to expand amount_money

amount
INTEGER

currency
STRING

orders (table), amount_money (attribute)

card_details
OBJECT

Click to expand card_details

avs_status
STRING

card
OBJECT

Click to expand card

bin
STRING

card_brand
STRING

card_type
STRING

exp_month
INTEGER

exp_year
INTEGER

fingerprint
STRING

last_4
STRING

prepaid_type
STRING

orders (table), card (attribute)

cvv_status
STRING

entry_method
STRING

statement_description
STRING

status
STRING

orders (table), card_details (attribute)

category_data
OBJECT

Click to expand category_data

name
STRING

orders (table), category_data (attribute)

closed_at
DATE-TIME

created_at
DATE-TIME

delay_action
STRING

delay_duration
STRING

delayed_until
STRING

discount_data
OBJECT

Click to expand discount_data

amount_money
OBJECT

Click to expand amount_money

amount
INTEGER

currency
STRING

orders (table), amount_money (attribute)

discount_type
STRING

name
STRING

orders (table), discount_data (attribute)

fulfillments
ARRAY

Click to expand fulfillments

pickup_details
OBJECT

Click to expand pickup_details

canceled_at
DATE-TIME

expired_at
DATE-TIME

expires_at
DATE-TIME

note
STRING

pickup_at
DATE-TIME

recipient
OBJECT

Click to expand recipient

display_name
STRING

orders (table), recipient (attribute)

rejected_at
DATE-TIME

orders (table), pickup_details (attribute)

state
STRING

type
STRING

uid
STRING

orders (table), fulfillments (attribute)

is_deleted
BOOLEAN

line_items
ARRAY

Click to expand line_items

base_price_money
OBJECT

Click to expand base_price_money

amount
INTEGER

currency
STRING

orders (table), base_price_money (attribute)

catalog_object_id
STRING

gross_sales_money
OBJECT

Click to expand gross_sales_money

amount
INTEGER

currency
STRING

orders (table), gross_sales_money (attribute)

name
STRING

note
STRING

quantity
STRING

total_discount_money
OBJECT

Click to expand total_discount_money

amount
INTEGER

currency
STRING

orders (table), total_discount_money (attribute)

total_money
OBJECT

Click to expand total_money

amount
INTEGER

currency
STRING

orders (table), total_money (attribute)

total_tax_money
OBJECT

Click to expand total_tax_money

amount
INTEGER

currency
STRING

orders (table), total_tax_money (attribute)

uid
STRING

variation_name
STRING

variation_total_price_money
OBJECT

Click to expand variation_total_price_money

amount
INTEGER

currency
STRING

orders (table), variation_total_price_money (attribute)
orders (table), line_items (attribute)

location_id
STRING

The ID of the location associated with the order.

Reference:

net_amounts
OBJECT

Click to expand net_amounts

discount_money
OBJECT

Click to expand discount_money

amount
INTEGER

currency
STRING

orders (table), discount_money (attribute)

service_charge_money
OBJECT

Click to expand service_charge_money

amount
INTEGER

currency
STRING

orders (table), service_charge_money (attribute)

tax_money
OBJECT

Click to expand tax_money

amount
INTEGER

currency
STRING

orders (table), tax_money (attribute)

tip_money
OBJECT

Click to expand tip_money

amount
INTEGER

currency
STRING

orders (table), tip_money (attribute)

total_money
OBJECT

Click to expand total_money

amount
INTEGER

currency
STRING

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

note
STRING

order_id
STRING

The order ID.

Reference:

payment_id
STRING

The order payment ID.

Reference:

present_at_all_locations
BOOLEAN

processing_fee
ARRAY

Click to expand processing_fee

amount_money
OBJECT

Click to expand amount_money

amount
INTEGER

currency
STRING

orders (table), amount_money (attribute)

effective_at
STRING

type
STRING

orders (table), processing_fee (attribute)

reason
STRING

receipt_number
STRING

receipt_url
STRING

refund_ids
ARRAY

A list of refunds associated with the order.

refunded_money
OBJECT

Click to expand refunded_money

amount
INTEGER

currency
STRING

orders (table), refunded_money (attribute)

refunds
ARRAY

return_amounts
OBJECT

Click to expand return_amounts

discount_money
OBJECT

Click to expand discount_money

amount
INTEGER

currency
STRING

orders (table), discount_money (attribute)

service_charge_money
OBJECT

Click to expand service_charge_money

amount
INTEGER

currency
STRING

orders (table), service_charge_money (attribute)

tax_money
OBJECT

Click to expand tax_money

amount
INTEGER

currency
STRING

orders (table), tax_money (attribute)

tip_money
OBJECT

Click to expand tip_money

amount
INTEGER

currency
STRING

orders (table), tip_money (attribute)

total_money
OBJECT

Click to expand total_money

amount
INTEGER

currency
STRING

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

returns
ARRAY

Click to expand returns

return_line_items
ARRAY

Click to expand return_line_items

base_price_money
OBJECT

Click to expand base_price_money

amount
INTEGER

currency
STRING

orders (table), base_price_money (attribute)

gross_return_money
OBJECT

Click to expand gross_return_money

amount
INTEGER

currency
STRING

orders (table), gross_return_money (attribute)

quantity
STRING

total_discount_money
OBJECT

Click to expand total_discount_money

amount
INTEGER

currency
STRING

orders (table), total_discount_money (attribute)

total_money
OBJECT

Click to expand total_money

amount
INTEGER

currency
STRING

orders (table), total_money (attribute)

total_tax_money
OBJECT

Click to expand total_tax_money

amount
INTEGER

currency
STRING

orders (table), total_tax_money (attribute)

uid
STRING

variation_total_price_money
OBJECT

Click to expand variation_total_price_money

amount
INTEGER

currency
STRING

orders (table), variation_total_price_money (attribute)
orders (table), return_line_items (attribute)

source_order_id
STRING

Reference:

uid
STRING

orders (table), returns (attribute)

source
OBJECT

Click to expand source

name
STRING

orders (table), source (attribute)

source_type
STRING

state
STRING

status
STRING

tax_data
OBJECT

Click to expand tax_data

name
STRING

orders (table), tax_data (attribute)

tenders
ARRAY

total_discount_money
OBJECT

Click to expand total_discount_money

amount
INTEGER

currency
STRING

orders (table), total_discount_money (attribute)

total_money
OBJECT

Click to expand total_money

amount
INTEGER

currency
STRING

orders (table), total_money (attribute)

total_service_charge_money
OBJECT

Click to expand total_service_charge_money

amount
INTEGER

currency
STRING

orders (table), total_service_charge_money (attribute)

total_tax_money
OBJECT

Click to expand total_tax_money

amount
INTEGER

currency
STRING

orders (table), total_tax_money (attribute)

total_tip_money
OBJECT

Click to expand total_tip_money

amount
INTEGER

currency
STRING

orders (table), total_tip_money (attribute)

type
STRING

version
INTEGER

payments

View table schema on GitHub
Replication Method :

Full Table

 Primary Key :

id
API endpoint :

List payments (V2)

The payments table contains information about all payments taken in Square.

payments table schema

id
STRING

The payment ID.

Reference:

amount_money
OBJECT

Click to expand amount_money

amount
INTEGER

currency
STRING

payments (table), amount_money (attribute)

card_details
OBJECT

Click to expand card_details

auth_result_code
STRING

avs_status
STRING

card
OBJECT

Click to expand card

bin
STRING

card_brand
STRING

card_type
STRING

exp_month
INTEGER

exp_year
INTEGER

fingerprint
STRING

last_4
STRING

prepaid_type
STRING

payments (table), card (attribute)

cvv_status
STRING

entry_method
STRING

errors
ARRAY

Click to expand errors

category
STRING

code
STRING

detail
STRING

field
STRING

payments (table), errors (attribute)

statement_description
STRING

status
STRING

payments (table), card_details (attribute)

cardholder_name
STRING

created_at
DATE-TIME

customer_id
STRING

delay_action
STRING

delay_duration
STRING

delayed_until
DATE-TIME

location_id
STRING

The ID of the location associated with the payment.

Reference:

note
STRING

order_id
STRING

The ID of the order associated with the payment.

Reference:

processing_fee
ARRAY

Click to expand processing_fee

amount_money
OBJECT

Click to expand amount_money

amount
INTEGER

currency
STRING

payments (table), amount_money (attribute)

effective_at
DATE-TIME

type
STRING

payments (table), processing_fee (attribute)

receipt_number
STRING

receipt_url
STRING

reference_id
STRING

refund_ids
ARRAY

A list of refunds associated with the payment.

Click to expand refund_ids
payments (table), refund_ids (attribute)

refunded_money
OBJECT

Click to expand refunded_money

amount
INTEGER

currency
STRING

payments (table), refunded_money (attribute)

source_type
STRING

status
STRING

total_money
OBJECT

Click to expand total_money

amount
INTEGER

currency
STRING

payments (table), total_money (attribute)

updated_at
DATE-TIME

refunds

View table schema on GitHub
Replication Method :

Full Table

 Primary Key :

id
API endpoint :

List payment refunds (V2)

The refunds table contains information about refunds on items in Square.

refunds table schema