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.
Connect Square to Mattering
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
Test Connection passes but a node returns a 403
An update fails with a version or VERSION_MISMATCH error
Square: List Invoices fails asking for a location id
A payment was authorized but the money never arrived
Amounts are 100 times too large or too small
Square: Upsert Catalog Object fails on create or update
Publishing an invoice charged the customer immediately
Related
The Square MCP
What connecting Square unlocks for AI agents and automations, with common uses and FAQs.
More guides
All Automations documentation
Every integration guide, plus how connectors, credentials, and workflows fit together.
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.