Fulfilling multiple orders for the same customer using API

Payments + Shipping & Fulfilment

Topic summary

Goal: Combine two separate customer orders into a single shipment from the same merchant-managed location via the Fulfillment API.

Attempt: A single fulfillment request was created using line_items_by_fulfillment_order with two fulfillment_order_id entries (each from a different order), plus one shared tracking_info.

Result: The API returns an error stating all fulfillment orders in one fulfillment must belong to the same order, and identifies multiple order IDs. This indicates the API disallows creating one fulfillment that spans items from different orders. (A “fulfillment order” is the system’s unit of work tied to a single order/location.)

Status: No workaround or solution provided in the thread. The key open question is how to ship multiple orders together under one tracking number when the API restricts fulfillments to a single order. The code snippet and error message are central to understanding the issue.

Summarized with AI on January 21. AI used: gpt-5.
1

Hello,

I am building an Order management app for my business.

So all orders are routed and will be fulfilled from the same “merchant managed location” but there are cases when a customer places two orders and wants it fulfilled together under the same shipment/fulfillment.

If I do this in fulfillment object API:

{
  "fulfillment": {
    "line_items_by_fulfillment_order": [
      {
        "fulfillment_order_id": "6467120070961",
        "fulfillment_order_line_items": [
          {
            "id": "14295468638513",
            "quantity": "2"
          }
        ]
      },
      {
        "fulfillment_order_id": "6445747110193",
        "fulfillment_order_line_items": [
          {
            "id": "14242613428529",
            "quantity": "1"
          }
        ]
      }
    ],
    "tracking_info": {
      "number": "12345",
      "url": "www.kangaroo.com",
      "company": "Kangaroo Shipping"
    },
    "notify_customer": false,
    "origin_address": null,
    "message": "test message"
  }
}

I get this error:

{
    "errors": [
        "All fulfillment orders must belong to the same order. Multiple orders with ids [5512091402545, 5528552276273] were found."
    ]
}

I know this isn’t unique to us, how can one go about doing this?

Thanks,

Amin