How to correctly use the fulfillment order line items prepared for pick up mutation

Technical Q&A
1

Hi,

I am struggling to use the `fulfillmentOrderLineItemsPreparedForPickup’ mutation to mark items as ready for pick up.

I have been using the Shopify GraphiQL App to query my test store but I cannot get this to work despite having all the correct access scopes/permissions etc.

For example, I have the below fulfillment which hasn’t been processed yet.

image
image1331×706 53 KB

I use the ‘FulfillmentOrderShow’ to check that fulfillment is associated with the order

query FulfillmentOrderShow($id: ID!) {
  fulfillmentOrder(id: $id) {
    assignedLocation {
      location {
        id
      }
    }
    channelId
    destination {
      address1
      address2
      city
      company
      countryCode
      zip
      firstName
      lastName
    }
    fulfillAt
    fulfillBy
    requestStatus
    status
    lineItems(first: 10) {
      edges {
        node {
          inventoryItemId
          remainingQuantity
          requiresShipping
          weight {
            unit
            value
          }
        }
      }
    }
  }
}

{
  "id": "gid://shopify/FulfillmentOrder/7436723912882"
}

and this is the response I get with the status being open

{
  "data": {
    "fulfillmentOrder": {
      "assignedLocation": {
        "location": {
          "id": "gid://shopify/Location/81880907954"
        }
      },
      "channelId": null,
      "destination": {
        "address1": "1 Meta Way",
        "address2": null,
        "city": "Menlo Park",
        "company": null,
        "countryCode": "US",
        "zip": "94025"
      },
      "fulfillAt": "2025-10-12T22:00:00Z",
      "fulfillBy": null,
      "requestStatus": "UNSUBMITTED",
      "status": "OPEN",
      "lineItems": {
        "edges": [
          {
            "node": {
              "inventoryItemId": "gid://shopify/InventoryItem/48544701972658",
              "remainingQuantity": 1,
              "requiresShipping": true,
              "weight": {
                "unit": "OUNCES",
                "value": 2.5
              }
            }
          }
        ]
      }
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 10,
      "actualQueryCost": 7,
      "throttleStatus": {
        "maximumAvailable": 20000,
        "currentlyAvailable": 19993,
        "restoreRate": 1000
      }
    }
  }
}

I now try and call the ‘fulfillmentOrderLineItemsPreparedForPickup‘ mutation with the below request

mutation fulfillmentOrderLineItemsPreparedForPickup($input: FulfillmentOrderLineItemsPreparedForPickupInput!) {
  fulfillmentOrderLineItemsPreparedForPickup(input: $input) {
    userErrors {
      field
      message
    }
  }
}

{
  "input": {
    "lineItemsByFulfillmentOrder": [
      {
        "fulfillmentOrderId": "gid://shopify/FulfillmentOrder/7436723912882"
      }
    ]
  }
}

Always end up with the response saying invalid fulfillment order id provided. I have tried with a different order as well. Is there a step that I am missing in between to get this working correctly? Any help would be appreciated.

{
  "data": {
    "fulfillmentOrderLineItemsPreparedForPickup": {
      "userErrors": [
        {
          "field": [
            "input",
            "lineItemsByFulfillmentOrder",
            "0",
            "fulfillmentOrderId"
          ],
          "message": "Invalid fulfillment_order_id provided 7436723912882"
        }
      ]
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 10,
      "actualQueryCost": 10,
      "throttleStatus": {
        "maximumAvailable": 20000,
        "currentlyAvailable": 19990,
        "restoreRate": 1000
      }
    }
  }
}
2

This issue usually happens because the Fulfillment Order ID you’re passing isn’t yet eligible for pickup preparation even if it exists and looks valid. A few things to check:

  1. Ensure the order is a local pickup order, not shipping. The mutation fulfillmentOrderLineItemsPreparedForPickup only works for pickup-type fulfillment orders. You can confirm by checking the deliveryMethodType field in the fulfillmentOrder query it should return "PICK_UP".

  2. Confirm the fulfillment order is assigned to a location with pickup enabled. If the location in your response isn’t configured for in-store pickup, the API will reject the ID as invalid for this mutation.

  3. If you’re testing with a development store, make sure the fulfillment order was created via a pickup order, not a regular shipping one — otherwise Shopify treats it differently in the fulfillment lifecycle.

Here’s a quick example of what a valid input might look like:

mutation {
  fulfillmentOrderLineItemsPreparedForPickup(
    input: {
      lineItemsByFulfillmentOrder: [
        {
          fulfillmentOrderId: "gid://shopify/FulfillmentOrder/7436723912882",
          fulfillmentOrderLineItems: [
            { id: "gid://shopify/FulfillmentOrderLineItem/XXXX", quantity: 1 }
          ]
        }
      ]
    }
  ) {
    userErrors { field message }
  }
}

If you’re still getting the same “invalid ID” error after confirming the above, it’s likely that the fulfillment order hasn’t transitioned into a pickup-eligible state.

I have helped a few merchant set up and guide these pickup workflows using GraphQL and custom fulfillment apps if you’d like, I can take a quick look at your test setup and help you get it working properly.

3

From what you’ve described, it looks like your fulfillmentOrderLineItemsPreparedForPickup mutation is failing because of a state mismatch or missing required fields in the mutation input.

A few quick checks before retrying:

Confirm fulfillment type:
The assigned location must be tied to a local pickup fulfillment service type. If the order was created with a standard shipping method, the pickup mutation will return invalid fulfillment order id provided.

Add the fulfillmentOrderLineItems parameter explicitly:
Even though the mutation name sounds like it acts on the entire order, Shopify expects the specific fulfillmentOrderLineItems node array.

Ensure correct order flow:
The mutation can only be used once the order’s fulfillment request has been accepted or acknowledged. Try confirming the fulfillment request first using the fulfillmentOrderAcceptFulfillmentRequest mutation.

let me know if you understand and if it works

4

Thank you both for your help! It was indeed the delivery method type. All my orders were set to ‘Shipping’ instead of ‘Pickup in store‘.

I ended up creating a new location and configured it to allow in-store pickups. I then tested it through the checkout page by selecting ‘Pick up’ as the delivery method.

After doing all the above, I could use the fulfillmentOrderLineItemsPreparedForPickup mutation.