API

Commerce API

v2.4.0

ACTIVE

https://api.commerce.io/v2

Production

production

All servers

https://api.commerce.io/v2

Production

production
https://staging-api.commerce.io/v2

Staging

staging
http://localhost:4000/v2

Local development

development

Security

BearerAuth ApiKey

Commerce API

OpenAPI 3.1.0 ACTIVE Commerce Platform Team

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.

Commerce Platform Team Apache 2.0 Terms of Service

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

Authentication and token management

POST /auth/login

Obtain access token

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

Auth

Parameters Request Body required Responses 3 Code Samples

No parameters.

User credentials

application/json

Commerce API 2.4.0

email* string(email)

password* string(password)

remember boolean Issue a long-lived refresh token (30 days) default: false

200 Token issued application/json

application/json

Commerce API 2.4.0

accessToken* string JWT access token

tokenType* string

expiresIn* integer Seconds until the access token expires

refreshToken string nullable Opaque refresh token (httpOnly cookie in web flow)

401 Invalid email or password application/json

application/json

Commerce API 2.4.0

code* string Machine-readable error code

message* string Human-readable error message

details array[object] nullable Field-level validation errors

429 Too many requests — rate limit exceeded application/json

application/json

Commerce API 2.4.0

code* string Machine-readable error code

message* string Human-readable error message

details array[object] nullable Field-level validation errors

cURL JavaScript Python

3 samples

curl -X POST https://api.commerce.io/v2/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"jane@example.com","password":"s3cr3t!"}'

JavaScript

const res = await fetch('https://api.commerce.io/v2/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: 'jane@example.com', password: 's3cr3t!' }),
});
const { accessToken } = await res.json();

Python

import requests

resp = requests.post(
    'https://api.commerce.io/v2/auth/login',
    json={'email': 'jane@example.com', 'password': 's3cr3t!'},
)
access_token = resp.json()['accessToken']

POST /auth/refresh

Refresh access token

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

Auth

Parameters Request Body required Responses 2

No parameters.

application/json

Commerce API 2.4.0

refreshToken* string Opaque refresh token from the login response

200 New tokens issued application/json

application/json

Commerce API 2.4.0

accessToken* string JWT access token

tokenType* string

expiresIn* integer Seconds until the access token expires

refreshToken string nullable Opaque refresh token (httpOnly cookie in web flow)

401 Refresh token invalid or expired application/json

application/json

Commerce API 2.4.0

code* string Machine-readable error code

message* string Human-readable error message

details array[object] nullable Field-level validation errors

DELETE /auth/logout

Revoke session

Revokes the current access token and its associated refresh token.

Auth BearerAuth

Parameters Request Body Responses 2

No parameters.

No request body.

204 Session revoked successfully

No response body.

401 Unauthorized — missing or invalid credentials application/json

application/json

Commerce API 2.4.0

code* string Machine-readable error code

message* string Human-readable error message

details array[object] nullable Field-level validation errors

Products

Product catalogue — create, read, update, delete

GET /products

List products

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

Products BearerAuth

Parameters 7 Request Body Responses 3 Code Samples

Query

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

No request body.

200 Paginated product list application/json

application/json

Commerce API 2.4.0

data array[object]

Commerce API 2.4.0

productId* string(uuid) read-only

sku* string Stock-keeping unit

name* string

description string nullable

price* number

currency* string ISO 4217 currency code

stock* integer

category* enum "footwear" "apparel" "accessories" "electronics" "home"

imageUrl string(uri) nullable

active* boolean default: true

createdAt string(date-time) read-only

updatedAt string(date-time) nullableread-only

total integer Total matching items

page integer

pageSize integer

pages integer Total pages

401 Unauthorized — missing or invalid credentials application/json

application/json

Commerce API 2.4.0

code* string Machine-readable error code

message* string Human-readable error message

details array[object] nullable Field-level validation errors

429 Too many requests — rate limit exceeded application/json

application/json

Commerce API 2.4.0

code* string Machine-readable error code

message* string Human-readable error message

details array[object] nullable Field-level validation errors

cURL JavaScript

2 samples

curl -G https://api.commerce.io/v2/products \
  -H 'Authorization: Bearer <token>' \
  -d page=1 \
  -d pageSize=20 \
  -d category=footwear

JavaScript

const params = new URLSearchParams({ page: '1', pageSize: '20', category: 'footwear' });
const res = await fetch(`https://api.commerce.io/v2/products?${params}`, {
  headers: { Authorization: `Bearer ${token}` },
});
const { data, total } = await res.json();

POST /products

Create product

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

Products BearerAuth

Parameters Request Body required Responses 5

No parameters.

application/json

Commerce API 2.4.0

sku* string

name* string

description string nullable

price* number

currency* string

stock* integer

category* enum "footwear" "apparel" "accessories" "electronics" "home"

imageUrl string(uri) nullable

active boolean default: true

201 Product created application/json

application/json

Commerce API 2.4.0

productId* string(uuid) read-only

sku* string Stock-keeping unit

name* string

description string nullable

price* number

currency* string ISO 4217 currency code

stock* integer

category* enum "footwear" "apparel" "accessories" "electronics" "home"

imageUrl string(uri) nullable

active* boolean default: true

createdAt string(date-time) read-only

updatedAt string(date-time) nullableread-only

400 Bad request — invalid input application/json

application/json

Commerce API 2.4.0

code* string Machine-readable error code

message* string Human-readable error message

details array[object] nullable Field-level validation errors

401 Unauthorized — missing or invalid credentials application/json

application/json

Commerce API 2.4.0

code* string Machine-readable error code

message* string Human-readable error message

details array[object] nullable Field-level validation errors

403 Forbidden — insufficient permissions application/json

application/json

Commerce API 2.4.0

code* string Machine-readable error code

message* string Human-readable error message

details array[object] nullable Field-level validation errors

409 SKU already exists application/json

application/json

Commerce API 2.4.0

code* string Machine-readable error code

message* string Human-readable error message

details array[object] nullable Field-level validation errors

GET /products/{productId}

Get product

Products BearerAuth

Parameters 1 Request Body Responses 3

Path

Name	In	Type	Req	Description
`productId`	path	`string (uuid)`	req	Product UUID

No request body.

200 Product detail application/json

application/json

Commerce API 2.4.0

productId* string(uuid) read-only

sku* string Stock-keeping unit

name* string

description string nullable

price* number

currency* string ISO 4217 currency code

stock* integer

category* enum "footwear" "apparel" "accessories" "electronics" "home"

imageUrl string(uri) nullable

active* boolean default: true

createdAt string(date-time) read-only

updatedAt string(date-time) nullableread-only

401 Unauthorized — missing or invalid credentials application/json

application/json

Commerce API 2.4.0

code* string Machine-readable error code

message* string Human-readable error message

details array[object] nullable Field-level validation errors

404 Resource not found application/json

application/json

Commerce API 2.4.0

code* string Machine-readable error code

message* string Human-readable error message

details array[object] nullable Field-level validation errors

PATCH /products/{productId}

Update product

Partially updates a product. Only supplied fields are changed.

Products BearerAuth

Parameters 1 Request Body required Responses 5

Path

Name	In	Type	Req	Description
`productId`	path	`string (uuid)`	req	Product UUID

application/json

Commerce API 2.4.0

sku* string

name* string

description string nullable

price* number

currency* string

stock* integer

category* enum "footwear" "apparel" "accessories" "electronics" "home"

imageUrl string(uri) nullable

active boolean default: true

200 Updated product application/json

application/json

Commerce API 2.4.0

productId* string(uuid) read-only

sku* string Stock-keeping unit

name* string

description string nullable

price* number

currency* string ISO 4217 currency code

stock* integer

category* enum "footwear" "apparel" "accessories" "electronics" "home"

imageUrl string(uri) nullable

active* boolean default: true

createdAt string(date-time) read-only

updatedAt string(date-time) nullableread-only

400 Bad request — invalid input application/json

application/json

Commerce API 2.4.0

code* string Machine-readable error code

message* string Human-readable error message

details array[object] nullable Field-level validation errors

401 Unauthorized — missing or invalid credentials application/json

application/json

Commerce API 2.4.0

code* string Machine-readable error code

message* string Human-readable error message

details array[object] nullable Field-level validation errors

403 Forbidden — insufficient permissions application/json

application/json

Commerce API 2.4.0

code* string Machine-readable error code

message* string Human-readable error message

details array[object] nullable Field-level validation errors

404 Resource not found application/json

application/json

Commerce API 2.4.0

code* string Machine-readable error code

message* string Human-readable error message

details array[object] nullable Field-level validation errors

DELETE /products/{productId}

Delete product

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

Products BearerAuth

Parameters 1 Request Body Responses 4

Path

Name	In	Type	Req	Description
`productId`	path	`string (uuid)`	req	Product UUID

No request body.

204 Deleted

No response body.

401 Unauthorized — missing or invalid credentials application/json

application/json

Commerce API 2.4.0

code* string Machine-readable error code

message* string Human-readable error message

details array[object] nullable Field-level validation errors

403 Forbidden — insufficient permissions application/json

application/json

Commerce API 2.4.0

code* string Machine-readable error code

message* string Human-readable error message

details array[object] nullable Field-level validation errors

404 Resource not found application/json

application/json

Commerce API 2.4.0

code* string Machine-readable error code

message* string Human-readable error message

details array[object] nullable Field-level validation errors

Orders

Order lifecycle management

GET /orders

List orders

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

Orders BearerAuth

Parameters 5 Request Body Responses 3

Query

Name	In	Type	Req	Description
`page`	query	`integer`	opt	Page number (1-based)
`pageSize`	query	`integer`	opt	Items per page (max 100)
`status`	query	`string`	opt	Filter by order status `pending` `confirmed` `shipped` `delivered` `cancelled` `refunded`
`from`	query	`string (date-time)`	opt	Created at or after (ISO 8601)
`to`	query	`string (date-time)`	opt	Created before (ISO 8601)

No request body.

200 Paginated order list application/json

application/json

Commerce API 2.4.0

data array[object]

Commerce API 2.4.0

orderId* string(uuid) read-only

customerId* string(uuid)

items* array[object]

Commerce API 2.4.0

productId* string(uuid)

sku string read-only

name string read-only

quantity* integer

unitPrice* number read-only

lineTotal number read-only

subtotal* number read-only

discount number nullableread-only

total* number read-only

currency* string

status* enum "pending" "confirmed" "shipped" "delivered" "cancelled" "refunded"

notes string nullable

createdAt string(date-time) read-only

updatedAt string(date-time) nullableread-only

total integer

page integer

pageSize integer

pages integer

401 Unauthorized — missing or invalid credentials application/json

application/json

Commerce API 2.4.0

code* string Machine-readable error code

message* string Human-readable error message

details array[object] nullable Field-level validation errors

429 Too many requests — rate limit exceeded application/json

application/json

Commerce API 2.4.0

code* string Machine-readable error code

message* string Human-readable error message

details array[object] nullable Field-level validation errors

POST /orders

Place order

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

Orders BearerAuth

Parameters Request Body required Responses 4 Code Samples

No parameters.

application/json

Commerce API 2.4.0

customerId* string(uuid)

items* array[object]

Commerce API 2.4.0

productId* string(uuid)

quantity* integer

notes string nullable

coupon string nullable Coupon code to apply

201 Order placed application/json

application/json

Commerce API 2.4.0

orderId* string(uuid) read-only

customerId* string(uuid)

items* array[object]

Commerce API 2.4.0

productId* string(uuid)

sku string read-only

name string read-only

quantity* integer

unitPrice* number read-only

lineTotal number read-only

subtotal* number read-only

discount number nullableread-only

total* number read-only

currency* string

status* enum "pending" "confirmed" "shipped" "delivered" "cancelled" "refunded"

notes string nullable

createdAt string(date-time) read-only

updatedAt string(date-time) nullableread-only

400 Bad request — invalid input application/json

application/json

Commerce API 2.4.0

code* string Machine-readable error code

message* string Human-readable error message

details array[object] nullable Field-level validation errors

401 Unauthorized — missing or invalid credentials application/json

application/json

Commerce API 2.4.0

code* string Machine-readable error code

message* string Human-readable error message

details array[object] nullable Field-level validation errors

422 Unprocessable entity — business rule violation application/json

application/json

Commerce API 2.4.0

code* string Machine-readable error code

message* string Human-readable error message

details array[object] nullable Field-level validation errors

cURL JavaScript

2 samples

curl -X POST https://api.commerce.io/v2/orders \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "customerId": "cust-uuid",
  "items": [
    { "productId": "prod-uuid-1", "quantity": 2 }
  ]
}'

JavaScript

const res = await fetch('https://api.commerce.io/v2/orders', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    customerId: 'cust-uuid',
    items: [{ productId: 'prod-uuid-1', quantity: 2 }],
  }),
});
const order = await res.json();

GET /orders/{orderId}

Get order

Orders BearerAuth

Parameters 1 Request Body Responses 4

Path

Name	In	Type	Req	Description
`orderId`	path	`string (uuid)`	req	Order UUID

No request body.

200 Order detail application/json

application/json

Commerce API 2.4.0

orderId* string(uuid) read-only

customerId* string(uuid)

items* array[object]

Commerce API 2.4.0

productId* string(uuid)

sku string read-only

name string read-only

quantity* integer

unitPrice* number read-only

lineTotal number read-only

subtotal* number read-only

discount number nullableread-only

total* number read-only

currency* string

status* enum "pending" "confirmed" "shipped" "delivered" "cancelled" "refunded"

notes string nullable

createdAt string(date-time) read-only

updatedAt string(date-time) nullableread-only

401 Unauthorized — missing or invalid credentials application/json

application/json

Commerce API 2.4.0

code* string Machine-readable error code

message* string Human-readable error message

details array[object] nullable Field-level validation errors

403 Forbidden — insufficient permissions application/json

application/json

Commerce API 2.4.0

code* string Machine-readable error code

message* string Human-readable error message

details array[object] nullable Field-level validation errors

404 Resource not found application/json

application/json

Commerce API 2.4.0

code* string Machine-readable error code

message* string Human-readable error message

details array[object] nullable Field-level validation errors

PATCH /orders/{orderId}/status

Update order status

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

Orders BearerAuth

Parameters 1 Request Body required Responses 6

Path

Name	In	Type	Req	Description
`orderId`	path	`string (uuid)`	req	Order UUID

application/json

Commerce API 2.4.0

status* enum "confirmed" "shipped" "delivered" "cancelled" "refunded"

reason string nullable Required when cancelling or refunding

200 Order status updated application/json

application/json

Commerce API 2.4.0

orderId* string(uuid) read-only

customerId* string(uuid)

items* array[object]

Commerce API 2.4.0

productId* string(uuid)

sku string read-only

name string read-only

quantity* integer

unitPrice* number read-only

lineTotal number read-only

subtotal* number read-only

discount number nullableread-only

total* number read-only

currency* string

status* enum "pending" "confirmed" "shipped" "delivered" "cancelled" "refunded"

notes string nullable

createdAt string(date-time) read-only

updatedAt string(date-time) nullableread-only

400 Bad request — invalid input application/json

application/json

Commerce API 2.4.0

code* string Machine-readable error code

message* string Human-readable error message

details array[object] nullable Field-level validation errors

401 Unauthorized — missing or invalid credentials application/json

application/json

Commerce API 2.4.0

code* string Machine-readable error code

message* string Human-readable error message

details array[object] nullable Field-level validation errors

403 Forbidden — insufficient permissions application/json

application/json

Commerce API 2.4.0

code* string Machine-readable error code

message* string Human-readable error message

details array[object] nullable Field-level validation errors

404 Resource not found application/json

application/json

Commerce API 2.4.0

code* string Machine-readable error code

message* string Human-readable error message

details array[object] nullable Field-level validation errors

422 Unprocessable entity — business rule violation application/json

application/json

Commerce API 2.4.0

code* string Machine-readable error code

message* string Human-readable error message

details array[object] nullable Field-level validation errors