Menu

Mattering Automations Square integration

Connect Square to Mattering Automations: payments, refunds, orders, invoices, catalog, inventory, and customers as workflow steps, authenticated with a Square access token and testable end to end in Square's sandbox.

The Mattering Automations Square integration adds Square to your automation canvas: take and refund payments, create and price orders, draft and publish invoices, manage the catalog and the customer directory, read and adjust inventory, and look up locations and team members, 39 nodes in all.

Setup takes a few minutes: copy the personal access token from your application in the Square Developer Console, attach it as a credential in Mattering, and test the connection. This guide walks through each step and ends with the full node reference.

Money is handled structurally. Exactly five nodes move real money: Square: Create Payment, Square: Complete Payment, Square: Pay Order, Square: Refund Payment, and Square: Publish Invoice, which by Square's own docs can charge the customer's card on file the moment it runs. Everything else, including creating orders and invoice drafts, moves nothing. Each money node is flagged for gating behind a condition, an approval step, or a manual run, carries an explicit idempotency_key field for replay protection, and has a use_sandbox switch so the whole flow can be rehearsed against Square's sandbox with zero real money.

Before you start

  • A Square account. Every account has at least one location, which is all the integration needs to verify itself.
  • Access to the Square Developer Console (developer.squareup.com/apps) to open or create an application and copy its access token.
  • A Mattering workspace with access to the Automations app.
  • For testing money flows: the sandbox test account that comes free with a Square developer account, and its separate sandbox access token.

Create a Square access token

Mattering authenticates to Square with an access token sent as Authorization: Bearer on every request. For automating your own account, use the personal access token from your application in the Developer Console; no OAuth flow is involved. Mattering also pins the Square-Version header to 2026-07-15 on every request, so API behavior stays on that release instead of floating with your application's default version.

Open the Square Developer Console (developer.squareup.com/apps) and open or create an application.
In the application's credentials, copy the access token for the environment you want: the production token for live work, or the sandbox token for testing.
Sandbox and production tokens are separate credentials from the same application, and Square's docs are explicit that credentials from one environment cannot be used with the other. A production token never works against the sandbox host, and a sandbox token never works against production.
Note the permissions granted to the application. The access token carries the application's permission set, and a token missing a permission returns 403 on that surface even though the connection test passes.

Connect Square to Mattering

In Mattering Automations, open Connectors and click Add Connector.
Choose Square from the list.
Click Create new credential, paste your access token, and save.
The credential is stored encrypted in Google Secret Manager and never appears in workflow logs.
Click Test Connection: Mattering calls Square's production locations endpoint and confirms the token authenticates. A sandbox-only token fails this test with a 401 while still working on nodes that have their sandbox switch on; use a production token here if you have one.
Click Connect. All 39 Square nodes appear in your canvas palette.

Verify it works

After connecting, open any automation canvas and check the palette: a Square section should list the query and action nodes. Drop Square: List Locations onto the canvas and run a test step. It takes no parameters, every Square account has at least one location, and it is a safe, read-only call; a successful response lists the account's locations with their ids. Keep those ids handy, because payments, orders, invoices, and inventory nodes are all scoped to a location.

To confirm the rest of the surface, run Square: List Payments for recent activity, or Square: Calculate Order with a location id and a test line item, which prices an order without creating anything. Everything in the verify path is read-only or a pure calculation; none of it can reach the five money-moving nodes.

Node reference

39 nodes, generated from the connector itself so this reference always matches what ships.

Read and query nodes 22

Square: Batch Get Catalog Objects

square_batch_retrieve_catalog_objects

Retrieve up to 1,000 catalog objects by id in one call, optionally with their related objects. A POST, but purely a read.

Square: Calculate Order

square_calculate_order

Price an order (totals, taxes, discounts) WITHOUT creating anything. A POST, but purely a calculation with no side effects: the safe way to preview totals before Square: Create Order.

Square: Get Catalog Object

square_get_catalog_object

Retrieve one catalog object (item, variation, category, tax, discount, modifier, image) by id, optionally with its related objects.

Square: Get Customer

square_get_customer

Retrieve one customer profile by id.

Square: Get Inventory Counts

square_batch_retrieve_inventory_counts

Retrieve current stock counts for catalog item variations, filtered by object ids, locations, state or last update time. A POST, but purely a read. Quantities come back as decimal strings.

Square: Get Invoice

square_get_invoice

Retrieve one invoice by id, including its status and the version needed for publish, cancel and delete.

Square: Get Item Inventory

square_retrieve_inventory_count

Retrieve the current stock counts of one catalog item variation, per location and inventory state.

Square: Get Location

square_get_location

Retrieve one location by id. Also accepts the literal id 'main' for the account's main location.

Square: Get Order

square_get_order

Retrieve one order by id, with line items and totals.

Square: Get Payment

square_get_payment

Retrieve one payment by id, including status, card details and the version_token used for safe completion.

Square: Get Refund

square_get_payment_refund

Retrieve one refund by id, including its status.

Square: Get Team Member

square_get_team_member

Retrieve one team member by id.

Square: List Catalog

square_list_catalog

Page through catalog objects of the requested types (items, variations, categories, taxes, discounts, modifiers, images). Always set types explicitly so new object types introduced by Square do not surprise the flow.

Square: List Customers

square_list_customers

List customer profiles in the Customer Directory, sorted and paginated. Use Square: Search Customers instead when you need to filter by email, phone, reference id or timestamps.

Square: List Invoices

square_list_invoices

List invoices for a location, newest first, including drafts. location_id is required by the API.

Square: List Locations

square_list_locations

List all of the seller's locations, including inactive ones. Needs no parameters and every Square account has at least one location, so this is also the credential health check. Location ids from here feed payments, orders, invoices and inventory nodes.

Square: List Payments

square_list_payments

List payments the account has taken, newest first by default, filtered by time window, location, amount or card details. Defaults to the last year when no time window is given.

Square: List Refunds

square_list_payment_refunds

List refunds the account has issued, filtered by time window, location, status or source type. Defaults to the last year when no time window is given.

Square: Search Catalog Objects

square_search_catalog_objects

Search catalog objects with structured queries: exact, prefix, or text search on attributes, items for tax, items for modifier list, and more. A POST, but purely a read.

Square: Search Customers

square_search_customers

Search customer profiles with filters (email, phone, reference id, created/updated timestamps, group membership, creation source) and sorting. A POST, but purely a read. An empty query returns all customers.

Square: Search Orders

square_search_orders

Search orders across one or more locations, filtered by state, date range, customer or fulfillment, sorted by created/updated/closed time. A POST, but purely a read.

Square: Search Team Members

square_search_team_members

List or filter the business's team members (staff), by location and status. A POST, but purely a read. An empty query returns everyone. Team member ids feed the team_member_id fields on payments and refunds.

Action nodes 17

Square: Adjust Inventory

square_batch_change_inventory

Apply inventory changes: physical counts (set the absolute quantity) or adjustments (move quantity between states, for example IN_STOCK to WASTE). Changes are recorded history, but stock levels are correctable by a follow-up count, so this is reversible in effect. The idempotency_key stops a retried run from double-adjusting.

Square: Cancel Invoice

square_cancel_invoice

Cancel a published invoice: Square stops payment collection and reminders, and the customer can no longer pay it. Irreversible; a canceled invoice cannot be reactivated. Invoices already paid or refunded cannot be canceled. For a draft, use Square: Delete Invoice Draft instead.

Square: Cancel Payment

square_cancel_payment

Cancel (void) a payment that is in the APPROVED state, releasing the hold on the buyer's card before any money moves. Irreversible: a canceled payment cannot be completed or reopened; take a new payment instead. Only works on payments created with autocomplete false that have not been completed.

Square: Complete Payment

square_complete_payment

Capture an APPROVED payment: the authorized amount is actually charged to the buyer's card. This MOVES REAL MONEY and cannot be undone (only refunded afterwards with Square: Refund Payment). The second half of the authorize-then-capture flow started by Square: Create Payment with autocomplete false.

Square: Create Customer

square_create_customer

Create a customer profile in the Customer Directory. Square requires at least one of: given_name, family_name, company_name, email_address or phone_number. Reversible: delete the profile with Square: Delete Customer.

Square: Create Invoice Draft

square_create_invoice

Create an invoice as a DRAFT for an existing order. Drafts bill nobody: Square's docs say a draft remains in the account and no action is taken until it is published. Review the draft, then run Square: Publish Invoice to actually bill the customer, or remove it with Square: Delete Invoice Draft.

Square: Create Order

square_create_order

Create an order (line items from the catalog or ad hoc). Creating an order moves NO money by itself; it is a record of a purchase. Money moves only when a payment is taken against it (Square: Create Payment with order_id, or Square: Pay Order). An unpaid order can be canceled by updating its state to CANCELED.

Square: Create Payment

square_create_payment

Charge a payment source. This COSTS REAL MONEY: with autocomplete true (the default) the card is charged the moment this node runs. Set autocomplete false to only authorize (hold) the amount and capture later with Square: Complete Payment or void with Square: Cancel Payment. The idempotency_key is the double-charge protection; template it from stable upstream data. Test with use_sandbox and sandbox test sources (cnon:card-nonce-ok), never a real card.

Square: Delete Catalog Object

square_delete_catalog_object

Delete a catalog object AND everything nested under it: deleting an item also deletes all of its variations. Irreversible through the API; the response lists every id that was deleted.

Square: Delete Customer

square_delete_customer

Permanently delete a customer profile from the directory. Irreversible: the profile and its cards on file are gone. Existing payments and invoices keep their records but lose the live customer link.

Square: Delete Invoice Draft

square_delete_invoice

Permanently delete a DRAFT invoice. Only drafts can be deleted (a published invoice must be canceled instead), and the associated order's status changes to CANCELED. Irreversible.

Square: Pay Order

square_pay_order

Pay an order with one or more APPROVED payments (created with autocomplete false). This MOVES REAL MONEY: the approved payments are captured and the order closes. The payment amounts must together equal the order total. Test against the sandbox, never a live account.

Square: Publish Invoice

square_publish_invoice

Publish a draft invoice. This BILLS A REAL CUSTOMER: depending on the invoice configuration Square emails or texts the invoice for payment, or IMMEDIATELY CHARGES the customer's card on file (automatic_payment_source CARD_ON_FILE). A published invoice cannot go back to draft; the way out is Square: Cancel Invoice. Test with use_sandbox, never a live customer.

Square: Refund Payment

square_refund_payment

Refund all or part of a payment. This MOVES REAL MONEY back to the buyer and cannot be undone. The idempotency_key is the double-refund protection; template it from stable upstream data. Give payment_id for a normal (linked) refund; for unlinked refunds (cash or external payments) set unlinked true with destination_id and location_id instead. Test with use_sandbox, never a live account.

Square: Update Customer

square_update_customer

Update a customer profile. This is a sparse update: send only the fields to change; omitted fields keep their values. To clear a field, send it as JSON null via the body passthrough object.

Square: Update Order

square_update_order

Update an open order with a sparse order object: fields present are set, fields_to_clear paths are removed. The order object must carry the order's current version. Setting state to CANCELED is how an unpaid order is canceled.

Square: Upsert Catalog Object

square_upsert_catalog_object

Create or update one catalog object (with nested variations). To create, give the object a temporary id starting with #, for example #NewItem; Square returns the real id in id_mappings. To update, use the real id and include the current version field or the call fails.

Using the integration

On the automation canvas

Square nodes chain with every other node: a scheduled Square: List Payments sweep can write daily totals into a Mattering database, a new form submission can become a customer via Square: Create Customer with a follow-up task in Mattering Productivity, and Square: Get Inventory Counts can open a reorder task when a variation runs low. There is no inbound Square trigger in this integration (the webhook subscription and Events APIs were deliberately omitted this round), so reacting to Square activity means polling a list or search node on a schedule and filtering for what changed.

From AI assistants over MCP

Every node speaks MCP, the open protocol for connecting AI assistants to tools. Claude, ChatGPT, and Matter can read sales, search the customer directory, check stock, and price prospective orders through the same nodes your workflows use. The list, get, search, and calculate nodes are read-only or pure calculations, which makes them the safest Square surface to hand an agent; keep the five money nodes behind gates regardless of who is driving.

The money boundary

Five nodes move real money. Square: Create Payment charges the card the moment it runs when autocomplete is on, which is Square's default; set autocomplete off to only authorize, then capture with Square: Complete Payment or release the hold with Square: Cancel Payment (the hold also lapses on its own after Square's delay window, 7 days by default). Square: Pay Order captures approved payments against an order and closes it. Square: Refund Payment sends money back and cannot be undone. Square: Publish Invoice bills a real customer: depending on the invoice's configuration Square emails or texts it for payment, or immediately charges the card on file. Invoices are draft-first by Square's own model: Square: Create Invoice Draft bills nobody, and a draft can be removed with Square: Delete Invoice Draft; once published, the way out is Square: Cancel Invoice, which is itself irreversible. Creating orders moves no money either; an unpaid order is canceled by setting its state to CANCELED via Square: Update Order.

Idempotency keys as replay protection

Square requires an idempotency_key on its money mutations and batch writes: the first request with a given key runs, and any retry with the same key returns the first result instead of running twice. The integration exposes these as explicit fields and never generates them, because a silently random key per run would defeat the protection. Template the key from stable upstream data, such as an order id or a trigger event id, so one logical charge maps to exactly one key. The key is required on Square: Create Payment, Square: Refund Payment, Square: Pay Order, Square: Upsert Catalog Object, and Square: Adjust Inventory, and accepted on the order, customer, and invoice writes.

Testing in the sandbox

Every node has a use_sandbox switch that targets Square's sandbox environment (connect.squareupsandbox.com) instead of production. Pair it with a sandbox credential and the full matrix is testable for free, including the money nodes: charge a test source like cnon:card-nonce-ok with Square: Create Payment, then refund it; authorize with autocomplete off, then complete or cancel; publish an invoice to a sandbox customer. The sandbox Dashboard mirrors the seller view so you can eyeball what a test created. Known sandbox gaps: receipts are not generated, and the Invoices product has limited sandbox support, so treat invoice delivery (the email or text a customer receives) as something to confirm carefully in production rather than in sandbox. Never test money nodes against a production credential.

Versions, amounts, and the pinned API version

Square uses optimistic concurrency widely: customers carry a version, orders require order.version on update, payments carry a version_token, and invoices require version on publish and cancel; read the current value with the matching get node (Square: Get Invoice, Square: Get Order, Square: Get Payment) just before writing. Money is integer minor units inside Money objects (an amount of 1000 with currency USD is 10 US dollars), inventory quantities are decimal strings, and timestamps are RFC 3339. The integration pins the Square-Version header to 2026-07-15, so response shapes stay on that release; the pin is bumped deliberately against Square's release notes rather than floating.

Troubleshooting

Test Connection fails with a 401
The token is invalid, was revoked or replaced in the Developer Console, or picked up stray whitespace when pasted. There is also a case specific to this integration: the connection test probes the production locations endpoint, so a sandbox-only token fails it with a 401 even though it is a perfectly good sandbox credential. Sandbox tokens still work on any node whose use_sandbox switch is on; to make the connection test pass, use the application's production token.
Test Connection passes but a node returns a 403
The token is missing a permission for that surface. Access tokens carry their application's permission set, and the connection test only lists locations, so a token can pass the test while payments, invoices, or catalog calls are refused. Review the application's permissions in the Developer Console, grant what the automation needs, and update the credential if the token changed.
An update fails with a version or VERSION_MISMATCH error
Square's optimistic concurrency caught a stale write. Orders require the current order.version on Square: Update Order, invoices require the current version on Square: Publish Invoice and Square: Cancel Invoice, catalog updates through Square: Upsert Catalog Object must include the object's current version, and Square: Complete Payment uses the payment's version_token. Read the record with the matching get node immediately before the write and pass the version it returns.
Square: List Invoices fails asking for a location id
The Square API requires location_id on that call; it is the one required query parameter in the integration. Run Square: List Locations once and pass one of the returned ids. The same ids feed payments, orders, and inventory nodes, so it is worth capturing the value early in the workflow.
A payment was authorized but the money never arrived
The payment was created with autocomplete off, which only authorizes: it places a hold that must be captured by Square: Complete Payment (or Square: Pay Order when the payment belongs to an order) before any money moves. Uncaptured holds lapse on their own after Square's delay window, 7 days by default. Check the payment's status with Square: Get Payment: APPROVED means it is still waiting for capture, and once the hold has expired or been canceled the payment cannot be completed, so take a new payment instead.
Amounts are 100 times too large or too small
Square represents money as integer minor units inside Money objects: an amount of 1000 with currency USD is 10 US dollars, not 1000 dollars. When templating amounts from upstream data, convert to minor units first, and when writing totals into records or messages, divide for display. Related: inventory quantities come back as decimal strings, so treat them as strings until you explicitly convert.
Square: Upsert Catalog Object fails on create or update
The two modes have different id rules. To create, give the object a temporary id starting with #, for example #NewItem; Square returns the real id in id_mappings. To update, use the real id and include the object's current version, or the call fails. Also note that Square: Delete Catalog Object cascades: deleting an item deletes all of its variations, and the response lists every id that was removed.
Publishing an invoice charged the customer immediately
That is Square's documented behavior when the invoice's automatic payment source is the customer's card on file: publish is the billing step, and with that configuration the charge happens the moment Square: Publish Invoice runs. Drafts created by Square: Create Invoice Draft never bill anyone, so review the draft's payment configuration with Square: Get Invoice before publishing, and keep the publish node behind an approval step. A published invoice cannot return to draft; Square: Cancel Invoice stops collection but is itself irreversible.

Square is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.

Start Free Explore our Products