Square
Use this page to set up the Square source connector and find reference information.
Prerequisites
-
A Square Developer account with an application created.
-
A personal access token or OAuth credentials: Client ID, Client Secret and refresh token. See Square access tokens for details.
-
For OAuth authentication, authorise the refresh token for the permissions required by your chosen streams. A personal access token grants full access to the seller account’s resources.
Permission Streams ITEMS_READItems, Categories, Discounts, Taxes, Modifier Lists PAYMENTS_READPayments, Refunds ORDERS_READOrders MERCHANT_PROFILE_READLocations (also used to list locations for the Orders stream) EMPLOYEES_READTeam Members, Team Member Wages TIMECARDS_READShifts CUSTOMERS_READCustomers INVENTORY_READInventory BANK_ACCOUNTS_READBank Accounts CASH_DRAWER_READCash Drawers LOYALTY_READLoyalty
Setup guide
Step 1: Set up Square
- Create a Square Application.
- Get a personal access token or complete the OAuth flow. You’ll receive a Client ID, Client Secret and refresh token.
Step 2: Set up Square in Airbyte
- In Airbyte, go to Sources and click + New source.
- Select Square from the source type dropdown.
- Choose an authentication method:
- API Key: Enter the access token from your Square Application settings page, under Credentials.
- OAuth: Enter the Client ID and Client Secret from your Square Application settings page, under OAuth. Also enter the refresh token from the authorisation flow.
- If you’re using a Square sandbox environment, set Sandbox to
true. - Set a Start Date in UTC using the
YYYY-MM-DDformat. It defaults to2021-01-01. Incremental streams don’t replicate data before this date. Full refresh streams ignore it. - Optionally, enable Include Deleted Objects to sync deleted Items, Categories, Discounts, Taxes and Modifier Lists.
Supported sync modes
The Square source connector supports these sync modes:
Supported streams
- Items (Incremental)
- Categories (Incremental)
- Discounts (Incremental)
- Taxes (Incremental)
- Modifier Lists (Incremental)
- Payments (Incremental)
- Refunds (Incremental)
- Orders (Incremental)
- Locations
- Team Members
- Team Member Wages
- Customers
- Shifts
- Inventory
- Bank Accounts
- Cash Drawers
- Loyalty
Limitations and considerations
Square uses dynamic rate limits that vary by endpoint and current API load. The connector handles 429 Too Many Requests responses by waiting 30 seconds before retrying. See Square’s rate limit guidance for details.
If Square returns 403 Forbidden or 404 Not Found for a stream, the connector skips it. The sync continues without an error. If a stream unexpectedly syncs zero records, check your credentials include the permission listed in Prerequisites.
The Shifts stream reads from Square’s Search Timecards endpoint, which replaces the retired Shift endpoints. Square no longer returns employee_id on timecards. The connector therefore populates employee_id with the value of team_member_id.
The Orders stream is partitioned by location. The connector fetches each location’s orders independently through the SearchOrders endpoint. Each request has a page size of 1,000 records.
Useful links
IP allow list
If you use Airbyte Cloud and your organisation restricts access to specific IPs, add the Airbyte Cloud IP addresses to your allow list.
Changelog
Expand to review
| Version | Date | Pull Request | Subject |
|---|---|---|---|
| 1.8.2 | 2026-11-10 | 91735 | Update dependencies |
| 1.8.1 | 2026-11-09 | 91287 | Update external documentation URLs |
| 1.8.1 | 2026-11-03 | 90784 | Update dependencies |
| 1.8.0 | 2026-10-22 | 85911 | Migrate the shifts stream to Square’s Timecards API (Labor Shift endpoints retired) and paginate it with cursor; employee_id is now populated from team_member_id |
| 1.7.34 | 2026-10-20 | 89448 | Update dependencies |
| 1.7.33 | 2026-10-13 | 88838 | Update dependencies |
| 1.7.32 | 2026-10-06 | 88067 | Update dependencies |
| 1.7.31 | 2026-09-29 | 87389 | Update dependencies |
| 1.7.30 | 2026-09-22 | 86826 | Update dependencies |
| 1.7.29 | 2026-09-15 | 86264 | Update dependencies |
| 1.7.28 | 2026-09-08 | 85690 | Update dependencies |
| 1.7.27 | 2026-08-18 | 84792 | Update dependencies |
| 1.7.26 | 2026-08-11 | 84144 | Update dependencies |
| 1.7.25 | 2026-08-04 | 83647 | Update dependencies |
| 1.7.24 | 2026-07-28 | 83144 | Update dependencies |
| 1.7.23 | 2026-07-21 | 82636 | Update dependencies |
| 1.7.22 | 2026-07-14 | 82047 | Update dependencies |
| 1.7.21 | 2026-06-30 | 81274 | Update dependencies |
| 1.7.20 | 2026-06-23 | 80667 | Update dependencies |
| 1.7.19 | 2026-06-16 | 80085 | Update dependencies |
| 1.7.18 | 2026-06-15 | 77704 | Fix orders stream pagination — was silently capping at 500 records per location partition; now follows Square’s cursor to fetch all pages |
| 1.7.17 | 2026-06-09 | 79525 | Update dependencies |
| 1.7.16 | 2026-06-02 | 78955 | Update dependencies |
| 1.7.15 | 2026-04-28 | 77463 | Update dependencies |
| 1.7.14 | 2026-04-21 | 75866 | Update dependencies |
| 1.7.13 | 2026-03-17 | 75101 | Update dependencies |
| 1.7.12 | 2026-03-10 | 74570 | Update dependencies |
| 1.7.11 | 2026-02-17 | 72374 | Update dependencies |
| 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-24 | 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 |