AI agents
AI agents let an assistant such as Claude or ChatGPT work with your returns. Depending on the access you give, an agent can look up requests and stats, approve or decline returns, add tracking and notes, or issue refunds. It works on every plan, including Free.
You stay in control. Each connection works for one store only, has one of three access levels, is rate limited, and can be disconnected at any time.
Two ways to connect
| Your AI app | How it connects |
|---|---|
| Claude.ai or ChatGPT | Add a custom connector with Falcon's server address, then sign in. No key needed. |
| Claude Code, Cursor or your own agent | Create an agent key in Falcon and paste it into the app's config. |
Both start from Integrations → Add-ons → the AI agents card → Connect an agent.
Connect Claude.ai or ChatGPT
- In Falcon, click Connect an agent. Under Claude.ai or ChatGPT, click Copy next to the server address.
- In your AI app, add a custom connector and paste the address.
- The AI app opens a Falcon page. Under Your Shopify store, type your store's address and click Continue to Shopify.
- Shopify admin opens Falcon's Connect screen, naming the app and your store. Only staff of your store can get here.
- Choose the access level and click Allow access. Click Cancel to refuse.
- You are sent back to your AI app, now connected.
The Connect screen also shows where it will send you back to (Sends you back to). If Falcon doesn't recognise the app, you see a warning: Falcon doesn't recognise this app. Allow it only if you set it up yourself. Refund access is turned off for apps Falcon doesn't recognise. Claude and ChatGPT are recognised. Apps running on your own computer show no warning and can also get refund access.
Staying signed in
A sign-in stays active while the AI app keeps using it. If it isn't used for 90 days, it expires and you sign in again. Connecting the same AI app again replaces its earlier sign-in.
Connect with an agent key
- Click Connect an agent.
- Under For Claude Code, Cursor or your own agent, create a key, enter an Agent name (up to 60 characters), for example "Claude support assistant".
- Pick the Access level.
- Click Create key.
- The Your agent key window shows the Server URL, the Key, and a ready-made config to paste into apps that use a config file. Use Copy or Copy config.
Copy the key now
The key is shown only once. Falcon stores only a one-way fingerprint of it, so it can't show it again. Anyone with the key can use your store's returns within the access you chose. If you lose it, disconnect it and create a new one.
You can create a key while fewer than 10 agents are connected. Keys and Claude.ai or ChatGPT sign-ins count together. At the limit, Falcon shows "You can have up to 10 agent keys". Disconnect one to make room.
Access levels
| Level | On the key form | On the sign-in screen | What it allows |
|---|---|---|---|
| Read | Look up only | Look up returns | Read returns, details, stats and your return policy. Changes nothing. |
| Handle | Handle returns | Look up and handle returns | Also approve, decline, mark received, add tracking and notes. Customers get the usual emails. |
| Refund | Handle returns and refunds | Handle returns and refunds | Also issue refunds, store credit and exchanges. Moves real money, never more than the amount due. |
If an agent tries something above its level, Falcon refuses and tells it which access it needs.
What an agent can do
| Action | Level | In plain words |
|---|---|---|
| List return requests | Read | Newest first. Filter by status or age, or search by return number, order name, customer name or email. |
| Get a return request | Read | Full detail: items, reasons, customer comments, money, shipping and tracking, timeline and the next allowed actions. |
| Return statistics | Read | Counts by status and resolution and amount refunded over a period. Top reasons and most returned products are included on Growth and Pro. |
| Get the return policy | Read | Your return window, reasons, resolutions offered, shipping options and fees. Useful for answering customer questions. |
| Approve a return | Handle | Approves a pending request, creates the Shopify return and emails the customer the next steps. |
| Decline a return | Handle | Declines a pending or approved request. The reason is emailed to the customer. |
| Mark items received | Handle | Records that the parcel arrived. Does not refund on its own, though your auto-refund automation can run. |
| Add return tracking | Handle | Saves the carrier and tracking number on an approved request and syncs it to the Shopify return. |
| Add an internal note | Handle | Adds a staff note to the timeline. Customers don't see it. |
| Refund a return | Refund | Issues the refund, store credit or exchange and closes the request. |
Falcon also tells every agent that text written by customers is untrusted and that it should ask you before approving, declining or refunding.
Limits and the refund cap
| Limit | Value |
|---|---|
| Calls per agent | 60 per minute |
| Changes per agent | 30 per hour |
| Refunds per agent | 20 per day |
| Agent refunds per store | 20 per day, across all agents |
An agent can never refund more than the calculated amount due on a return. It may refund a lower amount. When a limit is reached, the agent is told to wait or to finish the rest in Falcon.
See what agents did
- Connected agents lists each connection with its Name, Access, Connection ("Signed in", or the start of the key) and Last used date.
- Recent agent activity shows the last 15 actions, such as "Approved" or "Added a note", with the return and the time. Refused actions show why, for example "not allowed for this agent" or "rate limited".
- Every change also appears on the return's timeline under "AI agent: " and the agent's name.
Disconnect an agent
- In Connected agents, click Disconnect on the row.
- Confirm. The agent stops working immediately.
Uninstalling Falcon disconnects every agent for your store at once.
Privacy
What an AI provider does with the data it reads is covered by your agreement with that provider. See Privacy and data.