A Square MCP where you rehearse the money before you move it
Connect one access token and Square payments, refunds, orders, invoices, the catalog, inventory, and the customer directory become workflow steps for visual automations and AI agents. Five nodes move real money, each one flagged and gated as a deliberate step, and every node has a sandbox switch so even the money movers can be tested end to end without a real card.
What the Square MCP connector does
The Square connector for Mattering Automations is 39 nodes across the Square API: payments (charge, authorize then capture, cancel, list, get), refunds (linked and unlinked), orders (create, update, search, plus a pure pricing calculation), invoices (draft, publish, cancel, delete, list), the catalog (list, search, get, upsert, delete, batch get), inventory (counts and adjustments), the customer directory (full CRUD plus search), locations, and read-only team member lookup.
Every node speaks MCP, the open protocol for connecting AI assistants to tools, so Claude, ChatGPT, and any MCP-capable assistant can use them, alongside Matter, the AI assistant built into the platform. An assistant can answer what yesterday's sales looked like, which items are low on stock, and which invoices are still unpaid, without anyone opening the Square Dashboard.
Because Mattering is a work platform rather than middleware, Square work lands somewhere useful by default: a scheduled payments sweep can write daily totals into a Mattering database, a failed payment can open a task in Mattering Productivity, and a new Square customer can become a record the rest of the workspace can see, all on one canvas next to the rest of the work.
The money boundary is structural, not advisory. 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 email the invoice, do nothing, or immediately charge the customer's card on file depending on configuration. Each is flagged so it can sit behind a condition, an approval step, or a manual run. Invoices are draft-first by Square's own model: Square: Create Invoice Draft bills nobody until a separate publish step runs. And every money mutation carries an explicit idempotency_key field, never auto-generated, so a retried run returns the first result instead of charging twice.
One connection, three surfaces
- Visual automations. Drag Square nodes onto the canvas and wire them to triggers, conditions, and other apps.
- AI agents, yours or ours. These nodes speak MCP, the open protocol, so Claude, ChatGPT, and any MCP-capable assistant can use them, and Matter, the agent built into the platform, uses them natively.
- The whole platform. Combine with native tasks, projects, and other connectors, no middleware in between.
Every Square node, ready to drop on the canvas
39 nodes, generated from the connector itself so this list always matches what ships. Expand a category to browse.
Read and query nodes 22
Square: Batch Get 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
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
Retrieve one catalog object (item, variation, category, tax, discount, modifier, image) by id, optionally with its related objects.
Square: Get Customer
Retrieve one customer profile by id.
Square: Get 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
Retrieve one invoice by id, including its status and the version needed for publish, cancel and delete.
Square: Get Item Inventory
Retrieve the current stock counts of one catalog item variation, per location and inventory state.
Square: Get Location
Retrieve one location by id. Also accepts the literal id 'main' for the account's main location.
Square: Get Order
Retrieve one order by id, with line items and totals.
Square: Get Payment
Retrieve one payment by id, including status, card details and the version_token used for safe completion.
Square: Get Refund
Retrieve one refund by id, including its status.
Square: Get Team Member
Retrieve one team member by id.
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
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
List invoices for a location, newest first, including drafts. location_id is required by the API.
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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.
Connecting Square takes one credential
Square issues access tokens per application in its Developer Console at developer.squareup.com/apps. For automating your own account, use the application's personal access token, sent as Authorization: Bearer on every request; OAuth exists for distributing an app to other sellers and is not part of this connector. Sandbox and production tokens are separate credentials from the same application, and neither works against the other environment. Mattering pins the Square-Version header to 2026-07-15 on every request so response shapes stay stable instead of floating with your application's default.
In the Square Developer Console (developer.squareup.com/apps), open or create an application and copy its access token: the production token for live work, or the sandbox token for testing.
In Mattering Automations, open Connectors, click Add Connector, choose Square, and create a credential with that token.
Click Test Connection. Mattering calls Square's production locations endpoint and confirms the token authenticates. A sandbox-only token fails this test but still works on any node with its sandbox switch on.
All 39 Square nodes appear in the canvas palette. Run Square: List Locations first: it needs no parameters, every Square account has at least one location, and the location ids it returns feed the payments, orders, invoices, and inventory nodes.
Common uses for the Square MCP
Sales and refunds the team can see
Square: List Payments and Square: List Refunds page through what the account has taken and given back, filtered by time window, location, or amount, defaulting to the last year when no window is given. Run them on a schedule and route the results into a Mattering database or a daily summary task, so revenue questions get answered without opening the Dashboard.
Pricing an order before it exists
Square: Calculate Order prices an order end to end (totals, taxes, discounts) without creating anything: a POST, but a pure calculation with no side effects. It is the safe way to preview what a cart would cost before Square: Create Order writes a record, and creating an order still moves no money by itself.
Invoices that wait for a person
Square: Create Invoice Draft builds an invoice against an existing order, and by Square's model a draft bills nobody: no email, no charge, nothing until publish. Square: Publish Invoice is the deliberate second step that bills the real customer, and depending on the invoice's configuration it can charge a card on file immediately, so keep it behind an approval task or a condition.
A customer directory agents can search
Square: Search Customers filters profiles by email, phone, reference id, or timestamps, and Square: Create Customer and Square: Update Customer keep the directory current from forms or records elsewhere in the workspace. Updates are sparse: send only the fields to change and everything else stays put.
Catalog and stock without the dashboard
Square: Upsert Catalog Object creates or updates items and variations, Square: Get Inventory Counts reads current stock across locations, and Square: Adjust Inventory records counts and state moves. A scheduled stock sweep that opens a reorder task when a variation runs low is a small canvas, not a project.
Rehearse the money in the sandbox
Every node has a use_sandbox switch that points it at Square's sandbox environment with a separate sandbox credential. Square provides test sources like cnon:card-nonce-ok that simulate a successful card, so the entire money path, charge, capture, refund, invoice publish, can be exercised end to end with zero real money before the workflow ever touches the production account.
Example: An order becomes a priced invoice draft, with a person before anyone is billed
Built on the Automations canvas in a few minutes, or described in plain language to Matter and built for you.
Trigger: a form submission or a record in a Mattering database delivers a customer, line items, and quantities.
Square: List Locations supplies the location id that orders and invoices require.
Square: Calculate Order prices the cart, taxes and discounts included, without creating anything, so the numbers are known first.
Square: Create Order writes the order record. No money moves: an order is a record of a purchase, not a charge.
Square: Create Invoice Draft builds the invoice for that order. Drafts bill nobody, so the workflow can stop here safely.
An approval task in Mattering Productivity gates Square: Publish Invoice, the one step in this flow that bills the customer. Until a person clears the task, nothing is sent and nothing is charged.
Square MCP questions, answered
What Square operations are supported?
39 nodes: payments (create, complete, cancel, list, get), refunds (linked and unlinked, plus list and get), orders (create, update, search, get, calculate, pay), invoices (draft, publish, cancel, delete, list, get), catalog objects (list, search, get, batch get, upsert, delete), inventory counts and adjustments, customer directory CRUD plus search, locations, and read-only team member lookup. Deliberately not shipped this round: the Checkout, Terminal, Cards on file, Subscriptions, Disputes, and Payouts APIs, catalog images and invoice attachments (both need multipart file upload), the bulk batch families, team member writes, and OAuth.
Does this work with Claude, ChatGPT, or other AI assistants?
Yes. Mattering exposes these nodes over MCP, an open protocol for connecting AI assistants to tools, so any MCP-capable assistant, including Claude and ChatGPT, can connect to your workspace and use them. Matter, the assistant built into the platform, uses the same nodes natively.
Can this connector move real money by accident?
It is built so that it cannot do so silently. Exactly five nodes move money: Square: Create Payment charges a card the moment it runs with autocomplete on (Square's default, spelled out on the field), Square: Complete Payment captures an authorized payment, Square: Pay Order captures approved payments against an order, Square: Refund Payment sends money back, and Square: Publish Invoice bills a customer and can charge a card on file immediately depending on the invoice's configuration. All five are flagged so they can be gated behind a condition, an approval step, or a manual run, and everything else, including creating orders and invoice drafts, moves nothing.
How do I test payment flows without spending real money?
Use the sandbox. Every node has a use_sandbox switch that targets Square's separate sandbox environment, and a free Square developer account includes a sandbox test account with its own credential. Test sources like cnon:card-nonce-ok simulate a successful card, so even the five money nodes can run end to end in tests: charge, then refund; authorize, then complete or cancel; publish an invoice to a sandbox customer. One caveat: the sandbox's support for the Invoices product is limited, so treat invoice delivery (the email or text a customer would receive) as something to confirm in production carefully rather than in sandbox.
What stops a retried workflow from charging twice?
Square requires an idempotency_key on its money mutations, and the connector exposes it as an explicit field rather than generating one silently, because a 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 first request with a key runs, and any retry with the same key returns the first result instead of running again.
Can a Square payment trigger a workflow?
Not as a trigger node in this connector. Square's webhook subscription and Events APIs were deliberately omitted this round, so there is no inbound Square trigger. The honest pattern today is polling: run Square: List Payments, Square: Search Orders, or Square: List Invoices on a schedule, filter by time window or status, and act on what changed.
What is location_id and why do so many nodes want it?
Square organizes a seller's business into locations, and payments, orders, invoices, and inventory are all scoped to one. Square: List Locations returns every location with its id, takes no parameters, and works on every account because every Square account has at least one location; it doubles as the connection health check. Square: List Invoices is the strictest case: the Square API requires location_id on that call. Square: Get Location also accepts the literal id main for the account's main location.
How are money amounts represented?
As integer minor units inside Money objects: an amount of 1000 with currency USD is 10 US dollars, and the connector never invents or converts prices on its own. Two related conventions to know: inventory quantities come back as decimal strings, and timestamps are RFC 3339 strings. The connector also pins the Square-Version header to 2026-07-15, so response shapes stay on that release instead of shifting under a workflow.
Put Square to work inside your workspace
Connect once, then use every node in visual automations and AI agent workflows across the Mattering platform.
All product names, logos, and brands are property of their respective owners and are used for identification purposes only. Use of these names, logos, and brands does not imply endorsement or affiliation. Square is a product of its respective owner; Mattering is an independent platform.