Square

Connect & Ingest data from 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.

CLI Pro Required: APIs require a CLI Pro token or Platform Plan.

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

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

Important: For production use, generate an access token with the appropriate read permissions for the data you need to extract.

Using sling conns

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

Environment Variable

See here to learn more about the .env.sling file.

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

Sling Env File YAML

See here to learn more about the sling env.yaml file.

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

With sandbox and anchor date:

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:

source: SQUARE
target: MY_POSTGRES

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

streams:
  # sync all endpoints
  '*':

Full refresh example for reference data:

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:

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 [email protected], on discord or open a Github Issue here.