fulfillmentOrderHold

mutation

Requires write_merchant_managed_fulfillment_orders access scope or write_third_party_fulfillment_orders access scope. Also: The user must have fulfill_and_ship_orders permission.

Applies a fulfillment hold on a fulfillment order.

As of the 2025-01 API version, the mutation can be successfully executed on fulfillment orders that are already on hold. To place multiple holds on a fulfillment order, apps need to supply the handle field. Each app can place up to 10 active holds per fulfillment order. If an app attempts to place more than this, the mutation will return a user error indicating that the limit has been reached. The app would need to release one of its existing holds before being able to apply a new one.

Arguments

Anchor to fulfillmentHoldfulfillmentHold • FulfillmentOrderHoldInput!required: The details of the fulfillment hold applied on the fulfillment order.
Anchor to idid • ID!required: The ID of the fulfillment order on which a fulfillment hold is applied.

Was this section helpful?

Anchor to FulfillmentOrderHoldPayload returnsFulfillmentOrderHoldPayload returns

Anchor to fulfillmentHoldfulfillmentHold • FulfillmentHold: The fulfillment hold created for the fulfillment order. Null if no hold was created.
Anchor to fulfillmentOrderfulfillmentOrder • FulfillmentOrder: The fulfillment order on which a fulfillment hold was applied.
Anchor to remainingFulfillmentOrderremainingFulfillmentOrder • FulfillmentOrder: The remaining fulfillment order containing the line items to which the hold wasn't applied, if specific line items were specified to be placed on hold.
Anchor to userErrorsuserErrors • [FulfillmentOrderHoldUserError!]!non-null: The list of errors that occurred from executing the mutation.

Was this section helpful?

Applies a fulfillment hold on an open fulfillment order
Put a fulfillment order on hold
fulfillmentOrderHold reference

Examples

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(

`#graphql

mutation FulfillmentOrderHold($fulfillmentHold: FulfillmentOrderHoldInput!, $id: ID!) {

fulfillmentOrderHold(fulfillmentHold: $fulfillmentHold, id: $id) {

fulfillmentOrder {

}

remainingFulfillmentOrder {

}

userErrors {

field

message

}

}`,

{

variables: {

"fulfillmentHold": {

"reason": "INVENTORY_OUT_OF_STOCK",

"reasonNotes": "Waiting on new shipment"

"id": "gid://shopify/FulfillmentOrder/1046001479"

mutation FulfillmentOrderHold($fulfillmentHold: FulfillmentOrderHoldInput!, $id: ID!) {
  fulfillmentOrderHold(fulfillmentHold: $fulfillmentHold, id: $id) {
    fulfillmentOrder {
      id
    }
    remainingFulfillmentOrder {
      id
    }
    userErrors {
      field
      message
    }
  }
}

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-04/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation FulfillmentOrderHold($fulfillmentHold: FulfillmentOrderHoldInput!, $id: ID!) { fulfillmentOrderHold(fulfillmentHold: $fulfillmentHold, id: $id) { fulfillmentOrder { id } remainingFulfillmentOrder { id } userErrors { field message } } }",
 "variables": {
    "fulfillmentHold": {
      "reason": "INVENTORY_OUT_OF_STOCK",
      "reasonNotes": "Waiting on new shipment"
    },
    "id": "gid://shopify/FulfillmentOrder/1046001479"
  }
}'

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(
  `#graphql
  mutation FulfillmentOrderHold($fulfillmentHold: FulfillmentOrderHoldInput!, $id: ID!) {
    fulfillmentOrderHold(fulfillmentHold: $fulfillmentHold, id: $id) {
      fulfillmentOrder {
        id
      }
      remainingFulfillmentOrder {
        id
      }
      userErrors {
        field
        message
      }
    }
  }`,
  {
    variables: {
      "fulfillmentHold": {
        "reason": "INVENTORY_OUT_OF_STOCK",
        "reasonNotes": "Waiting on new shipment"
      },
      "id": "gid://shopify/FulfillmentOrder/1046001479"
    },
  },
);

const data = await response.json();

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation FulfillmentOrderHold($fulfillmentHold: FulfillmentOrderHoldInput!, $id: ID!) {
      fulfillmentOrderHold(fulfillmentHold: $fulfillmentHold, id: $id) {
        fulfillmentOrder {
          id
        }
        remainingFulfillmentOrder {
          id
        }
        userErrors {
          field
          message
        }
      }
    }`,
    "variables": {
      "fulfillmentHold": {
        "reason": "INVENTORY_OUT_OF_STOCK",
        "reasonNotes": "Waiting on new shipment"
      },
      "id": "gid://shopify/FulfillmentOrder/1046001479"
    },
  },
});

session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  mutation FulfillmentOrderHold($fulfillmentHold: FulfillmentOrderHoldInput!, $id: ID!) {
    fulfillmentOrderHold(fulfillmentHold: $fulfillmentHold, id: $id) {
      fulfillmentOrder {
        id
      }
      remainingFulfillmentOrder {
        id
      }
      userErrors {
        field
        message
      }
    }
  }
QUERY

variables = {
  "fulfillmentHold": {
    "reason": "INVENTORY_OUT_OF_STOCK",
    "reasonNotes": "Waiting on new shipment"
  },
  "id": "gid://shopify/FulfillmentOrder/1046001479"
}

response = client.query(query: query, variables: variables)

Input variables

JSON

{

"fulfillmentHold": {

"reason": "INVENTORY_OUT_OF_STOCK",

"reasonNotes": "Waiting on new shipment"

"id": "gid://shopify/FulfillmentOrder/1046001479"

}

Response

JSON

{

"fulfillmentOrderHold": {

"fulfillmentOrder": {

"id": "gid://shopify/FulfillmentOrder/1046001479"

"remainingFulfillmentOrder": null,

"userErrors": []

}