ETL: Square

Configure the Square source in Integrate.io ETL to read payments, refunds, payouts, customers, catalog, and other Square data into your pipeline.

Use the Square source component to read data from your Square seller account into your Integrate.io ETL pipeline. The connector reads 14 Square objects, including payments, refunds, payouts, customers, and catalog objects. Payments and refunds support incremental loads.

Use this component instead of the generic REST API source with a Universal OAuth Square connection. The native connector handles authentication, pagination, and full history for you.

Prerequisites

• A Square account with access to the Square Developer Console.
• A personal access token from an application in the Developer Console. Square issues separate tokens for production and sandbox.

Connection setup

Create a Square connection from Connections → New connection → Square.

Field	Description
Name	Display name for the connection inside Integrate.io.
Access Token	Your Square personal access token. Integrate.io sends it as a bearer token on every request.
Environment	Production (default) or Sandbox. Production reads from connect.squareup.com. Sandbox reads from connect.squareupsandbox.com. Use a token that matches the environment. Square rejects a sandbox token on the production host, and the reverse, with HTTP 401.
Location ID	Optional. The Square location ID (for example, L88917AVBK2S5) to read payments and payouts from. Letters and digits only. The Save button stays disabled while the value contains other characters.

Use a personal access token, not an OAuth access token. Square OAuth access tokens expire after 30 days. Integrate.io does not refresh them for this connection, so scheduled jobs would start failing with HTTP 401. Personal access tokens do not expire.

After you fill in the form, click Test connection. The test reads the list of locations in your Square account.

Multiple locations

Square returns payments and payouts for the seller’s main location only, unless the request includes a location ID. Refunds and disputes include all locations and ignore the Location ID setting.

• If you leave Location ID blank, payments and payouts come from your main location only.
• If you set Location ID, payments and payouts come from that location only. An unknown location ID fails with HTTP 400.

To load payments and payouts from several locations, create one Square connection per location. Read the locations object to look up your location IDs.

Source properties

The source component is configured in Step 02 of the component editor.

Source table (object)

Select the Square object to read data from:

Object	Square endpoint	Incremental load
payments	/v2/payments	Supported (newer than only)
refunds	/v2/refunds	Supported (newer than only)
payouts	/v2/payouts	Not supported
customers	/v2/customers	Not supported
customer_groups	/v2/customers/groups	Not supported
customer_segments	/v2/customers/segments	Not supported
locations	/v2/locations	Not supported
catalog_objects	/v2/catalog/list	Not supported
disputes	/v2/disputes	Not supported
gift_cards	/v2/gift-cards	Not supported
payment_links	/v2/online-checkout/payment-links	Not supported
merchants	/v2/merchants	Not supported
team_member_jobs	/v2/team-members/jobs	Not supported
break_types	/v2/labor/break-types	Not supported

Orders are not available. Square lists orders only through a POST search endpoint, and this connector reads GET list endpoints. Bookings, invoices, cash drawer shifts, and loyalty programs are also not available.

Full loads of payments, refunds, and payouts read all history. Square limits these endpoints to the last year by default. Integrate.io requests records created since January 1, 2000 to remove that limit.

Load type

Select how records are loaded on each pipeline run:

• Full Load. Fetches all records for the selected object on every run.
• Incremental Load. Fetches only records newer than a reference date. Available for payments and refunds. For other objects, the UI shows Incremental Load not supported because Square’s list endpoints for them don’t accept a date filter.

Incremental load settings

When Incremental Load is selected, the following options appear:

Sync date field. The date field used to filter records. You can pick any date field detected for the object, such as updated_at or created_at. Integrate.io asks Square for records updated after the reference date, then keeps only the records whose selected field is after the reference date.

Load records. Only newer than ( > ) is available for Square objects. The older than ( < ) option is hidden.

Reference date. Choose the source of the date value:

• Last successful run. Loads records since the last successful run of this pipeline, using the $_PACKAGE_LAST_SUCCESSFUL_JOB_SUBMISSION_TIMESTAMP system variable. Recommended for scheduled pipelines.
• Fixed Date. Pick a specific calendar date. Integrate.io sends a date such as 2025-10-21 to Square as 2025-10-21T00:00:00Z (midnight UTC).
• Variable. Use a custom package variable. Dates without a time zone are read as UTC.

Use updated_at as the sync date field to pick up payments and refunds that changed after they were created, such as captured, refunded, or disputed payments.

Source schema

After configuring the source properties, the Schema section (Step 03) displays the available fields with their detected data types. Use the field selector to choose which columns to include in your pipeline. You can rename fields with aliases and change data types as needed.

Nested JSON objects in Square responses are flattened into individual columns with underscore-separated names. For example, risk_evaluation.created_at becomes risk_evaluation_created_at.

Integrate.io does not send a Square-Version header. Responses follow the API version your Developer Console application is set to, so field names can differ between applications on different versions.