Delivery Orders — Overview

A DeliveryOrder is a sub-order that targets a specific fulfillment location. When an order is dispatched, the platform splits it into one or more delivery orders — one per location. Each delivery order tracks its own lines, fulfillment lifecycle, and shipments independently.

---

Fulfillment Types

Type	Description
WAREHOUSE	Delegated to a connected third-party fulfillment service. The warehouse receives the request, accepts or rejects it, and manages preparation and shipping.
INTERNAL	Managed directly via the API. Stock movements, preparation, and shipping are handled by your own team.

---

Delivery Order Status

Status	Description
DRAFT	Created but not yet sent to the fulfillment location. Lines can still be modified.
PENDING	Submitted and awaiting processing. No further edits allowed.
OPENED	Fulfillment is actively in progress at the location.
COMPLETED	All lines have been fulfilled and shipments confirmed.

---

Delivery Order Line Status

Status	Description
NEW	Line just created, not yet processed.
AWAITING_STOCK	Waiting for stock to become available.
PENDING	Line submitted and awaiting warehouse action.
CANCELED	Line has been cancelled.
ACCEPTED	Warehouse has accepted the line.
IN_PROGRESS	Warehouse is actively preparing this line.
REJECTED	Warehouse rejected the line (e.g. insufficient stock).
FULFILLED	All requested units have been prepared.
PARTIALLY_FULFILLED	Only part of the requested quantity was fulfilled.
DELIVERED	Units have been shipped and confirmed delivered.
ERRORED	A processing error occurred on this line.

---

Fulfillment Events State Machine

Delivery orders move through fulfillment states via events. The state machine below describes the allowed transitions:

---

Fulfillment Events

Fulfillment events are appended to the fulfillmentData.events array and provide a detailed audit trail of the delivery order lifecycle. Each event has a level indicating its severity.

Event	Level	Description
FULFILLMENT_REQUESTED	NORMAL	Fulfillment request sent to the warehouse.
FULFILLMENT_ACCEPTED	NORMAL	Warehouse accepted the delivery order.
FULFILLMENT_REJECTED	ERROR	Warehouse rejected the delivery order.
INTEGRATED	NORMAL	Successfully integrated into the warehouse system.
INTEGRATION_ERROR	ERROR	Integration into the warehouse system failed.
INSUFFICIENT_STOCK	WARNING	One or more lines could not be fulfilled due to insufficient stock.
FULFILLMENT_IN_PROGRESS	NORMAL	The warehouse is actively preparing the order.
PACKED	NORMAL	All items have been packed and are ready for shipment.
SHIPPED	NORMAL	The order has been handed off to a carrier.
CANCELED	WARNING	The delivery order was cancelled.
HOLDED	WARNING	The delivery order was put on hold.
RESUMED	NORMAL	The delivery order was resumed from hold.
COMPLETED	NORMAL	The delivery order has been fully completed.

Event Levels

Level	Description
NORMAL	Informational — expected lifecycle progression.
WARNING	Requires attention — fulfillment may be delayed or incomplete.
ERROR	Critical failure — manual intervention likely required.

---

GraphQL Types

DeliveryOrderType

type DeliveryOrderType {
  id: ID!
  orderNumber: String!
  invoiceNumber: String
  status: DeliveryOrderStatusEnum!
  type: FulfillmentTypeEnum!       # WAREHOUSE | INTERNAL
  priority: PriorityEnum!
  total: Float
  currency: String
  location: LocationType
  deliveryAddress: AddressType
  lines: [DeliveryOrderLineType!]!
  orders: [OrderType!]!
  fulfillmentData: DeliveryOrderFulfillmentData
  shipments: [ShipmentType!]
  createdAt: DateTime!
  updatedAt: DateTime!
}

DeliveryOrderFulfillmentData

type DeliveryOrderFulfillmentData {
  events: [FulfillmentEventType!]!
}

FulfillmentEventType

type FulfillmentEventType {
  type: FulfillmentEventTypeEnum!
  level: FulfillmentEventLevelEnum!  # NORMAL | WARNING | ERROR
  message: String
  date: DateTime!
}

---

Operations

Queries

Operation	Scope	Description
deliveryOrder	view_delivery_orders	Retrieve a delivery order by ID
deliveryOrders	view_delivery_orders	Retrieve all delivery orders for a given order

Mutations

Operation	Scope	Description
deliveryOrderCreate	create_delivery_orders	Manually create a delivery order
deliveryOrderOpen	edit_delivery_orders	Open a draft delivery order
deliveryOrderCancel	edit_delivery_orders	Cancel a delivery order
deliveryOrderHold	edit_delivery_orders	Pause fulfillment
deliveryOrderResume	edit_delivery_orders	Resume a held delivery order
deliveryOrderRequestFulfillment	edit_delivery_orders	Send to warehouse for fulfillment

---

Best Practices

1. Monitor fulfillment events. Poll fulfillmentData.events regularly or subscribe to webhooks to detect ERROR-level events early.
2. Handle INTEGRATION_ERROR proactively. When integration fails, the delivery order will not progress until the issue is resolved and fulfillment is re-requested.
3. Use deliveryOrderHold before modifying related data. If you need to update shipping address or priority, hold the order first to prevent race conditions with warehouse processing.
4. Check line statuses individually. A delivery order may reach COMPLETED with some lines PARTIALLY_FULFILLED — always inspect line-level statuses for accurate fulfillment reporting.
5. Use INTERNAL type for direct control. If you manage your own warehouse, use INTERNAL locations and drive the lifecycle via API mutations rather than waiting for warehouse callbacks.