Orders API

REST API endpoints for reading and managing orders across all connected marketplaces.

Overview

The Orders API provides access to all orders from all connected marketplaces. Use it to read order data, update fulfillment status, and confirm shipments programmatically. All endpoints require the orders:read or orders:write scope.

Endpoints

List Orders

GET /api/orders

Query Parameters:

Parameter	Type	Description
limit	integer	Results per page (default: 50, max: 200)
cursor	string	Pagination cursor
status	string	Filter: `pending`, `confirmed`, `processing`, `shipped`, `delivered`, `completed`, `cancelled`
marketplace	string	Filter to specific marketplace
fulfillment_method	string	`FBM`, `FBA`, or `FBS`
start_date	string	ISO 8601 date (orders placed on or after)
end_date	string	ISO 8601 date (orders placed on or before)
has_returns	boolean	Filter to orders with at least one return

Example Response:

{
  "data": [
    {
      "id": "ord_01HXK9MZPQ3B8C7D2E5F6G",
      "external_order_id": "123-4567890-1234567",
      "marketplace": "amazon_us",
      "status": "confirmed",
      "fulfillment_method": "FBM",
      "total_amount": 27.98,
      "currency": "USD",
      "created_at": "2026-03-12T09:00:00.000Z",
      "line_items": [
        {
          "sku": "SKU-001",
          "title": "Blue Widget 500ml",
          "quantity": 2,
          "unit_price": 13.49,
          "line_total": 26.98
        }
      ]
    }
  ],
  "meta": {"total": 8421, "limit": 50, "nextCursor": "cursor_xyz789"}
}

Get Order

GET /api/orders/:orderId

Returns a single order with full detail including line items, shipping address, and sync history.

Confirm Shipment

POST /api/orders/:orderId/shipment

Required scope: orders:write

Submit shipment confirmation. NexusCommerce pushes the confirmation to the originating marketplace.

Request Body:

{
  "carrier": "DHL",
  "tracking_number": "1234567890",
  "shipped_date": "2026-03-12T10:00:00.000Z",
  "line_items": [
    {"external_line_item_id": "item_123", "quantity": 2}
  ]
}

Response: HTTP 200 with the updated order.

Cancel Order

POST /api/orders/:orderId/cancel

Required scope: orders:write

Request cancellation on the originating marketplace.

Request Body:

{
  "reason": "CustomerRequest"
}

Response: HTTP 202 Accepted. Cancellation is subject to marketplace approval.

Bulk Shipment

POST /api/orders/bulk-shipment

Required scope: orders:write

Confirm shipments for multiple orders at once.

Request Body:

{
  "shipments": [
    {
      "order_id": "ord_01HX...",
      "carrier": "DHL",
      "tracking_number": "1234567890"
    },
    {
      "order_id": "ord_01HY...",
      "carrier": "UPS",
      "tracking_number": "1Z999AA10123456784"
    }
  ]
}

Response:

{
  "data": {
    "succeeded": 2,
    "failed": 0,
    "errors": []
  }
}

Error Codes

Code	HTTP Status	Description
`ORDER_NOT_FOUND`	404	Order ID does not exist
`INVALID_STATUS_TRANSITION`	422	Cannot transition order to requested status
`ALREADY_SHIPPED`	409	Order already has a confirmed shipment
`MARKETPLACE_REJECTION`	422	Marketplace rejected the shipment confirmation

On this page