API Overview

rCommerce exposes a versioned REST API. All endpoints accept and return JSON.

Base URL

https://your-domain.com/api/v1

Authentication

Three authentication methods:

JWT Bearer token

curl -H "Authorization: Bearer <token>" https://api.example.com/api/v1/products

Obtained via /api/v1/auth/login. Tokens expire after 24 hours (configurable).

API key

curl -H "Authorization: Bearer <api_key>" https://api.example.com/api/v1/products

Created via CLI: rcommerce api-key create --name "My App" --scopes "products:read,orders:write"

Public endpoints

Some endpoints require no authentication:

• GET /api/v1/products — list products
• GET /api/v1/products/:id — get product
• GET /api/v1/categories — list categories
• POST /api/v1/auth/register — create account
• POST /api/v1/auth/login — authenticate

Pagination

List endpoints return paginated results:

{
  "products": [...],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 150,
    "total_pages": 8
  }
}

Query parameters: ?page=2&per_page=50

Error format

{
  "error": {
    "code": "validation_error",
    "message": "Field 'title' is required"
  }
}

HTTP status codes: 400 validation, 401 unauthorized, 403 forbidden, 404 not found, 429 rate limited, 500 server error.

Rate limiting

Default: 60 requests/minute per IP. API keys get higher limits (configurable).

WebSocket

Real-time events via WebSocket at /api/v1/ws. Requires JWT authentication.

Endpoints

Resource	Endpoints
Products	CRUD, variants, images, categories
Orders	CRUD, status transitions, fulfillments
Customers	CRUD, addresses
Cart	Add/remove items, totals
Checkout	Initiate, select shipping, complete
Payments	Process, refund
Shipping	Rates, tracking
Webhooks	CRUD, event subscriptions

CLI reference

Every API operation has a CLI equivalent:

rcommerce product list
rcommerce order get <id>
rcommerce api-key create --name "Integration" --scopes "read"

See CLI reference for the full command list.