Type: Fix / Developer Guide · Stage: Scale · Topic: Fulfillment orders / Location routing / GraphQL
Quick answer
A Shopify order tag, an inventory location and a fulfillment-order assignment are three different things. If a fulfillment order refuses to move to a warehouse or 3PL, check the fulfillment order’s status and request status, whether the destination stocks the inventory item, and whether the app has the correct fulfillment-order permissions. Use the GraphQL Admin API’s locationsForMove before attempting fulfillmentOrderMove; it tells you which destinations are eligible and why others are not.
Do not repeatedly move a fulfillment order after a fulfillment service has accepted the request. Shopify blocks reassignment during specific request states to prevent two locations from fulfilling the same items.
On this page
Why “change the location” is not a simple order edit
Shopify automatically creates fulfillment orders after its order-routing process. Each fulfillment order represents work assigned to a location, not just a field on the original order. One customer order can have multiple fulfillment orders, and moving some lines may produce a different fulfillment-order ID from the one you started with.
This is why an integration that adds a tag such as “send to special warehouse” can look successful in the Shopify admin while the 3PL still receives the wrong shipment. Tags may help an external rule decide what to do, but they do not themselves execute Shopify’s fulfillment-order move. See the related Shopify Dude explanation of order tags and 3PL routing; the problem here is the next step, where an actual move is rejected.
Older REST-era integration guides often focus on changing a fulfillment-order location with a direct endpoint. Shopify’s REST Admin API is legacy for new public apps, and the current GraphQL API provides a better diagnostic path: inspect the fulfillment order and its eligible destinations first, then make the smallest permitted move.
Read the fulfillment order before touching it
Use a supported Admin GraphQL API version, such as 2026-10, and query the specific fulfillment order ID. This example also retrieves candidate destinations and their move eligibility:
query CheckFulfillmentMove($id: ID!) {
fulfillmentOrder(id: $id) {
id
status
requestStatus
assignedLocation { location { id name } }
supportedActions { action }
locationsForMove(first: 20) {
edges {
node {
location { id name }
movable
message
availableLineItemsCount { count }
unavailableLineItemsCount { count }
}
}
}
}
}
Supply an ID in the form gid://shopify/FulfillmentOrder/.... The message on each candidate is useful operational evidence: Shopify can explicitly say that no items are stocked at a location. A location existing in Settings → Locations does not prove that the inventory item is stocked there or that this particular fulfillment order is movable.
Interpret the blockers
| Finding | Meaning | Safe next action |
|---|---|---|
| Destination is not movable; no items stocked | Requested inventory item is not stocked at destination | Review inventory-item/location stocking and intended fulfillment ownership |
| Fulfillment order is closed | Its work cannot be reassigned with the ordinary move | Investigate the lifecycle; do not force a new shipment |
| Request status is SUBMITTED or ACCEPTED | Fulfillment service has an active request | Use the supported cancellation-request process and wait for service acceptance before reassignment |
| Request status is CANCELLATION_REQUESTED or CANCELLATION_REJECTED | Service-side cancellation is unresolved | Resolve with the service rather than moving anyway |
| Progress was manually reported | Fulfillment order may need to be marked open before move | Review whether fulfillmentOrderOpen is supported for this state |
| Permissions error or missing orders | App cannot access or modify that fulfillment-order class | Review read/write merchant-managed and third-party scopes and staff permission |
Be careful with partial fulfillment. Already-fulfilled lines cannot be reassigned. When only unfulfilled lines move, the returned moved fulfillment order may be different from the original. An integration that keeps using the old ID after a successful split/move can then report a false failure or send duplicate instructions.
Move only after eligibility is confirmed
Shopify documents the following GraphQL mutation for a move. It accepts an optional fulfillmentOrderLineItems array when only a subset should be moved; without it, Shopify attempts to move the unfulfilled lines that can be moved under the mutation’s rules.
mutation MoveFulfillment($id: ID!, $newLocationId: ID!) {
fulfillmentOrderMove(id: $id, newLocationId: $newLocationId) {
movedFulfillmentOrder {
id
status
assignedLocation { location { id name } }
}
originalFulfillmentOrder { id status }
userErrors { field message }
}
}
Supply both IDs as Shopify GIDs, and inspect userErrors even if the HTTP request succeeded. Save the movedFulfillmentOrder.id returned by Shopify and re-query the order’s current fulfillment orders before notifying the warehouse. The mutation’s remainingFulfillmentOrder response field is deprecated; do not build a new integration around it.
For selective routing based on engraving, personalization or a special handling rule, validate the SKU and required line-item property on the same order line, then map that line to the corresponding fulfillment-order line and quantity. Do not move the whole fulfillment order just because one qualifying SKU exists. If a third-party order management platform or 3PL also has routing rules, decide which system owns the final assignment and prevent the other from re-routing it back.
Build a safe retry policy
A move is not an operation to retry blindly. Record the original fulfillment-order ID, destination ID, intended line-item IDs and quantities, and the returned moved ID. Before any retry, re-read the current fulfillment orders. If the desired lines are already at the destination, treat that as success; if a fulfillment request was submitted meanwhile, stop and review. An external 3PL may already have a shipment in progress even if your app missed the first response.
Common misunderstanding
“The SKU exists at the destination, so Shopify must allow the move.” The destination must stock the relevant inventory item and the fulfillment order must be eligible. “The order has the right tag, so it has been routed.” Tags do not change fulfillment-order assignments. “A successful GraphQL HTTP response means the move succeeded.” Always inspect the mutation’s userErrors and returned fulfillment-order IDs.
How to test this
- Create a test order with a normal line and a line that requires special handling. Record the Shopify order line IDs and resulting fulfillment-order IDs.
- Query
locationsForMovebefore changing anything. Confirm the intended warehouse is marked movable and record its message. - Test a destination that does not stock the inventory item. Confirm the integration refuses to move it and creates an actionable review state.
- Move only the qualifying unfulfilled lines. Confirm the returned moved ID, destination, quantities and remaining fulfillment orders.
- Repeat the workflow without resetting the order. Confirm idempotent behavior and no duplicate 3PL request.
- Test a submitted or accepted fulfillment request. Verify the app stops and follows the supported cancellation process instead of bypassing it.
- Test partially fulfilled lines and a closed fulfillment order. Verify no already-fulfilled units are reassigned.
- Inspect Shopify admin, the external order manager and the 3PL destination together. Confirm exactly one system receives the fulfillment instruction.
Sources and further reading
- Shopify GraphQL Admin: fulfillmentOrder, locationsForMove and lifecycle
- Shopify GraphQL Admin: fulfillmentOrderMove and restrictions
- Shopify GraphQL Admin: fulfillmentOrderOpen
- Shopify GraphQL Admin: supported fulfillment-order actions
- Legacy REST reference: LocationsForMove (historical integration context)
- Shopify Dude: why order tags do not route a fulfillment order
- Shopify Dude: match a SKU and line-item property on the same line
Shopify documentation checked October 27, 2026.

