Skip to main content

Orders API

The Orders API provides endpoints for managing orders throughout their lifecycle.

Endpoints Overview​

MethodEndpointDescription
GET/api/v1/OrdersList orders
GET/api/v1/Orders/{orderId}Get order
PATCH/api/v1/Orders/{orderId}/statusUpdate status
POST/api/v1/Orders/assign-carrierAssign carrier
POST/api/v1/Orders/deleteDelete orders
POST/api/v1/Orders/{orderId}/add-dimension-presetAdd dimensions
POST/api/v1/Orders/{orderId}/assign-collection-dateSet collection
POST/api/v1/Orders/{orderId}/shipmentCreate shipment

List Orders​

Get a paginated list of orders.

GET /api/v1/Orders

Query Parameters​

ParameterTypeDescription
PageintegerPage number (default: 1)
PageSizeintegerItems per page (max: 100)
$orderbystringSort order
$filterstringFilter expression
$searchstringSearch text

Example Request​

GET /api/v1/Orders?Page=1&PageSize=25&$filter=status eq 'pending'

Response​

{
  "data": [
    {
      "guid": "order-uuid",
      "orderNumber": "ORD-001234",
      "status": "pending",
      "customer": {
        "guid": "customer-uuid",
        "name": "John Doe"
      },
      "items": [
        {
          "description": "Product A",
          "quantity": 2,
          "price": 25.00
        }
      ],
      "deliveryAddress": {
        "street": "123 Main St",
        "city": "City",
        "state": "State",
        "postalCode": "12345"
      },
      "createdAt": "2024-01-15T10:00:00Z"
    }
  ],
  "page": 1,
  "pageSize": 25,
  "totalCount": 500,
  "success": true
}

Get Order​

Retrieve a specific order.

GET /api/v1/Orders/{orderId}

Path Parameters​

ParameterTypeDescription
orderIduuidOrder identifier

Response​

{
  "data": {
    "guid": "order-uuid",
    "orderNumber": "ORD-001234",
    "status": "processing",
    "customer": {
      "guid": "customer-uuid",
      "name": "John Doe",
      "email": "john@example.com"
    },
    "items": [
      {
        "guid": "item-uuid",
        "description": "Product A",
        "quantity": 2,
        "price": 25.00,
        "dimensions": {
          "length": 10,
          "width": 10,
          "height": 10,
          "weight": 1.5
        }
      }
    ],
    "deliveryAddress": {
      "street": "123 Main St",
      "city": "City",
      "state": "State",
      "postalCode": "12345",
      "country": "Country"
    },
    "carrier": {
      "guid": "carrier-uuid",
      "name": "Carrier Name"
    },
    "shipments": [],
    "totalValue": 50.00,
    "createdAt": "2024-01-15T10:00:00Z",
    "updatedAt": "2024-01-15T11:00:00Z"
  },
  "success": true
}

Update Order Status​

Change the status of an order.

PATCH /api/v1/Orders/{orderId}/status

Request Body​

{
  "status": "processing",
  "notes": "Order picked for packing"
}

Response​

{
  "data": {
    "guid": "order-uuid",
    "status": "processing"
  },
  "success": true
}

Assign Carrier​

Assign a carrier to one or more orders.

POST /api/v1/Orders/assign-carrier

Request Body​

{
  "orderIds": [
    "order-uuid-1",
    "order-uuid-2"
  ],
  "carrierId": "carrier-uuid",
  "serviceLevel": "standard"
}

Response​

{
  "success": true
}

Delete Orders​

Delete one or more orders.

POST /api/v1/Orders/delete

Request Body​

[
  {
    "guid": "order-uuid-1"
  },
  {
    "guid": "order-uuid-2"
  }
]

Response​

{
  "data": [],
  "success": true
}

Add Dimension Preset​

Apply a dimension preset to an order.

POST /api/v1/Orders/{orderId}/add-dimension-preset

Request Body​

{
  "presetId": "preset-uuid",
  "itemId": "item-uuid"
}

Response​

{
  "data": {
    "guid": "order-uuid"
  },
  "success": true
}

Set Collection Date​

Assign a collection date to an order.

POST /api/v1/Orders/{orderId}/assign-collection-date

Request Body​

{
  "collectionDate": "2024-01-16T10:00:00Z",
  "timeWindow": {
    "start": "09:00",
    "end": "12:00"
  }
}

Response​

{
  "data": {
    "guid": "order-uuid",
    "collectionDate": "2024-01-16T10:00:00Z"
  },
  "success": true
}

Create Shipment from Order​

Generate a shipment from an order.

POST /api/v1/Orders/{orderId}/shipment

Request Body​

{
  "itemIds": ["item-uuid-1", "item-uuid-2"],
  "generateLabel": true
}

Response​

{
  "data": {
    "guid": "shipment-uuid",
    "trackingNumber": "TRK123456789",
    "orderId": "order-uuid",
    "status": "created"
  },
  "success": true
}

Order Statuses​

StatusDescription
draftOrder created but not submitted
pendingAwaiting processing
processingBeing prepared
readyReady for pickup
shippedIn transit
deliveredSuccessfully delivered
cancelledOrder cancelled

Error Responses​

404 Not Found​

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Order not found"
  }
}

400 Bad Request​

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid status transition"
  }
}

409 Conflict​

{
  "success": false,
  "error": {
    "code": "CONFLICT",
    "message": "Order already has shipment"
  }
}