---
title: "Hold an order's fulfillments"
description: "Put all of the order's fulfillment orders on hold, with an optional reason."
url: https://docs.stoqapp.com/v2-reference/preorders-orders/hold-an-orders-fulfillments/
api: "API v2 reference"
method: POST
path: "/preorders/orders/{id}/hold_fulfillments"
---

# Hold an order's fulfillments

`POST https://app.stoqapp.com/api/v2/external/preorders/orders/{id}/hold_fulfillments`

Put all of the order's fulfillment orders on hold, with an optional reason.

**Note:** Matches the dashboard action Hold fulfillments and the Flow action Hold all fulfillments. Every open or scheduled fulfillment order is held, preorder or not; one this app already holds is skipped. reason_notes is shown on the hold in Shopify; without it the default hold note is used. outcome lists each fulfillment order held, skipped or rejected. Fails (422) when nothing could be held.

## Path parameters

- `id` (string, required): The order, by STOQ's order ID or the Shopify order ID.

## Headers

- `Idempotency-Key` (string): A fresh unique key for every write (a new UUID, say); reuse it only to retry that write. Keys are remembered for 1 hour: the same key and the same request within that hour returns the first result, with `Idempotent-Replayed: true`, without running again; the same key with a different method, path or body is refused (422 `idempotency_key_reused`); a retry while the first is still running gets 409 `idempotency_key_in_progress`. Keys are per store. Server errors and rate limits are not kept, so their retry runs.

## Request body

- `reason_notes` (string): Reason shown on the hold in Shopify. Defaults to the standard hold note.

## Returns

- `id` (string): STOQ's id for the order. Pass it, or shopify_order_id, as :id to the other order endpoints.
- `type` (string): Kind of order: preorder, or back_in_stock for an order STOQ attributed to a back-in-stock alert. One of: `preorder`, `back_in_stock`.
- `shopify_order_id` (string): The Shopify order gid (gid://shopify/Order/&lt;id&gt;).
- `name` (string): The Shopify order name, such as #1001.
- `customer` (object): The customer who placed the order, as recorded on it.
  - `id` (null): The customer's STOQ id, the value the customer_id filter takes. Null when the order isn't linked to a STOQ customer.
  - `shopify_customer_id` (null): The Shopify customer gid (gid://shopify/Customer/&lt;id&gt;). Null when the order isn't linked to a customer.
  - `email` (string): Email address on the order.
  - `phone` (string): Phone number on the order, or null when none was given.
  - `name` (string): Customer's first and last name, or null when the order has neither.
- `total_price` (string): Order total in the order's currency, as a decimal string such as &quot;49.99&quot;.
- `currency` (string): ISO 4217 code of the currency the order was paid in, such as USD.
- `financial_status` (string): The Shopify financial status, such as paid, partially_paid, pending, authorized, refunded, partially_refunded or voided.
- `fulfillment_status` (string): Shopify's fulfillment status for the whole order, lowercased, such as unfulfilled, partially_fulfilled, fulfilled, scheduled or on_hold. Null until Shopify reports one.
- `payment_status` (string): Where the order's payment stands, from the values Shopify synced: paid_in_full (no deferred balance), balance_pending, balance_overdue (due date passed), balance_collected, paid, not_synced (outstanding amount not known yet), cancelled, or the refund status (refunded, partially_refunded). One of: `paid_in_full`, `balance_pending`, `balance_overdue`, `balance_collected`, `paid`, `not_synced`, `cancelled`, `refunded`, `partially_refunded`.
- `cancelled_at` (null): When the order was cancelled (ISO 8601), or null when it isn't.
- `created_at` (string): When STOQ recorded the order (ISO 8601). The from and to filters match on this.
- `updated_at` (string): When STOQ last changed its record of the order (ISO 8601).
- `payments` (object): What the order cost, what has been paid and what is still owed. Also at GET /preorders/orders/:id/payments.
  - `currency` (string): ISO 4217 code of the currency of every amount in this section.
  - `payment_status` (string): Where the order's payment stands: paid_in_full, balance_pending, balance_overdue, balance_collected, paid, not_synced, cancelled, or the refund status (refunded, partially_refunded). One of: `paid_in_full`, `balance_pending`, `balance_overdue`, `balance_collected`, `paid`, `not_synced`, `cancelled`, `refunded`, `partially_refunded`.
  - `financial_status` (string): The Shopify financial status, such as paid, partially_paid, pending, authorized, refunded, partially_refunded or voided.
  - `subtotal_price` (string): Shopify's current subtotal, before tax and shipping, as a decimal string. Null when Shopify hasn't reported it.
  - `tax_lines` (array of anys): The taxes Shopify charged on the order.
  - `total_price` (string): Order total as a decimal string, including tax and shipping.
  - `total_outstanding` (string): Amount still owed according to Shopify, as a decimal string. Null until Shopify has reported it.
  - `amount_paid` (string, nullable): Amount paid so far (total_price minus total_outstanding), as a decimal string. Null when the outstanding amount isn't known yet or the order was refunded.
  - `deferred_amount` (string, nullable): The part of the order left to pay later under a partial payment offer, as a decimal string. Null when nothing was deferred.
  - `due_at` (string): When the remaining balance is due (ISO 8601), or null when there is no payment schedule.
  - `overdue` (boolean): Whether the due date has passed with a balance still outstanding.
  - `balance_collected` (boolean): Whether a deferred balance has been fully paid.
  - `balance_collected_at` (null): When STOQ saw the deferred balance paid off (ISO 8601), or null.
  - `last_payment_attempt` (null): The latest charge STOQ attempted on the customer's saved payment method, automatic or manual. Null when there has been none.
  - `payment_attempts` (array of anys): Up to the 10 most recent charges STOQ attempted, newest first.
- `fulfillment` (object): How the order is being fulfilled: holds, scheduled fulfillments and separate orders. Also at GET /preorders/orders/:id/fulfillment.
  - `fulfillment_status` (string): Shopify's fulfillment status for the whole order, lowercased, such as unfulfilled, partially_fulfilled, fulfilled, scheduled or on_hold.
  - `preorder_fulfillment_status` (null): State of the fulfillment orders holding the preorder items, the most blocked one first: on_hold, scheduled or open (awaiting fulfillment). Null when nothing is left to fulfill or it hasn't been read from Shopify yet.
  - `hold_reason_note` (string, nullable): The note Shopify received with the fulfillment hold, from the offer that caused it. Null when no offer on the order holds fulfillments.
  - `holds_applied_at` (string): When STOQ last placed the order's fulfillments on hold (ISO 8601), or null.
  - `shopify_split_order_ids` (array of anys): Shopify order gids of the separate orders STOQ moved preorder items to. Empty when the order wasn't split.
  - `offers` (array of objects): The offers on the order and how each fulfills its items.
    - `offer_id` (string): The offer's id.
    - `handling` (string): How the offer fulfills preorder items: none, hold_all (holds every fulfillment), split_fulfillments (ships in-stock items first) or separate_orders (moves preorder items to their own order). One of: `none`, `hold_all`, `split_fulfillments`, `separate_orders`.
- `notifications` (object): The preorder messages sent to the customer for this order. Also at GET /preorders/orders/:id/notifications.
  - `confirmation_email` (object): The preorder confirmation email.
    - `sent_count` (integer): How many times it was sent for this order.
    - `last_sent_at` (null): When it was last sent (ISO 8601), or null when it never was.
    - `last_triggered_by` (null): What sent it last, such as automatic or manual. Null when it was never sent.
  - `confirmation_sms` (object): The preorder confirmation SMS.
    - `sent_count` (integer): How many times it was sent for this order.
    - `last_sent_at` (null): When it was last sent (ISO 8601), or null when it never was.
    - `last_triggered_by` (null): What sent it last, such as automatic or manual. Null when it was never sent.
  - `shipping_update_email` (object): The shipping update email.
    - `sent_count` (integer): How many times it was sent for this order.
    - `last_sent_at` (null): When it was last sent (ISO 8601), or null when it never was.
    - `last_triggered_by` (null): What sent it last, such as automatic or manual. Null when it was never sent.
- `tags` (object): The order's tags.
  - `tags` (array of strings): The Shopify order's tags, read live from Shopify. Null when Shopify couldn't be reached.
  - `configured_by_offers` (array of strings): The tags the order's offers are set to add to their orders.
- `attributed_offers` (array of objects): The offers the order's preorder items were bought through, with each offer's current shipping settings.
  - `offer_id` (string): The offer's id.
  - `offer_name` (string): The offer's name.
  - `offer_internal_name` (string): The offer's internal name, shown only in the STOQ admin.
  - `current_status` (string): The offer's state now: live, off, scheduled (starts later) or deleted. One of: `live`, `false`, `scheduled`, `deleted`.
  - `shipping` (object): The offer's shipping settings as they are now, in the same shape as GET /preorders/offers/:id/shipping. They may have changed since the order was placed.
    - `timeline` (object): The shipping timeline text shown with the preorder button.
      - `scope` (string): same shows one shipping text for every product; per_variant uses each variant's own shipping text. One of: `same`, `per_variant`.
      - `show_shipping_text` (boolean): Whether the shipping text shows with the preorder button.
      - `shipping_text` (string): The line under the preorder button.
      - `variant_shipping_text` (string): A variant's shipping text when it has none of its own; every variant's when scope is same.
    - `delivery_timing` (string): Fulfillment status of preorder items: asap is Unfulfilled (ship now), exact_time is Scheduled (on ships_at or days_after_checkout), unknown is On hold (no date promised). One of: `asap`, `exact_time`, `unknown`.
    - `ships_at` (null): Ship date as a UTC timestamp (ISO 8601). Null unless items ship on a fixed date.
    - `days_after_checkout` (null): Days after checkout that items ship. Null unless items ship a set time after purchase.
    - `fulfillment` (object): How preorder items are fulfilled: held, split, or moved to a separate order.
      - `handling` (string): How the offer fulfills preorder items: none, hold_all (holds every fulfillment), split_fulfillments (ships in-stock items first) or separate_orders (moves preorder items to their own order). One of: `none`, `hold_all`, `split_fulfillments`, `separate_orders`.
      - `hold_reason` (string): The hold reason shown in Shopify.
      - `separate_orders` (object): Settings for the separate orders preorder items move to, used when handling is separate_orders.
        - `grouping` (string): offer creates one separate order per offer; variant one per variant; ship_date one per ship date. One of: `offer`, `variant`, `ship_date`.
        - `number_format` (string): sequential gives each separate order its own order number; suffix appends suffix to the original order name. One of: `sequential`, `suffix`.
        - `suffix` (string): Suffix appended to the separate order name.
        - `hold_fulfillments` (boolean): Whether fulfillments on the separate order are held until they're released.
        - `tag` (string): Tag applied to the separate preorder order.
        - `transaction_gateway` (string): Payment gateway recorded on the separate order transaction.
        - `original_order_hold_tag` (null): Tag on the original order while it is being split, removed once the split finishes. Null when none is set.
        - `original_order_split_tag` (null): Tag on the original order after the preorder items move to a separate order. Null when none is set.
    - `on_hold` (object): When held fulfillments are released.
      - `release_schedule` (string): scheduled releases held fulfillments on release_at; manual leaves them held. One of: `scheduled`, `manual`.
      - `release_at` (null): When held fulfillments are released (ISO 8601). Null unless release_schedule is scheduled.
      - `require_payment` (boolean): Whether holds are only released once the balance is paid.
  - `shopify_line_item_ids` (array of strings): Shopify line item gids of this order's items bought through the offer. A bundle lists its components.
  - `attribution_url` (string): API path of the offer, relative to the host.
- `line_items` (array of objects): Every item on the order, preorder or not. A bundle is one entry with its parts under components.
  - `id` (string): STOQ's id for the line item. collect_payment takes it in line_item_ids.
  - `shopify_line_item_id` (string): The Shopify line item gid (gid://shopify/LineItem/&lt;id&gt;). Null for a bundle, which has no Shopify line item of its own.
  - `shopify_line_item_group_id` (null): The Shopify line item group gid (gid://shopify/LineItemGroup/&lt;id&gt;) of the bundle the item belongs to, or null when it isn't part of one.
  - `shopify_variant_id` (string): The Shopify variant gid (gid://shopify/ProductVariant/&lt;id&gt;).
  - `title` (string): Product title.
  - `variant_title` (string): Variant title, or null for a product with only its default variant.
  - `fulfillment_status` (null): Shopify's fulfillment status for the item: fulfilled, partial, or null while nothing has shipped.
  - `preorder_fulfillment_status` (null): State of the fulfillment order holding a preorder item: on_hold, scheduled or open. A bundle takes its most blocked part's. Null for an in-stock item or once nothing is left to fulfill.
  - `is_preorder` (boolean): Whether the item was bought as a preorder.
  - `offer_id` (string, nullable): The id of the offer the item was preordered through, or null for an in-stock item.
  - `quantity` (integer): Quantity ordered.
  - `line_total` (string): Price times quantity plus tax, as a decimal string in the order's currency: what collecting payment for this item charges.
- `outcome` (object): What the action did to the order: the fields it changed and, for fulfillment and payment actions, Shopify's answer.
  - `fulfillment_orders` (array of objects): Each Shopify fulfillment order the action was applied to, with Shopify's answer. Shopify can accept some and reject others.
    - `fulfillment_order_id` (integer): The Shopify fulfillment order's numeric id.
    - `status` (string): success, failure, or skipped when the fulfillment order couldn't be held in its current state (hold only). One of: `success`, `failure`, `skipped`.
    - `error` (string, nullable): Why Shopify rejected or STOQ skipped the fulfillment order, or null on success.
  - `succeeded` (integer): How many fulfillment orders succeeded.
  - `failed` (integer): How many fulfillment orders failed or were skipped.

Rate limit: this call costs 2 points ([rate limits](https://docs.stoqapp.com/docs/rate-limits/)).

## Example request

```sh
curl -X POST "https://app.stoqapp.com/api/v2/external/preorders/orders/5f0c8a3e-6b2d-4f1a-9c7e-2d8b1a4e6f30/hold_fulfillments" \
  -H "X-Auth-Token: $STOQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason_notes": "Waiting on stock"
  }'
```

## 202

Success: example response shown.

```json
{
  "id": "5f0c8a3e-6b2d-4f1a-9c7e-2d8b1a4e6f30",
  "type": "preorder",
  "shopify_order_id": "gid://shopify/Order/6123456789012",
  "name": "#1047",
  "customer": {
    "id": "9b3e5f71-24c8-4d0a-b6e2-81f4c7a9d3e5",
    "shopify_customer_id": "gid://shopify/Customer/7234567890123",
    "email": "jordan.lee@example.com",
    "phone": "+14155550142",
    "name": "Jordan Lee"
  },
  "total_price": "110.00",
  "currency": "USD",
  "financial_status": "partially_paid",
  "fulfillment_status": null,
  "payment_status": "balance_pending",
  "cancelled_at": null,
  "created_at": "2026-06-12T14:32:10Z",
  "updated_at": "2026-06-20T09:15:02Z",
  "payments": {
    "currency": "USD",
    "payment_status": "balance_pending",
    "financial_status": "partially_paid",
    "subtotal_price": "110.00",
    "tax_lines": [],
    "total_price": "110.00",
    "total_outstanding": "55.00",
    "amount_paid": "55.00",
    "deferred_amount": "55.00",
    "due_at": "2026-08-01T12:00:00Z",
    "overdue": false,
    "balance_collected": false,
    "balance_collected_at": null,
    "last_payment_attempt": null,
    "payment_attempts": []
  },
  "fulfillment": {
    "fulfillment_status": null,
    "preorder_fulfillment_status": "on_hold",
    "hold_reason_note": "Waiting on stock",
    "holds_applied_at": "2026-06-20T09:15:01Z",
    "shopify_split_order_ids": [],
    "offers": [
      {
        "offer_id": "73a74948-2b57-4cc3-971f-2b441828c977",
        "handling": "hold_all"
      }
    ]
  },
  "notifications": {
    "confirmation_email": {
      "sent_count": 1,
      "last_sent_at": "2026-06-12T14:32:16Z",
      "last_triggered_by": "automatic"
    },
    "confirmation_sms": {
      "sent_count": 0,
      "last_sent_at": null,
      "last_triggered_by": null
    },
    "shipping_update_email": {
      "sent_count": 0,
      "last_sent_at": null,
      "last_triggered_by": null
    }
  },
  "tags": {
    "tags": [
      "STOQ-preorder",
      "summer-drop"
    ],
    "configured_by_offers": [
      "STOQ-preorder"
    ]
  },
  "attributed_offers": [
    {
      "offer_id": "73a74948-2b57-4cc3-971f-2b441828c977",
      "offer_name": "Summer Sneaker Drop",
      "offer_internal_name": "summer-2026",
      "current_status": "live",
      "shipping": {
        "timeline": {
          "scope": "same",
          "show_shipping_text": true,
          "shipping_text": "Shipping: {{ date }}",
          "variant_shipping_text": "Ships in August"
        },
        "delivery_timing": "exact_time",
        "ships_at": "2026-08-01T16:00:00Z",
        "days_after_checkout": null,
        "fulfillment": {
          "handling": "hold_all",
          "hold_reason": "Waiting on stock",
          "separate_orders": {
            "grouping": "offer",
            "number_format": "suffix",
            "suffix": "SPLIT",
            "hold_fulfillments": false,
            "tag": "STOQ-split-order",
            "transaction_gateway": "Prepaid",
            "original_order_hold_tag": null,
            "original_order_split_tag": null
          }
        },
        "on_hold": {
          "release_schedule": "manual",
          "release_at": null,
          "require_payment": false
        }
      },
      "shopify_line_item_ids": [
        "gid://shopify/LineItem/15873209441589"
      ],
      "attribution_url": "/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977"
    }
  ],
  "line_items": [
    {
      "id": "c41d7e2a-8f35-4b9c-a1e6-7d20b3f9e584",
      "shopify_line_item_id": "gid://shopify/LineItem/15873209441589",
      "shopify_line_item_group_id": null,
      "shopify_variant_id": "gid://shopify/ProductVariant/47284734423096",
      "title": "Classic Sneaker",
      "variant_title": "Blue / Medium",
      "fulfillment_status": null,
      "preorder_fulfillment_status": "on_hold",
      "is_preorder": true,
      "offer_id": "73a74948-2b57-4cc3-971f-2b441828c977",
      "quantity": 1,
      "line_total": "110.00"
    }
  ],
  "outcome": {
    "fulfillment_orders": [
      {
        "fulfillment_order_id": 7034112983349,
        "status": "success",
        "error": null
      }
    ],
    "succeeded": 1,
    "failed": 0
  }
}
```

## 401

Missing or invalid `X-Auth-Token`.

```json
{
  "errors": [
    "Invalid API key"
  ],
  "code": "auth_invalid",
  "details": [
    {
      "code": "auth_invalid",
      "message": "Invalid API key",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}
```

## 404

The resource does not exist for this shop, or the action path is not registered.

```json
{
  "errors": [
    "Offer not found"
  ],
  "code": "not_found",
  "details": [
    {
      "code": "not_found",
      "message": "Offer not found",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}
```

## 409

An earlier request with the same Idempotency-Key is still running. Wait, then resend the same request with the same key.

```json
{
  "errors": [
    "A request with this Idempotency-Key is still running"
  ],
  "code": "idempotency_key_in_progress",
  "details": [
    {
      "code": "idempotency_key_in_progress",
      "message": "A request with this Idempotency-Key is still running",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}
```

## 422

The request failed validation.

```json
{
  "errors": [
    "name is required"
  ],
  "code": "validation_failed",
  "details": [
    {
      "code": "validation_failed",
      "message": "name is required",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}
```

## 429

Rate limited: cost-weighted per token (read 1, write 2; 360 points / 60s). Check `Retry-After`.

```json
{
  "errors": [
    "Rate limit exceeded"
  ],
  "code": "rate_limited",
  "details": [
    {
      "code": "rate_limited",
      "message": "Rate limit exceeded",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}
```

