Order Reservations and Allocations

When an order is created, it is typical that stock is reserved to be used as part of fulfilling the order. In order to achieve this, inventory must be set aside for pending orders.

In some cases, there can be a significant length of time between an order being placed, and the order being fulfilled. For example:

  • An item is out of stock at all locations, with new stock expected sometime in future.
  • An order has been specified as needing to be shipped on a specific date in future.

In such cases, it may be desirable to be sure that sufficient inventory is held across locations, without necessarily requiring a specific location to hold inventory for an extended period to fulfil a specific order.

This is the purpose of an order reservation. When the order enters the committed state, reservations for each line item are created. The reservations of items and corresponding quantities are reflected in the aggregate inventory levels (sum of inventory across all locations), but not at a location level as the location(s) that will fulfil the order have yet to be determined.

An order allocation is conceptually the same as an order reservation, with the difference being that allocations are tied to a location. When an allocation is created for an order, it states that the specified line items from the order are going to be packaged and fulfilled from the specified location.

Either directly after the order enters the committed state, or at a configurable time period prior to the order shipping date, the order is sent to the allocations service.

The allocations service is responsible for creating allocations from an order resource. It is responsible for the following:

  • Retrieving the inventory items associated with a given product variant (as found in the order line items).
  • Providing a routing mechanism for deciding which locations are used to fulfil the order.
  • Geocoding the order (destination) address if the order address is used as part of the process (eg. routing orders to warehouses nearest to the delivery address).
  • Querying the inventory service to determine which locations have sufficient stock levels for the required inventory items.

The allocations service routes orders to the location nearest to the order destination address that has sufficient inventory for the order line items. If no single inventory holds all the items in sufficient quantity, multiple allocations are created.

Future plans include support for alternative (custom/externally hosted) allocations services. That is to say, the routing aspect may be hosted on the organisation's servers, and implement customised routing logic. this is possible currently by using a combination of the webhooks functionality, inventory and allocation endpoints, though if this is a use case that is of particular interest to you, please contact us to discuss the scenario further.

Order fulfilments are created against order allocations. An order cannot have fulfilments created against it without first creating allocations.

Allocations can be modified to adjust items and quantities up until the point at which they are marked as completed. At this point it is not possible to modify the allocation further, and the inventory levels for the items in the allocation are permanently decreased.

The overall order reservation/allocation workflow can be summarised as follows:

OrderReservationInventoryAllocation ServiceAllocationPickingFulfilmentShipmentLocationloop[OrderCommitted:]loop[AllocationPolling:]A shipping detail ID must be passed if the order resource has multiple shipping details present.par[Decrease Inventory Levels:][Notify order service of fulfilment status change:]loop[Tracking status change:]eg. shipment status changes from pre_transit -> in_transitloop[Update order status:]State changed to 'committed'1Create reservations for line items2Subsequent updates to line items pushed to reservations3Update inventory levels with reserved quantities4Notify allocation service of new order5Schedule creation of allocations6Geocode order destination address7Query for item reservations requiring allocation8Query inventory for levels and locations9Create allocations for chosen locations and items10Mark as unallocated if allocation cannot be handled automatically11Update reservations with the quantity of items in the reservation that have been allocated12Update inventory counts with allocated quantities13Order service notified once all items in an order are allocated.14Retrieve allocations for orders15Create fulfilment for each allocation16Mark allocation as complete on fulfilment creation17Fulfilment finalisation requested. Shipment options specified here.18Query order to check committed status. Fulfilment not possible until order committed.19Fulfilment service creates shipment, passing specified options to shipments service.20Destination address retrieved from order shipping detail.21Origin & return address retrieved from location service.22Shipment created, attached to fulfilment.23Allocation marked as completed once fulfilment is finalised.24On allocation completion, inventory levels permanently decreased.25Change order status to fulfilled/partially fulfilled.26Tracking status of shipment is updated27Notify fulfilment of change in shipment status28Order service notified of change to shipment state of one or more fulfilments.29Update order status depending on state of fulfilment and associated shipment.30OrderReservationInventoryAllocation ServiceAllocationPickingFulfilmentShipmentLocation