API Overview

API Overview

The ecommus REST API is served by Fastify 5 on port 4000. It provides two namespaces:

• /api/admin/* — Protected by JWT auth + tenant isolation. Used by the admin panel.
• /api/storefront/* — Public-facing. Serves storefront data (products, cart, checkout).

Swagger UI

When running locally, the full interactive API docs are available at:

http://localhost:4000/docs

The Swagger UI is powered by @fastify/swagger-ui and auto-generated from Zod schemas on all routes.

Authentication

All /api/admin/* routes require a valid JWT in the Authorization header:

Authorization: Bearer <access-token>

Plus a tenant identifier (one of):

• X-Tenant-Id: <tenantId> header
• Subdomain: mystore.ecommus.app

See Authentication for the full auth flow.

Admin Routes

Authentication

Method	Path	Description
POST	/api/admin/auth/login	Login with email + password
POST	/api/admin/auth/refresh	Refresh access token
POST	/api/admin/auth/logout	Invalidate refresh token

Products

Method	Path	Description
GET	/api/admin/products	List products (paginated, filterable)
POST	/api/admin/products	Create product
GET	/api/admin/products/:id	Get product by ID
PUT	/api/admin/products/:id	Update product
DELETE	/api/admin/products/:id	Soft-delete product

Orders

Method	Path	Description
GET	/api/admin/orders	List orders
GET	/api/admin/orders/:id	Get order with items
PUT	/api/admin/orders/:id/status	Update order status
POST	/api/admin/orders/:id/refund	Initiate refund

Customers

Method	Path	Description
GET	/api/admin/customers	List customers
GET	/api/admin/customers/:id	Get customer profile
PUT	/api/admin/customers/:id	Update customer

Categories

Method	Path	Description
GET	/api/admin/categories	List categories (tree)
POST	/api/admin/categories	Create category
PUT	/api/admin/categories/:id	Update category
DELETE	/api/admin/categories/:id	Delete category

Plugins

Method	Path	Description
GET	/api/admin/plugins	List loaded plugins with schemas
GET	/api/admin/plugins/:name/settings	Get plugin settings (tenant-scoped)
PUT	/api/admin/plugins/:name/settings	Save plugin settings

Storefront Routes

Products

Method	Path	Description
GET	/api/storefront/products	List published products
GET	/api/storefront/products/:slug	Get product by slug
GET	/api/storefront/search	Full-text + semantic product search

Cart

Method	Path	Description
GET	/api/storefront/cart	Get current cart
POST	/api/storefront/cart/items	Add item to cart
PUT	/api/storefront/cart/items/:id	Update cart item qty
DELETE	/api/storefront/cart/items/:id	Remove item from cart

Checkout

Method	Path	Description
POST	/api/storefront/checkout	Create order from cart
GET	/api/storefront/checkout/shipping-methods	Available shipping methods
GET	/api/storefront/checkout/payment-methods	Available payment methods

Account

Method	Path	Description
POST	/api/storefront/auth/register	Register customer
POST	/api/storefront/auth/login	Login customer
GET	/api/storefront/account/orders	Customer order history

Response Format

All endpoints return JSON. Errors follow the format:

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "product_not_found"
}

Success responses return the resource directly (no wrapper):

{
  "id": "cm_abc123",
  "name": "Blue T-Shirt",
  "price": 9900,
  "currency": "RON"
}