Advanced Analytica Advanced Analytica: IBOM
← All connectors
Square logo

Source connector

Square

Set up Square as a source and move its data into your chosen destination.

Version 1.8.2 community beta

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.

    PermissionStreams
    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

  1. Create a Square Application.
  2. 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

  1. In Airbyte, go to Sources and click + New source.
  2. Select Square from the source type dropdown.
  3. 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.
  4. If you’re using a Square sandbox environment, set Sandbox to true.
  5. Set a Start Date in UTC using the YYYY-MM-DD format. It defaults to 2021-01-01. Incremental streams don’t replicate data before this date. Full refresh streams ignore it.
  6. 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

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.

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
VersionDatePull RequestSubject
1.8.22026-11-1091735Update dependencies
1.8.12026-11-0991287Update external documentation URLs
1.8.12026-11-0390784Update dependencies
1.8.02026-10-2285911Migrate 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.342026-10-2089448Update dependencies
1.7.332026-10-1388838Update dependencies
1.7.322026-10-0688067Update dependencies
1.7.312026-09-2987389Update dependencies
1.7.302026-09-2286826Update dependencies
1.7.292026-09-1586264Update dependencies
1.7.282026-09-0885690Update dependencies
1.7.272026-08-1884792Update dependencies
1.7.262026-08-1184144Update dependencies
1.7.252026-08-0483647Update dependencies
1.7.242026-07-2883144Update dependencies
1.7.232026-07-2182636Update dependencies
1.7.222026-07-1482047Update dependencies
1.7.212026-06-3081274Update dependencies
1.7.202026-06-2380667Update dependencies
1.7.192026-06-1680085Update dependencies
1.7.182026-06-1577704Fix orders stream pagination — was silently capping at 500 records per location partition; now follows Square’s cursor to fetch all pages
1.7.172026-06-0979525Update dependencies
1.7.162026-06-0278955Update dependencies
1.7.152026-04-2877463Update dependencies
1.7.142026-04-2175866Update dependencies
1.7.132026-03-1775101Update dependencies
1.7.122026-03-1074570Update dependencies
1.7.112026-02-1772374Update dependencies
1.7.102025-11-2570017Update dependencies
1.7.92025-11-1869524Update dependencies
1.7.82025-11-0469161Update dependencies
1.7.72025-08-2465422Update dependencies
1.7.62025-07-2063672Update dependencies
1.7.52025-06-2862212Update dependencies
1.7.42025-06-1449109Update dependencies
1.7.32025-03-2553695fix object_types string to array
1.7.32025-02-1553695Fix parameter of categories, discounts, items, modifier_list taxes
1.7.22024-10-2947869Update dependencies
1.7.12024-10-2847608Update dependencies
1.7.02024-10-0646527Migrate to Manifest-only
1.6.232024-10-0546409Update dependencies
1.6.222024-09-2846162Update dependencies
1.6.212024-09-2145787Update dependencies
1.6.202024-09-1445550Update dependencies
1.6.192024-09-0745045Update dependencies
1.6.182024-08-2444745Update dependencies
1.6.172024-08-1744325Update dependencies
1.6.162024-08-1243915Update dependencies
1.6.152024-08-1043498Update dependencies
1.6.142024-08-0343110Update dependencies
1.6.132024-07-2742638Update dependencies
1.6.122024-07-2042226Update dependencies
1.6.112024-07-1341913Update dependencies
1.6.102024-07-1041502Update dependencies
1.6.92024-07-0941124Update dependencies
1.6.82024-07-0640989Update dependencies
1.6.72024-06-2540313Update dependencies
1.6.62024-06-2240027Update dependencies
1.6.52024-06-0639206[autopull] Upgrade base image to v1.2.2
1.6.42024-06-1230315Fix customer stream pagination limit
1.6.32024-06-1439377Add error handlers, migrate to inline schemas, move spec to manifest
1.6.22024-05-0337800Migrate to Poetry. Replace custom components with default classes
1.6.12023-11-0731481Fix duplicate records for Payments and Refunds stream
1.6.02023-10-1831115Add customer_id field to Payments and Orders streams
1.5.02023-10-1631045Added New Stream bank_accounts
1.4.02023-10-1331106Add new stream Loyalty
1.3.02023-10-1231107Add new stream Inventory
1.2.02023-10-1031065Add new stream Cash drawers shifts
1.1.32023-10-1030960Update airbyte-cdk version to >=0.51.31
1.1.22023-07-1028019fix display order of spec fields
1.1.12023-06-2827762Update following state breaking changes
1.1.02023-05-2426485Remove deprecated authSpecification in favour of advancedAuth
1.0.12023-05-0325784Fix Authenticator
1.0.02023-05-0325784Fix Authenticator
0.2.22023-03-2222867Specified date formatting in specification
0.2.12023-03-0623231Publish using low-code CDK Beta version
0.2.02022-11-1419369Migrate to low code (YAML); update API to version 2022-10-19; update docs
0.1.42021-12-026842Added oauth support
0.1.32021-12-068425Update title, description fields in spec
0.1.22021-11-087499Remove base-python dependencies
0.1.12021-07-094645Update _send_request method due to Airbyte CDK changes
0.1.02021-06-304439Initial release supporting the Square API
Advanced Analytica

Most businesses are sitting on information they can’t use at speed. The people who hold it are busy, and when they leave, the knowledge goes with them. The documents are static, and the processes around them weren’t designed for AI.

Advanced Analytica works with these businesses to turn that information into structured data assets. Once they're integrated, AI systems can govern it, and the business can use it. We bring in the strategy, the specification and the AI skills to rework how the business operates.

MOVE FAST. STAY SAFE.