Authorize your Square account so the agent can search the catalog, look up orders, and create Square-hosted payment links
Authorizing Square creates an agent that reads your Square catalog live, looks up a customer’s orders, previews order pricing, and creates Square-hosted checkout links, on the web widget and every other channel. Square is connected in the browser, not with lua integrations, and the same authorization also enables the appointments tools.Verified against lua-cli 3.33.0.Before you begin
A Square account with the business you want to connect; if it has several businesses you choose one during authorization.
An email Lua can link your admin account to: the merchant owner’s email, else the main location’s business email, else the first team member marked as owner.
Choosing the business when the Square account has more than one.
Review the permissions and select Allow. Lua requests items (read), orders (read and write), payments (write), customers (read and write), appointments and appointment settings (read and write), team members (read), and the merchant profile (read).
Square's permission screen for Lua.
2
Admin dashboard: finish setup
Square redirects to the admin dashboard, where the agent and its organization exist already and a persona is being drafted from your business details. Refine the persona and connect channels from there.
The admin dashboard after a successful Square authorization.
3
Try it
On the web widget or a connected channel, ask “Do you have a medium blue sundress?”. The agent searches the catalog and, on request, previews the order and creates a payment link.
Search catalog items by text, category, and product type (regular items, services, food and beverage, events, digital goods, donations); search catalog objects of any type; retrieve one object by ID.
Create the Square customer for the end user, or return the existing one, and read it back.
List the seller’s locations and retrieve one.
Search a customer’s orders by state, date range, fulfillment type, and fulfillment state; retrieve orders by ID; preview an order’s pricing without creating it.
Create a Square-hosted checkout link for an order, and read the merchant’s and a location’s checkout settings (accepted payment methods, tipping, policies).
Catalog, orders, and customers are read from Square on every call. Nothing is synced, so Products and Baskets stay empty for a Square agent, and inventory counts aren’t read: keep sold-out items out of the catalog, or mark them in the item name.
Square isn’t a Unified.to integration type, so there is no Integrations.passthrough('square', …). For endpoints the tools don’t cover, write a tool that calls Square’s API with your own access token from env() (see Call your API). To add your own tools to this agent, run lua init --agent-id <id> in a new folder (find the ID with lua agents --json --ci), then follow Add a tool.
One Square account (merchant) per agent; every location of that account is reachable. For an agent per location, create separate agents and authorize each.
Lua refreshes the Square access token itself. Revoking the app in Square (Settings › App Integrations › Lua › Disconnect App) stops the agent’s access; repeating the authorization reconnects it.
Disconnecting Lua under App Integrations in the Square Dashboard.
The business wasn’t selected, a permission was declined, or Square couldn’t provide an email to link (owner, main location, or an owner team member). Fix the account in Square and start again at auth.heylua.ai/square/auth.
The agent can't find an item
Search matches item and variation names within the product types it was asked for, live from Square. Give the item a descriptive name and try the exact name; there is no sync to wait for.
The wrong business is connected
Disconnect Lua under App Integrations in the Square Dashboard, start the authorization again, and pick the other business when asked.
