Troubleshooting

Before debugging, have this ready:

• Your Shopify *.myshopify.com domain.
• The scopes you configured on the custom app (read_orders, read_products, read_customers).
• A specific order number or customer email where the problem shows.

​

Common scenarios

Jump to the symptom that matches what you’re seeing.

​

Connection fails on save

Likely cause: wrong domain format or invalid token. Fix:

• Use the *.myshopify.com domain, not your custom storefront domain (e.g. example.myshopify.com, not www.example.com).
• If you already revealed the token and lost it, go to your Shopify admin, uninstall the custom app, reinstall it, and reveal a new token.
• Confirm the app has read_orders, read_products, and read_customers scopes enabled. OpenCX checks scopes on save and rejects the connection if any are missing.

​

AI doesn’t return order details

Likely cause: order is archived or email mismatch. Fix:

• Auto-archival: in your Shopify admin, go to Settings → General → Order processing and confirm Automatically archive the order is unchecked. Archived orders are not returned by the Shopify API. If you recently disabled auto-archival, previously archived orders remain archived — you need to unarchive them manually in Shopify.
• Email mismatch: the AI verifies the customer’s email against the order before revealing details. If the contact in OpenCX has a different email than the one on the Shopify order, the lookup is rejected. Confirm the contact’s email matches.
• Order number format: the customer must provide the order number as it appears in Shopify (e.g. #1042 or 1042). Custom prefixes like UK-1042 work if that is the order name in Shopify.

​

Product search returns irrelevant results

Likely cause: keyword mismatch between the customer’s question and your product data. Fix:

• The AI searches your catalog using Shopify’s native keyword search. If products have generic titles or sparse descriptions, searches for specific attributes (color, material, size) may not match.
• Improve product titles and descriptions in Shopify to include the terms customers actually use.
• Results are sorted by relevance and capped to avoid overwhelming the AI with data. If a product ranks outside the top results, it may not appear.

​

Customer metadata not showing in the inbox sidebar

Likely cause: missing scope or no email match. Fix:

• Confirm the custom app has the read_customers scope. Without it, metadata enrichment is disabled entirely.
• Confirm the contact in OpenCX has an email address set.
• Confirm a customer with that exact email exists in your Shopify store. The match is exact — [email protected] does not match [email protected] if Shopify stored it differently.
• If you recently connected the store, try refreshing the inbox page. Metadata loads on sidebar open.

​

Knowledge base content not appearing in AI answers

Likely cause: sync incomplete or scope mismatch. Fix:

• Open AI Training → Data Sources and check the Shopify source status. If it shows Syncing, wait for it to complete.
• Verify that the custom app used for Knowledge Sync has the scopes matching your selected streams: read_online_store_pages for pages, read_content for articles, read_products for products.
• If scopes were missing, update them in the Shopify admin, then disconnect and reconnect the source in OpenCX.

​

Multi-store: AI looks up the wrong store

Likely cause: no clear signal for the AI to distinguish stores. Fix:

• Use order number prefixes per store (e.g. UK-, DE-, NL-) so the AI can route by the prefix. Configure in Shopify admin under Settings → General → Order processing.
• Train the AI with store-specific instructions that explain which store serves which region or product line.
• Confirm each store has a distinct *.myshopify.com domain configured in OpenCX — duplicate domains will cause conflicts.

​

None of the above

If your issue isn’t listed here, contact support with:

• Your OpenCX organization name.
• The Shopify domain(s) involved.
• A specific session ID or order number where the problem occurred.
• Screenshots of any error messages.

​

Limits and timing

---

​

Related Documentation