Get an offer
API v2 is in public beta: endpoints and fields can change before general availability. See the changelog
/preorders/offers/{id}Costs 1 rate-limit point · Rate limits
Read a preorder offer's full representation.
Each section can also be read alone (GET /preorders/offers/:id/widget, .../payments and so on) and is edited with its own PATCH. products holds the selection rule and variant_count, not the variants: list them with GET /preorders/offers/:id/products/variants. locale lays that language's saved text over the text fields, as the storefront shows them; translations lists only languages with saved text. A discarded offer still returns 200, with availability.current_status deleted; an unknown id returns 404 not_found.
Also searched asshow offerget preorder offerlook up offerview offer
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
The offer object.
Errors
not_foundThe path is valid but nothing with that id exists in this store.
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" \
-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", {
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",
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")
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?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?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?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?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){
"id": "73a74948-2b57-4cc3-971f-2b441828c977",
"shopify_selling_plan_group_id": "gid://shopify/SellingPlanGroup/100",
"name": "Summer Sneaker Drop",
"internal_name": "summer-2026",
"widget": {
"button": {
"button_text": "Preorder Now",
"custom_colors_enabled": true,
"text_color": "#ffffff",
"background_color": "#8700d3"
},
"disclaimer": {
"show_disclaimer": true,
"disclaimer_text": "Expected to ship by August 2026",
"text_color": "#FFFFFF",
"background_color": "#1F2937",
"border_radius": 4
},
"badge": {
"show_badge": true,
"badge_text": "Pre-Order",
"text_color": "#FFFFFF",
"background_color": "#000000"
}
},
"inventory": {
"stock_condition": "out_of_stock",
"reserve": "on_sale"
},
"products": {
"selection": "custom",
"shopify_collection_id": null,
"tags": [],
"eligible_inventory_policy": "all",
"excluded_shopify_variant_ids": [],
"exclusion_tag": null
},
"shipping": {
"timeline": {
"scope": "same",
"show_shipping_text": true,
"shipping_text": "Shipping: As soon as possible",
"variant_shipping_text": "ASAP"
},
"delivery_timing": "asap",
"ships_at": null,
"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
}
},
"payments": {
"options_offered": "full",
"default_option": "full",
"full": {
"selling_plan_id": "gid://shopify/SellingPlan/101",
"checkout_charge": {
"charge_type": "percentage",
"charge_amount": 100
},
"remaining_balance": {
"charge_trigger": "no_remaining_balance",
"charge_exact_time": null,
"days_after_checkout": null
},
"price_adjustment": {
"adjustment_type": null,
"adjustment_amount": null
},
"option_title": "Full payment",
"option_description": "Pay the full price now",
"discount_text": "Save {{ discount }}"
},
"collection_schedule": "manual",
"show_payment_widget": false,
"show_discounted_price": null,
"currency_code": "USD"
},
"availability": {
"schedule": "enabled",
"starts_at": null,
"ends_at": null,
"current_status": "live"
},
"limits": {
"default_per_variant": null,
"display_style": "none",
"limit_text": "{{ quantity }} units available for preorder",
"show_icons": true,
"progress_bar": {
"progress_text": "{{ sold }} of {{ total }} claimed",
"fill_color": "#ffffff",
"background_color": "#e5e5e5",
"box_background_color": null,
"text_color": "#ffffff",
"border_radius": 4,
"show_percentage": false
},
"order_tags": [
"STOQ-preorder"
],
"terms": {
"require_acceptance": false,
"terms_text": "I acknowledge and agree to the preorder terms and conditions for this product.",
"disable_button_until_accepted": false,
"record_acceptance": false,
"acceptance_label": "Preorder Terms Accepted"
},
"cart": {
"allowed_items": "mixed",
"error_message": "Preorders must be purchased separately from regular items. Please complete your current order first, or clear your cart to continue."
},
"order_quantity": {
"minimum": null,
"maximum": null
}
},
"countdown": {
"show_when": "disabled",
"date_source": "schedule",
"starts_at": null,
"ends_at": null,
"starts_text": null,
"ends_text": null,
"labels": {
"days": "Days",
"hours": "Hours",
"minutes": "Mins",
"seconds": "Secs"
},
"text_color": "#000000",
"background_color": "#f5f5f5",
"border_radius": 8,
"units": [
"days",
"hours",
"minutes",
"seconds"
],
"current": {
"visible_phase": "hidden",
"target_at": null,
"heading_text": null,
"starts_at": null,
"ends_at": null
}
},
"markets": {
"scope": "all",
"shopify_market_ids": []
},
"advanced": {
"checkout_method": "selling_plan",
"cart_attributes": {
"show_payment": false,
"show_shipping": true,
"custom_text": null
}
},
"integrations": {
"pos": {
"enable_pos": true,
"inventory_check": "required"
},
"b2b": {
"enable_b2b": true
}
},
"batches": {
"release_strategy": "all_at_once",
"advance_schedule": "automatic",
"label_format": "Batch {{ n }}",
"status_text": {
"past": "Sold out",
"live": "Live",
"upcoming": "Coming soon"
},
"widget": {
"style": "roadmap",
"progress": "counts",
"show_other_ship_dates": true,
"show_names": false
},
"items": []
},
"translations": {},
"created_at": "2026-06-25T10:30:45Z",
"updated_at": "2026-06-25T11:45:30Z"
}{
"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
}
]
}