airbyte/docs/integrations/sources/square.md

Square

This page contains the setup guide and reference information for the Square source connector.

Prerequisites

To set up the Square source connector with Airbyte, you'll need to create your Square Application and use Personal token or Oauth access token.

Setup guide

Step 1: Set up Square

1. Create Square Application
2. Obtain Personal token or Oauth access token.

Step 2: Set up the Square connector in Airbyte

For Airbyte Cloud:

1. Log into your Airbyte Cloud account.
2. In the left navigation bar, click Sources. In the top-right corner, click + New source.
3. On the Set up the source page, enter the name for the Square connector and select Square from the Source type dropdown.
4. Choose authentication method:
   • Api-Key
     • Fill in API key token with "Access token" from Square Application settings page (Credentials on the left)
   • Oauth authentication
     • Fill in Client ID and Client secret with data from Square Application settings page (Oauth on the left)
     • Fill in refresh token with one obtained during the authentication process
5. Choose if your account is sandbox
6. Choose start date
7. Choose if you would like to include Deleted objects (for streams: Items, Categories, Discounts, Taxes)

For Airbyte OSS:

1. Navigate to the Airbyte Open Source dashboard.
2. Set the name for your source.
3. On the Set up the source page, enter the name for the Square connector and select Square from the Source type dropdown.
4. Choose authentication method:
   • Api-Key
     • Fill in API key token with "Access token" from Square Application settings page (Credentials on the left)
   • Oauth authentication
     • Fill in Client ID and Client secret with data from Square Application settings page (Oauth on the left)
     • Fill in refresh token with one obtained during the authentication process
5. Choose if your account is sandbox
6. Choose start date
7. Choose if you would like to include Deleted objects (for streams: Items, Categories, Discounts, Taxes)

Supported sync modes

The Square source connector supports the following sync modes:

• Full Refresh - Overwrite
• Full Refresh - Append
• Incremental - Append
• Incremental - Append + Deduped

Supported Streams

• Items (Incremental)
• Categories (Incremental)
• Discounts (Incremental)
• Taxes (Incremental)
• ModifierLists (Incremental)
• Payments (Incremental)
• Refunds (Incremental)
• Locations
• Team Members
• List Team Member Wages
• Customers
• Shifts
• Inventory
• Orders
• Cash drawers
• Loyalty

Connector-specific features & highlights

Useful links:

• Square API Explorer
• Square API Docs
• Square Developer Dashboard

Performance considerations (if any)

No defined API rate limits were found in Square documentation however considering this information it has 10 QPS limits. The connector doesn't handle rate limits exceptions, but no errors were raised during testing. Exponential Backoff strategy recommended.

Data type map

Integration Type	Airbyte Type	Notes
string	string
integer	integer
array	array
object	object
boolean	boolean

Changelog

Expand to review

Version	Date	Pull Request	Subject
1.7.10	2025-11-25	70017	Update dependencies
1.7.9	2025-11-18	69524	Update dependencies
1.7.8	2025-11-04	69161	Update dependencies
1.7.7	2025-08-23	65422	Update dependencies
1.7.6	2025-07-20	63672	Update dependencies
1.7.5	2025-06-28	62212	Update dependencies
1.7.4	2025-06-14	49109	Update dependencies
1.7.3	2025-03-25	53695	fix object_types string to array
1.7.3	2025-02-15	53695	Fix parameter of categories, discounts, items, modifier_list taxes
1.7.2	2024-10-29	47869	Update dependencies
1.7.1	2024-10-28	47608	Update dependencies
1.7.0	2024-10-06	46527	Migrate to Manifest-only
1.6.23	2024-10-05	46409	Update dependencies
1.6.22	2024-09-28	46162	Update dependencies
1.6.21	2024-09-21	45787	Update dependencies
1.6.20	2024-09-14	45550	Update dependencies
1.6.19	2024-09-07	45045	Update dependencies
1.6.18	2024-08-24	44745	Update dependencies
1.6.17	2024-08-17	44325	Update dependencies
1.6.16	2024-08-12	43915	Update dependencies
1.6.15	2024-08-10	43498	Update dependencies
1.6.14	2024-08-03	43110	Update dependencies
1.6.13	2024-07-27	42638	Update dependencies
1.6.12	2024-07-20	42226	Update dependencies
1.6.11	2024-07-13	41913	Update dependencies
1.6.10	2024-07-10	41502	Update dependencies
1.6.9	2024-07-09	41124	Update dependencies
1.6.8	2024-07-06	40989	Update dependencies
1.6.7	2024-06-25	40313	Update dependencies
1.6.6	2024-06-22	40027	Update dependencies
1.6.5	2024-06-06	39206	[autopull] Upgrade base image to v1.2.2
1.6.4	2024-06-12	30315	Fix customer stream pagination limit
1.6.3	2024-06-14	39377	Add error handlers, migrate to inline schemas, move spec to manifest
1.6.2	2024-05-03	37800	Migrate to Poetry. Replace custom components with default classes
1.6.1	2023-11-07	31481	Fix duplicate records for Payments and Refunds stream
1.6.0	2023-10-18	31115	Add customer_id field to Payments and Orders streams
1.5.0	2023-10-16	31045	Added New Stream bank_accounts
1.4.0	2023-10-13	31106	Add new stream Loyalty
1.3.0	2023-10-12	31107	Add new stream Inventory
1.2.0	2023-10-10	31065	Add new stream Cash drawers shifts
1.1.3	2023-10-10	30960	Update airbyte-cdk version to >=0.51.31
1.1.2	2023-07-10	28019	fix display order of spec fields
1.1.1	2023-06-28	27762	Update following state breaking changes
1.1.0	2023-05-24	26485	Remove deprecated authSpecification in favour of advancedAuth
1.0.1	2023-05-03	25784	Fix Authenticator
1.0.0	2023-05-03	25784	Fix Authenticator
0.2.2	2023-03-22	22867	Specified date formatting in specification
0.2.1	2023-03-06	23231	Publish using low-code CDK Beta version
0.2.0	2022-11-14	19369	Migrate to low code (YAML); update API to version 2022-10-19; update docs
0.1.4	2021-12-02	6842	Added oauth support
0.1.3	2021-12-06	8425	Update title, description fields in spec
0.1.2	2021-11-08	7499	Remove base-python dependencies
0.1.1	2021-07-09	4645	Update _send_request method due to Airbyte CDK changes
0.1.0	2021-06-30	4439	Initial release supporting the Square API