# Square

Square is a payment processing and business management platform that provides tools for point-of-sale, online payments, invoicing, and more. The Sling Square connector extracts data from the Square REST API, supporting payments, customers, orders, catalog items, invoices, refunds, inventory, and more.

{% hint style="success" %}
**CLI Pro Required**: APIs require a [CLI Pro token](/sling-cli/cli-pro.md) or [Platform Plan](/sling-platform/platform.md).
{% endhint %}

## Setup

The following credentials and inputs are accepted:

**Secrets:**

* `access_token` **(required)** -> Your Square Access Token
* `api_version` (optional) -> Square API version to use (default: `2026-01-22`)

**Inputs:**

* `base_url` (optional) -> Base URL for the Square API (default: `https://connect.squareup.com/v2`). Use `https://connect.squareupsandbox.com/v2` for sandbox testing.
* `anchor_date` (optional) -> The starting date for historical data extraction (default: 1 year ago). Format: `YYYY-MM-DD`

### Getting Your Access Token

1. Log in to the [Square Developer Dashboard](https://developer.squareup.com/apps)
2. Create or select an application
3. Go to **Credentials** in the left sidebar
4. Copy the **Access Token** for production, or use the **Sandbox Access Token** for testing

{% hint style="warning" %}
**Important:** For production use, generate an access token with the appropriate read permissions for the data you need to extract.
{% endhint %}

### Using `sling conns`

{% code overflow="wrap" %}

```bash
sling conns set SQUARE type=api spec=square secrets='{ access_token: sq0atp-xxxxxxxxxxxx }'
```

{% endcode %}

### Environment Variable

See [here](https://docs.slingdata.io/connections/api-connections/pages/eAdVs2BHCgdr6RS8GoJC#dot-env-file-.env.sling) to learn more about the `.env.sling` file.

{% code overflow="wrap" %}

```bash
export SQUARE='{ type: api, spec: square, secrets: { access_token: "sq0atp-xxxxxxxxxxxx" } }'
```

{% endcode %}

### Sling Env File YAML

See [here](https://docs.slingdata.io/connections/api-connections/pages/eAdVs2BHCgdr6RS8GoJC#sling-env-file-env.yaml) to learn more about the sling `env.yaml` file.

```yaml
connections:
  SQUARE:
    type: api
    spec: square
    secrets:
      access_token: "sq0atp-xxxxxxxxxxxx"
```

**With sandbox and anchor date:**

```yaml
connections:
  SQUARE:
    type: api
    spec: square
    secrets:
      access_token: "EAAAl_sandbox_token_here"
    inputs:
      base_url: "https://connect.squareupsandbox.com/v2"
      anchor_date: "2023-01-01"
```

## Replication

Here's an example replication configuration to sync Square data to a PostgreSQL database:

```yaml
source: SQUARE
target: MY_POSTGRES

defaults:
  mode: incremental
  object: square.{stream_name}

streams:
  # sync all endpoints
  '*':
```

**Full refresh example for reference data:**

```yaml
source: SQUARE
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: square.{stream_name}

streams:
  locations:
  team_members:
  disputes:
  gift_cards:
```

## Endpoints

### Core Payment Data

| Endpoint    | Description              | Incremental |
| ----------- | ------------------------ | ----------- |
| `locations` | Business locations       | No          |
| `payments`  | Payment transactions     | Yes         |
| `refunds`   | Payment refunds          | Yes         |
| `payouts`   | Payouts to bank accounts | Yes         |
| `disputes`  | Payment disputes         | No          |

### Customers

| Endpoint    | Description      | Incremental |
| ----------- | ---------------- | ----------- |
| `customers` | Customer records | Yes         |

### Orders & Invoices

| Endpoint   | Description                        | Incremental |
| ---------- | ---------------------------------- | ----------- |
| `orders`   | Orders (iterates over locations)   | Yes         |
| `invoices` | Invoices (iterates over locations) | No          |

### Catalog & Inventory

| Endpoint           | Description                                      | Incremental |
| ------------------ | ------------------------------------------------ | ----------- |
| `catalog_objects`  | Items, categories, taxes, discounts, modifiers   | Yes         |
| `inventory_counts` | Inventory counts per item variation and location | Yes         |

### Other

| Endpoint           | Description              | Incremental |
| ------------------ | ------------------------ | ----------- |
| `team_members`     | Team/employee members    | No          |
| `subscriptions`    | Subscriptions            | No          |
| `gift_cards`       | Gift cards               | No          |
| `loyalty_accounts` | Loyalty program accounts | No          |

To discover available endpoints:

```bash
sling conns discover SQUARE
```

## Incremental Sync

The Square connector supports incremental sync on several endpoints using different timestamp fields:

* **payments, refunds**: Uses `updated_at_begin_time` parameter to fetch records updated since last sync
* **customers**: Uses the search API with `updated_at` filter
* **orders**: Uses `date_time_filter.updated_at` in the search API
* **catalog\_objects**: Uses `begin_time` parameter for modified objects
* **inventory\_counts**: Uses `updated_after` parameter
* **payouts**: Uses `begin_time` parameter based on creation date

### First Run Behavior

* Fetches all records from `anchor_date` (default: 1 year ago) to present
* Subsequent runs only fetch records updated after the last sync

## Location-Dependent Endpoints

The `orders` and `invoices` endpoints require a location ID. The connector automatically:

1. Fetches all locations from the `locations` endpoint
2. Iterates over each location to retrieve orders and invoices

Ensure the `locations` endpoint runs before `orders` and `invoices` in your replication.

## Rate Limiting

Square API rate limits vary by endpoint but are generally around 5-10 requests per second. The connector:

* Uses conservative rate limiting (5 requests/second)
* Retries with exponential backoff on 429 (rate limit) responses
* Supports up to 5 retry attempts

If you are facing issues connecting, please reach out to us at <support@slingdata.io>, on [discord](https://discord.gg/q5xtaSNDvp) or open a Github Issue [here](https://github.com/slingdata-io/sling-cli/issues).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.slingdata.io/connections/api-connections/square.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.