Files · Return Reason Agent for Shopify Merchants

# Return Reason Agent for Shopify Merchants
 
> Automate refund/RMA decisions from return reasons in seconds, not hours.
 
A tutorialized reference solution from [reaatech.com](https://reaatech.com), demonstrating how to build production-grade AI systems with the `@reaatech/*` package family.
 
This recipe listens for Shopify return-reason webhooks, sanitizes input through a guardrail chain (PII redaction, prompt injection, toxicity), retrieves relevant store-policy chunks from a hybrid RAG pipeline (Qdrant vector + BM25), packs the LLM context window with prioritized policy chunks, calls an agnostic LLM via the Vercel AI SDK, repairs malformed structured output via the six-strategy repair engine, and returns a typed decision (refund/replacement/rma/escalate) submitted back to the Shopify Admin API.
 
```
┌─────────────────────────────────────────────────────────────────┐
│                    Return Reason Agent                           │
│                                                                  │
│  Shopify Webhook                                                 │
│  (return reason)                                                 │
│       │                                                          │
│       ▼                                                          │
│  ┌──────────────┐    ┌────────────────┐    ┌──────────────────┐  │
│  │  Guardrail    │───▶│  RAG Retriever  │───▶│ Context Planner  │  │
│  │  Chain        │    │  (Qdrant+BM25)  │    │  (Priority-      │  │
│  │  (PII/Inject/ │    │                 │    │   Greedy/Pack)   │  │
│  │   Toxicity)   │    └────────────────┘    └────────┬─────────┘  │
│  └──────────────┘                                    │           │
│       │                                              │           │
│       ▼                                              ▼           │
│  ┌──────────────────────────────────────────────────────────┐    │
│  │                    Vercel AI SDK                           │    │
│  │              openai("gpt-5.2") + generateText              │    │
│  └──────────────────────────┬───────────────────────────────┘    │
│                             │                                    │
│                             ▼                                    │
│  ┌──────────────────────────────────────────────────────────┐    │
│  │              Structured Repair Engine                     │    │
│  │  (strip-fences → extract-json → fix-syntax → coerce-     │    │
│  │   types → fuzzy-match → remove-extra-fields)             │    │
│  └──────────────────────────┬───────────────────────────────┘    │
│                             │                                    │
│                             ▼                                    │
│  ┌──────────────────────────────────────────────────────────┐    │
│  │          Shopify Admin API (submit decision)               │    │
│  │          ┌──────────┐ ┌───────────┐ ┌──────┐              │    │
│  │          │  Refund  │ │Replacement│ │ RMA │              │    │
│  │          └──────────┘ └───────────┘ └──────┘              │    │
│  └──────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘
```
 
## Environment Variables
 
| Variable | Description | Required |
|----------|-------------|----------|
| `OPENAI_API_KEY` | OpenAI API key for embeddings and chat completions | Yes |
| `SHOPIFY_API_KEY` | Shopify API key (custom store app) | Yes |
| `SHOPIFY_API_SECRET_KEY` | Shopify API secret | Yes |
| `SHOPIFY_SHOP` | Your Shopify shop domain (e.g. my-store.myshopify.com) | Yes |
| `SHOPIFY_ACCESS_TOKEN` | Shopify Admin API access token | Yes |
| `QDRANT_URL` | Qdrant vector database URL (default: http://localhost:6333) | Yes |
| `POSTGRES_URL` | Postgres connection string for decision storage | Yes |
| `RERANKER_API_KEY` | Optional reranker API key | No |
 
## Quick Start
 
```bash
pnpm install
pnpm dev
```
 
## Running tests
 
```bash
pnpm test            # vitest run with coverage
```
 
## Project layout
 
```
app/                  Next.js App Router pages + API routes
src/                  services, lib, adapters
tests/                vitest suite (mirrors src/)
packages/             API references for every dependency (read these first)
DEV_PLAN.md           build plan for this recipe
```
 
## License
 
MIT — see [LICENSE](./LICENSE).