Commerce API
ACTIVEThe 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
Common responses
Auth
3
Authentication and token management
Auth
3Authentication 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.
No parameters.
User credentials
application/json
false
200 Token issued application/json
application/json
401 Invalid email or password application/json
application/json
429 Too many requests — rate limit exceeded application/json
application/json
curl -X POST https://api.commerce.io/v2/auth/login \
-H 'Content-Type: application/json' \
-d '{"email":"jane@example.com","password":"s3cr3t!"}'
POST
/auth/refresh
Refresh access token
Issues a new access token using a valid refresh token. The old refresh token is rotated.
No parameters.
application/json
200 New tokens issued application/json
application/json
401 Refresh token invalid or expired application/json
application/json
DELETE
/auth/logout
Revoke session
Revokes the current access token and its associated refresh token.
No parameters.
No request body.
204 Session revoked successfully
No response body.
401 Unauthorized — missing or invalid credentials application/json
application/json
Products
5
Product catalogue — create, read, update, delete
Products
5Product catalogue — create, read, update, delete
GET
/products
List products
Returns a paginated, filterable list of products in the catalogue.
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
|
No request body.
200 Paginated product list application/json
application/json
"footwear"
"apparel"
"accessories"
"electronics"
"home"
true
401 Unauthorized — missing or invalid credentials application/json
application/json
429 Too many requests — rate limit exceeded application/json
application/json
curl -G https://api.commerce.io/v2/products \
-H 'Authorization: Bearer <token>' \
-d page=1 \
-d pageSize=20 \
-d category=footwear
POST
/products
Create product
Adds a new product to the catalogue. Requires `products:write` permission.
No parameters.
application/json
"footwear"
"apparel"
"accessories"
"electronics"
"home"
true
201 Product created application/json
application/json
"footwear"
"apparel"
"accessories"
"electronics"
"home"
true
400 Bad request — invalid input application/json
application/json
401 Unauthorized — missing or invalid credentials application/json
application/json
403 Forbidden — insufficient permissions application/json
application/json
409 SKU already exists application/json
application/json
GET
/products/{productId}
Get product
Path
| Name | In | Type | Required | Description |
|---|---|---|---|---|
productId
|
path |
string (uuid)
|
required |
Product UUID
|
No request body.
200 Product detail application/json
application/json
"footwear"
"apparel"
"accessories"
"electronics"
"home"
true
401 Unauthorized — missing or invalid credentials application/json
application/json
404 Resource not found application/json
application/json
PATCH
/products/{productId}
Update product
Partially updates a product. Only supplied fields are changed.
Path
| Name | In | Type | Required | Description |
|---|---|---|---|---|
productId
|
path |
string (uuid)
|
required |
Product UUID
|
application/json
"footwear"
"apparel"
"accessories"
"electronics"
"home"
true
200 Updated product application/json
application/json
"footwear"
"apparel"
"accessories"
"electronics"
"home"
true
400 Bad request — invalid input application/json
application/json
401 Unauthorized — missing or invalid credentials application/json
application/json
403 Forbidden — insufficient permissions application/json
application/json
404 Resource not found application/json
application/json
DELETE
/products/{productId}
Delete product
Soft-deletes a product. Orders referencing this product are unaffected.
Path
| Name | In | Type | Required | Description |
|---|---|---|---|---|
productId
|
path |
string (uuid)
|
required |
Product UUID
|
No request body.
204 Deleted
No response body.
401 Unauthorized — missing or invalid credentials application/json
application/json
403 Forbidden — insufficient permissions application/json
application/json
404 Resource not found application/json
application/json
Orders
4
Order lifecycle management
Orders
4Order lifecycle management
GET
/orders
List orders
Returns a paginated list of orders. Non-admin users see only their own orders.
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)
|
No request body.
200 Paginated order list application/json
application/json
"pending"
"confirmed"
"shipped"
"delivered"
"cancelled"
"refunded"
401 Unauthorized — missing or invalid credentials application/json
application/json
429 Too many requests — rate limit exceeded application/json
application/json
POST
/orders
Place order
Creates a new order. Stock is reserved atomically at creation time.
No parameters.
application/json
201 Order placed application/json
application/json
"pending"
"confirmed"
"shipped"
"delivered"
"cancelled"
"refunded"
400 Bad request — invalid input application/json
application/json
401 Unauthorized — missing or invalid credentials application/json
application/json
422 Unprocessable entity — business rule violation application/json
application/json
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 }
]
}'
GET
/orders/{orderId}
Get order
Path
| Name | In | Type | Required | Description |
|---|---|---|---|---|
orderId
|
path |
string (uuid)
|
required |
Order UUID
|
No request body.
200 Order detail application/json
application/json
"pending"
"confirmed"
"shipped"
"delivered"
"cancelled"
"refunded"
401 Unauthorized — missing or invalid credentials application/json
application/json
403 Forbidden — insufficient permissions application/json
application/json
404 Resource not found application/json
application/json
PATCH
/orders/{orderId}/status
Update order status
Transitions an order to a new status. Only valid state transitions are accepted.
Path
| Name | In | Type | Required | Description |
|---|---|---|---|---|
orderId
|
path |
string (uuid)
|
required |
Order UUID
|
application/json
"confirmed"
"shipped"
"delivered"
"cancelled"
"refunded"
200 Order status updated application/json
application/json
"pending"
"confirmed"
"shipped"
"delivered"
"cancelled"
"refunded"
400 Bad request — invalid input application/json
application/json
401 Unauthorized — missing or invalid credentials application/json
application/json
403 Forbidden — insufficient permissions application/json
application/json
404 Resource not found application/json
application/json
422 Unprocessable entity — business rule violation application/json
application/json