Skip to main content
Commerce API
ACTIVE

Commerce API

ACTIVE
OpenAPI 3.1.0 v2.4.0 Multi-tenant e-commerce platform API

The Commerce API provides a complete set of endpoints for managing products, orders, customers, and authentication. All requests must include a valid bearer token obtained from the `/auth/login` endpoint, except where otherwise noted. Rate limits are enforced per API key at 1 000 requests / minute for standard plans and 10 000 for enterprise.

Security schemes

BearerAuth Short-lived JWT (1 h). Obtain via POST /auth/login.
ApiKey Server-to-server API key. Issued per integration in the dashboard.

Common responses

200 OK 201 Created 204 No Content 400 Bad Request 401 Unauthorized 403 Forbidden 404 Not Found 422 Unprocessable Entity 429 Too Many Requests

Auth

3

Authentication and token management

POST /auth/login

Authenticates a user with email and password and returns a short-lived JWT access token plus an opaque refresh token.

Auth

No parameters.

POST /auth/refresh

Issues a new access token using a valid refresh token. The old refresh token is rotated.

Auth

No parameters.

DELETE /auth/logout

Revokes the current access token and its associated refresh token.

Auth BearerAuth

No parameters.

Products

5

Product catalogue — create, read, update, delete

GET /products

Returns a paginated, filterable list of products in the catalogue.

Products BearerAuth

Query

Name In Type Required Description
page
query integer optional
Page number (1-based) e.g. 1
pageSize
query integer optional
Items per page (max 100) e.g. 20
search
query string optional
Full-text search on name and description
category
query string optional
Filter by product category
footwear apparel accessories electronics home
active
query boolean optional
Filter by active status
sort
query string optional
Sort field
name price stock createdAt
order
query string optional
Sort direction
asc desc
POST /products

Adds a new product to the catalogue. Requires `products:write` permission.

Products BearerAuth

No parameters.

GET /products/{productId}
Products BearerAuth

Path

Name In Type Required Description
productId
path string (uuid) required
Product UUID
PATCH /products/{productId}

Partially updates a product. Only supplied fields are changed.

Products BearerAuth

Path

Name In Type Required Description
productId
path string (uuid) required
Product UUID
DELETE /products/{productId}

Soft-deletes a product. Orders referencing this product are unaffected.

Products BearerAuth

Path

Name In Type Required Description
productId
path string (uuid) required
Product UUID

Orders

4

Order lifecycle management

GET /orders

Returns a paginated list of orders. Non-admin users see only their own orders.

Orders BearerAuth

Query

Name In Type Required Description
page
query integer optional
Page number (1-based) e.g. 1
pageSize
query integer optional
Items per page (max 100) e.g. 20
status
query string optional
Filter by order status
pending confirmed shipped delivered cancelled refunded
from
query string (date-time) optional
Created at or after (ISO 8601)
to
query string (date-time) optional
Created before (ISO 8601)
POST /orders

Creates a new order. Stock is reserved atomically at creation time.

Orders BearerAuth

No parameters.

GET /orders/{orderId}
Orders BearerAuth

Path

Name In Type Required Description
orderId
path string (uuid) required
Order UUID
PATCH /orders/{orderId}/status

Transitions an order to a new status. Only valid state transitions are accepted.

Orders BearerAuth

Path

Name In Type Required Description
orderId
path string (uuid) required
Order UUID