Square

Square

This connector works with one Square seller account through the Square API (https://connect.squareup.com, or https://connect.squareupsandbox.com for the sandbox), version 2026-09-16: business and locations, payments and refunds, orders, customers, the item catalog, inventory counts, invoices and team members.

Setup (about 5 minutes)

1. Sign in at https://developer.squareup.com/apps with the Square account and click Create an application (any name).
2. Open the application → Credentials. The toggle at the top switches between Sandbox and Production.
3. Copy the access token of that environment into SQUARE_ACCESS_TOKEN. It is a personal access token with full access to your own account, which is what this connector needs; it does not expire, but anyone holding it can act for the business, so keep it secret and replace it on the same page if it leaks.
4. Set SQUARE_API_URL to https://connect.squareupsandbox.com for the sandbox token or https://connect.squareup.com for the production token. A token only works against its own environment (401 otherwise).
5. Install and run square_get_merchant to check the business name.

Sandbox: the sandbox token belongs to a default test seller. To look at the results as a seller, open the developer console → Sandbox test accounts → the account → Square Dashboard. The sandbox never emails invoices; use the invoice's public_url.

Money and customer emails: confirm first. square_refund_payment sends money back, square_publish_invoice sends the invoice to the customer (email) and makes it payable, and square_cancel_invoice and square_upsert_catalog_object change data customers see. Before calling them, state what will happen (amount, customer, ids) and wait for the user's yes. square_delete_customer, square_delete_catalog_object and square_delete_invoice are installed switched off.

Idempotency keys: every create, refund, publish and upsert takes an idempotency_key. Use a fresh UUID per action, and reuse the same key only when retrying the same action after a timeout.

Money: amounts are integers in the smallest unit of the currency ({"amount": 1999, "currency": "EUR"} is 19.99 EUR); the currency must be the seller's (see square_get_merchant). Times are RFC 3339 (2026-10-01T00:00:00Z).

Locations: most data belongs to a location. square_list_locations gives their ids; "main" works as the id of the main location in square_get_location. square_list_payments without location_id covers only the main location; square_search_orders needs 1 to 10 location_ids; square_list_invoices needs one location_id.

Orders: square_search_orders filters by state (OPEN, COMPLETED, CANCELED), dates and customers. When you filter by a date field, sort by the same field ("sort": {"sort_field": "CLOSED_AT"} with a closed_at filter). Orders taken offline can take up to 72 hours to appear.

Invoices: an invoice is built on an OPEN order. Steps: square_create_order (location, line items, customer) → square_create_invoice with that order_id, the customer_id, one payment_requests entry ({"request_type": "BALANCE", "due_date": "2026-11-01"}) and accepted_payment_methods ({"card": true}) → it is a DRAFT until square_publish_invoice. Publishing and cancelling need the invoice's current version (from square_get_invoice). For EMAIL delivery the customer needs an email address. Deleting a draft also cancels its order.

Customers: square_search_customers filters by email, phone (E.164, +4976112345), reference id or dates; a new or changed customer can take a few seconds to become searchable. square_update_customer changes only the fields you send; pass version to avoid overwriting a newer change.

Catalog: square_list_catalog takes types (ITEM, ITEM_VARIATION, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, ...). square_search_catalog_items searches item names, SKUs and descriptions. square_upsert_catalog_object creates or REPLACES a whole object: to change an item, read it with square_get_catalog_object, change the copy and send it back with its version, or fields you leave out (variations included) are removed. New objects use temporary ids starting with #.

Inventory: counts are per item variation (not per item) and location: square_get_inventory_counts with variation ids, or square_get_inventory_count for one.

Paging: list and search answers carry cursor while more pages exist; pass it back to continue.

Common errors (errors[].code and detail)

• 401 UNAUTHORIZED: wrong token, or a sandbox token against the production URL (or the other way round).
• 400 INVALID_REQUEST_ERROR / VERSION_MISMATCH: a field or an outdated version; read the object again.
• 404 NOT_FOUND: wrong id, or an object from another location or environment.
• 429 RATE_LIMITED: wait a moment and retry.

Out of scope here: taking card payments, gift cards, loyalty, bookings, subscriptions, payouts and webhooks.