Square

Point of sale and commerce. Take payments, issue refunds, and manage customers, catalog items, orders, invoices, and stock.

Measured routing accuracy

45 golden cases replayed through the router over the whole index: measured over corpus ea4f12ad2948 (65 toolkits, 2283 tools indexed and 13 declared uncallable), 34 cases written by hand and 11 cases from the paraphrase pass. A case counts as top-1 when its gold tool ranked first and top-8 when it reached the slate at all.

The sweep is offline: the reranker is a deterministic identity fake that returns candidates in the order retrieval produced them, so top-1 measures retrieval order rather than a reranked slate. just eval-live measures the same cases through the live reranker.

Authentication

Connect an entity with ConnectionsService.InitiateConnection, naming this toolkit's slug. Credentials stay in the connections vault; callers hold connected-account ids only.

api_key

Submit the key with ConnectionsService rather than putting it in a request; it is sealed at rest and never returned.

Tools

34 action tools. The catalog-wide slug is square.<tool>, which is what search_tools returns and call_tool takes.

square.create_payment

Charge a card, wallet, or cash source in Square to collect a one-time payment. Use when the user wants to take, run, charge, or collect a payment or sale. Attach a customer or order id to link the charge. Set autocomplete false to authorize now and capture later.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /payments.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "ring up this sale on the card reader", "take a payment for this order", "bill this customer's card right now", "run their card for the total", "collect money for this purchase".

square.get_payment

Get one Square payment by id: its status, amount, and linked customer or order. Use when the user asks whether a charge went through or wants details on a specific payment. For a list, use list_payments.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /payments/{{params.payment_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "did that charge go through at the register", "check on this transaction's status", "what happened with this sale", "look up a specific charge by its id".

square.list_payments

List Square payments for a location or date range. Use when the user asks for recent charges, sales history, or transactions in a given window. For one known payment, use get_payment.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /payments.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "show me today's sales", "what have we taken in this week", "pull up recent transactions at this store", "transaction history for a location".

square.complete_payment

Capture funds on a Square payment that was authorized with autocomplete false, completing the charge. Use when the user wants to capture, collect, or finalize an authorized hold, e.g. after fulfilling an order.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /payments/{{params.payment_id}}/complete.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "finish collecting on that held charge", "go ahead and capture the authorized amount", "close out the hold on their card now".

square.cancel_payment

Cancel a Square payment that has not yet been completed, releasing any authorization hold. Irreversible once canceled; a new payment is needed to charge later. Use when the user wants to abandon, drop, or void a pending or authorized charge before it captures.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). No scopes beyond the connection's defaults. Calls POST /payments/{{params.payment_id}}/cancel.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "never mind, don't charge them after all", "release the hold we put on their card", "drop this pending charge before it settles", "abandon this authorization".

square.create_refund

Refund a Square payment, in full or in part. Irreversible once processed; funds return to the customer's original payment method. Use when the user wants to refund, reverse, or give money back for a Square charge or sale.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). No scopes beyond the connection's defaults. Calls POST /refunds.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "give the customer their money back", "reverse this sale, they returned the item", "send a refund for this transaction", "credit them back for what they bought", "undo this charge".

square.get_refund

Get one Square refund by id: its status, amount, and the payment it applies to. Use when the user asks whether a specific refund went through.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /refunds/{{params.refund_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "did the refund actually go through", "check the status of money we sent back", "look up a specific refund".

square.list_refunds

List Square refunds, optionally filtered by status or date range. Use when the user asks what has been refunded or wants a refund history for the account. For a single known refund, use get_refund.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /refunds.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what have we refunded lately", "show our refund history", "pull up every reversed sale".

square.create_customer

Create a new customer profile in Square. Use when the user wants to add, register, or set up a new customer or buyer before charging them or linking them to an order. Optional name, email, and phone.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /customers.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "add a new shopper to square", "set up a profile for this buyer", "register a new client in our system", "onboard someone before we charge them".

square.get_customer

Get one Square customer's details by id: name, email, phone, and notes. Use when the user names a specific customer. For finding customers by email or phone, use search_customers; to browse all of them, use list_customers.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /customers/{{params.customer_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "pull up this shopper's profile", "what's on file for this buyer", "look up their contact info".

square.list_customers

List Square customers on the account, newest or oldest first. Use when the user wants to browse the whole customer base. To filter by email or phone, use search_customers instead.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /customers.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "who's in our customer base", "show everyone we've got on file", "browse the full client list".

square.search_customers

Find Square customers by exact email or phone number. Use when the user wants to look someone up by their contact details rather than browse the whole list. For one known customer id, use get_customer.

Class read (reads only). No scopes beyond the connection's defaults. Calls POST /customers/search.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "find the buyer with this phone number", "look someone up by their email", "do we have a customer with this contact info".

square.update_customer

Edit an existing Square customer's name, email, phone, or note. Use when the user wants to update, correct, or change a customer's contact details. Only the fields given change; omit others to leave them as is.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls PUT /customers/{{params.customer_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "fix their phone number on file", "this shopper's email changed", "correct the contact details we have saved", "change what's on record for them".

square.delete_customer

Permanently delete a Square customer profile. Irreversible; past payments and orders are not deleted with it. Use only when the user explicitly asks to delete or remove a customer record entirely.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). No scopes beyond the connection's defaults. Calls DELETE /customers/{{params.customer_id}}.

Arguments:

Also retrieved by: "wipe this shopper out of square for good", "erase their profile entirely", "remove them from our records completely", "they asked to be forgotten, delete their account".

square.create_catalog_item

Create a new item in the Square catalog with a name and price. Use when the user wants to add, list, or create a new product, item, or menu entry for sale. Optional description and SKU.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /catalog/object.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "add a new product to the menu", "list this item for sale", "set up a new thing we sell with a price", "create a menu entry".

square.get_catalog_item

Get one Square catalog item by its object id: name, description, and price. Use when the user names a specific product or menu item. For browsing or keyword lookup, use list_catalog_items or search_catalog_items.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /catalog/object/{{params.object_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "look up this product's details", "what's the price on this menu item", "pull up one specific thing we sell".

square.list_catalog_items

List every item in the Square catalog. Use when the user wants to browse the whole menu, product list, or catalog rather than search by keyword. For a keyword or category search, use search_catalog_items.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /catalog/list.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "show the whole menu", "what products do we carry", "browse everything in our catalog".

square.search_catalog_items

Search Square catalog items by name or category keyword. Use when the user asks to find, look up, or search for a product or menu item by what it's called. For the full catalog, use list_catalog_items.

Class read (reads only). No scopes beyond the connection's defaults. Calls POST /catalog/search-catalog-items.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "find the product called cold brew", "look up items by keyword", "search the menu for something".

square.update_catalog_item

Change an existing Square catalog item's name, description, or price. Use when the user wants to edit, rename, or reprice a product or menu item that already exists. Requires the item's existing object and variation ids.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /catalog/object.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "change the price on this product", "rename this menu item", "edit the description for something we sell".

square.delete_catalog_item

Permanently delete an item from the Square catalog. Irreversible; the item and its variations stop being sellable. Use only when the user explicitly asks to delete, remove, or discontinue a product or menu item entirely.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). No scopes beyond the connection's defaults. Calls DELETE /catalog/object/{{params.object_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "discontinue this product for good", "take this item off the menu permanently", "remove this thing we sell entirely".

square.create_order

Create a new Square order with one or more line items at a location. Use when the user wants to start, open, or ring up a new order or sale before taking payment. Pay it with pay_order once it's ready.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /orders.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "start a new tab for this table", "open a sale with these items", "ring up a new order before payment".

square.get_order

Get one Square order by id: its state, line items, and total. Use when the user asks about a specific order's contents or status. For searching across many orders, use search_orders.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /orders/{{params.order_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what's on this order", "pull up the contents of a specific sale", "check the total for this tab".

square.update_order

Change an existing Square order's line items or state, e.g. marking it completed. Use when the user wants to edit, add to, or update an order that hasn't been paid yet. To take payment, use pay_order.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls PUT /orders/{{params.order_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "add another item to this open order", "mark this order finished", "change what's on this tab before it's paid".

square.search_orders

Search Square orders across one or more locations, optionally filtered by state. Use when the user asks for a location's recent orders, open tabs, or completed sales. For one known order, use get_order.

Class read (reads only). No scopes beyond the connection's defaults. Calls POST /orders/search.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what orders are still open at this location", "show completed sales for today", "browse recent tabs across our stores".

square.pay_order

Settle a Square order by attaching one or more completed payments to it. Use when the user wants to close out, collect on, or finish paying for an order that already has a total. Create the payment first with create_payment.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /orders/{{params.order_id}}/pay.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "close out this tab with the payment we took", "settle this order now that it's paid", "apply this charge to finish the sale".

square.create_invoice

Create a draft invoice in Square for an existing order and customer. Use when the user wants to start, draft, or bill an order to a customer instead of collecting payment on the spot. Send it with publish_invoice once it's ready.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /invoices.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "draft a bill for this customer's order", "start an invoice we can send later", "set up a bill instead of charging them now".

square.get_invoice

Get one Square invoice by id: its status, due date, and hosted payment page url. Use when the user names a specific invoice or bill. For browsing all of them, use list_invoices.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /invoices/{{params.invoice_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "pull up this specific bill", "what's the status of an invoice", "check the payment page link for a bill".

square.list_invoices

List Square invoices for a location. Use when the user asks about unpaid bills, invoice history, or what's been sent to customers. For one known invoice, use get_invoice.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /invoices.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what invoices are still unpaid", "show our billing history", "what have we sent to customers".

square.publish_invoice

Publish a draft Square invoice, emailing it to the customer and opening it for payment. Use when the user wants to send, deliver, or issue an invoice that was drafted but not yet sent.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /invoices/{{params.invoice_id}}/publish.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "send this draft bill to the customer", "email the invoice so they can pay it", "issue this bill now".

square.cancel_invoice

Cancel a published Square invoice that will never be paid. Irreversible; the invoice stays on record marked canceled instead of being deleted. Use when the user wants to cancel, kill, or void an invoice that was sent by mistake.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). No scopes beyond the connection's defaults. Calls POST /invoices/{{params.invoice_id}}/cancel.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "void this bill, it went out by mistake", "kill this invoice, they don't need to pay it", "this bill should never be collected on".

square.delete_invoice

Permanently delete a draft Square invoice that has not been published. Irreversible and only works while the invoice is still a draft. For a published invoice that should never be paid, use cancel_invoice instead.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). No scopes beyond the connection's defaults. Calls DELETE /invoices/{{params.invoice_id}}.

Arguments:

Also retrieved by: "scrap this draft bill entirely", "get rid of this invoice before it's sent", "remove this unpublished bill for good".

square.get_inventory_count

Get the current stock count for one Square catalog item variation, optionally at specific locations. Use when the user asks how many of something are left, in stock, or on hand. For several items at once, use batch_get_inventory_counts.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /inventory/{{params.catalog_object_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "how many do we have left of this item", "check the stock on this product", "is this thing still in stock".

square.adjust_inventory

Change the stock count for a Square catalog item variation at a location, e.g. after a delivery or a stock take. Use when the user wants to restock, adjust, correct, or write off inventory. Moves a quantity from one state to another, such as received stock to in stock.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /inventory/changes/batch-create.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "restock this item after the delivery came in", "correct the count, we did a stock take", "write off some damaged stock", "update how much of this we have on hand".

square.batch_get_inventory_counts

Get stock counts for several Square catalog item variations at once, optionally filtered to specific locations. Use when the user wants a stock report or wants to check several products' inventory together. For a single item, use get_inventory_count.

Class read (reads only). No scopes beyond the connection's defaults. Calls POST /inventory/counts/batch-retrieve.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "give me a stock report across several products", "check inventory on a bunch of items at once", "what's on hand for these products together".