Hold an order's fulfillments
API v2 is in public beta: endpoints and fields can change before general availability. See the changelog
/preorders/orders/{id}/hold_fulfillmentsCosts 2 rate-limit points · Rate limits
Put all of the order's fulfillment orders on hold, with an optional reason.
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.
Also searched ashold fulfillmentshold orderput order on holdstop order from shippinghold all fulfillments
Path parameters
idstringRequiredThe order, by STOQ's order ID or the Shopify order ID.
Headers
Idempotency-KeystringA 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 (422idempotency_key_reused); a retry while the first is still running gets 409idempotency_key_in_progress. Keys are per store. Server errors and rate limits are not kept, so their retry runs.
Request body
reason_notesstringReason shown on the hold in Shopify. Defaults to the standard hold note.
Returns
idstringSTOQ's id for the order. Pass it, or shopify_order_id, as :id to the other order endpoints.
typestringKind of order: preorder, or back_in_stock for an order STOQ attributed to a back-in-stock alert.
One ofpreorderback_in_stockshopify_order_idstringThe Shopify order gid (gid://shopify/Order/<id>).
namestringThe Shopify order name, such as #1001.
customerobjectThe customer who placed the order, as recorded on it.
Show 5 child attributesHide child attributes
idnullThe customer's STOQ id, the value the customer_id filter takes. Null when the order isn't linked to a STOQ customer.
shopify_customer_idnullThe Shopify customer gid (gid://shopify/Customer/<id>). Null when the order isn't linked to a customer.
emailstringEmail address on the order.
phonestringPhone number on the order, or null when none was given.
namestringCustomer's first and last name, or null when the order has neither.
total_pricestringOrder total in the order's currency, as a decimal string such as "49.99".
currencystringISO 4217 code of the currency the order was paid in, such as USD.
financial_statusstringThe Shopify financial status, such as paid, partially_paid, pending, authorized, refunded, partially_refunded or voided.
fulfillment_statusstringShopify's fulfillment status for the whole order, lowercased, such as unfulfilled, partially_fulfilled, fulfilled, scheduled or on_hold. Null until Shopify reports one.
payment_statusstringWhere 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 ofpaid_in_fullbalance_pendingbalance_overduebalance_collectedpaidnot_syncedcancelledrefundedpartially_refundedcancelled_atnullWhen the order was cancelled (ISO 8601), or null when it isn't.
created_atstringWhen STOQ recorded the order (ISO 8601). The from and to filters match on this.
updated_atstringWhen STOQ last changed its record of the order (ISO 8601).
paymentsobjectWhat the order cost, what has been paid and what is still owed. Also at GET /preorders/orders/:id/payments.
Show 15 child attributesHide child attributes
currencystringISO 4217 code of the currency of every amount in this section.
payment_statusstringWhere 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 ofpaid_in_fullbalance_pendingbalance_overduebalance_collectedpaidnot_syncedcancelledrefundedpartially_refundedfinancial_statusstringThe Shopify financial status, such as paid, partially_paid, pending, authorized, refunded, partially_refunded or voided.
subtotal_pricestringShopify's current subtotal, before tax and shipping, as a decimal string. Null when Shopify hasn't reported it.
tax_linesarray of anysThe taxes Shopify charged on the order.
total_pricestringOrder total as a decimal string, including tax and shipping.
total_outstandingstringAmount still owed according to Shopify, as a decimal string. Null until Shopify has reported it.
amount_paidstring, nullableAmount 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_amountstring, nullableThe part of the order left to pay later under a partial payment offer, as a decimal string. Null when nothing was deferred.
due_atstringWhen the remaining balance is due (ISO 8601), or null when there is no payment schedule.
overduebooleanWhether the due date has passed with a balance still outstanding.
balance_collectedbooleanWhether a deferred balance has been fully paid.
balance_collected_atnullWhen STOQ saw the deferred balance paid off (ISO 8601), or null.
last_payment_attemptnullThe latest charge STOQ attempted on the customer's saved payment method, automatic or manual. Null when there has been none.
payment_attemptsarray of anysUp to the 10 most recent charges STOQ attempted, newest first.
fulfillmentobjectHow the order is being fulfilled: holds, scheduled fulfillments and separate orders. Also at GET /preorders/orders/:id/fulfillment.
Show 6 child attributesHide child attributes
fulfillment_statusstringShopify's fulfillment status for the whole order, lowercased, such as unfulfilled, partially_fulfilled, fulfilled, scheduled or on_hold.
preorder_fulfillment_statusnullState 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_notestring, nullableThe note Shopify received with the fulfillment hold, from the offer that caused it. Null when no offer on the order holds fulfillments.
holds_applied_atstringWhen STOQ last placed the order's fulfillments on hold (ISO 8601), or null.
shopify_split_order_idsarray of anysShopify order gids of the separate orders STOQ moved preorder items to. Empty when the order wasn't split.
offersarray of objectsThe offers on the order and how each fulfills its items.
Show 2 child attributesHide child attributes
offer_idstringThe offer's id.
handlingstringHow 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 ofnonehold_allsplit_fulfillmentsseparate_orders
notificationsobjectThe preorder messages sent to the customer for this order. Also at GET /preorders/orders/:id/notifications.
Show 3 child attributesHide child attributes
confirmation_emailobjectThe preorder confirmation email.
Show 3 child attributesHide child attributes
sent_countintegerHow many times it was sent for this order.
last_sent_atnullWhen it was last sent (ISO 8601), or null when it never was.
last_triggered_bynullWhat sent it last, such as automatic or manual. Null when it was never sent.
confirmation_smsobjectThe preorder confirmation SMS.
Show 3 child attributesHide child attributes
sent_countintegerHow many times it was sent for this order.
last_sent_atnullWhen it was last sent (ISO 8601), or null when it never was.
last_triggered_bynullWhat sent it last, such as automatic or manual. Null when it was never sent.
shipping_update_emailobjectThe shipping update email.
Show 3 child attributesHide child attributes
sent_countintegerHow many times it was sent for this order.
last_sent_atnullWhen it was last sent (ISO 8601), or null when it never was.
last_triggered_bynullWhat sent it last, such as automatic or manual. Null when it was never sent.
tagsobjectThe order's tags.
Show 2 child attributesHide child attributes
tagsarray of stringsThe Shopify order's tags, read live from Shopify. Null when Shopify couldn't be reached.
configured_by_offersarray of stringsThe tags the order's offers are set to add to their orders.
attributed_offersarray of objectsThe offers the order's preorder items were bought through, with each offer's current shipping settings.
Show 7 child attributesHide child attributes
offer_idstringThe offer's id.
offer_namestringThe offer's name.
offer_internal_namestringThe offer's internal name, shown only in the STOQ admin.
current_statusstringThe offer's state now: live, off, scheduled (starts later) or deleted.
One oflivefalsescheduleddeletedshippingobjectThe 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.
Show 6 child attributesHide child attributes
timelineobjectThe shipping timeline text shown with the preorder button.
Show 4 child attributesHide child attributes
scopestringsame shows one shipping text for every product; per_variant uses each variant's own shipping text.
One ofsameper_variantshow_shipping_textbooleanWhether the shipping text shows with the preorder button.
shipping_textstringThe line under the preorder button.
variant_shipping_textstringA variant's shipping text when it has none of its own; every variant's when scope is same.
delivery_timingstringFulfillment 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 ofasapexact_timeunknownships_atnullShip date as a UTC timestamp (ISO 8601). Null unless items ship on a fixed date.
days_after_checkoutnullDays after checkout that items ship. Null unless items ship a set time after purchase.
fulfillmentobjectHow preorder items are fulfilled: held, split, or moved to a separate order.
Show 3 child attributesHide child attributes
handlingstringHow 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 ofnonehold_allsplit_fulfillmentsseparate_ordershold_reasonstringThe hold reason shown in Shopify.
separate_ordersobjectSettings for the separate orders preorder items move to, used when handling is separate_orders.
Show 8 child attributesHide child attributes
groupingstringoffer creates one separate order per offer; variant one per variant; ship_date one per ship date.
One ofoffervariantship_datenumber_formatstringsequential gives each separate order its own order number; suffix appends suffix to the original order name.
One ofsequentialsuffixsuffixstringSuffix appended to the separate order name.
hold_fulfillmentsbooleanWhether fulfillments on the separate order are held until they're released.
tagstringTag applied to the separate preorder order.
transaction_gatewaystringPayment gateway recorded on the separate order transaction.
original_order_hold_tagnullTag on the original order while it is being split, removed once the split finishes. Null when none is set.
original_order_split_tagnullTag on the original order after the preorder items move to a separate order. Null when none is set.
on_holdobjectWhen held fulfillments are released.
Show 3 child attributesHide child attributes
release_schedulestringscheduled releases held fulfillments on release_at; manual leaves them held.
One ofscheduledmanualrelease_atnullWhen held fulfillments are released (ISO 8601). Null unless release_schedule is scheduled.
require_paymentbooleanWhether holds are only released once the balance is paid.
shopify_line_item_idsarray of stringsShopify line item gids of this order's items bought through the offer. A bundle lists its components.
attribution_urlstringAPI path of the offer, relative to the host.
line_itemsarray of objectsEvery item on the order, preorder or not. A bundle is one entry with its parts under components.
Show 12 child attributesHide child attributes
idstringSTOQ's id for the line item. collect_payment takes it in line_item_ids.
shopify_line_item_idstringThe Shopify line item gid (gid://shopify/LineItem/<id>). Null for a bundle, which has no Shopify line item of its own.
shopify_line_item_group_idnullThe Shopify line item group gid (gid://shopify/LineItemGroup/<id>) of the bundle the item belongs to, or null when it isn't part of one.
shopify_variant_idstringThe Shopify variant gid (gid://shopify/ProductVariant/<id>).
titlestringProduct title.
variant_titlestringVariant title, or null for a product with only its default variant.
fulfillment_statusnullShopify's fulfillment status for the item: fulfilled, partial, or null while nothing has shipped.
preorder_fulfillment_statusnullState 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_preorderbooleanWhether the item was bought as a preorder.
offer_idstring, nullableThe id of the offer the item was preordered through, or null for an in-stock item.
quantityintegerQuantity ordered.
line_totalstringPrice times quantity plus tax, as a decimal string in the order's currency: what collecting payment for this item charges.
outcomeobjectWhat the action did to the order: the fields it changed and, for fulfillment and payment actions, Shopify's answer.
Show 3 child attributesHide child attributes
fulfillment_ordersarray of objectsEach Shopify fulfillment order the action was applied to, with Shopify's answer. Shopify can accept some and reject others.
Show 3 child attributesHide child attributes
fulfillment_order_idintegerThe Shopify fulfillment order's numeric id.
statusstringsuccess, failure, or skipped when the fulfillment order couldn't be held in its current state (hold only).
One ofsuccessfailureskippederrorstring, nullableWhy Shopify rejected or STOQ skipped the fulfillment order, or null on success.
succeededintegerHow many fulfillment orders succeeded.
failedintegerHow many fulfillment orders failed or were skipped.
Errors
forbiddenThe credential is valid, but the store's plan or settings do not allow this operation.
plan_requiredThe change uses a feature that is only available on a paid STOQ plan. Connecting a paid-only integration returns 403; a write that sets paid-only fields returns 422 and saves nothing.
not_foundThe path is valid but nothing with that id exists in this store.
conflictThe request is well formed, but the resource's current state does not allow it.
invalid_stateThe order's current state rules this operation out, such as releasing a cancelled order.
idempotency_key_in_progressAn earlier request with the same Idempotency-Key is still running. Wait, then resend the same request with the same key.
fetch_failedSTOQ could not read the order's fulfillment orders from Shopify.
hold_failedShopify rejected holding the order's fulfillment orders.
invalid_paramsOne or more fields failed the action's schema.
no_fulfillment_ordersShopify has no fulfillment orders for this order, so there is nothing to hold.
validation_failedThe request failed validation.
Any request can also fail with auth_invalid (401) or rate_limited (429).
Every error has the same shape: see Errors and the list of error codes.
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"
}'const res = await fetch("https://app.stoqapp.com/api/v2/external/preorders/orders/5f0c8a3e-6b2d-4f1a-9c7e-2d8b1a4e6f30/hold_fulfillments", {
method: "POST",
headers: {
"X-Auth-Token": process.env.STOQ_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"reason_notes": "Waiting on stock"
}),
});
const data = await res.json();import os
import requests
res = requests.post(
"https://app.stoqapp.com/api/v2/external/preorders/orders/5f0c8a3e-6b2d-4f1a-9c7e-2d8b1a4e6f30/hold_fulfillments",
headers={"X-Auth-Token": os.environ["STOQ_API_KEY"]},
json={
"reason_notes": "Waiting on stock"
},
)
data = res.json()require "net/http"
require "json"
uri = URI("https://app.stoqapp.com/api/v2/external/preorders/orders/5f0c8a3e-6b2d-4f1a-9c7e-2d8b1a4e6f30/hold_fulfillments")
req = Net::HTTP::Post.new(uri, "X-Auth-Token" => ENV["STOQ_API_KEY"], "Content-Type" => "application/json")
req.body = {
reason_notes: "Waiting on stock"
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body){
"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
}
}{
"errors": [
"Invalid API key"
],
"code": "auth_invalid",
"details": [
{
"code": "auth_invalid",
"message": "Invalid API key",
"path": null,
"value": null,
"expected": null
}
]
}{
"errors": [
"Offer not found"
],
"code": "not_found",
"details": [
{
"code": "not_found",
"message": "Offer not found",
"path": null,
"value": null,
"expected": null
}
]
}{
"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
}
]
}{
"errors": [
"name is required"
],
"code": "validation_failed",
"details": [
{
"code": "validation_failed",
"message": "name is required",
"path": null,
"value": null,
"expected": null
}
]
}{
"errors": [
"Rate limit exceeded"
],
"code": "rate_limited",
"details": [
{
"code": "rate_limited",
"message": "Rate limit exceeded",
"path": null,
"value": null,
"expected": null
}
]
}