Docs
Sign in

Splits and merges

Updated May 29, 20264 min read

Most orders flow as one Order → one fulfillment order → one Shipment. Some need to split (across fulfillment locations, across delivery types, or across parcels). Some need to merge (several fulfillment orders combined into one). And separately, multiple Shipments can travel together as a consolidated shipment without their underlying orders being merged.

The fulfillment order is the unit that gets split or merged. The Shipment is the unit that gets consolidated.

Splits

A split can happen at two levels.

Order → multiple fulfillment orders (at allocation)

The most common kind of split. When the order is allocated, the allocation engine may produce more than one fulfillment order. Common causes:

  • Multi-location. No single fulfillment location has stock for every line. Carriyo splits the order across locations automatically based on inventory availability.
  • Mixed delivery types. Some lines ship Express, others Standard, on different schedules. One fulfillment order per delivery type.
  • Customer choice. Multi-address shipping at checkout. Each destination gets its own fulfillment order.

Each fulfillment order then proceeds independently and produces at least one Shipment when booked.

How Carriyo supports this. Splits are decided by the Allocation engine at create-order time. Multi-location splits use Inventory availability across Locations. Delivery-type splits use the line-level delivery type or Delivery option carried in the create-order payload. Multi-address splits come from per-line destinations on the same payload.

Order ORDER-9001
   │   line 1: WIDGET   (fulfillment location A)
   │   line 2: GADGET   (fulfillment location B)
   │   line 3: GIZMO    (fulfillment location A)
   │
   ▼
allocation runs
   │
   ├── Fulfillment Order FO-9001-A   (fulfillment location A)
   │       lines: WIDGET, GIZMO
   │
   └── Fulfillment Order FO-9001-B   (fulfillment location B)
           lines: GADGET
   │
   ▼
each FO produces at least one Shipment when booked
   │
   ├── Shipment SHP-9001-A  ←── partner_shipment_reference = "ORDER-9001-A"
   └── Shipment SHP-9001-B  ←── partner_shipment_reference = "ORDER-9001-B"
                                   both:
                                   partner_order_reference = "ORDER-9001"

For the API-side walkthrough, see Recipe → split a fulfillment order.

Fulfillment order → multiple shipments (at booking)

Even when a single fulfillment order contains every line, the items may not be shippable together:

  • Carrier limits. Weight, dimension, or piece-count caps that one parcel can't carry.
  • Restricted commodity. Hazmat, oversized, or items requiring separate customs paths.

In these cases the fulfillment order is fulfilled from a single location but produces multiple Shipments. This is typically a user-initiated split from the Dashboard or via API.

How Carriyo supports this. Booking-time splits happen on the Shipping side. Users send one create-shipment call per parcel against the same Fulfillment Order; each call follows the standard Booking flow and produces an independent Shipment.

Merges

A merge combines multiple fulfillment orders within the same Order into a single fulfillment order. The trigger is usually a change in the conditions that caused the original split. Common scenarios:

  • Re-allocated to a single location. An order was split across locations because no single one had complete stock. Inventory shifts (replenishment, transfer, or a manual override) make one location capable of fulfilling everything, so ops re-allocates and merges the FOs.
  • Mixed delivery types collapsed. The customer agrees to drop Express on a faster line and take everything as Standard. The delivery-type-split FOs merge into one.
  • Delivery method changed to Collection. The customer asks to collect their entire order from a single collection point instead of having part delivered. The delivery-method-split FOs merge into one COLLECTION FO.
  • Multi-address reversed. The customer changes their mind pre-processing and wants everything sent to one address. The destination-split FOs merge.
Order ORDER-9001
   │   FO-9001-A   (fulfillment location A; lines: WIDGET, GIZMO)
   │   FO-9001-B   (fulfillment location B; lines: GADGET)
   │
   ▼   stock of GADGET arrives at location A; ops re-allocates
   │
   └── Fulfillment Order FO-9001    (fulfillment location A)
          lines: WIDGET, GADGET, GIZMO

How Carriyo supports this. Merges are user-initiated from the Dashboard. Multiple fulfillment orders can be merged together and allocated to a single location, with a single delivery option and address. For cross-Order scenarios such as grouping shipments across orders, see Consolidated shipments below.

Consolidated shipments

A consolidated shipment is a different operation from a merge. It does not combine fulfillment orders. Instead, multiple Shipments are grouped together and physically moved as a single load, while each Shipment keeps its own identity and tracking.

Common cases:

  • Cross-border consolidation. Multiple Shipments going to the same destination country are batched into one international load to share customs paperwork and freight cost.
  • Click-and-collect consolidation. Multiple Shipments destined for the same collection point are loaded onto one delivery from the central warehouse to the store.

For the mechanics and the API, see Consolidated shipments.

Splits, merges, and customer experience

Customer-facing tracking should always group by the customer's order, not by Carriyo's shipment. To the customer, an order is what they paid for. If their order produced three shipments (split), show three tracking entries grouped under the order. Consolidated shipments are invisible to the customer: each of their shipments still tracks individually even when it physically travels with someone else's parcel.

How it fits with other modules

  • Orders. Splits and merges are fulfillment-side decisions on top of the Order.
  • Allocation engine. Drives when allocation-time splits happen.
  • Shipping. The resulting shipments are normal Shipment objects.
  • Post-purchase CX. Splits and merges shape the customer-facing tracking UI.