Split a fulfillment order

Updated September 28, 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, carrying the lines you want to separate. Carriyo allocates one here; to send your own fulfillment orders at creation instead, 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.

Step 1, split the line into a new fulfillment order

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: omit it and the new fulfillment order inherits the source's reference, leaving both unaddressable by partner reference (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.

Step 2, 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 inherits the source's reference. Two of them then share one partner reference, which makes both unaddressable by it: any call that takes a fulfillment order by reference returns 400. Use fulfillment_order_id instead.
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.