Split a fulfillment order

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 FO into a new FO at a location you choose. The original FO 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 FO 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 OMP7782ABCDEF with one fulfillment order FOMP7782NJ001 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 FO at LA

curl -X POST \
  'https://api.carriyo.com/orders/OMP7782ABCDEF/fulfillment-orders/FOMP7782NJ001/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 '{
    "location_id": "CA-WH-02",
    "line_items": [
      { "id": "line-mon", "quantity": 1 }
    ]
  }'

• location_id is where the split-off lines go. It accepts a partner_location_code (used here) or Carriyo's internal location id.
• line_items names which lines (and quantities) to peel off into the new FO, referenced by the order line item id.

The new FO inherits the source FO'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 FO keeps the keyboard; a new FO appears at LA carrying the monitor:

{
  "order_id": "OMP7782ABCDEF",
  "status": "allocated",
  "fulfillment_orders": [
    {
      "fulfillment_order_id": "FOMP7782NJ001",
      "location_id": "NJ-WH-01",
      "status": "allocated",
      "line_items": [
        { "id": "line-kbd", "quantity": 1, "status": "allocated" }
      ]
    },
    {
      "fulfillment_order_id": "FOMP7782LA001",
      "location_id": "CA-WH-02",
      "status": "allocated",
      "line_items": [
        { "id": "line-mon", "quantity": 1, "status": "allocated" }
      ],
      "creation_date": "2026-05-12T15:08:11.000Z"
    }
  ]
}

Each FO 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 FO. For example, splitting { "id": "line-mon", "quantity": 2 } off a line of 5 leaves 3 on the source FO and creates a new FO with 2.

Pitfalls

• Status guard. The FO must be open or allocated. A processing or fulfilled FO must be rolled back (unpick / unfulfill) before it can be split.
• Active picks block the split. If the Fulfillment App has started a pick on the FO, the split is rejected. Cancel the pick first.
• Lines reference the order's line-item id. The id in the line_items array is the order line item id, not a SKU.