# Eturns Developer Integration Map
---
Canonical URL: https://api.eturns.app
Operating Stack: React Router 7, Prisma 7, PostgreSQL, Redis

## ⚡ Immediate Health & Diagnostic Endpoints
- GET /healthz : Incredibly fast startup status. Returns: { status: "healthy" }
- GET /readyz : Deep system dependency check. Returns: { db: "connected", redis: "connected" }

## 🛡️ Ingest & Admin Action Routes
- POST /api/v1/ingest/tickets : Programmatic ticket creation. Body: { externalId: String, body: String, customerId: String }
- POST /api/v1/admin/returns/:id/decide : Resolve pending return. Body: { action: "APPROVE"|"DECLINE"|"EXCHANGE", incentiveId: String }
- POST /api/v1/admin/returns/:id/inspect : Commit restock warehouse & fee. Body: { restockLocation: String, restockingFeeCents: BigInt, disposition: String }
- POST /api/v1/admin/digest-send : Manually trigger weekly analytics digest transmission.
- POST /api/admin/policy-retrieve : Fetch, calibrate, and commit Shopify policy settings.

## 📊 Core Persistent Ledgers & Schemas
- ReturnRequest: { id: String, shop_id: String, customer_id: String, state: "OPEN"|"RECEIVED"|"CLOSED", restocking_fee_cents: BigInt, restocked_by: String }
- CustomerMirror: { id: String, shop_id: String, email_hash: String, return_count: Int, fraud_score: Float }
- Shop: { id: String, shop_domain: String, plan_tier: "free"|"starter"|"growth"|"scale"|"plus" }
- CostCounter: { shop_id: String, day: String, total_micros: BigInt }

## 🔐 Row-Level Security (RLS) Requirements
- Set shop context prior to all queries: SET LOCAL app.current_shop_id = 'merchant-id';
- Verify tenancies on every nested join.