> ## Documentation Index
> Fetch the complete documentation index at: https://www.integrate.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](http://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](/docs/etl/using-components-rest-api-source) with a [Universal OAuth](/docs/etl/allowing-integrateio-etl-access-to-any-api-with-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](https://developer.squareup.com/apps).
* 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. |

<Note>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.</Note>

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 |

<Note>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.</Note>

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.

<Tip>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.</Tip>

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.