How to identify line items on-hold in a split order?

GraphQL Admin API Troubleshooting
1

Is there a way to identify the line items of an order that are on-hold without having to request the GraphQL relation Order.fulfillmentOrders ?

I’m not sure that I have identified the correct way to identify line items on hold when an order is split. I’m thinking to use the nonFulfillableQuantity property of the LineItem but the documentation is not clear if it (always) includes on-hold line items.

Currently the application use currentQuantity and I was wrongly expecting currentQuantity to not include on-hold line items.

A screenshot to illustrate what I mean by split order with on hold items:

CleanShot 2025-10-20 at 15.06.51
CleanShot 2025-10-20 at 15.06.51685×728 51.2 KB

1 Like
2

Internal Notes:

confirmed on test store:

  • queried order line items from open fulfillment order

  • placed fulfillment order on hold

  • queried order line items and fulfillment order hold again

    • the nonFulfillableQuantity and other fields on the order.lineItem isn’t affected by the fulfilment order being on hold

  • to see if a line items is on hold, they will need to retrieve the order.fulfillmentOrder and check for any holds on the Fulfillment Order and see what line items are included in the fulfillment order with the order.fulfillmentOrder.fulfillmentHolds and order.fulfillmentOrder.lineItems

3

Hi @Antonio,

At this time there is no way to tell if a line item on an order is included in a Fulfillment Order Hold, without querying the Fulfillment Order directly.

I can confirm that the order.lineItems.nonFulfillableQuantity field does not reflect if the line item is included in a Fulfillment Order Hold or not. Even if the line item is on hold, it is still technically fulfillable and won’t be counted with nonFulfillableQuantity

Currently the only way to see if a line item on an order is included in a Fulfillment Order Hold, is to query the Fulfillment Order itself, and see if there is any holds active with the fulfillmentOrder.status field or querying the fulfillmentOrder.fulfillmentHolds connector.

Here’s an example query that you can use to see if a Fulfillment Order is on hold, and what line items are included.

{
    order(id: "gid://shopify/Order/12345678910") {
        id
        fulfillmentOrders(first: 10) {
            nodes {
                id
                status
                fulfillmentHolds {
                    id
                    handle
                    reason
                    displayReason
                }
                lineItems(first:10){ #represents the line item on the Fulfillment Order
                    nodes{
                        id
                        productTitle
                        totalQuantity
                        remainingQuantity
                        lineItem{ #represents the line item on the Order
                            id
                            title
                        }
                    }
                }
                
            }
        }
    }
}
4

Thank you very much @Kellan-Shopify !

Requesting the order.fulfillmentOrder brings my application in the complicated World of the Fulfillment Order scopes:

  • read_merchant_managed_fulfillment_orders
  • read_assigned_fulfillment_orders
  • read_third_party_fulfillment_orders

From my understanding, a picking application like mine is in the class of Order management apps but I’m not sure that the scope read_merchant_managed_fulfillment_orders is enough to get all the line items on hold.
Maybe it’s enough, maybe I should request the three read fulfillment scopes to be safe. Is there a clear guideline for a case like mine?

5

Hey @Antonio,

I’m happy to help!

I can confirm that you would need the read...fulfillment_orders scopes to be able to check the fulfillment order hold status.

You can certainly request all 3 scopes, but you will only need the scope for the type of orders that you would be checking specifically.

  • read_merchant_managed_fulfillment_orders

    • this will allow you to check the status from orders that the merchant must fulfill via the Shopify Admin directly.

  • read_assigned_fulfillment_orders

    • this will allow you to check the status from orders that are assigned to your own fulfillment service app, if your app is creating the actual fulfillments for the order.

  • read_third_party_fulfillment_orders

    • this will alow you to check the status from orders that are assigned to be fulfilled by other 3rd party apps.
6

Thank you @Kellan-Shopify,

I think you gave me all I need to add this feature to my picking app !

1 Like