Skip to main content

Merge Fulfillment Orders

POST 
/api/fulfillment-orders/:fulfillmentOrder/merge

Fold a sibling fulfillment order (source_fulfillment_order_id) INTO the route FO (the target). The source's lines are merged into the target per sales order line, the emptied source FO is deleted, and the target is returned. One fulfillment order → one submission → one shipment.

Required scope: orders:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Mutability gate. Both FOs must be status=open AND request_status in {unsubmitted, rejected}, at the SAME warehouse, on the SAME sales order. Violations return 409 (not mutable) or 422 (different warehouse / different sales order / self-merge).

Body fields:

  • source_fulfillment_order_id (required, integer, must exist) — the FO to merge in and remove.
  • requested_shipping_method_id (optional, integer, nullable) — resolved shipping method id (overwrites the target's).
  • requested_shipping_method (optional, string, nullable) — resolved shipping method label.
  • requested_ship_date (optional, date, nullable) — resolved requested ship date.
  • requested_metadata (optional, object, nullable) — resolved provider metadata; REPLACES the target's metadata wholesale, so send the complete merged object. Allowed keys: notes, fulfillment_sequence, signature_required, veracore_packing_slip_comments, veracore_shipping_comments, veracore_third_party_type (1–3), veracore_third_party_account_number, isInsured, instructionsForWarehouse.

The resolved-shipping fields are the CONFLICT RESOLUTION chosen in the merge dialog — omit them entirely to keep the target's existing shipping details.

On an order that mixes shipped and Click & Collect items, a pickup and a shipping fulfillment order cannot be merged, and the resolved shipping method may not switch the merged fulfillment order between shipping and pickup (409).

Required permission: fulfillment_orders.update (Fulfillment Orders → Edit) and fulfillment_orders.index (Fulfillment Orders → View). A token also needs its orders scope; the owner needs these role permissions.

Request​

Responses​

OK

Response Headers
    Content-Type