API Reference

Overview

The NexusCommerce REST API is the programmatic interface to all platform features. The API is built with NestJS 11 and follows REST conventions: resources are nouns, HTTP verbs define actions, and responses use consistent JSON envelopes.

Base URL:

https://your-nexuscommerce.com/api

API Version: v1 (implicit in all paths)

Content-Type: application/json for all requests and responses.

Key Concepts

Authentication — All API requests require a bearer token in the Authorization header. Tokens are either:

• User JWTs — Issued by Supabase Auth on login. Expire after 24 hours. Used by the web frontend.
• API Keys — Long-lived bearer tokens generated in Settings > API Keys. Used for integrations.

Tenant Isolation — Every request must include the X-Tenant-ID header. The API validates that the token has access to the specified tenant and enforces row-level data isolation.

Pagination — List endpoints use cursor-based pagination. The response includes data, meta.total, meta.page, meta.limit, and meta.nextCursor fields.

Error Responses — All errors follow a consistent shape:

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Product with SKU SKU-001 not found",
    "details": {}
  }
}

Getting Started

Authentication

Include your API key in every request:

curl https://your-nexuscommerce.com/api/products \
  -H "Authorization: Bearer nxc_live_abc123..." \
  -H "X-Tenant-ID: 3714240b-2e06-4c35-8856-ccc1c096323e"

A successful response returns HTTP 200 with a JSON body. An invalid or expired token returns HTTP 401.

Rate Limits

The API enforces rate limits per API key:

Rate limit headers are included in every response:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1741787460

When the limit is exceeded, the API returns HTTP 429 with a Retry-After header.

Features

Standard Response Envelope

All list responses:

{
  "data": [...],
  "meta": {
    "total": 1248,
    "page": 1,
    "limit": 50,
    "nextCursor": "cursor_abc123"
  }
}

All single-resource responses:

{
  "data": { ... }
}

Pagination

Use limit and cursor query parameters:

GET /api/products?limit=50&cursor=cursor_abc123

Iterate through all pages by following the nextCursor until it is null.

Filtering

Most list endpoints support filtering via query parameters:

GET /api/orders?status=confirmed&marketplace=amazon_us&start_date=2026-03-01

Sorting

Sort with sort (field name) and order (asc or desc):

GET /api/products?sort=created_at&order=desc

Field Selection

Request only specific fields with the fields parameter:

GET /api/products?fields=sku,title,status,price

Webhook Signatures

Outbound webhooks from NexusCommerce to your systems are signed with HMAC-SHA256. Verify signatures using your webhook secret from Settings > Notifications:

X-NexusCommerce-Signature: sha256=<hmac>

Health Check

No authentication required:

GET /api/health

Response:

{
  "status": "ok",
  "version": "2.0.0",
  "timestamp": "2026-03-12T14:32:01.123Z"
}

Configuration

API behavior can be configured per-key in Settings > API Keys: