Skip to content

Release an order's holds

API v2 is in public beta: endpoints and fields can change before general availability. See the changelog

POST/preorders/orders/{id}/release

Costs 2 rate-limit points · Rate limits

Release the order's fulfillment holds without applying offer-configured order tags.

Matches the merchant dashboard action Release "On hold" fulfillments. outcome lists each fulfillment order Shopify released or rejected.

Also searched asrelease orderrelease fulfillmentslet it shipunhold orderopen fulfillments

Path parameters

  • idstringRequired

    The order, by STOQ's order ID or the Shopify order ID.

Headers

  • Idempotency-Keystring

    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.

Returns

  • idstring

    STOQ's id for the order. Pass it, or shopify_order_id, as :id to the other order endpoints.

  • typestring

    Kind of order: preorder, or back_in_stock for an order STOQ attributed to a back-in-stock alert.

    One of preorderback_in_stock
  • shopify_order_idstring

    The Shopify order gid (gid://shopify/Order/<id>).

  • namestring

    The Shopify order name, such as #1001.

  • customerobject

    The customer who placed the order, as recorded on it.

    Show 5 child attributesHide child attributes
    • idnull

      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_idnull

      The Shopify customer gid (gid://shopify/Customer/<id>). Null when the order isn't linked to a customer.

    • emailstring

      Email address on the order.

    • phonestring

      Phone number on the order, or null when none was given.

    • namestring

      Customer's first and last name, or null when the order has neither.

  • total_pricestring

    Order total in the order's currency, as a decimal string such as "49.99".

  • currencystring

    ISO 4217 code of the currency the order was paid in, such as USD.

  • financial_statusstring

    The Shopify financial status, such as paid, partially_paid, pending, authorized, refunded, partially_refunded or voided.

  • fulfillment_statusstring

    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_statusstring

    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_fullbalance_pendingbalance_overduebalance_collectedpaidnot_syncedcancelledrefundedpartially_refunded
  • cancelled_atnull

    When the order was cancelled (ISO 8601), or null when it isn't.

  • created_atstring

    When STOQ recorded the order (ISO 8601). The from and to filters match on this.

  • updated_atstring

    When STOQ last changed its record of the order (ISO 8601).

  • paymentsobject

    What 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
    • currencystring

      ISO 4217 code of the currency of every amount in this section.

    • payment_statusstring

      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_fullbalance_pendingbalance_overduebalance_collectedpaidnot_syncedcancelledrefundedpartially_refunded
    • financial_statusstring

      The Shopify financial status, such as paid, partially_paid, pending, authorized, refunded, partially_refunded or voided.

    • subtotal_pricestring

      Shopify's current subtotal, before tax and shipping, as a decimal string. Null when Shopify hasn't reported it.

    • tax_linesarray of anys

      The taxes Shopify charged on the order.

    • total_pricestring

      Order total as a decimal string, including tax and shipping.

    • total_outstandingstring

      Amount still owed according to Shopify, as a decimal string. Null until Shopify has reported it.

    • amount_paidstring, 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_amountstring, 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_atstring

      When the remaining balance is due (ISO 8601), or null when there is no payment schedule.

    • overdueboolean

      Whether the due date has passed with a balance still outstanding.

    • balance_collectedboolean

      Whether a deferred balance has been fully paid.

    • balance_collected_atnull

      When STOQ saw the deferred balance paid off (ISO 8601), or null.

    • last_payment_attemptnull

      The latest charge STOQ attempted on the customer's saved payment method, automatic or manual. Null when there has been none.

    • payment_attemptsarray of anys

      Up to the 10 most recent charges STOQ attempted, newest first.

  • fulfillmentobject

    How 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_statusstring

      Shopify's fulfillment status for the whole order, lowercased, such as unfulfilled, partially_fulfilled, fulfilled, scheduled or on_hold.

    • preorder_fulfillment_statusnull

      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_notestring, 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_atnull

      When STOQ last placed the order's fulfillments on hold (ISO 8601), or null.

    • shopify_split_order_idsarray of anys

      Shopify order gids of the separate orders STOQ moved preorder items to. Empty when the order wasn't split.

    • offersarray of objects

      The offers on the order and how each fulfills its items.

      Show 2 child attributesHide child attributes
      • offer_idstring

        The offer's id.

      • handlingstring

        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 nonehold_allsplit_fulfillmentsseparate_orders
  • notificationsobject

    The preorder messages sent to the customer for this order. Also at GET /preorders/orders/:id/notifications.

    Show 3 child attributesHide child attributes
    • confirmation_emailobject

      The preorder confirmation email.

      Show 3 child attributesHide child attributes
      • sent_countinteger

        How many times it was sent for this order.

      • last_sent_atnull

        When it was last sent (ISO 8601), or null when it never was.

      • last_triggered_bynull

        What sent it last, such as automatic or manual. Null when it was never sent.

    • confirmation_smsobject

      The preorder confirmation SMS.

      Show 3 child attributesHide child attributes
      • sent_countinteger

        How many times it was sent for this order.

      • last_sent_atnull

        When it was last sent (ISO 8601), or null when it never was.

      • last_triggered_bynull

        What sent it last, such as automatic or manual. Null when it was never sent.

    • shipping_update_emailobject

      The shipping update email.

      Show 3 child attributesHide child attributes
      • sent_countinteger

        How many times it was sent for this order.

      • last_sent_atnull

        When it was last sent (ISO 8601), or null when it never was.

      • last_triggered_bynull

        What sent it last, such as automatic or manual. Null when it was never sent.

  • tagsobject

    The order's tags.

    Show 2 child attributesHide child attributes
    • tagsarray of strings

      The Shopify order's tags, read live from Shopify. Null when Shopify couldn't be reached.

    • configured_by_offersarray of strings

      The tags the order's offers are set to add to their orders.

  • attributed_offersarray of objects

    The offers the order's preorder items were bought through, with each offer's current shipping settings.

    Show 7 child attributesHide child attributes
    • offer_idstring

      The offer's id.

    • offer_namestring

      The offer's name.

    • offer_internal_namestring

      The offer's internal name, shown only in the STOQ admin.

    • current_statusstring

      The offer's state now: live, off, scheduled (starts later) or deleted.

      One of livefalsescheduleddeleted
    • shippingobject

      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.

      Show 6 child attributesHide child attributes
      • timelineobject

        The shipping timeline text shown with the preorder button.

        Show 4 child attributesHide child attributes
        • scopestring

          same shows one shipping text for every product; per_variant uses each variant's own shipping text.

          One of sameper_variant
        • show_shipping_textboolean

          Whether the shipping text shows with the preorder button.

        • shipping_textstring

          The line under the preorder button.

        • variant_shipping_textstring

          A variant's shipping text when it has none of its own; every variant's when scope is same.

      • delivery_timingstring

        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 asapexact_timeunknown
      • ships_atnull

        Ship date as a UTC timestamp (ISO 8601). Null unless items ship on a fixed date.

      • days_after_checkoutnull

        Days after checkout that items ship. Null unless items ship a set time after purchase.

      • fulfillmentobject

        How preorder items are fulfilled: held, split, or moved to a separate order.

        Show 3 child attributesHide child attributes
        • handlingstring

          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 nonehold_allsplit_fulfillmentsseparate_orders
        • hold_reasonstring

          The hold reason shown in Shopify.

        • separate_ordersobject

          Settings for the separate orders preorder items move to, used when handling is separate_orders.

          Show 8 child attributesHide child attributes
          • groupingstring

            offer creates one separate order per offer; variant one per variant; ship_date one per ship date.

            One of offervariantship_date
          • number_formatstring

            sequential gives each separate order its own order number; suffix appends suffix to the original order name.

            One of sequentialsuffix
          • suffixstring

            Suffix appended to the separate order name.

          • hold_fulfillmentsboolean

            Whether fulfillments on the separate order are held until they're released.

          • tagstring

            Tag applied to the separate preorder order.

          • transaction_gatewaystring

            Payment gateway recorded on the separate order transaction.

          • original_order_hold_tagnull

            Tag on the original order while it is being split, removed once the split finishes. Null when none is set.

          • original_order_split_tagnull

            Tag on the original order after the preorder items move to a separate order. Null when none is set.

      • on_holdobject

        When held fulfillments are released.

        Show 3 child attributesHide child attributes
        • release_schedulestring

          scheduled releases held fulfillments on release_at; manual leaves them held.

          One of scheduledmanual
        • release_atnull

          When held fulfillments are released (ISO 8601). Null unless release_schedule is scheduled.

        • require_paymentboolean

          Whether holds are only released once the balance is paid.

    • shopify_line_item_idsarray of strings

      Shopify line item gids of this order's items bought through the offer. A bundle lists its components.

    • attribution_urlstring

      API path of the offer, relative to the host.

  • line_itemsarray of objects

    Every item on the order, preorder or not. A bundle is one entry with its parts under components.

    Show 12 child attributesHide child attributes
    • idstring

      STOQ's id for the line item. collect_payment takes it in line_item_ids.

    • shopify_line_item_idstring

      The 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_idnull

      The 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_idstring

      The Shopify variant gid (gid://shopify/ProductVariant/<id>).

    • titlestring

      Product title.

    • variant_titlestring

      Variant title, or null for a product with only its default variant.

    • fulfillment_statusnull

      Shopify's fulfillment status for the item: fulfilled, partial, or null while nothing has shipped.

    • preorder_fulfillment_statusnull

      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_preorderboolean

      Whether the item was bought as a preorder.

    • offer_idstring, nullable

      The id of the offer the item was preordered through, or null for an in-stock item.

    • quantityinteger

      Quantity ordered.

    • line_totalstring

      Price times quantity plus tax, as a decimal string in the order's currency: what collecting payment for this item charges.

  • outcomeobject

    What 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 objects

      Each 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_idinteger

        The Shopify fulfillment order's numeric id.

      • statusstring

        success, failure, or skipped when the fulfillment order couldn't be held in its current state (hold only).

        One of successfailureskipped
      • errorstring, nullable

        Why Shopify rejected or STOQ skipped the fulfillment order, or null on success.

    • succeededinteger

      How many fulfillment orders succeeded.

    • failedinteger

      How many fulfillment orders failed or were skipped.

Errors

403
forbidden

The credential is valid, but the store's plan or settings do not allow this operation.

403
plan_required

The 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.

404
not_found

The path is valid but nothing with that id exists in this store.

409
conflict

The request is well formed, but the resource's current state does not allow it.

409
invalid_state

The order's current state rules this operation out, such as releasing a cancelled order.

422
validation_failed

The 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.

POST/preorders/orders/{id}/release
curl -X POST "https://app.stoqapp.com/api/v2/external/preorders/orders/5f0c8a3e-6b2d-4f1a-9c7e-2d8b1a4e6f30/release" \
  -H "X-Auth-Token: $STOQ_API_KEY"
Response
{
  "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-07-30T13:40:12Z",
  "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": "open",
    "hold_reason_note": "Waiting on stock",
    "holds_applied_at": "2026-06-12T14:32:20Z",
    "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": "open",
      "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
  }
}