> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Shopify troubleshooting

> Debug Shopify connection errors, missing orders, search relevance, and inbox metadata issues.

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.

<Tip>
  Go to [**Settings → Integrations**](https://platform.open.cx/settings/integrations) → Shopify as your first step. If the connection is not listed or shows an error, re-enter your credentials.
</Tip>

## Common scenarios

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

### **Connection fails on save**

<Tooltip tip="Usually caused by the wrong domain format, a token that was already revealed and lost, or missing scopes on the custom app.">Likely cause</Tooltip>: 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**

<Tooltip tip="The two most common causes are auto-archival hiding the order from the API, or the customer's email not matching the email on the order.">Likely cause</Tooltip>: 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**

<Tooltip tip="Product search uses Shopify's built-in keyword search. Results depend on how your product titles, descriptions, and tags are written.">Likely cause</Tooltip>: 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**

<Tooltip tip="The read_customers scope may be missing, the contact may not have an email, or no Shopify customer matches that email.">Likely cause</Tooltip>: 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 — `john@example.com` does not match `John@Example.com` 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**

<Tooltip tip="The initial sync may still be running, or the OAuth scopes don't cover the selected streams.">Likely cause</Tooltip>: sync incomplete or scope mismatch.

**Fix:**

* Open [**AI Training → Data Sources**](https://platform.open.cx/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**

<Tooltip tip="Without distinguishing information (like order number prefixes), the AI may pick the wrong store when multiple are connected.">Likely cause</Tooltip>: 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

|                                     | Value                                          |
| ----------------------------------- | ---------------------------------------------- |
| **Contact metadata cache**          | 1 minute                                       |
| **Orders loaded per customer**      | Up to 50 per store                             |
| **Knowledge Base initial sync**     | Minutes to an hour depending on content volume |
| **Knowledge Base incremental sync** | Scheduled (configurable per source)            |
| **Product search results**          | Capped to prevent noisy data in AI context     |

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Connect Store" icon="plug" href="/integrations/shopify/connect">
    Re-check credentials, scopes, and domain format.
  </Card>

  <Card title="AI Actions" icon="robot" href="/integrations/shopify/ai-actions">
    Confirm the right actions are enabled.
  </Card>

  <Card title="Knowledge Base Sync" icon="book" href="/knowledge/sources/shopify/connect">
    Re-check OAuth credentials and stream selection.
  </Card>

  <Card title="Handoff settings" icon="user-group" href="/handoff/introduction">
    Global handoff rules and office hours.
  </Card>
</CardGroup>