Get shipping
API v2 is in public beta: endpoints and fields can change before general availability. See the changelog
/preorders/offers/{id}/shippingCosts 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
idstringRequiredThe offer's ID, from
GET /preorders/offers.
Query parameters
localestringLanguage for translated text, such as fr or pt-BR. Omit for the shop's default language.
Returns
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 timeline shows on the widget.
shipping_textstringThe line under the preorder button. A {{ date }} placeholder is filled with variant_shipping_text.
variant_shipping_textstringShip date text for a variant that has no shipping text of its own, and for every variant 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, ISO 8601 in UTC. Null unless delivery_timing is exact_time with a fixed date.
days_after_checkoutnullDays after checkout that items ship. Null unless delivery_timing is exact_time with a delay instead of a date.
fulfillmentobjectHow preorder items are fulfilled: held, split, or moved to a separate order.
Show 3 child attributesHide child attributes
handlingstringnone; hold_all holds every fulfillment; split_fulfillments ships in-stock items first; separate_orders moves preorder items to their own order.
One ofnonehold_allsplit_fulfillmentsseparate_ordershold_reasonstringHold reason shown in Shopify on held fulfillments.
separate_ordersobjectSettings for separate orders, 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 released.
tagstringTag applied to the separate preorder order.
transaction_gatewaystringPayment gateway recorded on the separate order's transaction. Default "Prepaid".
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 its 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 in UTC. Null when not set.
require_paymentbooleanOnly release once the balance is paid.
Errors
not_foundThe path is valid but nothing with that id exists in this store.
invalid_paramsOne or more fields failed the action's schema.
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 "https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/shipping" \
-H "X-Auth-Token: $STOQ_API_KEY"const res = await fetch("https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/shipping", {
headers: {
"X-Auth-Token": process.env.STOQ_API_KEY,
},
});
const data = await res.json();import os
import requests
res = requests.get(
"https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/shipping",
headers={"X-Auth-Token": os.environ["STOQ_API_KEY"]},
)
data = res.json()require "net/http"
require "json"
uri = URI("https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/shipping")
req = Net::HTTP::Get.new(uri, "X-Auth-Token" => ENV["STOQ_API_KEY"])
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)curl "https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/shipping?locale=fr" \
-H "X-Auth-Token: $STOQ_API_KEY"const res = await fetch("https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/shipping?locale=fr", {
headers: {
"X-Auth-Token": process.env.STOQ_API_KEY,
},
});
const data = await res.json();import os
import requests
res = requests.get(
"https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/shipping?locale=fr",
headers={"X-Auth-Token": os.environ["STOQ_API_KEY"]},
)
data = res.json()require "net/http"
require "json"
uri = URI("https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/shipping?locale=fr")
req = Net::HTTP::Get.new(uri, "X-Auth-Token" => ENV["STOQ_API_KEY"])
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body){
"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
}
}{
"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": [
"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
}
]
}