Split a fulfillment order

Updated September 22, 20263 min read

After an order is allocated, ops sometimes needs to move part of a fulfillment order to a different location, before any items are picked. Splitting peels selected line items off an existing fulfillment order into a new fulfillment order at a location you choose. The original fulfillment order keeps the rest.

Scenario

An order was allocated to a single fulfillment order at the New Jersey warehouse, carrying two lines: a keyboard and a monitor. A stock check shows the monitor's last unit at NJ went to another order. The Los Angeles warehouse has it. Ops splits the monitor line off into a new fulfillment order at LA, leaving the keyboard at NJ.

Prerequisites

API credentials: see Getting started.
An order with an allocated fulfillment order to split, see Place an order with multiple fulfillment orders.
A destination location for the split-off lines.

Starting state

Assume order OMTV36M0ACTKSZT with one fulfillment order FOMTV36M0F6RRSMM (partner reference YOUR_ORDER_REF-NJ) at NJ-WH-01, in allocated, carrying:

Keyboard, line item id line-kbd, quantity 1
Monitor, line item id line-mon, quantity 1

Neither line has been picked yet.

Split the monitor line into a new fulfillment order at LA

curl -X POST \
  'https://api.carriyo.com/orders/OMTV36M0ACTKSZT/fulfillment-orders/FOMTV36M0F6RRSMM/split' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'tenant-id: YOUR_TENANT_ID' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "partner_fulfillment_order_reference": "YOUR_ORDER_REF-LA",
    "fulfillment_location": { "partner_location_code": "CA-WH-02" },
    "line_items": [
      { "id": "line-mon", "quantity": 1 }
    ]
  }'

partner_fulfillment_order_reference is your reference for the new fulfillment order. Send one: if you omit it, Carriyo copies the source fulfillment order's reference onto the new fulfillment order, and once two fulfillment orders on the order share a reference, neither can be addressed by it (see Pitfalls).
fulfillment_location is where the split-off lines go. It references the location by partner_location_code (used here) or partner_location_id (Carriyo's internal location id); provide one of the two.
line_items names which lines (and quantities) to peel off into the new fulfillment order, referenced by the order line item id. Only items in open or allocated can be moved.

The new fulfillment order inherits the source fulfillment order's delivery method, address, and schedule; only the location and the moved lines change.

Read the response

The response is the updated order. The source fulfillment order keeps the keyboard; a new fulfillment order appears at LA carrying the monitor, its allocation_history recording which fulfillment order it was split from (response abridged):

{
  "order_id": "OMTV36M0ACTKSZT",
  "merchant": "ACME",
  "partner_order_reference": "YOUR_ORDER_REF",
  "status": "allocated",
  "fulfillment_orders": [
    {
      "fulfillment_order_id": "FOMTV36M0F6RRSMM",
      "partner_fulfillment_order_reference": "YOUR_ORDER_REF-NJ",
      "fulfillment_location": {
        "partner_location_id": "ACCOUNT_f2b82334-96d6-43bb-987d-ca36c2305824",
        "partner_location_code": "NJ-WH-01",
        "partner_location_name": "New Jersey Warehouse"
      },
      "status": "allocated",
      "delivery_method": "DELIVERY",
      "line_items": [
        { "id": "line-kbd", "quantity": 1, "status": "allocated" }
      ]
    },
    {
      "fulfillment_order_id": "FOMTV36THNN7LKLW",
      "partner_fulfillment_order_reference": "YOUR_ORDER_REF-LA",
      "fulfillment_location": {
        "partner_location_id": "ACCOUNT_cda49552-ddc6-4223-961f-29e93d32c6f4",
        "partner_location_code": "CA-WH-02",
        "partner_location_name": "California Warehouse"
      },
      "allocation_history": [
        {
          "date": "2026-09-10T05:28:26.324Z",
          "partner_location_id": "ACCOUNT_cda49552-ddc6-4223-961f-29e93d32c6f4",
          "reason": "Split from FO: FOMTV36M0F6RRSMM"
        }
      ],
      "creation_date": "2026-09-10T05:28:26.324Z",
      "status": "allocated",
      "delivery_method": "DELIVERY",
      "line_items": [
        { "id": "line-mon", "quantity": 1, "status": "allocated" }
      ]
    }
  ]
}

Each fulfillment order is now independently fulfillable and shippable from its own location.

Partial-quantity splits

If a line has quantity > 1, you can split part of it. Send the quantity to move; the remainder stays on the source fulfillment order. For example, splitting { "id": "line-mon", "quantity": 2 } off a line of 5 leaves 3 on the source fulfillment order and creates a new fulfillment order with 2.

Pitfalls

Send partner_fulfillment_order_reference. Omit it and the new fulfillment order is created with the source fulfillment order's reference. A partner reference shared by more than one fulfillment order on the order returns 400 wherever the API takes a fulfillment order by reference, so after such a split neither fulfillment order is addressable by partner reference; use the fulfillment_order_id.
The status guard is per item. Only items in open or allocated can be moved; an item that has been picked, packed, or fulfilled doesn't qualify.
Unfinished picks block the split. While the fulfillment order has an open, processing or stopped pick, the split is rejected. Cancel the pick first; a pick with picked units stops on the first cancel and needs a second.
Identify lines by id or product. The id in the line_items array is the order line item id. Send product_id, product_ref or sku instead, when that identifier names exactly one line.