Square integration

In short

Read payments, orders and the catalog, and manage customers. Connect it on the Integrations page; your app then calls Square through Sapilon without ever holding a Block credential.

Lets your app read a Square seller’s locations, payments, orders and catalog, and search, create and update customers, with an access token.

Connecting

On the Integrations page choose Connect on Square and fill in:

Production access token — developer.squareup.com/apps → your application → Credentials → Production → Access token.

Sapilon checks the key with the provider before it saves it, and stores it encrypted; it is never shown again.

Only production accounts are supported; Square sandbox tokens are not accepted.

What your app can do

Only these requests are available; anything else is refused.

GET /v2/locations
GET /v2/payments
GET /v2/payments/*
POST /v2/orders/search
GET /v2/orders/*
GET|POST /v2/customers
POST /v2/customers/search
GET|PUT /v2/customers/*
GET /v2/catalog/list
POST /v2/catalog/search

How the agent uses it

Use integrations.request('square', …); paths are relative to https://connect.squareup.com.

GET /v2/locations — most calls need a location_id.
GET /v2/payments, GET /v2/payments/{id} — Example: { method: 'GET', path: '/v2/payments', query: { begin_time: '2026-10-01T00:00:00Z', location_id: 'L1' } }.
POST /v2/orders/search — Example: { method: 'POST', path: '/v2/orders/search', body: { location_ids: ['L1'], query: { filter: { state_filter: { states: ['COMPLETED'] } } }, limit: 50 } }. GET /v2/orders/{id} — one order.
GET|POST /v2/customers, GET|PUT /v2/customers/{id} — Example: { method: 'POST', path: '/v2/customers', body: { given_name: 'Sara', email_address: 'sara@acme.com', idempotency_key: 'c-1' } }.
POST /v2/customers/search — Example: body: { query: { filter: { email_address: { exact: 'sara@acme.com' } } } }.
GET /v2/catalog/list, POST /v2/catalog/search — items and prices.

Payments and orders are read-only. Amounts are in the smallest currency unit.