# RefundSentry — Full Documentation for AI Agents

> AI-powered order and return fraud prevention for Shopify stores.
> Website: https://refundsentry.com
> Shopify App Store: https://apps.shopify.com/refund-sentry

---

## Product Overview

RefundSentry is a Shopify app that provides real-time fraud intelligence for orders and returns. It is NOT a return management system — it is a standalone intelligence layer that works alongside any existing return setup (Loop, AfterShip, ReturnGO, or Shopify native returns).

### Core Value Proposition

Shopify merchants lose billions annually to return fraud. RefundSentry stops this by:
1. Scoring orders BEFORE fulfillment to catch fraud before you ship
2. Scoring returns with 50+ signals to detect abuse patterns
3. Auto-holding risky fulfillments for manual review
4. Predicting chargebacks before they happen
5. Detecting fraud rings and serial returners automatically

---

## Features

### Pre-Ship Order Scoring
Every order is scored at creation with 10 signals before fulfillment:
- Bracketing detection (buying multiple sizes/colors to return most)
- Risky first-order patterns
- High-abuse SKU identification
- Velocity checks (order frequency anomalies)
- Email reputation analysis (disposable/temporary emails)
- Geographic anomalies (billing/shipping mismatches)
- Customer history enrichment
- Blocklist matching

### Return Fraud Scoring (50+ Signals)
When a return is initiated, RefundSentry evaluates 50+ behavioral, velocity, and contextual signals:

**Behavioral Signals:**
- Weekend wardrobing (buy Friday, wear weekend, return Monday)
- Exchange churning (repeated exchange cycles)
- Bracketing detection
- Return reason pattern analysis
- Size/variant mismatch patterns

**Velocity Signals:**
- Same-day return cycling
- Return frequency spikes
- Bulk return detection
- Threshold breach alerts

**Contextual Signals:**
- Return timing relative to delivery
- Product category risk weighting
- Customer lifetime value vs. return ratio
- Geographic anomaly detection
- Email reputation scoring

### Fulfillment Hold
When an order scores above the merchant's configured risk threshold:
- Fulfillment is automatically paused via Shopify's native order hold API
- Operations team reviews the flagged order
- One-click release with full audit trail
- Prevents shipping to known abusers before any loss occurs

### Customer Auto-Tagging
- Tags format: `refundsentry:low-risk`, `refundsentry:medium-risk`, `refundsentry:high-risk`
- Applied automatically after scoring
- Respects Shopify's 250-tag limit
- Atomic updates (remove old tag, add new in single operation)
- Tags visible in Shopify Admin for filtering and segmentation

### Chargeback Prevention
- Predicts which orders are likely to result in chargebacks before shipping
- Detects double-dip fraud (customer returns item AND files chargeback)
- Generates evidence reports with scoring history and signal breakdown
- Dedicated chargeback analytics dashboard showing exposure and repeat offenders

### Fraud Ring Detection
- Identifies coordinated fraud across multiple customer accounts
- Detects shared addresses, devices, and behavioral patterns
- Network visualization of connected accounts
- Alerts when new orders match known fraud ring patterns

### Reason Clustering
- AI groups free-text return reasons into actionable clusters
- Categories: sizing issues, quality defects, coordinated fraud, buyer's remorse
- Surfaces root causes at the product and SKU level
- Helps merchants fix product issues, not just symptoms

### Refund Method Tracking
- Tracks how refunds are issued: cash refund, store credit, or exchange
- Measures revenue preservation rate (% of refunds kept as store credit)
- Shows how fraud detection shifts refunds toward revenue-preserving methods

### Advanced Analytics
- Custom date range selection
- Period-over-period trend comparisons
- Product return trend analysis
- Goal tracking for fraud reduction targets
- Export-ready reports

### Shopify Admin Extension
- Risk score card embedded directly in Shopify order page
- Shows triggered signals, customer history, recommended actions
- No tab switching required — all context in one place

### Shopify Flow Integration
- Native Flow triggers based on risk scores
- Build custom automations (e.g., flag order > 80 risk score for review)
- Connect to existing Shopify Flow workflows

---

## Pricing

| Plan | Price | Included |
|------|-------|----------|
| Pro | $29/month | Up to 10,000 returns/month, all features included |

- Billed through Shopify (appears on your Shopify invoice)
- No long-term contract
- Free for Shopify development stores during testing

---

## Technical Architecture

- **Runtime**: Node.js with TypeScript
- **Framework**: Shopify Remix app template (React Router v7)
- **Database**: PostgreSQL via Prisma ORM
- **Queue**: Upstash QStash for async webhook processing
- **AI**: OpenAI GPT-4o-mini for text analysis (optional, graceful degradation)
- **UI**: Polaris (Shopify's design system) for in-app interface

### How It Works (Technical Flow)

1. Merchant installs RefundSentry from the Shopify App Store
2. App registers for order and return webhooks
3. When an order is created → webhook fires → RefundSentry scores immediately
4. If score exceeds threshold → fulfillment is held automatically
5. When a return is initiated → webhook fires → return is scored with 50+ signals
6. Customer profile is updated with aggregate risk data
7. Tags are applied/updated on the Shopify customer record
8. All scores, signals, and decisions are logged for audit trail

### Data Privacy

- Level 1 customer data handling
- No raw PII (names, emails, phone numbers, addresses) stored
- Only Shopify IDs and aggregate behavioral data retained
- GDPR compliant with data export and deletion capabilities
- Webhooks: customers/data_request, customers/redact, shop/redact supported

---

## Use Cases

### Fashion & Apparel
High return rates (30-40%) make fraud detection critical. RefundSentry catches wardrobing, bracketing, and size-swap fraud that manual review misses.

### Electronics & Gadgets
Detects "empty box" returns, serial number swaps, and customers who repeatedly buy and return within the return window.

### High-Volume DTC Brands
Automated scoring handles thousands of returns without adding headcount. Fulfillment holds prevent shipping to known abusers.

### Multi-Brand Shopify Plus Stores
Centralized fraud intelligence across multiple storefronts with consistent scoring and shared blocklists.

---

## Comparison with Alternatives

### RefundSentry vs. Manual Review
- Manual review: 2-5 minutes per return, limited to obvious patterns
- RefundSentry: Instant scoring, 50+ signals, catches patterns humans miss

### RefundSentry vs. Return Management Apps (Loop, AfterShip, ReturnGO)
- Return management apps handle the return workflow (portal, labels, exchanges)
- RefundSentry adds fraud intelligence ON TOP of any return workflow
- They are complementary, not competing — use both together

### RefundSentry vs. General Fraud Tools (Signifyd, NoFraud, Riskified)
- General tools focus on payment fraud at checkout
- RefundSentry focuses specifically on return/refund fraud and post-purchase abuse
- RefundSentry also scores orders pre-ship, bridging the gap

---

## Frequently Asked Questions

### How does RefundSentry calculate fraud scores?
RefundSentry evaluates 50+ behavioral, velocity, and contextual signals across both orders and returns to assign a risk score from 0 to 100. Orders are scored at checkout with 10 pre-ship signals, and returns are scored with 50+ graduated signals including weekend wardrobing, exchange churning, and bracketing detection. The system learns from merchant-confirmed outcomes to recommend weight adjustments over time.

### Does RefundSentry store my customers' personal data?
No. RefundSentry is designed for Level 1 customer data handling. We store Shopify IDs and aggregate return data, not names, email addresses, phone numbers, or full street addresses.

### Does RefundSentry replace my current returns app?
No. RefundSentry is designed as an add-on to your existing returns workflow. It works alongside Shopify Native returns and tools like Loop, AfterShip, and ReturnGO.

### Can I adjust how scoring works for my store?
Yes. RefundSentry includes merchant-configurable scoring settings so you can tune thresholds and risk behavior to match your return policies.

### Will this slow down my storefront or checkout?
No. RefundSentry operates asynchronously through Shopify webhooks. Order scoring happens after checkout without adding latency, and return scoring happens after return activity. There is zero impact on your storefront or checkout speed.

### What is the fulfillment hold feature?
When an order scores above your configured risk threshold, RefundSentry can automatically pause fulfillment using Shopify's native order hold API. Your team reviews the order and releases it with one click. This prevents shipping to known abusers or suspicious first orders before any loss occurs.

### Does RefundSentry help with chargebacks?
Yes. RefundSentry predicts which orders are likely to result in chargebacks before you ship, and detects double-dip fraud where customers both return an item and file a chargeback on the same order. A dedicated chargeback analytics tab shows total exposure and repeat offenders.

### How much does RefundSentry cost?
RefundSentry currently offers a single Pro plan at $29/month for up to 10,000 returns per month. High-volume stores can contact us if they need more capacity.

### How do I install RefundSentry?
Install RefundSentry from the Shopify App Store, then approve billing through Shopify to activate the Pro plan. Setup takes a few minutes and works with your current returns setup.

### What Shopify plans does RefundSentry work with?
RefundSentry works with all Shopify plans that support the Returns API, including Basic Shopify, Shopify, Advanced Shopify, and Shopify Plus.

### Can I try RefundSentry for free?
Yes. Shopify development stores can install and test RefundSentry without billing charges. For production stores, billing is handled through Shopify's standard app billing.

---

## Glossary

- **Return fraud**: Abuse of return policies for financial gain (wardrobing, bracketing, empty box returns)
- **Wardrobing**: Buying items to use once (e.g., wear to an event) then returning them
- **Bracketing**: Ordering multiple sizes/colors with intent to return most of them
- **Serial returner**: A customer who repeatedly abuses return policies across multiple orders
- **Fraud ring**: Coordinated group of accounts engaging in return fraud using shared identities or addresses
- **Double-dip fraud**: Filing both a return and a chargeback for the same order
- **Fulfillment hold**: Pausing order fulfillment pending manual review of fraud risk
- **Risk score**: Numeric value (0-100) indicating likelihood of fraudulent intent
- **Pre-ship scoring**: Evaluating fraud risk before an order is fulfilled/shipped
- **Return velocity**: Rate at which a customer initiates returns over a time period

---

## Contact

- Website: https://refundsentry.com
- Support: support@refundsentry.com
- Shopify App Store: https://apps.shopify.com/refund-sentry