Configuration

ReturnShield AI works with sensible defaults immediately after installation. This guide covers every configurable setting, what each one does, when to change it, and recommended configurations for stores of different sizes.

Settings Overview

All settings live under Apps → ReturnShield AI → Settings, organized into these sections:

| Section | What you configure | |---|---| | Action Queue | Auto-apply thresholds, priority weighting | | Alerts | Return spike triggers, serial returner notifications, bracketing detection | | Widget | Sizing social proof display settings and display text | | Post-Purchase Emails | Timing and content of follow-up emails | | Cost Assumptions | Per-return cost inputs for the True Cost Calculator | | Data | Retention policy, GDPR deletion, segment thresholds | | Integrations | Klaviyo, Omnisend, and other platform connections |

Action Queue Settings

Auto-Apply Threshold

By default, every Action Queue fix requires manual approval before being applied to your Shopify product listing. The auto-apply feature allows ReturnShield to apply fixes automatically when the AI's confidence exceeds a threshold you control.

Setting location: Settings → Action Queue → Auto-Apply

| Sub-setting | Description | Recommended starting value | |---|---|---| | Minimum confidence | Only auto-apply fixes above this confidence score | 92% | | Maximum monthly impact | Only auto-apply fixes with predicted savings below this value — larger changes go to manual review | $200/mo | | Notify on auto-apply | Email you each time a fix is applied automatically | Enabled | | Auto-apply categories | Restrict auto-apply to specific product categories | All (adjust as needed) |

How confidence scores work: The AI derives confidence from the volume and consistency of evidence. A fix with 20 return notes all mentioning the same issue scores higher than one with 6 notes showing mixed complaints. Fixes above 90% confidence have strong, consistent evidence — the AI found a clear signal. Fixes in the 70–85% range are often correct but may have a minor interpretation issue or imperfect wording.

Progression strategy: Start with manual review for the first four weeks. Once you have reviewed 25–30 fixes and found them accurate for your catalog, enable auto-apply at 92%+ with a $200/mo impact cap. After three months of consistent accuracy, consider lowering the confidence threshold to 85% to capture more automatic improvements.

Fix Priority Weighting

The Action Queue sort order is determined by a weighted score combining three factors. Adjust the weights to match your priorities.

| Factor | Default weight | Description | |---|---|---| | Expected savings | 40% | Predicted monthly cost reduction if the fix is applied, based on current return rate and average order value | | Confidence score | 35% | AI confidence that this specific change will reduce returns for this product | | Implementation effort | 25% | Inverse of complexity — simple one-sentence changes score higher than full rewrites |

Example: A fix with $800/mo expected savings, 78% confidence, and high effort scores differently from one with $200/mo expected savings, 96% confidence, and low effort. At default weights, the high-savings fix ranks first; with confidence boosted to 55%, the high-confidence fix ranks first.

When to adjust weights:

• Post-holiday season when return volume is high: boost Expected Savings to 55% to tackle the biggest cost items first
• After several inaccurate suggestions: boost Confidence Score to 50% to filter out weaker evidence
• When all fixes are time-consuming: boost Implementation Effort to 35% to surface quick wins

Alerts Configuration

Return Spike Alerts

Fires when a product's return rate exceeds its category benchmark by more than the configured multiplier. This is your early-warning system — it fires before a spike becomes a significant cost event, giving you a window to investigate before more orders ship.

Setting location: Settings → Alerts → Return Spikes

| Sub-setting | Default | Description | |---|---|---| | Spike multiplier | 1.5x | How far above benchmark triggers the alert | | Minimum order count | 20 | Ignore products with fewer recent orders (reduces noise from low-volume SKUs) | | Observation window | 14 days | Time window for calculating the spiked return rate | | Notification channels | Email + Shopify admin | Where to send the alert | | Cooldown period | 72 hours | Suppress repeat alerts for the same product within this window |

Multiplier guidance: 1.5x is sensitive but can generate noise for seasonal products. 2x is quieter but may miss gradual issues that never become dramatic spikes. For high-margin products where even a modest return rate increase is costly, use 1.2x.

Real-world scenario: Your Oxford shirt usually returns at 9%. During a new collection launch week, returns start mentioning "collar too stiff" — three notes become eight. At 14 days, the return rate has climbed to 16% (1.8x your benchmark). The alert fires. You review the last batch of notes, update the collar material description, and add a care note about fabric softening. The following two weeks, returns drop back to 10%.

Serial Returner Alerts

Fires the first time a customer crosses the Serial Returner threshold. This is a one-time event per customer (not recurring) unless the customer's return rate drops back below the threshold and then rises again.

Setting location: Settings → Alerts → Serial Returners

| Sub-setting | Description | |---|---| | Threshold | Return rate percentage that triggers Serial Returner classification (default: 40%) | | Minimum orders | Customer must have placed at least this many orders before being classified (default: 3) | | Notification | Admin email when new Serial Returner is identified |

Why minimum orders matters: A customer who places one order and returns it has a 100% return rate but is not a Serial Returner — they simply had a bad first experience. The three-order minimum ensures the pattern is established before the alert fires.

Bracketing Detection Alerts

Fires when an order contains multiple variants of the same product — a common pattern for customers planning to keep one size and return the rest.

Setting location: Settings → Fraud → Bracketing

| Sub-setting | Default | Description | |---|---|---| | Variant count threshold | 3 | Minimum variants in one order to trigger the alert | | Same-product definition | Product ID | Match on product ID (all sizes/colors count) or restrict to same-attribute variants | | Combine with customer tier | Off | Only alert when the bracketing customer is also At Risk or Serial Returner |

Practical note: Many legitimate customers buy two sizes because they genuinely do not know which fits — especially on first purchase from a new brand. The bracketing alert is most actionable when combined with the customer's segment. A Champion customer buying two sizes is likely just cautious; a Serial Returner doing so is more concerning.

Sizing Social Proof Widget

Enabling the Widget

1. Go to Settings → Widget
2. Toggle "Enable Sizing Widget" to on

The widget requires no theme changes. It reads from product metafields and injects itself using Shopify's native storefront API.

Widget Display Requirements

Before the widget appears for a given size, both conditions must be met:

| Requirement | Value | Notes | |---|---|---| | Minimum purchase count | 10 customers | Must have bought this exact size | | Minimum keep rate | 80% | At least 80% must have kept the item (not returned) |

If either threshold is not met, the widget is simply not shown for that size. There is no placeholder or "not enough data" message visible to customers.

Display Text Customization

The text string displayed in the widget supports these variables:

| Variable | Output | |---|---| | {kept_count} | Number of customers who kept this size | | {total_count} | Total buyers of this size | | {percentage} | Percentage who kept (rounded) | | {size} | The size label (S, M, 38, etc.) | | {product_name} | Full product name |

Default text: {percentage}% of customers kept size {size}.

Apparel example: {kept_count} out of {total_count} customers kept {product_name} in size {size}.

Footwear example: {percentage}% of customers found these true to size in {size}.

Tip: Keep the string under 60 characters to display cleanly on mobile without wrapping.

Post-Purchase Emails

"How's it Fit?" Email

Sends to customers after delivery to gather sizing and fit feedback proactively — before they initiate a return.

| Setting | Default | Recommendation | |---|---|---| | Enabled | Off | Enable explicitly when ready | | Send delay | 7 days after delivery | Reduce to 5 days for faster fashion with short decision windows | | Trigger basis | Carrier delivery date | Switch to "days from fulfillment" if carrier tracking updates unreliably | | Subject line | "How does your [Product Name] fit?" | Personalize to match your brand voice | | Minimum order value | $0 | Set a minimum if you want to exclude low-value orders |

Carrier delivery date dependency: This email sends based on the delivery date Shopify records from your carrier. If your shipping carrier does not provide tracking updates that Shopify can read, the delivery date will never be set and the email will not fire. Verify tracking integration under Shopify Admin → Settings → Shipping. If integration is unreliable, use "days from fulfillment date" as the trigger basis.

Post-Return Survey

Automatically sent after a return is processed in Shopify.

| Return reason | Survey branch | Questions | |---|---|---| | "Didn't fit" | Sizing branch | What size did you order? How did it compare to the description? Would you try a different size? | | "Not as described" | Description branch | What was different from the description? Which part of the listing was misleading? | | "Quality issue" | Quality branch | Where was the quality issue? How severe (minor/major)? | | "Changed my mind" | Preference branch | What influenced your decision to return? (Free text) | | No reason given | Generic branch | Brief free-text reason request |

Survey responses are matched to the product and order in ReturnShield's analysis pipeline. They receive 2x the weighting of return notes in the AI model because surveys are explicit feedback rather than incidental comments.

Cost Assumptions

The True Cost Calculator requires accurate per-unit inputs to produce reliable figures. Navigate to Settings → Cost Assumptions.

| Field | Description | How to calculate | |---|---|---| | Warehouse processing cost | Labor and overhead per return received | Total monthly warehouse staff time on returns ÷ monthly return count | | Return shipping cost | Your net cost per return label | Average label cost after any carrier discounts | | Restocking loss rate | Percentage of returned items that cannot be resold at full price | Track over 3 months: (items discounted or written off) ÷ (total items returned) | | Average restocking discount | Markdown applied to items resold below full price | Average discount % on items relisted as "open box" or similar |

Why bother: The True Cost Calculator is the most persuasive tool for justifying investment in return reduction to your leadership team. Accurate inputs make the case concrete. The default estimates (based on industry averages) often understate the real figure for brands with high restocking losses or expensive return shipping.

Data Retention

| Plan | Retention | |---|---| | Free | 90 days rolling | | Starter, Growth | 12 months | | Scale | Unlimited |

Data used for the AI models is retained independently of the retention window — model training data may persist longer for accuracy purposes. Customer-identifiable data is subject to deletion on request per GDPR.

GDPR Customer Data Deletion

To delete all data for a specific customer (e.g., in response to a subject access request):

1. Go to Settings → Data → Customer Data Deletion
2. Enter the customer's email address
3. Click "Delete customer data"

ReturnShield removes all records linked to that email address from its database within 72 hours. The deletion does not affect Shopify order records.

Integration Details: Klaviyo and Omnisend

ReturnShield writes the returnshield.risk_tier Shopify customer metafield (namespace: returnshield, key: risk_tier) with one of four string values: champion, standard, at_risk, serial_returner.

Klaviyo Setup

1. In Klaviyo, confirm your Shopify integration syncs customer properties (Settings → Integrations → Shopify → Sync customer data)
2. Create a list or segment: Customer properties → returnshield.risk_tier equals at_risk
3. Build a flow triggered by this segment for sizing guidance emails after purchase

Klaviyo syncs Shopify metafields on the standard sync cadence (typically every 15 minutes). There may be up to a 15-minute lag between a customer being reclassified in ReturnShield and the updated value being available in Klaviyo.

Omnisend Setup

1. In Omnisend, customer properties from Shopify sync automatically
2. Segments → Create a new segment → Shopify customer property → returnshield.risk_tier
3. Use this segment as the audience condition in an automation workflow

Recommended Configurations by Store Size

Small stores (under 100 orders/month)

| Setting | Value | |---|---| | Auto-apply | Disabled — review manually | | Return spike alert | 2x benchmark, 10-order minimum | | Widget | Enable on top 5 products by return rate | | Post-purchase emails | Enable when traffic justifies it |

Medium stores (100–1,000 orders/month)

| Setting | Value | |---|---| | Auto-apply | 92% confidence, $200/mo cap | | Return spike alert | 1.5x benchmark, 20-order minimum | | Widget | All products with return rate above 10% | | Post-purchase emails | Both "How's it fit?" (5 days) and post-return survey | | Klaviyo/Omnisend | Connect at_risk segment for sizing email flow |

Large stores (1,000+ orders/month)

| Setting | Value | |---|---| | Auto-apply | 85% confidence, $500/mo cap | | Serial returner flow | Shopify Flow automatic tagging | | Widget | All products above size return threshold | | Post-purchase emails | Full setup including conditional survey logic | | Segment export | Weekly CSV export to loyalty platform |

Next Steps

• AI Action Queue — how the word-level diff works and how to read evidence summaries
• Customer Segments — understanding the four tier system and acting on each segment
• Shopify Flow — automating order holds and notifications based on risk data