Skip to content

Get shipping

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

GET/preorders/offers/{id}/shipping

Costs 1 rate-limit point · Rate limits

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

shipping_text is the line under the Preorder button, shown while show_shipping_text is true. With timeline.scope per_variant each variant's own shipping_text (GET /preorders/offers/:id/products/variants) is used, falling back to variant_shipping_text. delivery_timing exact_time has either ships_at or days_after_checkout; asap and unknown have neither. separate_orders applies only while fulfillment.handling is separate_orders, and on_hold.release_at only while release_schedule is scheduled. Edit with PATCH /preorders/offers/:id/shipping.

Also searched asget shippingshow shippingview deliveryview fulfillmentview shipping textshipping settings

Path parameters

Query parameters

  • localestring

    Language for translated text, such as fr or pt-BR. Omit for the shop's default language.

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_atnull

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

  • days_after_checkoutnull

    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_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 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_atnull

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

    • require_paymentboolean

      Only release once the balance is paid.

Errors

404
not_found

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

422
invalid_params

One or more fields failed the action's schema.

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.

GET/preorders/offers/{id}/shipping
curl "https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/shipping" \
  -H "X-Auth-Token: $STOQ_API_KEY"
Response
{
  "timeline": {
    "scope": "same",
    "show_shipping_text": true,
    "shipping_text": "Ships by {{ date }}",
    "variant_shipping_text": "15 Aug 2026"
  },
  "delivery_timing": "exact_time",
  "ships_at": "2026-08-15T04:00:00Z",
  "days_after_checkout": null,
  "fulfillment": {
    "handling": "none",
    "hold_reason": "Order contains a preorder product. All fulfillments are on hold, as configured in STOQ > Preorders.",
    "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
  }
}