Reference

Troubleshooting common issues

The handful of problems that come up most often after install, and how to fix each one.

Last updated

Most issues with OrderWise after install fall into one of five categories. This page is a fast-path guide for each.

"The widget isn't showing on my storefront"

Three things to check, in order:

  1. Widget mode. Settings → Widget → Live mode. If it's still in "preview only", anonymous visitors won't see it.
  2. Theme app block placement. Open the theme editor, navigate to a storefront page, and confirm the OrderWise block is present in the theme tree. Some themes hide the block under "App embeds" rather than in a section.
  3. CSP / cookie consent. If the merchant's theme uses a strict Content Security Policy or a cookie banner that blocks third-party scripts until consent is given, the widget won't load until the visitor accepts. This is intentional and GDPR-correct.

"The AI is asking for the order number"

This usually means OrderWise can't identify the customer. Check:

  1. The widget loads with the customer logged in. The order lookup needs the customer ID, which only exists in a logged-in session.
  2. The OAuth scopes include read_customers and read_orders. Settings → Diagnostics → Scopes will flag missing scopes.
  3. The 90-day backfill job completed. New installs need 1-3 minutes for the backfill before order context is available — Settings → Diagnostics → Backfill shows the status.

"AI replies in the wrong language"

The AI tries three sources for the customer's language, in order:

  1. The Shopify.locale value from the storefront context.
  2. The Accept-Language header on the customer's request.
  3. Auto-detection on the customer's first message.

If the storefront is shipping the wrong locale (common with custom themes), force a specific locale per knowledge-base entry by adding the locale tag to the entry frontmatter.

"Auto-execution rule isn't firing"

The rules engine logs every decision under Settings → Rules → Log. A rule that should fire but doesn't typically falls into one of three buckets:

  • Confidence under threshold. The AI's confidence score is below 0.8 (or whatever you've set). Surface the conversation, look at the confidence value, and either lower the threshold or improve the knowledge-base entry the AI was reaching for.
  • Cap exceeded. The refund or cancel cap blocked the action. Check the cap under Settings → Rules → Caps.
  • Webhook not received. The rule depends on an event (e.g., "order_created") that hasn't been received yet. Confirm via Settings → Diagnostics → Webhooks.

"Embedded admin is blank or stuck loading"

Almost always a Shopify session-token issue. Two fixes:

  1. Open the embedded app from inside Shopify admin (not from a direct URL). The session token needs to be issued by Shopify.
  2. If the session token is present but the app still loads blank, check the browser console for CSP violations. The headers in next.config set frame-ancestors to admin.shopify.com and *.myshopify.com — a custom Shopify Plus install on a different domain will need that header extended.

If none of these match the issue, support is at hello@orderwise.dev with a screenshot and your shop domain.