# ReturnFlowAI — Merchant User Guide A returns-management platform for Shopify. This guide walks you from install to your first refund, then explains the features that separate ReturnFlowAI from a spreadsheet. --- ## 1. Getting started ### 1.1 Install 1. Open the [Shopify App Store listing](https://apps.shopify.com/) or go direct at `https://returnflow.tridentbi.com`. 2. Click **Install** and approve the requested scopes (orders, products, customers, fulfillments, returns, discounts, draft orders, gift cards, disputes). 3. On first load you'll land on the **Setup wizard** (`/app/setup`) — walk through the 6 steps: brand colors, policy, carriers, notifications, warehouse, team. ### 1.2 Setup checklist `/app/checklist` shows every remaining setup task with a green tick when done. Aim to get to 100% within the first week — many features (auto-approval, exchange offers, SMS notifications) stay dormant until their prerequisites are set. ### 1.3 Connecting a carrier Go to `/app/carriers` and click **Connect** on the carrier you use. | Carrier | Coverage | Setup | |---|---|---| | Shippo | 100+ carriers globally | One API key | | EasyPost | 100+ carriers globally | One API key | | Royal Mail (OBA) | UK direct | OBA credentials | | DHL Paket | DE/AT/CH direct | Parcel DE Shipping API v2 key | | Australia Post StarTrack | AU direct | API key + password | | DPD, Evri, PostNL, La Poste, Canada Post | Regional direct | Provider-specific — see per-carrier guide | If you already have contract rates with a specific carrier, use the direct integration to avoid aggregator markup. Otherwise Shippo/EasyPost is fastest. --- ## 2. Core workflows ### 2.1 A shopper starts a return 1. Customer opens your storefront return portal (Theme App Extension, or the direct link `returnflow.tridentbi.com/portal/`). 2. They pick items, choose a reason, and see resolution options (refund, store credit, exchange, keep-it). 3. If the return matches your **auto-approval rules** (`/app/workflows`), a shipping label is generated instantly and emailed. Otherwise it lands in your inbox at `/app/dashboard` for review. ### 2.2 Reviewing a return (merchant side) - `/app/dashboard` — real-time list of pending returns with fraud score, item value, reason, and recommended action. - Click a return to see the full timeline, customer history, and AI reviewer summary. - Actions: **Approve**, **Deny with reason**, **Ask for photo**, **Offer keep-it**, **Offer exchange**, **Manual review**. ### 2.3 Warehouse receipt When the parcel arrives: 1. Scan the label at `/app/warehouse/scan` (mobile-friendly). 2. Inspect items — mark condition (new / restockable / damaged / missing). 3. Optional: run **CV inspection** — upload a photo and the AI checks for damage/wear vs the product image. 4. Trigger refund/credit. Restock happens automatically if condition = restockable. ### 2.4 Refund or credit - **Refund cash** — issued back to original payment method via Shopify. - **Store credit** — issued as a Shopify gift card; bonus multipliers configurable in `/app/policy`. - **Keep-it** — no return required; refund is issued and item stays with customer (used when return cost > item value). - **Exchange** — draft order created for the new SKU/variant. Optional **instant exchange** ships the new item before the return arrives (fraud-gated). --- ## 3. Feature index ### 3.0 Network flywheel (new) - **Trust network** (`/app/network-trust`) — every shopper carries a portable trust score (0–100) computed across every merchant on Trident ReturnFlow. Trusted returners get instant approvals anywhere; abusers get flagged the first time they arrive at your store. - **Welcome Passes** (`/app/welcome-passes`) — opt in and high-trust shoppers from other network merchants automatically get a discount code the first time they visit your store. Zero-effort acquisition channel; toggle on in the page settings, cash in. - **Voice command** (`/app/voice`) — mic button in the admin. Web Speech transcribes → Claude answers about your returns, backlog, flagged items. Phase 2 will let voice trigger approvals. - **Policy suggestions** (`/app/policy-suggestions`) — a weekly Claude-generated policy tweak with a dollar impact estimate. Accept or dismiss; nothing changes without your click. - **Return QR** — the packing slip snippet in `docs/QR_RETURNS.md` prints a QR on every parcel. Shoppers scan → land pre-authenticated in your return portal. Three clicks removed, ~25% higher recovery-flow completion. - **Live State of Returns** — the public counter on your marketing site (fed by `/network-live.json`) shows how many returns and dollars the network processes weekly. Social proof, free of charge. ### 3.1 AI & automation - **Copilot** (`/app/copilot`) — chat interface. Ask "why did returns spike last week?" or "draft a policy that caps free returns at 3 per year." - **Agentic Reviewer** — reviews every return, scores fraud risk, and can auto-approve within your defined risk band. - **Policy Copilot** — natural-language policy editor. "Only accept returns within 30 days for full-price items, 14 days for sale items" → structured rules. - **PDP Proposals** (`/app/pdp-proposals`) — AI suggests product-page copy improvements to reduce returns (fit tips, warnings, sizing). - **Simulator** (`/app/simulator`) — replay past returns against a proposed new policy to see the financial impact before rolling it out. - **AI cost dashboard** (`/app/ai-cost`) — see monthly + daily AI spend by feature; hard-capped per plan. ### 3.2 Fraud & risk - **Fraud graph** (`/app/fraud`) — network view of connected returners (shared addresses, cards, IPs). - **Coalition scoring** — identifies rings across your store *and* the merchant network (opt-in). - **CV inspection** — computer vision damage check. - **Address anomaly detection** — flags mismatched shipping/billing/return addresses. - **VIP fast-lane** — trusted customers skip review. - **Chargeback dispute assist** — generates evidence packets for `disputes/create` webhooks. ### 3.3 Insights - **Reports** (`/app/reports`) — pre-built + custom pivot tables. - **Dashboard** (`/app/dashboard`) — daily KPI tiles. - **RTC lift** (`/app/rtc`) — measures how much revenue you saved by intercepting returns into exchange/keep-it flows. - **Benchmarks** (`/app/benchmarks`) — your metrics vs anonymized peers in your category. - **Profitability** (`/app/profitability`) — true landed cost per return by SKU / reason / carrier. - **CSAT** (`/app/csat`) — post-return survey scores + comments. - **Digest** (`/app/digest-preview`) — daily/weekly email summary for stakeholders. ### 3.4 Portal & branding - `/app/branding` — logo, colors, fonts. - `/app/email-templates` — customize every transactional email. - Portal supports **10 locales**; automatic locale detection by shopper country + browser. - **Portal chat** — shoppers can ask questions mid-return (fully guardrailed AI). ### 3.5 Integrations - `/app/integrations` — connect Twilio (SMS), Resend (email), QuickBooks / NetSuite / Xero (accounting), CRM systems. - `/app/klaviyo` — native Klaviyo integration. Paste your API key, flip toggles, and every return event ("Return Requested", "Return Approved", "Refunded", "Keep-It Accepted") flows into Klaviyo profiles + events automatically. Fires your post-return retention flows without any custom webhook. - `/app/api-keys` — issue scoped API keys for external systems. - `/app/webhooks` — outbound webhook subscriptions for your own systems. - `/app/migrate` — import from Loop / Returnly via CSV. ### 3.5b Exchange for anything (new) Shoppers can swap their return for **any** SKU in your Shopify catalog — not just a different size of the same product. - From the return portal, they see a "Swap for something else" button. - Full-catalog search modal with product images, prices, and availability. - Price delta handled automatically: cheaper item = store credit for the difference; pricier item = draft-order invoice they pay to complete the exchange. - Merchant view: `/app/exchanges` (Insights hub) shows every candidate with status, revenue delta, and drill-down to the source return. ### 3.6 Team & compliance - `/app/team` — invite team members with role-based permissions. - `/app/rbac` — define custom roles (viewer / agent / admin / owner). - `/app/sso` — SAML SSO (Enterprise plan). - `/app/audit` — every mutation logged with actor + timestamp. - `/app/compliance` — SOC 2 readiness dashboard. --- ## 4. Common tasks (how-to) ### 4.1 Set up auto-approval for low-risk returns 1. Go to `/app/workflows`. 2. Create rule: `If fraud score < 20 AND item value < $75 AND reason ≠ "changed_mind" → auto-approve`. 3. Save. Rules apply to all future returns; historical returns are not touched. ### 4.2 Offer keep-it for low-value items 1. Go to `/app/policy`. 2. Enable **Keep-it offers**. 3. Set threshold: "Offer keep-it if shipping cost > 40% of item value." 4. ReturnFlowAI will now auto-calculate the offer at review time. ### 4.3 Migrate from Loop or Returnly 1. Export historical returns from your current tool as CSV. 2. Go to `/app/migrate`. 3. Upload the CSV. Files over 200KB use Blob storage automatically. 4. Preview mapped fields, click **Import**. History becomes searchable in `/app/reports`. ### 4.4 Restrict a serial abuser 1. Open the customer profile from any return. 2. Click **Block returns** or **Require manual review**. 3. All future returns from this customer will be blocked or held. ### 4.5 Issue store credit that redeems across brands 1. Go to `/app/marketplace`. 2. Opt into **Cross-merchant credit shards**. 3. Store credit issued after opt-in will be redeemable at any participating merchant, at your configured redemption rate. --- ## 5. Troubleshooting | Symptom | Likely cause | Fix | |---|---|---| | Portal shows "Order not found" | Order placed before install date | Increase the order-lookback window in `/app/settings` | | Labels not generating | Carrier not connected or rate limit hit | Check `/app/carriers` connection status; verify carrier has funds | | AI features "budget exceeded" | Monthly or daily AI cap reached | Upgrade plan at `/app/billing` or wait for reset | | Emails not sending | Resend key missing/invalid | `/app/integrations` → reconnect Resend | | Webhook errors in Shopify admin | App URL changed | Reinstall the app; webhook subscriptions re-register automatically | | Return stuck in "Inspecting" | Manual step not completed | `/app/warehouse` → find the return → mark inspection complete | Full status: [`returnflow.tridentbi.com/status`](https://returnflow.tridentbi.com/status). --- ## 6. Support - **In-app help** — click the `?` icon in any admin page. - **Setup issues** — email `support@tridentbi.com`. - **Security & compliance** — `security@tridentbi.com` or `/app/compliance` for our SOC 2 dashboard. - **Feature requests** — `/app/suggestions` (in-app board with voting). - **What's new** — `/app/changelog`. --- *ReturnFlowAI is built by Trident BI. Docs updated 2026-08-24.*