Hold Fulfillment Order

//native

/**

 * Hold Fulfillment Order

 * Put a fulfillment order on hold so it can't be fulfilled until the hold is released. Pass line_items ({ id, quantity } of fulfillment order line items) to hold only part of it; the rest is split into remainingFulfillmentOrder. Up to 10 holds per app per fulfillment order.

 */

export async function main(

  auth: RT.Shopify,

  fulfillment_order_id: string,

  reason:

    | "AWAITING_PAYMENT"

    | "HIGH_RISK_OF_FRAUD"

    | "INCORRECT_ADDRESS"

    | "INVENTORY_OUT_OF_STOCK"

    | "UNKNOWN_DELIVERY_DATE"

    | "AWAITING_RETURN_ITEMS"

    | "OTHER",

  reason_notes: string | undefined,

  notify_merchant: boolean | undefined,

  handle: string | undefined,

  line_items: { id: string; quantity: number }[] | undefined

) {

  const response = await fetch(

    `https://${auth.store_name}.myshopify.com/admin/api/2026-10/graphql.json`,

    {

      method: "POST",

      headers: {

        "X-Shopify-Access-Token": auth.token,

        "Content-Type": "application/json",

        Accept: "application/json",

      },

      body: JSON.stringify({

        query: `mutation ($id: ID!, $fulfillmentHold: FulfillmentOrderHoldInput!) { fulfillmentOrderHold(id: $id, fulfillmentHold: $fulfillmentHold) { fulfillmentHold { id reason reasonNotes handle } fulfillmentOrder { id status } remainingFulfillmentOrder { id status } userErrors { field message } } }`,

        variables: {

          id: fulfillment_order_id.startsWith("gid://")

            ? fulfillment_order_id

            : `gid://shopify/FulfillmentOrder/${fulfillment_order_id}`,

          fulfillmentHold: {

            reason,

            reasonNotes: reason_notes || undefined,

            notifyMerchant: notify_merchant || undefined,

            handle: handle || undefined,

            fulfillmentOrderLineItems: line_items?.length

              ? line_items.map((li) => ({

                  id: li.id.startsWith("gid://")

                    ? li.id

                    : `gid://shopify/FulfillmentOrderLineItem/${li.id}`,

                  quantity: li.quantity,

                }))

              : undefined,

          },

        },

      }),

    }

  )

  if (!response.ok) {

    throw new Error(`${response.status} ${await response.text()}`)

  }

  const { data, errors } = await response.json()

  if (errors) {

    throw new Error(JSON.stringify(errors))

  }

  if (data.fulfillmentOrderHold.userErrors.length) {

    throw new Error(JSON.stringify(data.fulfillmentOrderHold.userErrors))

  }

  return data.fulfillmentOrderHold

}