Square
List instances
List every Square integration instance for the current tenant.
Create instance
Create a new Square integration instance. For v1, provide a personal access token from the Square Developer Console; OAuth is pending business verification.
Get instance
Fetch a single Square integration instance by ID.
Update instance
Update an existing instance. All fields are optional — only fields present in the body are changed.
Delete instance
Delete an integration instance. Also removes all synced Square orders, catalog items, locations, and webhook events for this instance. Linked SKU sales orders themselves are preserved.
Test connection
Call `/v2/merchants/me` on Square using the stored access token. Latches the returned `merchant_id` onto the instance if it isn't already set.
Sync (locations + catalog + orders)
Dispatches a background sync job for the instance. Returns immediately with a tracked_job_log_id.
Get OAuth authorize URL
Builds the Square OAuth authorization URL for this instance. Redirect the merchant's browser to the returned `authorization_url`; after they approve, Square redirects back and the connection is stored automatically with the granted scopes.
List locations
Paginated list of Square locations across all instances (or filter by `filter[integration_instance_id]`).
Update location mapping
Point a Square location at a SKU warehouse. Pass `warehouse_id: null` to unmap.
Sync locations
Synchronously call Square's `/v2/locations` and upsert `square_locations` rows.
List catalog items
Paginated list of Square catalog variations across all instances.
Get latest catalog sync info
Latest-sync summary for an instance's catalog: the most recently updated item plus total / mapped / unmapped product counts. Useful before queuing a refresh to decide whether a `since_latest` sync is sufficient.
Update catalog mapping
Point a Square catalog variation at a SKU Product. Pass `product_id: null` to unmap.
Sync catalog
Synchronously call Square's `/v2/catalog/list` (cursor-paginated) and upsert `square_catalog_items` rows.
List orders
Paginated list of Square orders across all instances.
Get latest order sync info
Latest-sync summary for an instance's orders: the most recently updated synced order and the total number of orders stored. Useful before queuing a refresh to decide whether a `since_latest` sync is sufficient.
Get order
Fetch one Square order with its line items and linked SKU sales order.
Sync orders
Queues a background sync of Square orders for the instance, then promotes new orders to SKU sales orders. Returns a tracked job log id that can be used to follow progress.
Submit fulfillments
Push pending fulfillment tracking back to Square for online orders shipped in SKU. Each eligible fulfillment updates the Square order's shipment fulfillment to COMPLETED with carrier, tracking number, tracking URL, and shipped-at time.
Receive webhook
**Public endpoint** — no bearer required. Square posts here for every subscribed event.
List payouts
List Square payouts (deposit/settlement batches) — the money Square transferred to the seller's bank account. Each payout aggregates the charges, refunds, and fees settled in that deposit; use it to reconcile channel revenue against bank deposits.
Get payout
Get a single Square payout, including its entry count and the connected Square account.
List payout entries
List the individual entries of one payout — each charge, refund, fee, or adjustment that was settled in the deposit, with gross/fee/net amounts and the Square payment it relates to.
Sync payouts
Start a background sync of payouts (and their entries) from Square for this connection. Payouts download per location from the last sync watermark; entries are refetched only when a payout changed. Returns a tracked job id for monitoring progress.