Orders API Reference

This page documents the Orders endpoints in the Core API.

List Orders

Returns a paginated list of orders with optional filtering.

URL: /v1/orders

Method: GET

Auth required: Yes

Parameters:

Example Request:

curl -X GET "https://api.uos.example.com/v1/orders?channel_id=channel-123&status=processing&page=1&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Success Response:

• Code: 200 OK
• Content:

{
  "data": [
    {
      "id": "order-123",
      "version": 2,
      "channel_id": "channel-123",
      "status": "processing",
      "order_number": "ORD-001",
      "order_date": "2023-06-01T12:00:00Z",
      "customer_info": { ... },
      "items": [ ... ],
      "totals": { ... },
      "shipping_info": { ... },
      "created_at": "2023-06-01T12:00:00Z",
      "updated_at": "2023-06-01T12:30:00Z"
    },
    // Additional orders...
  ],
  "pagination": {
    "total": 42,
    "page": 1,
    "limit": 10,
    "totalPages": 5
  }
}

Error Responses:

• Code: 400 Bad Request
  • Content: { "error": "Missing required channel_id parameter" }

Get Order by ID

Returns detailed information about a specific order.

URL: /v1/orders/{orderId}

Method: GET

Auth required: Yes

Parameters:

Example Request:

curl -X GET "https://api.uos.example.com/v1/orders/order-123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Success Response:

• Code: 200 OK
• Content: Full order object

Error Responses:

• Code: 404 Not Found
  • Content: { "error": { "code": "ORDER_NOT_FOUND", "message": "No order found with ID or order number" } }

Create Order

Creates a new order in the system.

URL: /v1/orders

Method: POST

Auth required: Yes

Request Body:

Example Request:

curl -X POST "https://api.uos.example.com/v1/orders" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "channel-123",
    "order_number": "ORD-001",
    "order_date": "2023-06-01T12:00:00Z",
    "customer_info": {
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "123-456-7890"
    },
    "items": [
      {
        "item_id": "PROD-001",
        "name": "Product 1",
        "quantity": 2,
        "price": 9.99
      }
    ],
    "totals": {
      "subtotal": 19.98,
      "shipping": 5.00,
      "tax": 2.50,
      "total": 27.48
    },
    "shipping_info": {
      "method": "standard",
      "address": {
        "line1": "123 Main St",
        "city": "Metropolis",
        "postal_code": "12345",
        "country": "US"
      }
    },
    "delivery_type": 0
  }'

Success Response:

• Code: 202 Accepted
• Content:

{
  "message": "Order creation accepted",
  "jobId": "job-123456",
  "orderData": { ... }
}

Update Order

Updates an existing order with new data.

URL: /v1/orders/{orderId}

Method: PUT

Auth required: Yes

Request Body: Same as for creating an order

Example Request:

curl -X PUT "https://api.uos.example.com/v1/orders/order-123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "channel-123",
    "order_number": "ORD-001",
    "items": [ ... ],
    // Other updated fields
  }'

Success Response:

• Code: 202 Accepted
• Content:

{
  "message": "Order update accepted",
  "jobId": "job-123457"
}

Error Responses:

• Code: 404 Not Found
  • Content: { "error": { "code": "ORDER_NOT_FOUND", "message": "No order found with ID or order number" } }

Update Order Status

Updates the status of an existing order.

URL: /v1/orders/{orderId}/status

Method: PATCH

Auth required: Yes

Request Headers

Request Body

X-Force-Transition Header

The X-Force-Transition header allows bypassing status transition validation for forward transitions only. This is useful when external systems (like CC Platform) need to sync order statuses that have already progressed through intermediate steps.

Important Rules:

• ✅ Forward transitions (e.g., picking → completed) can bypass validation when X-Force-Transition: true
• ❌ Backward transitions (e.g., completed → picking) are always rejected, even with the FORCE header (returns 403 Forbidden)
• 🔒 Loop Prevention: When X-Command-Origin is set, webhooks back to the originating system are automatically skipped

Example Request with Force Transition:

curl -X PATCH "https://api.uos.example.com/v1/orders/order-123/status" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Force-Transition: true" \
  -H "X-Command-Origin: cc-adapter" \
  -H "X-Correlation-Id: corr-123456" \
  -d '{
    "status": "completed",
    "metadata": {
      "source": "cc_platform",
      "updated_by": "naveo-enterprise-adapter"
    }
  }'

Example Request (Normal):

curl -X PATCH "https://api.uos.example.com/v1/orders/order-123/status" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "processing"
  }'

Success Response:

• Code: 202 Accepted
• Content:

{
  "message": "Order status update in progress",
  "jobId": "job-123458",
  "orderId": "order-123",
  "status": "processing",
  "forced_transition": false
}

When X-Force-Transition: true is used, the response includes:

{
  "message": "Order status update in progress",
  "jobId": "job-123458",
  "orderId": "order-123",
  "status": "completed",
  "forced_transition": true,
  "metadata": {
    "status_in_uos": "processing",
    "_internal_job_id": "job-abc123"
  }
}

Error Responses:

• Code: 400 Bad Request
  • Content: { "error": "Invalid status or missing required metadata" }
• Code: 403 Forbidden
  • Content: { "error": "Cannot force backward status transition from completed to picking. Force transitions are only allowed for forward transitions." }
• Code: 404 Not Found
  • Content: { "error": { "code": "ORDER_NOT_FOUND", "message": "No order found with ID or order number" } }

Get Order History

Returns the complete version history of an order with metadata.

URL: /v1/orders/{orderId}/history

Method: GET

Auth required: Yes

Example Request:

curl -X GET "https://api.uos.example.com/v1/orders/order-123/history" \
  -H "Authorization: Bearer YOUR_API_KEY"

Success Response:

• Code: 200 OK
• Content: Order history object

Error Responses:

• Code: 404 Not Found
  • Content: { "error": { "code": "ORDER_NOT_FOUND", "message": "No order found with ID or order number" } }

Get Order Version

Returns a specific historical version of an order.

URL: /v1/orders/{orderId}/versions/{version}

Method: GET

Auth required: Yes

Example Request:

curl -X GET "https://api.uos.example.com/v1/orders/order-123/versions/2" \
  -H "Authorization: Bearer YOUR_API_KEY"

Success Response:

• Code: 200 OK
• Content: Order version object

Error Responses:

• Code: 400 Bad Request
  • Content: { "error": "Invalid version number" }
• Code: 404 Not Found
  • Content: { "error": "Order version not found" }

Get Order Status History

Returns a chronological history of all status changes for an order.

URL: /v1/orders/{orderId}/status-history

Method: GET

Auth required: Yes

Example Request:

curl -X GET "https://api.uos.example.com/v1/orders/order-123/status-history" \
  -H "Authorization: Bearer YOUR_API_KEY"

Success Response:

• Code: 200 OK
• Content: Order status history object

Error Responses:

• Code: 404 Not Found
  • Content: { "error": { "code": "ORDER_NOT_FOUND", "message": "No order found with ID or order number" } }