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/:

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:

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 })
}

Request Validation with Zod

Medusa v2 uses Zod schemas for request body and query parameter validation:

Validation File Convention

Validator Skeleton

// src/api/store/custom/validators.ts
// Fetch live docs for Zod schema integration
import { z } from "zod"

export const PostStoreCustom = z.object({
  name: z.string(),
  description: z.string().optional(),
})

Validators are linked to routes via middleware configuration.

Middleware Configuration

All middleware is configured in src/api/middlewares.ts:

// src/api/middlewares.ts — Fetch live docs for defineMiddlewares API
import { defineMiddlewares, validateAndTransformBody } from "@medusajs/framework/http"
import { PostStoreCustom } from "./store/custom/validators"

export default defineMiddlewares({
  routes: [{ matcher: "/store/custom", method: "POST",
    middlewares: [validateAndTransformBody(PostStoreCustom)] }],
})

Built-in Middleware Utilities

Authentication Middleware

Requiring Customer Authentication

// In middlewares.ts routes array
// Fetch live docs for authenticate() options
{
  matcher: "/store/custom/me",
  middlewares: [authenticate("customer", ["session", "bearer"])],
}

Additional Data Pattern

Medusa v2 supports passing extra data through built-in API routes to workflow hooks:

• Client sends extra fields in the request body under additional_data
• Validated by defining an additionalDataValidator in middleware
• Received in workflow hooks as additional_data

This allows extending core commerce flows (e.g., adding custom fields to product creation) without overriding API routes.

Error Handling

Best Practices

• Use file-based routing conventions -- do not register routes programmatically
• Always validate request bodies with Zod schemas via validateAndTransformBody
• Resolve services from req.scope -- never import services directly
• Use the additional_data pattern to extend core routes instead of overriding them
• Apply authenticate() middleware explicitly for routes requiring auth outside default scopes
• Return consistent response shapes: { item } for single, { items, count, offset, limit } for lists
• Keep route handlers thin -- delegate business logic to workflows or services

Fetch the Medusa API route documentation for exact file conventions, middleware utilities, and Zod integration patterns before implementing.