Skip to main content
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.
1

Browser: authorize Square

Open https://auth.heylua.ai/square/auth, sign in to Square, and pick the business if asked.
Square business selection

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 permissions screen

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.
Lua admin dashboard after connecting Square

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.

​
What the agent can do

  • 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.

​
Raw API access

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.

​
Limits

  • 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.
Square App Integrations with Lua listed

Disconnecting Lua under App Integrations in the Square Dashboard.

​
If it isn’t working

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.
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.
Disconnect Lua under App Integrations in the Square Dashboard, start the authorization again, and pick the other business when asked.

​
Next steps

Square Appointments

Services, staff, availability, and bookings from the same authorization.

Channels

Sell on WhatsApp, Instagram, and Messenger with the same agent.

About the persona

Shape how the agent recommends and sells.

Call your API

A tool for Square endpoints the agent doesn’t have.