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

Step 1: 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.

Step 2: 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 3: 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 4: 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 5: 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.


cash_drawer_shifts

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.

id
STRING

The cash drawer shift ID.

closed_at
DATE-TIME

closed_cash_money
OBJECT

amount
INTEGER

currency
STRING

cash_drawer_shifts (table), closed_cash_money (attribute)

description
STRING

ended_at
DATE-TIME

expected_cash_money
OBJECT

amount
INTEGER

currency
STRING

cash_drawer_shifts (table), expected_cash_money (attribute)

opened_at
DATE-TIME

opened_cash_money
OBJECT

amount
INTEGER

currency
STRING

cash_drawer_shifts (table), opened_cash_money (attribute)

state
STRING


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 :

id

API endpoint :

List customers (v2)

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

id
STRING

The customer ID.

updated_at
DATE-TIME

address
OBJECT

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

email_unsubscribed
BOOLEAN

customers (table), preferences (attribute)

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 :

id

API endpoint :

List employees (V1)

The employees table contains information about your employees in Square.


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 :

id

API endpoint :

List locations (V2)

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

id
STRING

The location ID.

Reference:

address
OBJECT

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

periods
ARRAY

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

value
STRING

locations (table), capabilities (attribute)

coordinates
OBJECT

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


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 :

id

API endpoint :

Search orders (V2)

The orders table contains information about order updates in Square.

id
STRING

The order ID.

Reference:

updated_at
DATE-TIME

amount_money
OBJECT

amount
INTEGER

currency
STRING

orders (table), amount_money (attribute)

card_details
OBJECT

avs_status
STRING

card
OBJECT

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

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

amount_money
OBJECT

amount
INTEGER

currency
STRING

orders (table), amount_money (attribute)

discount_type
STRING

name
STRING

orders (table), discount_data (attribute)

fulfillments
ARRAY

pickup_details
OBJECT

canceled_at
DATE-TIME

expired_at
DATE-TIME

expires_at
DATE-TIME

note
STRING

pickup_at
DATE-TIME

recipient
OBJECT

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

item_data
OBJECT

name
STRING

product_type
STRING

skip_modifier_screen
BOOLEAN

variations
ARRAY

orders (table), item_data (attribute)

line_items
ARRAY

base_price_money
OBJECT

amount
INTEGER

currency
STRING

orders (table), base_price_money (attribute)

catalog_object_id
STRING

gross_sales_money
OBJECT

amount
INTEGER

currency
STRING

orders (table), gross_sales_money (attribute)

name
STRING

note
STRING

quantity
STRING

total_discount_money
OBJECT

amount
INTEGER

currency
STRING

orders (table), total_discount_money (attribute)

total_money
OBJECT

amount
INTEGER

currency
STRING

orders (table), total_money (attribute)

total_tax_money
OBJECT

amount
INTEGER

currency
STRING

orders (table), total_tax_money (attribute)

uid
STRING

variation_name
STRING

variation_total_price_money
OBJECT

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

discount_money
OBJECT

amount
INTEGER

currency
STRING

orders (table), discount_money (attribute)

service_charge_money
OBJECT

amount
INTEGER

currency
STRING

orders (table), service_charge_money (attribute)

tax_money
OBJECT

amount
INTEGER

currency
STRING

orders (table), tax_money (attribute)

tip_money
OBJECT

amount
INTEGER

currency
STRING

orders (table), tip_money (attribute)

total_money
OBJECT

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

amount_money
OBJECT

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

amount
INTEGER

currency
STRING

orders (table), refunded_money (attribute)

refunds
ARRAY

return_amounts
OBJECT

discount_money
OBJECT

amount
INTEGER

currency
STRING

orders (table), discount_money (attribute)

service_charge_money
OBJECT

amount
INTEGER

currency
STRING

orders (table), service_charge_money (attribute)

tax_money
OBJECT

amount
INTEGER

currency
STRING

orders (table), tax_money (attribute)

tip_money
OBJECT

amount
INTEGER

currency
STRING

orders (table), tip_money (attribute)

total_money
OBJECT

amount
INTEGER

currency
STRING

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

returns
ARRAY

return_line_items
ARRAY

base_price_money
OBJECT

amount
INTEGER

currency
STRING

orders (table), base_price_money (attribute)

gross_return_money
OBJECT

amount
INTEGER

currency
STRING

orders (table), gross_return_money (attribute)

quantity
STRING

total_discount_money
OBJECT

amount
INTEGER

currency
STRING

orders (table), total_discount_money (attribute)

total_money
OBJECT

amount
INTEGER

currency
STRING

orders (table), total_money (attribute)

total_tax_money
OBJECT

amount
INTEGER

currency
STRING

orders (table), total_tax_money (attribute)

uid
STRING

variation_total_price_money
OBJECT

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

name
STRING

orders (table), source (attribute)

source_type
STRING

state
STRING

status
STRING

tax_data
OBJECT

name
STRING

orders (table), tax_data (attribute)

tenders
ARRAY

total_discount_money
OBJECT

amount
INTEGER

currency
STRING

orders (table), total_discount_money (attribute)

total_money
OBJECT

amount
INTEGER

currency
STRING

orders (table), total_money (attribute)

total_service_charge_money
OBJECT

amount
INTEGER

currency
STRING

orders (table), total_service_charge_money (attribute)

total_tax_money
OBJECT

amount
INTEGER

currency
STRING

orders (table), total_tax_money (attribute)

total_tip_money
OBJECT

amount
INTEGER

currency
STRING

orders (table), total_tip_money (attribute)

type
STRING

version
INTEGER


Replication Method :

Full Table

Primary Key :

id

API endpoint :

List payments (V2)

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

id
STRING

The payment ID.

Reference:

amount_money
OBJECT

amount
INTEGER

currency
STRING

payments (table), amount_money (attribute)

card_details
OBJECT

auth_result_code
STRING

avs_status
STRING

card
OBJECT

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

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

amount_money
OBJECT

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.

payments (table), refund_ids (attribute)

refunded_money
OBJECT

amount
INTEGER

currency
STRING

payments (table), refunded_money (attribute)

source_type
STRING

status
STRING

total_money
OBJECT

amount
INTEGER

currency
STRING

payments (table), total_money (attribute)

updated_at
DATE-TIME


Replication Method :

Full Table

Primary Key :

id

API endpoint :

List payment refunds (V2)

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