Allocation engine

Updated May 28, 20262 min read

Allocation determines which fulfillment location ships which line items for an order. You control it through one of three modes.

Three modes

Mode	When	What runs
Pre-allocation	The create-order payload attaches fulfillment locations to the lines.	Carriyo respects the upstream decision and creates fulfillment orders accordingly. The engine does not run.
Auto-allocation	No location is provided and auto-allocation is enabled for the merchant.	The order allocation engine runs the pipeline below and picks a fulfillment location for each item.
Manual allocation	No location is provided and auto-allocation is not enabled.	The Order lands in `open` with no fulfillment orders. Ops staff allocate by hand from the Dashboard.

The allocation engine

When auto-allocation runs, the engine narrows the candidate list through five stages:

Inventory

Find every location with stock for the order's items. Digital items are skipped.

Eligibility

Keep only locations that are configured as fulfillment locations and whose fulfillment zone covers the delivery address.

Allocation rules

Evaluate any custom allocation rules in order. A rule either includes its target locations (discard everything else) or excludes them (keep everything else). The first matching rule wins; the engine exits with the filtered subset.

Prioritization rules

Apply prioritization rules in the configured sequence to break ties. Each rule maximizes one of: order fulfillment (fewest splits), location availability (most stock), or customer proximity (closest location).

Final pick

If multiple locations are still tied after every prioritization rule has run, the engine picks one at random.

Multi-pass and split allocation

If some items remain unallocated after the pipeline finishes and split allocation is enabled for the merchant, the engine runs the pipeline again for the remaining items. This continues until every item is allocated or no candidates remain.

Auto-cancellation

If items are still unallocated when the pipeline can no longer make progress and partial allocation is not allowed, the engine automatically cancels the order.

Allocation rules vs prioritization rules

Both run inside the engine but do different jobs:

	Allocation rules	Prioritization rules
Purpose	Filter (narrow the candidate list)	Tie-break (order the survivors)
Logic	Include or exclude based on conditions	Maximize one of: fulfillment, availability, proximity
Evaluation	First match wins; engine exits	Run in sequence until one location remains (or the last rule runs)

Re-allocation

A fulfillment order can be re-allocated as long as it is still open or allocated:

The fulfillment location can be changed.
Lines can be moved between fulfillment orders (split or merge).
The fulfillment order can be cancelled and recreated.

Once pick and pack has started (processing) or the FO is fulfilled, you must restore it to open or allocated first. The path back depends on the current status:

From processing. Line items can be unpicked, which rolls the fulfillment order back to allocated.
From fulfilled. The fulfillment order is unfulfilled, which cancels the associated Shipments and rolls the lines back to allocated.

From allocated, the fulfillment order can also be released. The reservation is cleared and the lines return to open, ready for the engine (or ops) to allocate them somewhere else.

How it fits with other modules

Orders. Allocation is the bridge from Order to fulfillment order.
Inventory. Feeds stage 1 of the pipeline.
Locations. The targets the engine picks between.
Checkout. A customer-chosen delivery option can constrain which locations are eligible at stage 2.
Shipping. Once allocation is locked, fulfillment orders produce Shipments.