# 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](https://docs.slingdata.io/sling-cli/cli-pro) or [Platform Plan](https://docs.slingdata.io/sling-platform/platform).
{% 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/sling-cli/environment#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/sling-cli/environment#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).