Nexa Commerce API v1

Nexa Commerce is a fictional cloud-based B2B commerce platform. Its REST API covers customer, product, order, payment, shipment, and webhook integrations.

The API follows a practical business flow: a customer portal creates an order, payment is recorded, fulfillment progresses through shipment states, and webhooks keep downstream systems synchronized.

Audience

Backend developers, integration engineers, and solution architects connecting an ERP, storefront, or fulfillment system to Nexa Commerce.

Base URL

https://api.nexacommerce.example.com/v1

Core resources

Authentication

Send a bearer token with every authenticated request. Requests and responses use JSON.

curl https://api.nexacommerce.example.com/v1/customers \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -H "Accept: application/json"

Create your first customer

curl -X POST https://api.nexacommerce.example.com/v1/customers \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Industrial Supplies","email":"ops@acme.example"}'

Pagination

Collection endpoints use cursor-based pagination. Treat the cursor as opaque — don't decode or construct it manually.

GET /orders?limit=25&cursor=eyJjcmVhdGVkX2F0Ijoi...

{
  "data": [ ... ],
  "pagination": { "limit": 25, "next_cursor": "..." }
}

Sorting and filtering

The default sort is -created_at. Resource-specific filters combine with logical AND. created_after and created_before accept RFC 3339 timestamps.

Idempotency

Order and payment creation accept an Idempotency-Key header so retries are safe to send.

Nexa Commerce models commerce as a small set of connected resources.

CUSTOMER  1 ───────── N  ORDER
                         │
                         ├── 1:N  ORDER ITEMS ── N:1 ── PRODUCT
                         ├── 1:N  PAYMENTS
                         └── 1:N  SHIPMENTS

Resource snapshots

Order items preserve the product SKU, name, and unit price at the time of purchase, so later catalog changes never rewrite historical orders.

Identifier patterns

The order state model makes business transitions explicit rather than implicit in application code.

DRAFT
  │
  ▼
PENDING ─────────────► CANCELLED
  │
  ▼
PAID
  │
  ▼
PROCESSING
  │
  ▼
SHIPPED
  │
  ▼
DELIVERED

Cancellation is a business action with side effects, not a data deletion — so the API models it as POST /orders/{orderId}/cancel rather than DELETE.

All 25 operations in Nexa Commerce v1, grouped by resource. Each entry follows the same order: method and path, purpose, parameters, then a sample request and response.

{
  "name": "Acme Industrial Supplies",
  "email": "ops@acme.example",
  "phone": "+1-555-0100"
}

{
  "id": "cus_01HZX8M4Y7",
  "name": "Acme Industrial Supplies",
  "email": "ops@acme.example",
  "status": "active"
}

{
  "data": [
    { "id": "cus_01HZX8M4Y7", "name": "Acme Industrial Supplies", "email": "ops@acme.example" }
  ],
  "pagination": { "limit": 25, "next_cursor": null }
}

{
  "id": "cus_01HZX8M4Y7",
  "name": "Acme Industrial Supplies",
  "email": "ops@acme.example",
  "status": "active"
}

{
  "phone": "+1-555-0199",
  "status": "active"
}

{
  "id": "cus_01HZX8M4Y7",
  "name": "Acme Industrial Supplies",
  "phone": "+1-555-0199",
  "status": "active"
}

{
  "sku": "IND-1001",
  "name": "Industrial Pump",
  "description": "Standard B2B pump",
  "unit_price": 125.00,
  "currency": "USD"
}

{
  "id": "prod_01HZX9A2K1",
  "sku": "IND-1001",
  "name": "Industrial Pump",
  "status": "active",
  "unit_price": 125.00,
  "currency": "USD"
}

{
  "data": [
    { "id": "prod_01HZX9A2K1", "sku": "IND-1001", "name": "Industrial Pump", "status": "active" }
  ],
  "pagination": { "limit": 25, "next_cursor": null }
}

{
  "id": "prod_01HZX9A2K1",
  "sku": "IND-1001",
  "name": "Industrial Pump",
  "status": "active",
  "unit_price": 125.00,
  "currency": "USD"
}

{
  "name": "Industrial Pump — Gen 2",
  "unit_price": 139.00
}

{
  "id": "prod_01HZX9A2K1",
  "sku": "IND-1001",
  "name": "Industrial Pump — Gen 2",
  "unit_price": 139.00,
  "currency": "USD"
}

{
  "customer_id": "cus_01HZX8M4Y7",
  "currency": "USD",
  "items": [
    { "product_id": "prod_01HZX9A2K1", "quantity": 10 }
  ],
  "billing_address": {
    "line1": "100 Market Street",
    "city": "Austin",
    "state": "TX",
    "postal_code": "78701",
    "country": "US"
  },
  "shipping_address": { "...": "..." }
}

{
  "id": "ord_01HZXA6D3P",
  "customer_id": "cus_01HZX8M4Y7",
  "status": "pending",
  "currency": "USD",
  "subtotal": 1250.00,
  "tax": 100.00,
  "shipping_cost": 25.00,
  "total": 1375.00
}

{
  "data": [
    { "id": "ord_01HZXA6D3P", "customer_id": "cus_01HZX8M4Y7", "status": "pending", "total": 1375.00 }
  ],
  "pagination": { "limit": 25, "next_cursor": null }
}

{
  "id": "ord_01HZXA6D3P",
  "customer_id": "cus_01HZX8M4Y7",
  "status": "pending",
  "currency": "USD",
  "total": 1375.00,
  "items": []
}

{
  "shipping_address": {
    "line1": "200 Congress Ave",
    "city": "Austin",
    "state": "TX",
    "postal_code": "78701",
    "country": "US"
  }
}

{
  "id": "ord_01HZXA6D3P",
  "status": "pending",
  "shipping_address": {
    "line1": "200 Congress Ave",
    "city": "Austin"
  }
}

{
  "id": "ord_01HZXA6D3P",
  "status": "cancelled",
  "updated_at": "2026-09-12T09:02:00Z"
}

{
  "product_id": "prod_01HZX9A2K1",
  "quantity": 5
}

{
  "id": "item_01HZXB1N5K",
  "product_id": "prod_01HZX9A2K1",
  "sku": "IND-1001",
  "name": "Industrial Pump",
  "quantity": 5,
  "unit_price": 125.00,
  "subtotal": 625.00
}

{ "quantity": 8 }

{
  "id": "item_01HZXB1N5K",
  "quantity": 8,
  "unit_price": 125.00,
  "subtotal": 1000.00
}

{
  "amount": 1375.00,
  "currency": "USD",
  "method": "purchase_order",
  "provider": "internal"
}

{
  "id": "pay_01HZXC1M6N",
  "order_id": "ord_01HZXA6D3P",
  "amount": 1375.00,
  "currency": "USD",
  "status": "processing",
  "method": "purchase_order",
  "provider": "internal"
}

{
  "data": [
    { "id": "pay_01HZXC1M6N", "order_id": "ord_01HZXA6D3P", "status": "processing", "amount": 1375.00 }
  ],
  "pagination": { "limit": 25, "next_cursor": null }
}

{
  "id": "pay_01HZXC1M6N",
  "order_id": "ord_01HZXA6D3P",
  "status": "succeeded",
  "amount": 1375.00,
  "currency": "USD"
}

{
  "data": [
    { "id": "shp_01HZXD7K3R", "order_id": "ord_01HZXA6D3P", "status": "shipped", "carrier": "Nexa Logistics", "tracking_number": "NX123456789" }
  ],
  "pagination": { "limit": 25, "next_cursor": null }
}

{
  "id": "shp_01HZXD7K3R",
  "order_id": "ord_01HZXA6D3P",
  "status": "shipped",
  "carrier": "Nexa Logistics",
  "tracking_number": "NX123456789"
}

{
  "url": "https://erp.acme.example/webhooks/nexa",
  "events": ["order.paid", "order.shipped", "order.delivered"]
}

{
  "id": "wh_01HZXE3P2D",
  "url": "https://erp.acme.example/webhooks/nexa",
  "events": ["order.paid", "order.shipped", "order.delivered"],
  "status": "active"
}

{
  "data": [
    { "id": "wh_01HZXE3P2D", "url": "https://erp.acme.example/webhooks/nexa", "status": "active" }
  ],
  "pagination": { "limit": 25, "next_cursor": null }
}

Webhooks let downstream systems react to commerce events without repeatedly polling the API.

Recommended consumer pattern

1. Verify the delivery's security mechanism.
2. Parse the event type and resource identifier.
3. Persist the event or idempotency key before processing.
4. Return a successful response quickly.
5. Perform long-running work asynchronously.

Errors use a stable envelope so clients can handle failures consistently across every resource.

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "One or more parameters are invalid.",
    "request_id": "req_01HZQ2M8F1",
    "details": [
      { "code": "INVALID_ENUM_VALUE", "message": "status must be active, inactive, or suspended.", "param": "status", "location": "query" },
      { "code": "VALUE_OUT_OF_RANGE", "message": "limit must be between 1 and 100.", "param": "limit", "location": "query" }
    ]
  }
}

Status code guide

Rate limiting

The API permits 60 requests per minute. Responses may include X-RateLimit-Limit, X-RateLimit-Remaining, and Retry-After.

A realistic integration combines synchronous API calls with asynchronous events.

1  POST /customers
        │
        ▼
2  POST /orders
        │
        ▼
3  POST /orders/{orderId}/payments
        │
        ├──── webhook: order.paid ────► ERP
        │
        ▼
4  GET /orders/{orderId}/shipments
        │
        └──── webhook: order.delivered ─► ERP

Integration guidance

Use API responses for immediate state and webhooks for asynchronous state changes. Avoid building critical workflows around polling alone.

Endpoint-first reference

Every endpoint follows the same reading order: method and path, then purpose, parameters, request, and response — so a reader can scan and compare operations quickly.

Centralized conventions

Pagination, sorting, filtering, validation, errors, rate limits, and authentication are each defined once as API-wide conventions rather than repeated per endpoint.

Business-aware guidance

The documentation explains behavior that can't be inferred from HTTP verbs alone — order cancellation, editable order states, payment processing, and historical item snapshots.

Machine-readable foundation

A companion OpenAPI 3.1 specification provides reusable parameters, schemas, responses, security definitions, and resource-specific collection schemas.