API docs by Redocly

Orchestrator API

Overview

The Xpand Edge Orchestrator implements a "bulletin board" architecture where the orchestrator maintains state that other actors in the system can read and update. The orchestrator is responsible for:

  • Exposing orders pulled from the cloud
  • Maintaining task state that can be updated by other system actors
  • Managing picker task enablement state
  • Coordinating system operations through state management

The orchestrator acts as a central state repository, allowing different system components to coordinate through shared state rather than direct orchestration.

Offline Development Mode

To support offline development mode with the orchestrator, the following can be applied:

  • Configuration switch that disables cloud sync (both pulling orders and pushing updates)
  • Configuration switch that enables /orders endpoints that manipulate the list of orders more directly - POST /orders to create an order DELETE /orders, etc.

Orders

The /orders set of endpoints are the key function of the orchestrator for synchronizing the workflow of orders between the cloud and the edge machine, updating the cloud about the state of the orders, and facilitating the fulfillment of the orders by serving the order data to other edge services and receiving updates form them.

Get all orders

Retrieve all orders currently maintained by the orchestrator. These are orders that have been pulled from the edge-gateway and are available for fulfillment.

This list will include both queued orders as well as orders in state of fetched, collecting, collected, ready, delivering, delivered.

The different actors in the system should filter orders for the states relevant to them.

Responses

Response samples

Content type
application/json
[
  • {
    • "id": "842",
    • "status": "queued",
    • "products": [
      • {
        • "productId": 123,
        • "productExternalId": "J57S",
        • "quantity": 2,
        • "fulfilledQuantity": 0
        },
      • {
        • "productId": 546,
        • "quantity": 1,
        • "fulfilledQuantity": 0,
        • "modifiers": {
          • "strength": "strong",
          • "milk": "with milk"
          }
        }
      ],
    • "deliveryDate": "2023-06-15",
    • "deliveryTime": "14:30",
    • "priority": 1,
    • "displayCode": 7465,
    • "pinCode": 5364,
    • "user": {
      • "name": "John Doe",
      • "address": "123 Main St, Anytown, AT 12345",
      • "phoneNumber": "+1-555-123-4567",
      • "locale": "en-US"
      }
    }
]

Update order status

Update the status of a specific order. This is used by fulfillment actors to report progress on order processing.

path Parameters
orderId
required
string

The unique identifier of the order

Request Body schema: application/json
required
status
required
string (OrderStatus)
Enum: "pending" "assigned" "picking" "picked" "delivered" "failed"

Order status values:

  • pending: Order received, waiting for assignment
  • assigned: Order assigned to picker
  • picking: Order currently being picked
  • picked: Order fully picked, ready for delivery
  • delivered: Order delivered to customer
  • failed: Order processing failed
pickerId
string or null

ID of the picker handling the order

notes
string

Additional notes about the status update

Responses

Request samples

Content type
application/json
{
  • "status": "pending",
  • "pickerId": "string",
  • "notes": "string"
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "message": "string",
  • "details": { },
  • "timestamp": "2019-08-24T14:15:22Z"
}

Update order item status

Update the status and picked quantity of a specific item within an order. This is typically used by pickers to report item-level progress.

path Parameters
orderId
required
string

The unique identifier of the order

productId
required
string

The product identifier

Request Body schema: application/json
required
fulfilledQuantity
required
integer >= 0

Quantity that was actually fulfilled

notes
string

Additional notes about the product update

Responses

Request samples

Content type
application/json
{
  • "fulfilledQuantity": 0,
  • "notes": "string"
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "message": "string",
  • "details": { },
  • "timestamp": "2019-08-24T14:15:22Z"
}

Tasks

Get all data collection tasks

Retrieve all data collection tasks currently maintained by the orchestrator.

Responses

Response samples

Content type
application/json
[
  • {
    • "id": "string",
    • "productId": "string",
    • "status": "pending",
    • "assignedTo": "string",
    • "dataType": "weight",
    • "priority": "low",
    • "createdAt": "2019-08-24T14:15:22Z",
    • "updatedAt": "2019-08-24T14:15:22Z",
    • "metadata": { }
    }
]

Create a new data collection task

Create a new data collection task that will be maintained by the orchestrator.

Request Body schema: application/json
required
productId
required
string

Product ID requiring data collection

dataType
required
string
Enum: "weight" "dimensions" "images" "barcode" "expiry"

Type of data to collect

priority
required
string
Enum: "low" "medium" "high" "urgent"

Task priority level

object

Additional task metadata

Responses

Request samples

Content type
application/json
{
  • "productId": "string",
  • "dataType": "weight",
  • "priority": "low",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "productId": "string",
  • "status": "pending",
  • "assignedTo": "string",
  • "dataType": "weight",
  • "priority": "low",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "metadata": { }
}

Update data collection task status

Update the status of a data collection task. Used by actors performing the task.

path Parameters
taskId
required
string

The unique identifier of the task

Request Body schema: application/json
required
status
required
string (TaskStatus)
Enum: "pending" "assigned" "in_progress" "completed" "failed" "cancelled"

Task status values:

  • pending: Task created, waiting for assignment
  • assigned: Task assigned to an actor
  • in_progress: Task currently being performed
  • completed: Task successfully completed
  • failed: Task failed to complete
  • cancelled: Task was cancelled
assignedTo
string or null

ID of the actor assigned to the task

progress
integer [ 0 .. 100 ]

Task completion percentage

notes
string

Additional notes about the task status update

completedAt
string or null <date-time>

When the task was completed

Responses

Request samples

Content type
application/json
{
  • "status": "pending",
  • "assignedTo": "string",
  • "progress": 100,
  • "notes": "string",
  • "completedAt": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "message": "string",
  • "details": { },
  • "timestamp": "2019-08-24T14:15:22Z"
}

Get all consolidation tasks

Retrieve all consolidation tasks currently maintained by the orchestrator.

Responses

Response samples

Content type
application/json
[
  • {
    • "id": "string",
    • "orderIds": [
      • "string"
      ],
    • "status": "pending",
    • "assignedTo": "string",
    • "consolidationType": "tote",
    • "priority": "low",
    • "createdAt": "2019-08-24T14:15:22Z",
    • "updatedAt": "2019-08-24T14:15:22Z",
    • "metadata": { }
    }
]

Create a consolidation task

Create a new consolidation task that will be maintained by the orchestrator.

Request Body schema: application/json
required
orderIds
required
Array of strings

Order IDs to consolidate

consolidationType
required
string
Enum: "tote" "pallet" "mixed"

Type of consolidation to perform

priority
required
string
Enum: "low" "medium" "high" "urgent"

Task priority level

object

Additional task metadata

Responses

Request samples

Content type
application/json
{
  • "orderIds": [
    • "string"
    ],
  • "consolidationType": "tote",
  • "priority": "low",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "orderIds": [
    • "string"
    ],
  • "status": "pending",
  • "assignedTo": "string",
  • "consolidationType": "tote",
  • "priority": "low",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "metadata": { }
}

Update consolidation task status

Update the status of a consolidation task. Used by actors performing the task.

path Parameters
taskId
required
string

The unique identifier of the task

Request Body schema: application/json
required
status
required
string (TaskStatus)
Enum: "pending" "assigned" "in_progress" "completed" "failed" "cancelled"

Task status values:

  • pending: Task created, waiting for assignment
  • assigned: Task assigned to an actor
  • in_progress: Task currently being performed
  • completed: Task successfully completed
  • failed: Task failed to complete
  • cancelled: Task was cancelled
assignedTo
string or null

ID of the actor assigned to the task

progress
integer [ 0 .. 100 ]

Task completion percentage

notes
string

Additional notes about the task status update

completedAt
string or null <date-time>

When the task was completed

Responses

Request samples

Content type
application/json
{
  • "status": "pending",
  • "assignedTo": "string",
  • "progress": 100,
  • "notes": "string",
  • "completedAt": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "message": "string",
  • "details": { },
  • "timestamp": "2019-08-24T14:15:22Z"
}

Get all pallet arrangement tasks

Retrieve all pallet arrangement tasks currently maintained by the orchestrator.

Responses

Response samples

Content type
application/json
[
  • {
    • "id": "string",
    • "palletIds": [
      • "string"
      ],
    • "status": "pending",
    • "assignedTo": "string",
    • "arrangementType": "optimization",
    • "targetLocation": "string",
    • "priority": "low",
    • "createdAt": "2019-08-24T14:15:22Z",
    • "updatedAt": "2019-08-24T14:15:22Z",
    • "metadata": { }
    }
]

Create a pallet arrangement task

Create a new pallet arrangement task that will be maintained by the orchestrator.

Request Body schema: application/json
required
palletIds
required
Array of strings

Pallet IDs to arrange

arrangementType
required
string
Enum: "optimization" "maintenance" "emergency"

Type of arrangement required

targetLocation
string

Target location for arrangement

priority
required
string
Enum: "low" "medium" "high" "urgent"

Task priority level

object

Additional task metadata

Responses

Request samples

Content type
application/json
{
  • "palletIds": [
    • "string"
    ],
  • "arrangementType": "optimization",
  • "targetLocation": "string",
  • "priority": "low",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "palletIds": [
    • "string"
    ],
  • "status": "pending",
  • "assignedTo": "string",
  • "arrangementType": "optimization",
  • "targetLocation": "string",
  • "priority": "low",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "metadata": { }
}

Update pallet arrangement task status

Update the status of a pallet arrangement task.

path Parameters
taskId
required
string

The unique identifier of the task

Request Body schema: application/json
required
status
required
string (TaskStatus)
Enum: "pending" "assigned" "in_progress" "completed" "failed" "cancelled"

Task status values:

  • pending: Task created, waiting for assignment
  • assigned: Task assigned to an actor
  • in_progress: Task currently being performed
  • completed: Task successfully completed
  • failed: Task failed to complete
  • cancelled: Task was cancelled
assignedTo
string or null

ID of the actor assigned to the task

progress
integer [ 0 .. 100 ]

Task completion percentage

notes
string

Additional notes about the task status update

completedAt
string or null <date-time>

When the task was completed

Responses

Request samples

Content type
application/json
{
  • "status": "pending",
  • "assignedTo": "string",
  • "progress": 100,
  • "notes": "string",
  • "completedAt": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "message": "string",
  • "details": { },
  • "timestamp": "2019-08-24T14:15:22Z"
}

Get all pallet replenishment tasks

Retrieve all pallet replenishment tasks currently maintained by the orchestrator.

Responses

Response samples

Content type
application/json
[
  • {
    • "id": "string",
    • "palletId": "string",
    • "status": "pending",
    • "assignedTo": "string",
    • "replenishmentType": "full",
    • "products": [
      • {
        • "productId": "string",
        • "quantity": 1
        }
      ],
    • "priority": "low",
    • "createdAt": "2019-08-24T14:15:22Z",
    • "updatedAt": "2019-08-24T14:15:22Z",
    • "metadata": { }
    }
]

Create a pallet replenishment task

Create a new pallet replenishment task that will be maintained by the orchestrator.

Request Body schema: application/json
required
palletId
required
string

Pallet ID requiring replenishment

replenishmentType
required
string
Enum: "full" "partial" "emergency"

Type of replenishment required

required
Array of objects (ProductQuantity)

Products and quantities to replenish

priority
required
string
Enum: "low" "medium" "high" "urgent"

Task priority level

object

Additional task metadata

Responses

Request samples

Content type
application/json
{
  • "palletId": "string",
  • "replenishmentType": "full",
  • "products": [
    • {
      • "productId": "string",
      • "quantity": 1
      }
    ],
  • "priority": "low",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "palletId": "string",
  • "status": "pending",
  • "assignedTo": "string",
  • "replenishmentType": "full",
  • "products": [
    • {
      • "productId": "string",
      • "quantity": 1
      }
    ],
  • "priority": "low",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "metadata": { }
}

Update pallet replenishment task status

Update the status of a pallet replenishment task.

path Parameters
taskId
required
string

The unique identifier of the task

Request Body schema: application/json
required
status
required
string (TaskStatus)
Enum: "pending" "assigned" "in_progress" "completed" "failed" "cancelled"

Task status values:

  • pending: Task created, waiting for assignment
  • assigned: Task assigned to an actor
  • in_progress: Task currently being performed
  • completed: Task successfully completed
  • failed: Task failed to complete
  • cancelled: Task was cancelled
assignedTo
string or null

ID of the actor assigned to the task

progress
integer [ 0 .. 100 ]

Task completion percentage

notes
string

Additional notes about the task status update

completedAt
string or null <date-time>

When the task was completed

Responses

Request samples

Content type
application/json
{
  • "status": "pending",
  • "assignedTo": "string",
  • "progress": 100,
  • "notes": "string",
  • "completedAt": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "message": "string",
  • "details": { },
  • "timestamp": "2019-08-24T14:15:22Z"
}

Get all order delivery tasks

Retrieve all order delivery (pickup) tasks currently maintained by the orchestrator.

Responses

Response samples

Content type
application/json
[
  • {
    • "id": "string",
    • "orderId": "string",
    • "status": "pending",
    • "assignedTo": "string",
    • "deliveryType": "pickup",
    • "customerCode": "string",
    • "priority": "low",
    • "createdAt": "2019-08-24T14:15:22Z",
    • "updatedAt": "2019-08-24T14:15:22Z",
    • "metadata": { }
    }
]

Create an order delivery task

Create a new order delivery task that will be maintained by the orchestrator.

Request Body schema: application/json
required
orderId
required
string

Order ID to deliver

deliveryType
required
string
Enum: "pickup" "automated" "manual"

Type of delivery method

customerCode
required
string

Customer pickup code

priority
required
string
Enum: "low" "medium" "high" "urgent"

Task priority level

object

Additional task metadata

Responses

Request samples

Content type
application/json
{
  • "orderId": "string",
  • "deliveryType": "pickup",
  • "customerCode": "string",
  • "priority": "low",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "orderId": "string",
  • "status": "pending",
  • "assignedTo": "string",
  • "deliveryType": "pickup",
  • "customerCode": "string",
  • "priority": "low",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "metadata": { }
}

Update order delivery task status

Update the status of an order delivery task.

path Parameters
taskId
required
string

The unique identifier of the task

Request Body schema: application/json
required
status
required
string (TaskStatus)
Enum: "pending" "assigned" "in_progress" "completed" "failed" "cancelled"

Task status values:

  • pending: Task created, waiting for assignment
  • assigned: Task assigned to an actor
  • in_progress: Task currently being performed
  • completed: Task successfully completed
  • failed: Task failed to complete
  • cancelled: Task was cancelled
assignedTo
string or null

ID of the actor assigned to the task

progress
integer [ 0 .. 100 ]

Task completion percentage

notes
string

Additional notes about the task status update

completedAt
string or null <date-time>

When the task was completed

Responses

Request samples

Content type
application/json
{
  • "status": "pending",
  • "assignedTo": "string",
  • "progress": 100,
  • "notes": "string",
  • "completedAt": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "message": "string",
  • "details": { },
  • "timestamp": "2019-08-24T14:15:22Z"
}

Get all tote review tasks

Retrieve all tote review tasks currently maintained by the orchestrator.

Responses

Response samples

Content type
application/json
[
  • {
    • "id": "string",
    • "toteId": "string",
    • "status": "pending",
    • "assignedTo": "string",
    • "reviewType": "quality",
    • "orderId": "string",
    • "priority": "low",
    • "createdAt": "2019-08-24T14:15:22Z",
    • "updatedAt": "2019-08-24T14:15:22Z",
    • "metadata": { }
    }
]

Create a tote review task

Create a new tote review task that will be maintained by the orchestrator.

Request Body schema: application/json
required
toteId
required
string

Tote ID to review

reviewType
required
string
Enum: "quality" "accuracy" "damage" "missing"

Type of review required

orderId
string or null

Associated order ID if applicable

priority
required
string
Enum: "low" "medium" "high" "urgent"

Task priority level

object

Additional task metadata

Responses

Request samples

Content type
application/json
{
  • "toteId": "string",
  • "reviewType": "quality",
  • "orderId": "string",
  • "priority": "low",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "toteId": "string",
  • "status": "pending",
  • "assignedTo": "string",
  • "reviewType": "quality",
  • "orderId": "string",
  • "priority": "low",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "metadata": { }
}

Update tote review task status

Update the status of a tote review task.

path Parameters
taskId
required
string

The unique identifier of the task

Request Body schema: application/json
required
status
required
string (TaskStatus)
Enum: "pending" "assigned" "in_progress" "completed" "failed" "cancelled"

Task status values:

  • pending: Task created, waiting for assignment
  • assigned: Task assigned to an actor
  • in_progress: Task currently being performed
  • completed: Task successfully completed
  • failed: Task failed to complete
  • cancelled: Task was cancelled
assignedTo
string or null

ID of the actor assigned to the task

progress
integer [ 0 .. 100 ]

Task completion percentage

notes
string

Additional notes about the task status update

completedAt
string or null <date-time>

When the task was completed

Responses

Request samples

Content type
application/json
{
  • "status": "pending",
  • "assignedTo": "string",
  • "progress": 100,
  • "notes": "string",
  • "completedAt": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "message": "string",
  • "details": { },
  • "timestamp": "2019-08-24T14:15:22Z"
}

Enabled Tasks

Get all picker task states

Retrieve the task enablement state for all pickers in the system. Returns a dictionary mapping picker IDs to their enabled task types.

Responses

Response samples

Content type
application/json
{
  • "property1": {
    • "fulfillment": true,
    • "dataCollection": true,
    • "consolidation": true,
    • "palletArrangement": true,
    • "palletReplenishment": true,
    • "orderDelivery": true,
    • "toteReview": true,
    • "maintenance": true
    },
  • "property2": {
    • "fulfillment": true,
    • "dataCollection": true,
    • "consolidation": true,
    • "palletArrangement": true,
    • "palletReplenishment": true,
    • "orderDelivery": true,
    • "toteReview": true,
    • "maintenance": true
    }
}

Get picker task states

Retrieve the task enablement state for a specific picker.

path Parameters
pickerId
required
string

The unique identifier of the picker

Responses

Response samples

Content type
application/json
{
  • "fulfillment": true,
  • "dataCollection": true,
  • "consolidation": true,
  • "palletArrangement": true,
  • "palletReplenishment": true,
  • "orderDelivery": true,
  • "toteReview": true,
  • "maintenance": true
}

Update picker task states

Update the task enablement state for a specific picker. This controls which types of tasks the picker is allowed to perform.

path Parameters
pickerId
required
string

The unique identifier of the picker

Request Body schema: application/json
required
fulfillment
required
boolean

Whether fulfillment tasks are enabled for this picker

dataCollection
required
boolean

Whether data collection tasks are enabled for this picker

consolidation
required
boolean

Whether consolidation tasks are enabled for this picker

palletArrangement
required
boolean

Whether pallet arrangement tasks are enabled for this picker

palletReplenishment
required
boolean

Whether pallet replenishment tasks are enabled for this picker

orderDelivery
required
boolean

Whether order delivery tasks are enabled for this picker

toteReview
required
boolean

Whether tote review tasks are enabled for this picker

maintenance
required
boolean

Whether maintenance tasks are enabled for this picker

Responses

Request samples

Content type
application/json
{
  • "fulfillment": true,
  • "dataCollection": true,
  • "consolidation": true,
  • "palletArrangement": true,
  • "palletReplenishment": true,
  • "orderDelivery": true,
  • "toteReview": true,
  • "maintenance": true
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "message": "string",
  • "details": { },
  • "timestamp": "2019-08-24T14:15:22Z"
}

Partially update picker task states

Partially update the task enablement state for a specific picker. Only the specified task types will be updated.

path Parameters
pickerId
required
string

The unique identifier of the picker

Request Body schema: application/json
required
fulfillment
boolean

Whether fulfillment tasks are enabled for this picker

dataCollection
boolean

Whether data collection tasks are enabled for this picker

consolidation
boolean

Whether consolidation tasks are enabled for this picker

palletArrangement
boolean

Whether pallet arrangement tasks are enabled for this picker

palletReplenishment
boolean

Whether pallet replenishment tasks are enabled for this picker

orderDelivery
boolean

Whether order delivery tasks are enabled for this picker

toteReview
boolean

Whether tote review tasks are enabled for this picker

maintenance
boolean

Whether maintenance tasks are enabled for this picker

Responses

Request samples

Content type
application/json
{
  • "fulfillment": true,
  • "dataCollection": true,
  • "consolidation": true,
  • "palletArrangement": true,
  • "palletReplenishment": true,
  • "orderDelivery": true,
  • "toteReview": true,
  • "maintenance": true
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "message": "string",
  • "details": { },
  • "timestamp": "2019-08-24T14:15:22Z"
}