Find an offer
API v2 is in public beta: endpoints and fields can change before general availability. See the changelog
/preorders/offer_lookupCosts 1 rate-limit point · Rate limits
Resolve one preorder offer from an exact id or a fuzzy name match. Returns the full offer (same shape as GET /preorders/offers/:id) on a unique match. If name matches more than one offer, returns {ambiguous: true, candidates: [...]} instead of guessing -- re-call with the chosen id. Omit both id and name for the most recently created offer.
name is compared without regard to case against both the offer's name and its internal_name. An exact match wins over partial ones, so name=Preorder returns the offer called exactly that even when other offers contain the word. Otherwise any offer whose name contains the text, or is contained in it, matches. Deleted offers are never returned. An offer id passed as name also works. No match returns 404 not_found; an empty name returns 422 validation_failed.
Also searched asfind offerresolve offerlook up offer by namewhich offerthe offer
Query parameters
idstringExact offer ID to return. Wins over name when both are sent.
namestringText matched against each offer's name and internal name, exact first, then partial. Omit both id and name for the most recently created offer.
Returns
idstringExample:stringshopify_selling_plan_group_idstringExample:stringnamestringExample:stringinternal_namestringExample:stringwidgetobjectShow 3 child attributesHide child attributes
buttonobjectShow 4 child attributesHide child attributes
button_textstringExample:stringcustom_colors_enabledbooleanExample:truetext_colorstringExample:stringbackground_colorstringExample:string
disclaimerobjectShow 5 child attributesHide child attributes
show_disclaimerbooleanExample:truedisclaimer_textstringExample:stringtext_colorstringExample:stringbackground_colorstringExample:stringborder_radiusintegerExample:1
badgeobjectShow 4 child attributesHide child attributes
show_badgebooleanExample:truebadge_textstringExample:stringtext_colorstringExample:stringbackground_colorstringExample:string
inventoryobjectShow 2 child attributesHide child attributes
stock_conditionstringExample:stringreservestringExample:string
productsobjectShow 7 child attributesHide child attributes
selectionstringExample:stringshopify_collection_idnulltagsarray of anyseligible_inventory_policystringExample:stringexcluded_shopify_variant_idsarray of anysexclusion_tagnullvariant_countintegerExample:1
shippingobjectShow 6 child attributesHide child attributes
timelineobjectShow 4 child attributesHide child attributes
scopestringExample:stringshow_shipping_textbooleanExample:trueshipping_textstringExample:stringvariant_shipping_textstringExample:string
delivery_timingstringExample:stringships_atnulldays_after_checkoutnullfulfillmentobjectShow 3 child attributesHide child attributes
handlingstringExample:stringhold_reasonstringExample:stringseparate_ordersobjectShow 8 child attributesHide child attributes
groupingstringExample:stringnumber_formatstringExample:stringsuffixstringExample:stringhold_fulfillmentsbooleanExample:truetagstringExample:stringtransaction_gatewaystringExample:stringoriginal_order_hold_tagnulloriginal_order_split_tagnull
on_holdobjectShow 3 child attributesHide child attributes
release_schedulestringExample:stringrelease_atnullrequire_paymentbooleanExample:true
paymentsobjectShow 7 child attributesHide child attributes
options_offeredstringExample:stringdefault_optionstringExample:stringfullobjectShow 7 child attributesHide child attributes
selling_plan_idnullcheckout_chargeobjectShow 2 child attributesHide child attributes
charge_typestringExample:stringcharge_amountintegerExample:1
remaining_balanceobjectShow 3 child attributesHide child attributes
charge_triggerstringExample:stringcharge_exact_timenulldays_after_checkoutnull
price_adjustmentobjectShow 2 child attributesHide child attributes
adjustment_typenulladjustment_amountnull
option_titlestringExample:stringoption_descriptionstringExample:stringdiscount_textstringExample:string
collection_schedulestringExample:stringshow_payment_widgetbooleanExample:trueshow_discounted_pricenullcurrency_codenull
availabilityobjectShow 5 child attributesHide child attributes
schedulestringExample:stringstarts_atnullends_atnullcurrent_statusstringExample:stringtime_zonestringExample:string
limitsobjectShow 9 child attributesHide child attributes
default_per_variantnulldisplay_stylestringExample:stringlimit_textstringExample:stringshow_iconsbooleanExample:trueprogress_barobjectShow 7 child attributesHide child attributes
progress_textstringExample:stringfill_colorstringExample:stringbackground_colorstringExample:stringbox_background_colornulltext_colorstringExample:stringborder_radiusintegerExample:1show_percentagebooleanExample:true
order_tagsarray of stringstermsobjectShow 5 child attributesHide child attributes
require_acceptancebooleanExample:trueterms_textstringExample:stringdisable_button_until_acceptedbooleanExample:truerecord_acceptancebooleanExample:trueacceptance_labelstringExample:string
cartobjectShow 2 child attributesHide child attributes
allowed_itemsstringExample:stringerror_messagestringExample:string
order_quantityobjectShow 2 child attributesHide child attributes
minimumnullmaximumnull
countdownobjectShow 12 child attributesHide child attributes
show_whenstringExample:stringdate_sourcestringExample:stringstarts_atnullends_atnullstarts_textnullends_textnulllabelsobjectShow 4 child attributesHide child attributes
daysstringExample:stringhoursstringExample:stringminutesstringExample:stringsecondsstringExample:string
text_colorstringExample:stringbackground_colorstringExample:stringborder_radiusintegerExample:1unitsarray of stringscurrentobjectShow 5 child attributesHide child attributes
visible_phasestringExample:stringtarget_atnullheading_textnullstarts_atnullends_atnull
marketsobjectShow 2 child attributesHide child attributes
scopestringExample:stringshopify_market_idsarray of anys
advancedobjectShow 2 child attributesHide child attributes
checkout_methodstringExample:stringcart_attributesobjectShow 3 child attributesHide child attributes
show_paymentbooleanExample:trueshow_shippingbooleanExample:truecustom_textnull
integrationsobjectShow 2 child attributesHide child attributes
posobjectShow 2 child attributesHide child attributes
enable_posbooleanExample:trueinventory_checkstringExample:string
b2bobjectShow 1 child attributeHide child attributes
enable_b2bbooleanExample:true
batchesobjectShow 6 child attributesHide child attributes
release_strategystringExample:stringadvance_schedulestringExample:stringlabel_formatstringExample:stringstatus_textobjectShow 3 child attributesHide child attributes
paststringExample:stringlivestringExample:stringupcomingstringExample:string
widgetobjectShow 4 child attributesHide child attributes
stylestringExample:stringprogressstringExample:stringshow_other_ship_datesbooleanExample:trueshow_namesbooleanExample:true
itemsarray of anys
translationsobjectline_item_revenuestringExample:stringorder_revenuestringExample:stringcreated_atstringExample:2026-01-15T09:30:00Zupdated_atstringExample:2026-01-15T09:30:00ZambiguousbooleanExample:truequerystringExample:stringcandidatesarray of objectsShow 8 child attributesHide child attributes
idstringExample:stringnamestringExample:stringinternal_namestringExample:stringcurrent_statusstringExample:stringline_item_revenuestringExample:stringorder_revenuestringExample:stringcreated_atstringExample:2026-01-15T09:30:00Zupdated_atstringExample:2026-01-15T09:30:00Z
Errors
not_foundThe path is valid but nothing with that id exists in this store.
validation_failedThe action refused the request for a reason that is not a single bad field.
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/offer_lookup" \
-H "X-Auth-Token: $STOQ_API_KEY"const res = await fetch("https://app.stoqapp.com/api/v2/external/preorders/offer_lookup", {
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/offer_lookup",
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/offer_lookup")
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/offer_lookup?name=Summer%20Sneaker%20Drop" \
-H "X-Auth-Token: $STOQ_API_KEY"const res = await fetch("https://app.stoqapp.com/api/v2/external/preorders/offer_lookup?name=Summer%20Sneaker%20Drop", {
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/offer_lookup?name=Summer%20Sneaker%20Drop",
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/offer_lookup?name=Summer%20Sneaker%20Drop")
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": "string",
"shopify_selling_plan_group_id": "string",
"name": "string",
"internal_name": "string",
"widget": {
"button": {
"button_text": "string",
"custom_colors_enabled": true,
"text_color": "string",
"background_color": "string"
},
"disclaimer": {
"show_disclaimer": true,
"disclaimer_text": "string",
"text_color": "string",
"background_color": "string",
"border_radius": 1
},
"badge": {
"show_badge": true,
"badge_text": "string",
"text_color": "string",
"background_color": "string"
}
},
"inventory": {
"stock_condition": "string",
"reserve": "string"
},
"products": {
"selection": "string",
"shopify_collection_id": null,
"tags": [
null
],
"eligible_inventory_policy": "string",
"excluded_shopify_variant_ids": [
null
],
"exclusion_tag": null,
"variant_count": 1
},
"shipping": {
"timeline": {
"scope": "string",
"show_shipping_text": true,
"shipping_text": "string",
"variant_shipping_text": "string"
},
"delivery_timing": "string",
"ships_at": null,
"days_after_checkout": null,
"fulfillment": {
"handling": "string",
"hold_reason": "string",
"separate_orders": {
"grouping": "string",
"number_format": "string",
"suffix": "string",
"hold_fulfillments": true,
"tag": "string",
"transaction_gateway": "string",
"original_order_hold_tag": null,
"original_order_split_tag": null
}
},
"on_hold": {
"release_schedule": "string",
"release_at": null,
"require_payment": true
}
},
"payments": {
"options_offered": "string",
"default_option": "string",
"full": {
"selling_plan_id": null,
"checkout_charge": {
"charge_type": "string",
"charge_amount": 1
},
"remaining_balance": {
"charge_trigger": "string",
"charge_exact_time": null,
"days_after_checkout": null
},
"price_adjustment": {
"adjustment_type": null,
"adjustment_amount": null
},
"option_title": "string",
"option_description": "string",
"discount_text": "string"
},
"collection_schedule": "string",
"show_payment_widget": true,
"show_discounted_price": null,
"currency_code": null
},
"availability": {
"schedule": "string",
"starts_at": null,
"ends_at": null,
"current_status": "string",
"time_zone": "string"
},
"limits": {
"default_per_variant": null,
"display_style": "string",
"limit_text": "string",
"show_icons": true,
"progress_bar": {
"progress_text": "string",
"fill_color": "string",
"background_color": "string",
"box_background_color": null,
"text_color": "string",
"border_radius": 1,
"show_percentage": true
},
"order_tags": [
"string"
],
"terms": {
"require_acceptance": true,
"terms_text": "string",
"disable_button_until_accepted": true,
"record_acceptance": true,
"acceptance_label": "string"
},
"cart": {
"allowed_items": "string",
"error_message": "string"
},
"order_quantity": {
"minimum": null,
"maximum": null
}
},
"countdown": {
"show_when": "string",
"date_source": "string",
"starts_at": null,
"ends_at": null,
"starts_text": null,
"ends_text": null,
"labels": {
"days": "string",
"hours": "string",
"minutes": "string",
"seconds": "string"
},
"text_color": "string",
"background_color": "string",
"border_radius": 1,
"units": [
"string"
],
"current": {
"visible_phase": "string",
"target_at": null,
"heading_text": null,
"starts_at": null,
"ends_at": null
}
},
"markets": {
"scope": "string",
"shopify_market_ids": [
null
]
},
"advanced": {
"checkout_method": "string",
"cart_attributes": {
"show_payment": true,
"show_shipping": true,
"custom_text": null
}
},
"integrations": {
"pos": {
"enable_pos": true,
"inventory_check": "string"
},
"b2b": {
"enable_b2b": true
}
},
"batches": {
"release_strategy": "string",
"advance_schedule": "string",
"label_format": "string",
"status_text": {
"past": "string",
"live": "string",
"upcoming": "string"
},
"widget": {
"style": "string",
"progress": "string",
"show_other_ship_dates": true,
"show_names": true
},
"items": [
null
]
},
"translations": {},
"line_item_revenue": "string",
"order_revenue": "string",
"created_at": "2026-01-15T09:30:00Z",
"updated_at": "2026-01-15T09:30:00Z",
"ambiguous": true,
"query": "string",
"candidates": [
{
"id": "string",
"name": "string",
"internal_name": "string",
"current_status": "string",
"line_item_revenue": "string",
"order_revenue": "string",
"created_at": "2026-01-15T09:30:00Z",
"updated_at": "2026-01-15T09:30:00Z"
}
]
}{
"errors": [
"Invalid API key"
],
"code": "auth_invalid",
"details": [
{
"code": "auth_invalid",
"message": "Invalid API key",
"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
}
]
}