Troubleshooting

This page covers the most common issues encountered after installing ReturnShield AI and how to resolve each one. For each issue, start with the diagnostic steps before attempting fixes.

Dashboard Shows No Data After Installation

The initial data sync imports 90 days of order and return history, then runs the full AI analysis pipeline. This process can take up to 24 hours for stores with large order volumes.

Expected timeline:

• Small stores (under 1,000 orders): 1–4 hours
• Medium stores (1,000–10,000 orders): 4–12 hours
• Large stores (10,000+ orders): 12–24 hours

Check sync status:

1. Go to Settings → Data Sync
2. Look for the sync progress bar and estimated completion time
3. The dashboard shows incremental data as it processes — return rate metrics typically appear before product-level risk scores

If sync progress has not moved in 4+ hours:

1. Click "Restart sync" in the Data Sync settings
2. Wait 30 minutes and check again
3. If still stuck, contact support — your store may require a manual sync trigger

Minimum data requirement: The dashboard requires at least 30 completed returns (refunded and returned in Shopify) before showing meaningful metrics. Stores with fewer returns will see a "Not enough data" message until more history accumulates.

Product Risk Scores Are Not Updating

Product risk scores recalculate nightly using the previous day's return data.

If a score has not changed after 48 hours following a high-return event:

1. Confirm the return was fully processed in Shopify — the order must be marked as refunded AND the return marked as received. Pending return requests and approved-but-not-yet-processed returns are not included in calculations.

2. Check Settings → Data Sync for any sync errors or failed jobs. A red error indicator means the last sync encountered a problem.

3. Trigger a manual recalculation: Settings → Data Sync → Recalculate Scores. This forces an out-of-schedule recalculation for all products.

4. If the product is new (added in the last 7 days), risk scores require a minimum of 5 returns before a score is assigned. New products show "Insufficient data" until this threshold is reached.

Action Queue Is Empty

An empty queue means one of the following:

| Cause | How to confirm | Fix | |---|---|---| | Not enough returns per product | Check product detail — is "data points" under 5 for all products? | Wait for more returns to accumulate | | All items reviewed | Check the Applied and Rejected tabs | No action needed — all suggestions have been acted on | | Plan limitation | Free plan users see this | Upgrade to Starter or higher | | Initial sync still running | Check Settings → Data Sync | Wait for sync to complete |

For stores with returns but an empty queue: The AI requires at least 5 returns for a specific product that share a common complaint before generating a fix. If your returns are spread across many products with 1–2 each, the queue may remain sparse. As volume grows and patterns emerge, fixes are generated automatically.

Shopify Flow Triggers Are Not Firing

Common Shopify error messages and what they mean:

• Trigger payload missing required field — ReturnShield sent a trigger but Flow could not parse the payload. This is usually a version mismatch. Check the changelog for the version that introduced this trigger and confirm you are on that version or later.
• Workflow is inactive — The workflow exists but was paused or left in draft status. Open Flow and activate it.
• Condition not met — The trigger fired but the workflow's condition was not satisfied. This is not an error — it means the trigger worked but filtered out this particular order.
• Action timed out — The Shopify Flow action (e.g., "Add Order Tag") timed out. Usually a transient Shopify API issue. Flow retries automatically.

Diagnostic checklist:

1. Check app permissions: Go to Shopify Admin → Apps → ReturnShield AI → App permissions and confirm the app has Shopify Flow permissions listed. If missing, uninstall and reinstall — Shopify will prompt you to re-authorize all permissions.

2. Check Flow workflow status: Go to Apps → Flow, find the ReturnShield workflow, and confirm it shows Active status. A paused or draft workflow receives no trigger events.

3. Check the trigger threshold: The "High-Risk Order Placed" trigger fires only when a customer's risk score exceeds your configured threshold. If no customers have been scored above that level yet, the trigger will never fire. Temporarily lower the threshold to confirm the trigger mechanism is working.

4. Review Flow run history: In Shopify Flow, open the workflow and check the Run history tab. Each run shows whether it succeeded, was skipped (condition not met), or encountered an error.

5. Confirm Growth plan: Shopify Flow integration is not available on Free or Starter plans. If you recently downgraded, Flow triggers will silently stop.

Fraud Detection Not Flagging Expected Orders

If an order you expected to be flagged was not:

1. Customer history threshold: Customers with fewer than 3 total orders are not scored for fraud risk regardless of their early return behavior. New customers score as Standard by default.

2. Bracketing alert threshold: The default is 3 or more variants of the same product. An order with 2 variants does not trigger the alert. Lower the threshold under Settings → Fraud → Bracketing if you want to catch 2-variant orders.

3. Flow workflow status: Even if the fraud signal fires, the Shopify Flow workflow listening to it must be Active to execute. A paused workflow silently discards trigger events.

4. Segment not elevated yet: The fraud signal alert fires when combined with an At Risk or Serial Returner segment. A Standard customer placing a bracketed order does not trigger the full alert by default. Adjust the segment filter in your workflow if you want to catch all bracketing regardless of customer tier.

Sizing Widget Is Not Appearing on Product Pages

Checklist in order:

1. Widget is enabled: Go to Settings → Widget and confirm the toggle is on.

2. Minimum purchase count: The widget requires at least 10 customers to have purchased a specific size AND at least 80% of those customers to have kept the item (not returned). Low-volume products or new size introductions will not show the widget until these thresholds are met.

3. Product page metafield rendering: The widget uses Shopify product metafields. If you are using a heavily customized product template that does not render standard metafields in the expected location, the widget injection point may not exist. Open your product page source and confirm standard Shopify product metafield components are rendered below the size selector.

4. Theme version: The widget uses Shopify's customer account extension API. Very old themes (pre-2021) may not support this API. Contact support if you believe a theme compatibility issue is preventing display.

"How's it Fit?" Email Is Not Sending

Check each of the following in sequence:

1. Email is enabled: Go to Settings → Post-Purchase Emails → "How's it Fit?" and confirm the toggle is on.

2. Send delay timing: If you set a 7-day delay, orders placed in the last 7 days have not yet triggered the email. The email will send on schedule.

3. Delivery date set in Shopify: The email sends relative to the carrier delivery date recorded in Shopify. If your carrier does not push delivery confirmations to Shopify, the delivery date is never set and the email is never triggered.

   • To diagnose: Open a recent order in Shopify and check the Timeline — does it show a "Delivered" event?
   • To fix: If delivery updates are not flowing, switch the trigger basis to "days from fulfillment date" under the email settings.

4. Shopify transactional email limits: Shopify imposes rate limits on transactional emails for high-volume stores. If your store processes thousands of orders per day and your email delivery rate is low, check your Shopify transactional email send logs.

Return Rate Metrics Do Not Match My Shopify Reports

ReturnShield and Shopify calculate return rates differently. This is intentional:

| System | What it counts | |---|---| | Shopify native | All return requests, including pending, denied, and expired requests | | ReturnShield | Only completed returns — orders where a refund was issued AND the item was marked as returned/received |

ReturnShield's rate will typically be lower and more accurately reflects your actual cost exposure. If you want to audit the difference:

1. Export your Shopify native return report for a specific period
2. Export ReturnShield's product risk table for the same period
3. The gap represents return requests that were denied, cancelled, or not yet processed

Why this approach: An approved return request that was never received (the customer kept the item and got a refund anyway through a chargeback, for example) would inflate your operational cost numbers. ReturnShield focuses on completed cost events.

App Conflicts

ReturnShield writes to two locations in Shopify: product descriptions (via write_products) and customer metafields (via write_customers metafields). Conflicts are possible with other apps that touch the same data.

Conflicts with Other Return Apps

If you have a returns management app (Loop Returns, AfterShip Returns, Return Prime) installed alongside ReturnShield:

• Return data: ReturnShield reads completed refund and return data from Shopify. Third-party return apps write this data back to Shopify via the same API. There is no write conflict — ReturnShield reads, it does not write to return records.
• Customer metafields: If another app writes to returnshield.risk_tier (unlikely — this namespace is proprietary), data could be overwritten. Check your other apps' metafield namespaces under Shopify Admin → Settings → Custom Data.
• Product descriptions: If another app also auto-updates product descriptions (e.g., an AI description generator), both apps may overwrite each other's changes. Disable auto-apply in ReturnShield's Action Queue and review fixes manually to prevent conflicts.

Conflicts with Review Apps

Apps that inject review content into product descriptions (rare, but possible in some older integrations) can interfere with ReturnShield's word-level diff calculation. If your Action Queue diffs show unusual content in the "current description" that does not match what you see in the Shopify product editor, a review app may be appending content dynamically. Contact support to enable a "clean diff" mode that strips known review app signatures before diff calculation.

Conflicts with Translation Apps

If you use a translation app (Langify, Weglot, Translate & Adapt), product descriptions may exist in multiple language versions. ReturnShield reads and writes the default (primary) language version. Translations of modified descriptions are not updated automatically. After applying a fix from the Action Queue, manually update the translated versions in your translation app.

Dashboard Loads Slowly

ReturnShield's dashboard is data-intensive. If it is loading slowly:

1. Check your date range filter: The default 90-day range processes all orders and returns in that window. Narrowing to 30 days dramatically reduces load time. Once data has loaded, expand back to 90 days.

2. Product count: Stores with 1,000+ active products with return data take longer to render the product risk table. The initial render loads the top 50 products by risk score — scrolling loads more.

3. Browser caching: ReturnShield caches dashboard data client-side for up to 15 minutes. Hard-refresh (Cmd+Shift+R / Ctrl+Shift+R) if you suspect stale data.

4. Night vs. day: The nightly recalculation runs between 00:00–04:00 in your store's timezone. Dashboard queries during this window may be slower than usual.

5. Contact support: If the dashboard consistently takes more than 10 seconds to load outside of nightly processing hours, share your Shopify store URL with support — they can check for data index issues specific to your store.

API Rate Limit Errors After Installation

ReturnShield uses Shopify's GraphQL Admin API to sync data. Large stores occasionally trigger rate limits during the initial 90-day import.

Symptoms: Initial sync progress stalls at a specific percentage. Error message in Settings → Data Sync: "API rate limit exceeded — retrying."

What to do: ReturnShield automatically retries on rate limit errors with exponential backoff. In most cases, the sync completes within a few extra hours. If the sync has been stalled for more than 8 hours with a rate limit error, contact support for a manual sync optimization.

Customer Segment Is Wrong for a Specific Customer

If you believe a customer has been placed in the wrong segment:

1. Open Customers → Segments and search for the customer
2. Click the customer to open their detail view
3. Review the risk score breakdown — which signals are elevated?
4. Check their order and return history for accuracy — are there returns in Shopify that should not be counted, or vice versa?

If the data in ReturnShield matches what is in Shopify but the segment still seems wrong, the segment thresholds may not be calibrated for your store's profile. Adjust thresholds under Settings → Customer Segments.

To manually override a segment for a specific customer (e.g., a business account that legitimately orders in bulk): contact support — manual overrides are available on Growth and Scale plans.

Getting Further Help

If none of the above resolves your issue:

1. Note your Shopify plan, date of installation, and approximate store order volume
2. Take a screenshot of the issue and any error messages visible in the app
3. Copy the error text from Settings → Data Sync if a sync error is shown
4. Contact support at plugkit.io/support — include your store URL, the issue description, and any screenshots

Response times:

• Scale plan: same business day
• Growth plan: next business day
• Starter plan: within 2 business days
• Free plan: community forum only

Next Steps

• Changelog — check if your issue was addressed in a recent update
• Configuration — review alert thresholds and sync settings
• Shopify Flow — diagnose Flow-specific trigger and action issues