Return reason agent for Shopify merchants

Automatically classify return reasons and trigger refund/replace decisions without human review.

shopify ecommerce return-reason-agent nextjs fastify llm agent lead-intake

The problem

A Shopify store owner receives dozens of return requests daily, each requiring manual review to determine if the item is defective, wrong size, or buyer's remorse. The owner must then decide whether to refund, replace, or offer store credit, consuming hours of time that could be spent on growth. This manual process is error-prone and inconsistent, leading to customer frustration and lost margin.

Built from

Intro

A Shopify store owner receives dozens of return requests daily, each requiring manual review to determine if the item is defective, wrong size, or buyer’s remorse. This recipe builds an automated return-reason agent that classifies return reasons using an LLM, enforces per-merchant budgets, and triggers refund, replacement, or store-credit decisions. You’ll use a provider-agnostic LLM client (OpenAI-compatible), the A2A agent-to-agent protocol, an intent classifier from @reaatech/agent-mesh-classifier, a budget engine from @reaatech/agent-budget-engine, and the Shopify Admin API. The agent exposes both a Next.js API route and a Fastify-based A2A server, with optional Langfuse observability.

Prerequisites

Node.js >= 22 and pnpm 10 (corepack enable && corepack prepare pnpm@10.0.0 --activate)
An OpenAI-compatible LLM provider key (OpenAI, DeepSeek, Groq, etc.)
A Shopify Partner development store with Admin API credentials (API key, secret, offline access token)
(Optional) A Langfuse account for LLM tracing

Step 1: Scaffold the project and install dependencies

Create the project directory and set up a Next.js 16 App Router shell. Copy the package.json below which pins every dependency to an exact version — no ^ or ~ ranges.

Example artifact

A complete, working implementation of this recipe — downloadable as a zip or browsable file by file. Generated by our build pipeline; tested with full coverage before publishing.

Download example (zip)Browse files

197 kB·83 tests·98.6% coverage·vitest passing

SHA-256e70c53f63234e9c9a6b74bcf739f12557d0e4f48330d533e9bc28d097e35a694

Book a conversation All solutions

Comments

Loading comments…

import Fastify from "fastify"; import { z } from "zod"; import { config } from "./lib/config.js"; import { createA2aApp, agentExecutor } from "./services/a2a-server-service.js"; import { processReturnRequest } from "./services/return-reason-agent.js"; import { ReturnRequestSchema } from "./lib/types.js"; const a2aApp = createA2aApp(agentExecutor); const honoFetch = a2aApp.fetch; const fastify = Fastify({ logger: true }); fastify.all("/*", async (req, reply) => { const protocol = req.protocol; const host = req.headers.host ?? config.A2A_SERVER_BASE_URL; const url = `${protocol}://${host}${req.url}`; const method = req.method; const headers = new Headers(); for (const [key, value] of Object.entries(req.headers)) { if (value !== undefined) { if (Array.isArray(value)) { for (const v of value) headers.append(key, v); } else { headers.set(key, value); } } } let body: BodyInit | undefined; if (method !== "GET" && method !== "HEAD") { const rawBody = await req.body; if (rawBody !== undefined) { body = typeof rawBody === "string" ? rawBody : JSON.stringify(rawBody); } } const webRequest = new Request(url, { method, headers, body }); const webResponse = await honoFetch(webRequest); reply.status(webResponse.status); for (const [key, value] of webResponse.headers.entries()) { reply.header(key, value); } reply.send(Buffer.from(await webResponse.arrayBuffer())); return reply; }); fastify.get("/healthz", () => { return { status: "ok", uptime: process.uptime() }; }); fastify.post<{ Body: unknown }>("/webhooks/shopify/return", async (req, reply) => { const parsed = ReturnRequestSchema.safeParse(req.body); if (!parsed.success) { reply.status(400).send({ error: "Invalid return request", details: z.treeifyError(parsed.error) }); return reply; } const { orderId, reasonText, customerNote } = parsed.data; const shopDomain = (req.body as Record<string, unknown>).shopDomain as string | undefined ?? ""; const decision = await processReturnRequest(shopDomain, orderId, reasonText, customerNote); reply.send(decision); return reply; }); const start = async () => { try { await fastify.listen({ port: config.A2A_SERVER_PORT, host: "0.0.0.0" }); fastify.log.info(`Server listening on port ${String(config.A2A_SERVER_PORT)}`); } catch (err) { fastify.log.error(err); process.exit(1); } }; process.on("SIGTERM", () => { fastify.log.info("SIGTERM received, shutting down"); fastify.close().then(() => process.exit(0)).catch(() => process.exit(1)); }); process.on("SIGINT", () => { fastify.log.info("SIGINT received, shutting down"); fastify.close().then(() => process.exit(0)).catch(() => process.exit(1)); }); export { start, fastify };

import { describe, it, expect, vi } from "vitest"; import { ReturnRequestSchema, ReturnDecisionSchema } from "../src/lib/types.js"; import { makeReturnRequest, makeReturnDecision, makeClassifierOutput } from "./helpers.js"; import { ZodError } from "zod"; vi.mock("@reaatech/agent-mesh", async () => { const { z } = await import("zod"); return { IncomingRequestSchema: z.object({}), AgentResponseSchema: { safeParse: vi.fn() }, }; }); describe("ReturnRequestSchema", () => { it("parses valid return request", () => { const result = ReturnRequestSchema.parse({ orderId: "ord-1", productId: "prod-1", reasonText: "broken", customerNote: "please refund", }); expect(result.orderId).toBe("ord-1"); expect(result.reasonText).toBe("broken"); }); it("throws on empty reasonText", () => { expect(() => ReturnRequestSchema.parse({ orderId: "ord-1", productId: "prod-1", reasonText: "" }), ).toThrow(ZodError); }); }); describe("ReturnDecisionSchema", () => { it("parses valid refund decision", () => { const result = ReturnDecisionSchema.parse({ action: "refund", confidence: 0.9, explanation: "Item is defective", estimatedCostUsd: 0.05, }); expect(result.action).toBe("refund"); expect(result.confidence).toBe(0.9); }); it("throws on invalid action", () => { expect(() => ReturnDecisionSchema.parse({ action: "invalid", confidence: 0.9, explanation: "test", estimatedCostUsd: 0 }), ).toThrow(ZodError); }); }); describe("factory functions", () => { it("makeReturnRequest produces valid ReturnRequest", () => { const req = makeReturnRequest(); const parsed = ReturnRequestSchema.parse(req); expect(parsed.orderId).toBe("ord-1"); }); it("makeReturnDecision produces valid ReturnDecision", () => { const dec = makeReturnDecision(); const parsed = ReturnDecisionSchema.parse(dec); expect(parsed.action).toBe("refund"); }); it("makeClassifierOutput produces valid ClassifierOutput", () => { const output = makeClassifierOutput(); expect(output.agent_id).toBe("refund-agent"); expect(output.confidence).toBe(0.9); }); });

import { describe, it, expect, vi } from "vitest"; import { z } from "zod"; vi.mock("../src/lib/config.js", () => ({ config: { LLM_API_KEY: "test-key", LLM_BASE_URL: "https://api.openai.com", LLM_MODEL: "gpt-5.2", SHOPIFY_SHOP_DOMAIN: "test-store.myshopify.com", SHOPIFY_ACCESS_TOKEN: "test-token", BUDGET_LIMIT_USD: 5, BUDGET_SOFT_CAP: 0.8, A2A_SERVER_PORT: 3001, A2A_SERVER_BASE_URL: "http://localhost:3001", }, })); vi.mock("openai", () => { class MockAPIError extends Error {} class MockOpenAI { static APIError = MockAPIError; chat: { completions: { create: ReturnType<typeof vi.fn> } }; constructor() { this.chat = { completions: { create: vi.fn() } }; } } return { default: MockOpenAI }; }); import { createLlmClient, generateDecision } from "../src/lib/llm-client.js"; describe("llm-client", () => { it("generateDecision returns parsable JSON with action, explanation, confidence", async () => { const client = createLlmClient(); client.chat.completions.create = vi.fn().mockResolvedValue({ id: "cmpl-test", choices: [{ index: 0, message: { role: "assistant", content: '{"action":"refund","explanation":"Item is defective","confidence":0.9}' }, finish_reason: "stop" }], usage: { prompt_tokens: 20, completion_tokens: 15, total_tokens: 35 }, }); const result = await generateDecision(client, "return reason: item arrived broken"); const parsed = z.object({ action: z.string(), explanation: z.string(), confidence: z.number() }) .parse(JSON.parse(result)); expect(parsed.action).toBeDefined(); expect(parsed.explanation).toBeDefined(); expect(parsed.confidence).toBeGreaterThan(0); }); it("generateDecision returns fallback {} on error", async () => { const client = createLlmClient(); client.chat.completions.create = vi.fn().mockRejectedValue(new Error("API error")); const result = await generateDecision(client, "return reason: test"); expect(result).toBe("{}"); }); it("generateDecision returns {} on null content from API", async () => { const client = createLlmClient(); client.chat.completions.create = vi.fn().mockResolvedValue({ id: "cmpl-test", choices: [{ index: 0, message: { role: "assistant", content: null } }], }); const result = await generateDecision(client, "return reason: test"); expect(result).toBe("{}"); }); });

Return reason agent for Shopify merchants

The problem

Built from

Intro

Prerequisites

Step 1: Scaffold the project and install dependencies

Example artifact

Comments

Intro

Prerequisites

Step 1: Scaffold the project and install dependencies

Step 2: Define domain types and Zod schemas

Step 3: Validate environment config with Zod

Step 4: Create the LLM client (provider-agnostic)

Step 5: Build the intent classifier service

Step 6: Build the budget service with InMemorySpendStore

Step 7: Build the Shopify client

Step 8: Wire the return reason agent orchestrator

Step 9: Add Langfuse observability

Step 10: Create the A2A client and server services

Step 11: Create the Fastify A2A server

Step 12: Create Next.js API routes and dashboard

Step 13: Set up MSW test infrastructure

Step 14: Write and run tests

Next steps