Skip to content

Update shipping

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

PATCH/preorders/offers/{id}/shipping

Costs 2 rate-limit points · Rate limits

Update any subset of the shipping settings on a preorder offer: the shipping timeline text, delivery timing, fulfillment handling (hold, split or separate orders) and hold release.

Deep partial: absent fields are unchanged, null clears. Settings the save changes on its own (the purchase option and payments when separate orders turns on, split fulfillments when delivery leaves asap) are listed in also_changed. reschedule_existing_orders: true is the editor's "Reschedule existing orders to this date" checkbox: after the save, every unfulfilled, uncancelled preorder on the offer has its scheduled fulfillments moved to the offer's ship date (ships_at), or to its own order date plus days_after_checkout, in the background. It needs delivery_timing exact_time after the save, can be sent alone to re-apply the current date, and does not email customers (send a shipping update from the orders endpoints for that). When sent, the response has rescheduled_orders_queued.

Also searched asedit shippingchange shipping settingschange deliverychange fulfillmentmodify shippingenable fulfillment holdhold preorder fulfillmentsturn on fulfillment holdprevent shipping until releasedhold all fulfillmentshold ordershold fulfillmentsdisable fulfillment holdrelease fulfillmentsstop holding fulfillmentsturn off fulfillment holdlet preorder ship immediatelydisable splitdisable split ordersdisable split fulfillmentsturn off order splittingstop separating preordersrelease fulfillment holdenable splitturn on order splittingenable split ordersseparate preorder from regularenable split fulfillmentsenable split hold fulfillmentshold split order fulfillmentshold fulfillments on split orderdon't ship split order immediatelydisable split hold fulfillmentsrelease split order fulfillmentsship split order immediatelystop holding split orderenable split sequential numbersequential split order numbersnumber split orders sequentiallysequential order name for splitdisable split sequential numberno sequential split order numbersstop numbering split orders sequentiallyauto release holdsautomatically release holdsrelease holds on a datestop releasing holds automaticallyrelease holds after paymentset delivery asapship asapset delivery to asapship as soon as possibleset delivery dateship on dateset ship dateset exact delivery dateset delivery windowship within daysset delivery in daysset ship windowfulfillment hold reasonset shipping textchange shipping textupdate shipping messageset delivery textchange PDP shipping lineset split order suffixchange split suffixset split order name suffixrename split order suffixchange split order label textset split order tagchange split tagset split order labelset split transaction gatewayset split payment gatewaychange split order gateway

Path parameters

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.

Request body

  • timelineobject

    The shipping timeline text shown with the preorder button.

    Show 3 child attributesHide child attributes
    • scopestring

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

      One of sameper_variant
    • show_shipping_textboolean

      Show shipping timeline on the widget. Also turns the cart line-item property (advanced.cart_attributes.show_shipping) on or off when it changes, as the editor does; sending the current value changes nothing.

    • shipping_textstring

      The line under the preorder button. Required while show_shipping_text is true.

  • delivery_timingstring

    Fulfillment status of preorder items: asap is Unfulfilled (ship now), exact_time is Scheduled (needs ships_at or days_after_checkout and the Shopify purchase option), unknown is On hold (no date promised). asap and unknown clear ships_at and days_after_checkout.

    One of asapexact_timeunknown
  • ships_atstring

    Ship date: a date (2026-11-05), read as midnight in the shop time zone, or an ISO 8601 datetime (kept as that exact moment). Returned as the UTC datetime. Sending it alone makes delivery_timing exact_time on that date. Also sets timeline.variant_shipping_text (the {{ date }} value) to the date in the shop time zone, as the editor does: "05 Nov 2026".

  • days_after_checkoutinteger

    Ship N days after checkout. Sending it alone makes delivery_timing exact_time with that delay; ships_at is then null. Also sets timeline.variant_shipping_text to "N days after checkout", as the editor does.

  • fulfillmentobject

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

    Show 3 child attributesHide child attributes
    • handlingstring

      none; hold_all holds every fulfillment; split_fulfillments ships in-stock items first (needs delivery_timing asap); separate_orders moves preorder items to their own order, which switches the Shopify purchase option off and resets partial payment, the discount and a Scheduled status (listed in also_changed).

      One of nonehold_allsplit_fulfillmentsseparate_orders
    • hold_reasonstring

      The hold reason shown in Shopify.

    • separate_ordersobject
      Show 8 child attributesHide child attributes
      • groupingstring

        offer creates one separate order per offer; variant one per variant; ship_date one per ship date (batch or shipping text), which needs timeline.scope per_variant or batches on.

        One of variantoffership_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

        Hold fulfillments on the separate order 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_tagstring

        Tag on the original order while it is being split. Removed once the split finishes.

      • original_order_split_tagstring

        Tag on the original order after the preorder items move to a separate order.

  • 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_atstring

      ISO 8601. Required while release_schedule is scheduled.

    • require_paymentboolean

      Only release once the balance is paid.

  • reschedule_existing_ordersboolean

    true also moves the scheduled fulfillments of existing unfulfilled preorders on this offer to the ship date (ships_at, or each order date plus days_after_checkout), as the editor's "Reschedule existing orders to this date" checkbox does. Needs delivery_timing exact_time. No customer email.

  • localestring

    Language the translated fields are written in, such as 'fr' or 'pt-BR'. Omitted: the shop's default language. Untranslated fields ignore it.

Returns

  • 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 timeline shows on the widget.

    • shipping_textstring

      The line under the preorder button. A {{ date }} placeholder is filled with variant_shipping_text.

    • variant_shipping_textstring

      Ship date text for a variant that has no shipping text of its own, and for every variant 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_atstring, nullable

    Ship date, ISO 8601 in UTC. Null unless delivery_timing is exact_time with a fixed date.

  • days_after_checkoutinteger, nullable

    Days after checkout that items ship. Null unless delivery_timing is exact_time with a delay instead of a date.

  • fulfillmentobject

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

    Show 3 child attributesHide child attributes
    • handlingstring

      none; hold_all holds every fulfillment; split_fulfillments ships in-stock items first; separate_orders moves preorder items to their own order.

      One of nonehold_allsplit_fulfillmentsseparate_orders
    • hold_reasonstring

      Hold reason shown in Shopify on held fulfillments.

    • separate_ordersobject

      Settings for separate orders, 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 released.

      • tagstring

        Tag applied to the separate preorder order.

      • transaction_gatewaystring

        Payment gateway recorded on the separate order's transaction. Default "Prepaid".

      • original_order_hold_tagstring, nullable

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

      • original_order_split_tagstring, nullable

        Tag on the original order after its 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_atstring, nullable

      When held fulfillments are released, ISO 8601 in UTC. Null when not set.

    • require_paymentboolean

      Only release once the balance is paid.

  • also_changedarray of objects

    Settings this write changed on its own because they depend on what you changed (turning one option off can reset another). Absent when nothing else changed.

    Show 5 child attributesHide child attributes
    • settingstring

      The setting that changed, as the dashboard names it.

    • fromstring

      Its value before the write.

    • tostring, nullable

      Its value after the write.

    • reasonstring

      Why it changed.

    • field_pathstring

      Dotted path of the changed field in this response, when it is one.

  • rescheduled_orders_queuedboolean

    true when existing orders' fulfillments are being moved to the new ship date in the background. Only when reschedule_existing_orders was sent.

Errors

404
not_found

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

409
idempotency_key_in_progress

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

422
invalid_params

One or more fields failed the action's schema.

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.

PATCH/preorders/offers/{id}/shipping
curl -X PATCH "https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/shipping" \
  -H "X-Auth-Token: $STOQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "days_after_checkout": 30,
    "fulfillment": {
      "handling": "hold_all",
      "hold_reason": "Waiting on stock"
    }
  }'
Response
{
  "timeline": {
    "scope": "same",
    "show_shipping_text": true,
    "shipping_text": "Shipping: {{ date }}",
    "variant_shipping_text": "ASAP"
  },
  "delivery_timing": "exact_time",
  "ships_at": null,
  "days_after_checkout": 30,
  "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
  }
}