Troubleshooting
Each problem below lists what you see, why it happens and how to fix it. The messages are the ones Falcon shows. If your problem isn't here, see Contact support.
An order or item can't be returned
On the return page, items that can't be returned are listed with a reason. Staff see the same reason as a badge in Create a return.
| Reason shown | Why | What to do |
|---|---|---|
| Unpaid order | The order isn't paid. | Wait until the order is paid. |
| Order has been refunded at Shopify | The order, or this item, was already refunded in Shopify. | Nothing to return. Check the order in Shopify. |
| Does not comply with the return policy | The order matches a block, for example a blocked email or country. | Check Block list. |
| Exchange item | The item was sent as part of an exchange. | Falcon doesn't take returns of exchange items, including in Create a return. Handle it in Shopify admin if you want to allow it. |
| Unfulfilled | The item hasn't been shipped yet. | Wait until it is fulfilled. |
| Missed the return window | The return window has closed. | Change the window in Return policy, or create the return yourself. Create a return ignores the window. |
| Non-returnable items | The item matches a block, such as a blocked collection or discounted items. | Check Block list. |
| Return app processed item | Every unit of this item is already in a return, including returns made in Shopify admin. | Open the existing return under Returns. |
A customer can't sign in to the return page
| What the customer sees | Why | What to do |
|---|---|---|
| "Please enter a valid order number and email address" (or "… phone number") | The order number and email or phone don't match the same order. | Ask them to use the email or phone on the order, exactly as entered at checkout. |
| "Too many attempts. Please wait a few minutes and try again." / "Too many codes requested. Please wait a few minutes." | Too many tries, or too many codes asked for, in a short time. | Wait a few minutes. |
| "Please request a verification code first." / "Too many wrong codes. Please request a new one." | Email code sign-in: no code was sent yet, or the code was typed wrong too often. | Request a new code. Codes expire in 10 minutes. |
| "Please confirm your email with the store, or find your order below." | Signed in with a store account whose email isn't verified. | They can use the order number form instead. |
| "Your session has expired. Please sign in again." | The return session timed out. | Sign in again. |
| "The return center is not available right now." | Falcon can't reach your store, for example after the app was removed. | Check that Falcon is installed. If it is, contact support. |
The return page link doesn't work
Cause: the menu link points to the wrong address.
Fix: the return page lives at your store's address followed by /apps/falcon-returns. Check the address on Falcon's Return page screen and update your menu. See Add the return link.
New returns are paused
What you see: customers get "We can't accept new return requests online right now. Please contact the store." Create a return in Falcon says "You've used all the returns in your plan for this period. Upgrade in Plan and billing to create more."
Cause: your plan's returns for this period are used up. On monthly paid plans this happens after the extra returns too.
Fix:
- Open Plan and billing to see your usage and when it Resets.
- Upgrade, or wait for the reset.
- Returns you create in Shopify admin are never blocked, so you can use that meanwhile.
See Plans and billing.
A prepaid label wasn't created
| Message | Fix |
|---|---|
| "International return labels aren't supported yet. Upload a label with Add tracking, or ask the customer to ship it themselves." | Upload your own label with Add tracking. |
| "Every rate for this return is above your limit of …" | Raise the spending limit in Settings → Carriers and labels, or upload a label with Add tracking. |
| "Shippo quotes this return in …, but your spending limit is in …" | Turn the spending limit off or contact support, and upload a label with Add tracking for now. |
| "Shippo didn't accept this API key. Check that it's copied in full." | Copy the full key from Shippo and connect again. |
| "The Shippo connection couldn't be opened. Reconnect it in Settings → Carriers and labels." | Reconnect Shippo. |
| "Couldn't reach Shippo. Try again in a minute." / "Shippo is not responding. Try again in a minute." | Wait a minute and try again. |
| "We couldn't confirm with Shippo whether the label was created…" or "This took too long. Check again: we look up the label first." | Click Check again after a few minutes. Falcon looks for the earlier label first and only buys a new one if there is none. |
| "This address is missing a street or city" / "This address needs a 2-letter country code" | Fix the address in Settings → Return addresses. |
Don't buy twice
If a purchase was unclear, wait and use Check again instead of buying a label in Shippo by hand. Falcon is built to avoid paying for two labels for the same return.
See Shippo and Carriers and labels.
Customers aren't getting emails
Check these in order:
- Is the email switched on? Open Settings → Email notifications and make sure that email is on.
- Is the address real? Falcon doesn't send to test addresses, such as those at
example.com,example.orgorexample.net, or ending in.test,.invalid,.exampleor.localhost. - Own mailbox? If you connected your own mailbox, send a test email from the same page. Gmail needs an app password; your normal password won't work. Microsoft 365 needs SMTP sending allowed for the mailbox (Authenticated SMTP).
- Spam folder. Ask the customer to check spam or promotions.
See Email notifications and Use your own mailbox.
Auto-approve didn't run
| Cause | Fix |
|---|---|
| Your plan doesn't include auto-approve. The page shows Automation workflows are paused on your plan. | Upgrade to Starter or higher. |
| The workflow is turned off. | Turn it on in Settings → Automations. |
| The request doesn't match every condition. With a reason condition, every item's reason must be in the list. The value condition counts refund plus exchange value. | Check the conditions. |
| The request was created by staff. Auto-approve runs on requests submitted on the return page. | Approve it by hand. |
| The approval failed in Shopify. | The return stays Pending review and the timeline shows "Workflow … could not approve this request: …". Fix the cause and approve by hand. |
Only the topmost matching workflow runs. See Auto-approve.
Auto-refund or auto-exchange didn't run
- It needs the Growth or Pro plan.
- It runs when items are marked received on an approved return, by staff in Falcon or by an AI agent. The workflow must be on and match the return.
- If Shopify refuses, the timeline shows "Workflow … could not refund: …" or "could not create the exchange", and the return stays for you to resolve by hand.
See Auto-refund.
Webhooks aren't arriving
- Look under the URL on the Webhooks tab for "Last delivery failed: …".
- Your endpoint must be public https, answer with 2xx within 5 seconds, and not redirect.
- Check the webhook is switched on and its Condition matches the request.
- Webhooks need the Pro plan.
See Webhooks.
An AI agent can't connect or act
| Message | Fix |
|---|---|
| "This Falcon key or sign-in is expired or revoked." | Create a new key, or connect the AI app again. |
| "This agent is read-only…" / "This agent cannot issue refunds…" | Disconnect it and connect again with more access. |
| "Refund access is only available for AI apps Falcon recognises." | Use a lower access level, or connect a recognised app. |
| "This sign-in link expired. Go back to your AI app and connect Falcon again." | Start the connection again from the AI app. |
| "Too many calls…" / "Too many changes…" / "Refund limit reached…" | Wait, or finish the rest in Falcon. |
See AI agents.
Plan change didn't go through
"Shopify couldn't start the plan change. Your current plan is unchanged. Try again in a moment." Wait a moment and try again. If the plan looks wrong, reload Plan and billing after a minute.