Troubleshooting and FAQ
| What you see | What to do |
|---|---|
| "AI connections are available on paid plans" on the Joy approval screen | Upgrade to any paid plan, then connect again. |
| A plan or upgrade error when asking a question | Your plan doesn't include the API (for example after a downgrade). Upgrade, then ask again. |
| "That doesn't look like a Shopify store domain" | Enter your .myshopify.com domain, not your custom domain. |
| "Rate limited" or "daily quota exceeded" | You've reached your plan's request limit. Wait a few seconds, or until midnight UTC for the daily limit. Narrow questions, like one member by email, use fewer requests. |
| The connector fails right after you approve (some tools show "no key provisioned") | Disconnect the app in AI connections and connect it again. Joy sets up the key when you approve. |
A ?store= connector fails right after you approve (some tools show "This connector URL is labelled for … but the authorized token belongs to …") | You entered a different store on the Joy page than the one in the URL. Remove the connector, add it again, and enter the domain from its URL. |
| The assistant can't make a change you asked for | Check which access the change needs. Member changes (points, tiers, rewards, loyalty page) need Full access: disconnect and reconnect with it, or on the local server use your secret key and set JOY_MCP_ENABLE_WRITES to "true". Program and widget settings need settings changes on the local server. |
| "Analytics aren't available yet" | Your store is on the previous Joy Analytics. On a Full access connection, ask the assistant to switch you to the new analytics, or switch in Joy → Analytics. Importing history takes a few minutes to a few tens of minutes. |
| Spend by tier fails with a metafield message | Turn on the VIP tier metafield in Joy → Settings → General → Metafield, then ask again. |
| A Shopify reports permission error on revenue questions | Revenue reports read Shopify's sales data. In Joy, open Analytics and select Enable insights on the reports banner, then ask again. |
| "Points expiring" finds nobody | This check covers points that expire individually. If all your points expire on one date, check that date in your Joy settings. |
| The connector was added but there are no Joy tools | Fully quit and reopen your AI tool. In ChatGPT, also pick Joy Loyalty with @ in the chat. |
| The app isn't listed under AI connections | You unticked Remember this and skip this screen next time when approving. Connect again with it ticked. |
| Local: "not a valid MCP server configuration" | Put quotes around "true" in JOY_MCP_ENABLE_WRITES and JOY_MCP_ENABLE_CONFIG_WRITES, then restart. |
| Local: the server won't start | Run node --version — it must be 20 or later. Check that JOY_APP_KEY and JOY_SECRET_KEY are both set and JOY_API_BASE_URL is unset. |
| Local: "Authentication failed" | JOY_APP_KEY isn't your App ID, or the key was regenerated. Copy both again from Manage keys and restart. |
| Local: "not permitted with the current credential" | You turned on JOY_MCP_ENABLE_WRITES with a read-only (ro_) key. Use your secret key, then restart. |
FAQ
Which AI tools are supported? With sign-in: Claude (web, desktop, mobile), ChatGPT, Claude Code, Cursor and Codex. With an API key: any MCP client that can run a local server, including Claude Desktop, Claude Code, Cursor, Codex and VS Code / GitHub Copilot.
Which plan do I need? Any paid Joy plan. Higher plans allow more requests.
Do I need to install anything?
Not with sign-in. The local server needs Node.js 20 or later; npx runs it without a
permanent install.
Can I connect more than one AI tool? Yes. Each AI tool is listed and disconnected separately, with its own access level. People who connect the same tool to the same store share one entry.
Can I connect more than one store? Yes — one connection per store. See Connect more than one store.
Will the assistant change anything without asking? Not on a read-only connection — it can't. On Full access, most AI tools ask before running a change unless you've set them to always allow it. Large deductions, balance corrections and settings changes preview first. Loyalty page text changes go live with no preview.
Can the assistant see my customers' personal data? Yes. When it looks up a member, Joy returns that member's details, which can include name, email, phone, birthday, spending, points and tier, even if you asked about only one of them. That data goes to your AI tool's provider, so treat it like any other app you connect to your store data.
Are the numbers the same as my dashboard? Analytics answers use the same data as the Analytics page in Joy, so compare the same dates and filters. Revenue answers use Shopify's own sales data, which can differ from Joy's loyalty-assisted revenue, and the assistant says which source a number comes from.
What happens when I disconnect? The app loses access within 5 minutes. Disconnecting doesn't undo earlier changes. Point and tier changes stay in your activity log; settings and design changes aren't logged there, so keep the conversation if you may need to trace them.
Does it work on a development store? Yes, as long as the store is on a paid Joy plan.