# Apply multiple holds to a single fulfillment order — Shopify developer changelog --- ## Apply multiple holds to a single fulfillment order With the introduction of support for placing more than one hold per fulfillment order, you can quickly and easily add another hold each time an issue arises. With all of the reasons captured separately, you can release individual holds confidently, safe in the knowledge that all other reasons are captured in their own holds. ## Migrating to the `2025-01` GraphQL API version ### Fetch all holds for a fulfillment order As of the `2025-01` API version, the [fulfillmentOrder.fulfillmentHolds field](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/FulfillmentOrder#field-fulfillmentholds) now returns all active holds applied to a fulfillment order. ### Place multiple holds per fulfillment order As of the `2025-01` API version, the [fulfillmentOrderHold mutation](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/fulfillmentOrderHold) can now be successfully executed on fulfillment orders that are already on hold. To place multiple holds on a fulfillment order, apps need to supply the new [handle field](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/FulfillmentHold#field-handle). This field is a unique identifier for the holds placed by an app and prevents apps from inadvertently creating duplicate holds. The handle must be unique among the holds that the app has placed on a single fulfillment order. If an app attempts to place two holds with the same handle, the second hold will be rejected with [a duplicate hold user error](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/FulfillmentOrderHoldUserErrorCode#value-duplicatefulfillmentholdhandle). For backward compatibility, the handle field is optional and will default to an empty string. However, a single app will not be able to place multiple holds on a fulfillment order without supplying a unique handle for each, as, by default, each hold will get the same default handle. Each app can place up to 10 active holds per fulfillment order. After this, the mutation will return [a user error indicating that the limit has been reached](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/FulfillmentOrderHoldUserErrorCode#value-fulfillmentorderholdlimitreached). The app would need to release one of its existing holds before being able to apply a new one. When placing a hold on a fulfillment order that is already held, the [fulfillmentHold.fulfillmentOrderLineItems input field](https://shopify.dev/docs/api/admin-graphql/2025-01/input-objects/FulfillmentOrderHoldInput#field-fulfillmentorderlineitems) should not be supplied. If this field is supplied, [a user error will be returned indicating that the fulfillment order is not able to be split](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/FulfillmentOrderHoldUserErrorCode#value-fulfillmentordernotsplittable). The [fulfillmentOrder.supportedActions](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/fulfillmentorder#field-supportedactions) field will now return the [HOLD](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/FulfillmentOrderAction#value-hold) action when a fulfillment order is on hold and an additional hold can be added. ### Supply hold id's when releasing holds *(highly recommended)* It is highly recommended that all apps that release holds specify the hold IDs when releasing. [Support for releasing holds by id was introduced in the 2024-10 API version](https://shopify.dev/changelog/fulfillment-holds-now-able-to-be-released-by-id). Releasing all holds on a fulfillment order without supplying the hold IDs will result in the fulfillment order being released prematurely and items being incorrectly fulfilled. ### Listen for individual holds being placed and released webhooks As of the `2025-01` API version, two new webhook topics are available for the fulfillment hold resource: [fulfillment_holds/added](https://shopify.dev/docs/api/webhooks?reference=toml#list-of-topics-fulfillment_holds/added) and [fulfillment_holds/released](https://shopify.dev/docs/api/webhooks?reference=toml#list-of-topics-fulfillment_holds/released). The new webhooks will be emitted each time a hold is placed and released. ### Continue to listen for fulfillment orders being held and released using existing webhooks The [fulfillment_orders/placed_on_hold](https://shopify.dev/docs/api/webhooks?reference=toml#list-of-topics-fulfillment_orders/placed_on_hold) and [fulfillment_orders/hold_released](https://shopify.dev/docs/api/webhooks?reference=toml#list-of-topics-fulfillment_orders/hold_released) topics will continue to be emitted in the same way as before. - The [fulfillment_orders/placed_on_hold](https://shopify.dev/docs/api/webhooks?reference=toml#list-of-topics-fulfillment_orders/placed_on_hold) webhook is emitted when a fulfillment order transitions to the `ON_HOLD` status. - The [fulfillment_orders/hold_released](https://shopify.dev/docs/api/webhooks?reference=toml#list-of-topics-fulfillment_orders/hold_released) webhook is emitted when a fulfillment order is released from all holds and is no longer on hold. As of the `2025-01` API version, now that a fulfillment order can have multiple holds, the `fulfillment_order.fulfillment_holds` field in the [fulfillment_orders/placed_on_hold](https://shopify.dev/docs/api/webhooks?reference=toml#list-of-topics-fulfillment_orders/placed_on_hold) webhook payload can now return multiple holds. ## Using GraphQL API versions prior to 2025-01 ### Continue to get the first hold placed on a fulfillment order The [fulfillment holds field on a fulfillment order](https://shopify.dev/docs/api/admin-graphql/2024-10/objects/FulfillmentOrder#field-fulfillmentholds) will continue to return an array of a single hold. If multiple holds exist on the fulfillment order, the oldest active hold will be returned. Once this hold is released, the next earliest will be returned until no holds remain. ### Continue to place a single hold per fulfillment order The [fulfillmentOrderHold mutation](https://shopify.dev/docs/api/admin-graphql/2024-10/mutations/fulfillmentOrderHold) will continue to only support placing a single hold per fulfillment order. If an app attempts to place a hold on a fulfillment order that is already being held, the same error will be returned as was previously returned. It will be a user error with a message saying "`Cannot apply a fulfillment hold on a fulfillment order in an uninterruptible state.`". ### Continue to release all holds from a fulfillment order *(discouraged)* The [fulfillmentOrderReleaseHold mutation](https://shopify.dev/docs/api/admin-graphql/2024-10/mutations/FulfillmentOrderReleaseHold) will continue to release the fulfillment order from being held by releasing it from all holds at once if no hold IDs are supplied. It is highly recommended that all apps which release holds migrate to using the `2024-10` API version or newer, so that they can selectively release holds by ID by specifying the [holdIds](https://shopify.dev/docs/api/admin-graphql/2024-10/mutations/FulfillmentOrderReleaseHold#argument-holdids) mutation argument. Releasing all holds on a fulfillment order without supplying the hold IDs will result in the fulfillment order being released prematurely and items being incorrectly fulfilled. ### Continue to listen for fulfillment orders being held and released using existing webhooks The [fulfillment_orders/placed_on_hold](https://shopify.dev/docs/api/webhooks?reference=toml#list-of-topics-fulfillment_orders/placed_on_hold) and [fulfillment_orders/hold_released](https://shopify.dev/docs/api/webhooks?reference=toml#list-of-topics-fulfillment_orders/hold_released) topics will continue to be emitted in the same way as before. - The [fulfillment_orders/placed_on_hold](https://shopify.dev/docs/api/webhooks?reference=toml#list-of-topics-fulfillment_orders/placed_on_hold) webhook is emitted when a fulfillment order transitions to the `ON_HOLD` status. - The [fulfillment_orders/hold_released](https://shopify.dev/docs/api/webhooks?reference=toml#list-of-topics-fulfillment_orders/hold_released) webhook is emitted when a fulfillment order is released from all holds and is no longer on hold. The `fulfillment_order["fulfillment_holds"]` field in the webhooks payload will continue to return an array of a single hold. If multiple holds exist on the fulfillment order, the oldest active hold will be returned. ## Using the REST API to interact with holds *(discouraged)* The REST API will not support multiple holds per fulfillment order. Apps should migrate to using the GraphQL API if they wish to use this feature. ### Continue to get the first hold placed on a fulfillment order The [fulfillment holds attribute on the fulfilment order resource](https://shopify.dev/docs/api/admin-rest/2025-01/resources/fulfillmentorder) will continue showing only the one oldest active hold under scenarios of multiple holds. Once this hold is released, the next earliest will be returned until no holds remain. ### Continue to place a single hold per fulfillment order The [hold endpoint](https://shopify.dev/docs/api/admin-rest/2025-01/resources/fulfillmentorder#post-fulfillment-orders-fulfillment-order-id-hold) will continue to only support placing a single hold per fulfillment order. If an app attempts to place a hold on a fulfillment order that is already being held, the same error will be returned as was previously returned. ### Continue to release all holds from a fulfillment order *(discouraged)* The [release hold endpoint](https://shopify.dev/docs/api/admin-rest/2025-01/resources/fulfillmentorder#post-fulfillment-orders-fulfillment-order-id-release-hold) will continue to release the fulfillment order from being held by releasing it from all holds at once. It is highly recommended that all apps which release holds migrate to using the [fulfillmentOrderReleaseHold mutation](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/FulfillmentOrderReleaseHold), so that they can selectively release holds by ID. Releasing all holds on a fulfillment order without supplying the hold IDs will result in the fulfillment order being released prematurely and items being incorrectly fulfilled. ### Continue to listen for fulfillment orders being held and released using existing webhooks The [fulfillment_orders/placed_on_hold](https://shopify.dev/docs/api/webhooks?reference=toml#list-of-topics-fulfillment_orders/placed_on_hold) and [fulfillment_orders/hold_released](https://shopify.dev/docs/api/webhooks?reference=toml#list-of-topics-fulfillment_orders/hold_released) topics will continue to be emitted in the same way as before. - The [fulfillment_orders/placed_on_hold](https://shopify.dev/docs/api/webhooks?reference=toml#list-of-topics-fulfillment_orders/placed_on_hold) webhook is emitted when a fulfillment order transitions to the `ON_HOLD` status. - The [fulfillment_orders/hold_released](https://shopify.dev/docs/api/webhooks?reference=toml#list-of-topics-fulfillment_orders/hold_released) webhook is emitted when a fulfillment order is released from all holds and is no longer on hold. The `fulfillment_order["fulfillment_holds"]` field in the webhooks payload will continue to return an array of a single hold. If multiple holds exist on the fulfillment order, the oldest active hold will be returned. ## Learn more Learn more about [putting an order's fulfillment on hold](https://help.shopify.com/en/manual/fulfillment/fulfilling-orders/holding-fulfillments). *Published: January 01, 2025* Tags: API, Update Link: https://shopify.dev/changelog/apply-multiple-holds-to-a-single-fulfillment-order ---