medusa-api-routes

Medusa v2 Custom API Routes

Before writing code

Fetch live docs:

1. Fetch https://docs.medusajs.com/learn/fundamentals/api-routes for API route overview
2. Web-search site:docs.medusajs.com custom API route file convention for file-based routing
3. Web-search site:docs.medusajs.com API route middleware for middleware configuration
4. Web-search site:docs.medusajs.com API route validation zod for request validation
5. Web-search site:docs.medusajs.com additional data API routes for the additional-data pattern

File-Based Routing

Medusa v2 uses a file-system router under src/api/:

File Path	Resulting Endpoint
src/api/store/custom/route.ts	GET/POST /store/custom
src/api/admin/custom/route.ts	GET/POST /admin/custom
src/api/store/custom/[id]/route.ts	GET/POST /store/custom/:id
src/api/custom/route.ts	GET/POST /custom (no auth prefix)

Conventions

• File must be named route.ts (not index.ts)
• Dynamic parameters use [param] folder syntax
• The store/ prefix applies storefront authentication scope
• The admin/ prefix applies admin authentication scope
• Routes outside these prefixes have no default authentication

HTTP Method Exports

Each route.ts exports named functions matching HTTP methods:

Export Name	HTTP Method
GET	GET
POST	POST
PUT	PUT
PATCH	PATCH
DELETE	DELETE

Route Handler Skeleton

// src/api/store/custom/route.ts
// Fetch live docs for MedusaRequest/MedusaResponse types
import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"

export const GET = async (req: MedusaRequest, res: MedusaResponse) => {
  const service = req.scope.resolve("my-module")
  res.json({ items: await service.listMyEntities() })
}

Route with Dynamic Parameter

// src/api/store/custom/[id]/route.ts
// Fetch live docs for path parameter access
export const GET = async (req: MedusaRequest, res: MedusaResponse) => {
  const item = await req.scope.resolve("my-module").retrieveMyEntity(req.params.id)
  res.json({ item })
}