Update developer settings
API v2 is in public beta: endpoints and fields can change before general availability. See the changelog
/preorders/settings/developerCosts 2 rate-limit points · Rate limits
Update the shop-wide preorder developer settings: dev mode, the custom CSS, and the theme selectors that place the Preorder button and each preorder element on product pages and on home, collection and search product cards. Selectors are used only while dev mode is on.
Deep partial. null or "" clears a selector so the theme default applies. dev_mode_enabled and css are shared with the back-in-stock widget: changing them here changes them there. Returns the developer section.
Also searched aschange preorder selectorsset preorder button selectorfix preorder button placement
Headers
Idempotency-KeystringA 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 (422idempotency_key_reused); a retry while the first is still running gets 409idempotency_key_in_progress. Keys are per store. Server errors and rate limits are not kept, so their retry runs.
Request body
dev_mode_enabledbooleanDev mode: place the Preorder button and preorder elements with the selectors below instead of the automatic placement. Shared with the back-in-stock widget's dev mode.
cssstringCustom CSS added on every storefront page, shared with back-in-stock. REPLACES the stored CSS; "" or null clears it.
product_pageobjectTheme selectors for the product form and add-to-cart button on product pages.
Show 4 child attributesHide child attributes
formstringA CSS selector in the theme. The product form the Preorder button belongs to.
add_to_cart_buttonstringA CSS selector in the theme. The theme's add-to-cart button the Preorder button replaces.
add_to_cart_textstringA CSS selector in the theme. The element inside the add-to-cart button holding its text.
original_pricestringA CSS selector in the theme. The price the discounted preorder price strikes through.
insertion_pointsobjectWhere each preorder element goes on product pages, as a selector and position.
Show 7 child attributesHide child attributes
disclaimerobjectShow 2 child attributesHide child attributes
selectorstringA CSS selector in the theme. Where the disclaimer goes on product pages.
insert_typestringWhere the element goes relative to the selector: beforebegin (before it), afterbegin (inside it, first), beforeend (inside it, last) or afterend (after it). Empty uses the default.
One ofbeforebeginafterbeginbeforeendafterend
payment_optionsobjectShow 2 child attributesHide child attributes
selectorstringA CSS selector in the theme. Where the payment options goes on product pages.
insert_typestringWhere the element goes relative to the selector: beforebegin (before it), afterbegin (inside it, first), beforeend (inside it, last) or afterend (after it). Empty uses the default.
One ofbeforebeginafterbeginbeforeendafterend
termsobjectShow 2 child attributesHide child attributes
selectorstringA CSS selector in the theme. Where the terms goes on product pages.
insert_typestringWhere the element goes relative to the selector: beforebegin (before it), afterbegin (inside it, first), beforeend (inside it, last) or afterend (after it). Empty uses the default.
One ofbeforebeginafterbeginbeforeendafterend
badgeobjectShow 2 child attributesHide child attributes
selectorstringA CSS selector in the theme. Where the badge goes on product pages.
insert_typestringWhere the element goes relative to the selector: beforebegin (before it), afterbegin (inside it, first), beforeend (inside it, last) or afterend (after it). Empty uses the default.
One ofbeforebeginafterbeginbeforeendafterend
discounted_priceobjectShow 2 child attributesHide child attributes
selectorstringA CSS selector in the theme. Where the discounted price goes on product pages.
insert_typestringWhere the element goes relative to the selector: beforebegin (before it), afterbegin (inside it, first), beforeend (inside it, last) or afterend (after it). Empty uses the default.
One ofbeforebeginafterbeginbeforeendafterend
countdown_timerobjectShow 2 child attributesHide child attributes
selectorstringA CSS selector in the theme. Where the countdown timer goes on product pages.
insert_typestringWhere the element goes relative to the selector: beforebegin (before it), afterbegin (inside it, first), beforeend (inside it, last) or afterend (after it). Empty uses the default.
One ofbeforebeginafterbeginbeforeendafterend
progress_barobjectShow 2 child attributesHide child attributes
selectorstringA CSS selector in the theme. Where the progress bar goes on product pages.
insert_typestringWhere the element goes relative to the selector: beforebegin (before it), afterbegin (inside it, first), beforeend (inside it, last) or afterend (after it). Empty uses the default.
One ofbeforebeginafterbeginbeforeendafterend
collectionobjectTheme selectors for product cards on collection pages.
Show 4 child attributesHide child attributes
formstringA CSS selector in the theme. The product card form on collection pages.
add_to_cart_buttonstringA CSS selector in the theme. The add-to-cart button on collection page product cards.
badgestringA CSS selector in the theme. Where the preorder badge goes on collection page product cards.
badge_insert_typestringWhere the element goes relative to the selector: beforebegin (before it), afterbegin (inside it, first), beforeend (inside it, last) or afterend (after it). Empty uses the default.
One ofbeforebeginafterbeginbeforeendafterend
homeobjectTheme selectors for product cards on the home page.
Show 3 child attributesHide child attributes
formstringA CSS selector in the theme. The product card form on home pages.
add_to_cart_buttonstringA CSS selector in the theme. The add-to-cart button on home page product cards.
badgestringA CSS selector in the theme. Where the preorder badge goes on home page product cards.
searchobjectTheme selectors for product cards on search results pages.
Show 3 child attributesHide child attributes
formstringA CSS selector in the theme. The product card form on search pages.
add_to_cart_buttonstringA CSS selector in the theme. The add-to-cart button on search page product cards.
badgestringA CSS selector in the theme. Where the preorder badge goes on search page product cards.
Returns
dev_mode_enabledbooleanExample:truecssstring, nullableExample:.stoq-preorder-button { border-radius: 24px; }product_pageobjectShow 4 child attributesHide child attributes
formstringExample:form[action*="/cart/add"]add_to_cart_buttonnullExample:button[name="add"]add_to_cart_textstringExample:spanoriginal_pricenullExample:.price__regular .price-item
insertion_pointsobjectShow 7 child attributesHide child attributes
disclaimerobjectShow 2 child attributesHide child attributes
selectornullExample:.product-form__buttonsinsert_typestringExample:afterend
payment_optionsobjectShow 2 child attributesHide child attributes
selectornullinsert_typestringExample:afterend
termsobjectShow 2 child attributesHide child attributes
selectorstring, nullableinsert_typestringExample:afterend
badgeobjectShow 2 child attributesHide child attributes
selectornullinsert_typestringExample:afterend
discounted_priceobjectShow 2 child attributesHide child attributes
selectornullinsert_typestringExample:afterend
countdown_timerobjectShow 2 child attributesHide child attributes
selectornullinsert_typestringExample:afterend
progress_barobjectShow 2 child attributesHide child attributes
selectornullinsert_typestringExample:beforebegin
collectionobjectShow 4 child attributesHide child attributes
formstringExample:form[action*="/cart/add"]add_to_cart_buttonstringExample:form[action*="/cart/add"] buttonbadgenullbadge_insert_typestringExample:afterend
homeobjectShow 3 child attributesHide child attributes
formstringExample:form[action*="/cart/add"]add_to_cart_buttonstringExample:form[action*="/cart/add"] buttonbadgestring, nullable
searchobjectShow 3 child attributesHide child attributes
formstringExample:form[action*="/cart/add"]add_to_cart_buttonstringExample:form[action*="/cart/add"] buttonbadgenull
Errors
idempotency_key_in_progressAn earlier request with the same Idempotency-Key is still running. Wait, then resend the same request with the same key.
invalid_paramsOne or more fields failed the action's schema.
shopify_rate_limitedShopify throttled the store's Admin API, so the call was not made.
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 -X PATCH "https://app.stoqapp.com/api/v2/external/preorders/settings/developer" \
-H "X-Auth-Token: $STOQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"dev_mode_enabled": true,
"product_page": {
"add_to_cart_button": "button[name=\"add\"]"
},
"insertion_points": {
"disclaimer": {
"selector": ".product-form__buttons",
"insert_type": "afterend"
}
}
}'const res = await fetch("https://app.stoqapp.com/api/v2/external/preorders/settings/developer", {
method: "PATCH",
headers: {
"X-Auth-Token": process.env.STOQ_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"dev_mode_enabled": true,
"product_page": {
"add_to_cart_button": "button[name=\"add\"]"
},
"insertion_points": {
"disclaimer": {
"selector": ".product-form__buttons",
"insert_type": "afterend"
}
}
}),
});
const data = await res.json();import os
import requests
res = requests.patch(
"https://app.stoqapp.com/api/v2/external/preorders/settings/developer",
headers={"X-Auth-Token": os.environ["STOQ_API_KEY"]},
json={
"dev_mode_enabled": True,
"product_page": {
"add_to_cart_button": "button[name=\"add\"]"
},
"insertion_points": {
"disclaimer": {
"selector": ".product-form__buttons",
"insert_type": "afterend"
}
}
},
)
data = res.json()require "net/http"
require "json"
uri = URI("https://app.stoqapp.com/api/v2/external/preorders/settings/developer")
req = Net::HTTP::Patch.new(uri, "X-Auth-Token" => ENV["STOQ_API_KEY"], "Content-Type" => "application/json")
req.body = {
dev_mode_enabled: true,
product_page: {
add_to_cart_button: "button[name=\"add\"]"
},
insertion_points: {
disclaimer: {
selector: ".product-form__buttons",
insert_type: "afterend"
}
}
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body){
"dev_mode_enabled": true,
"css": ".stoq-preorder-button { border-radius: 24px; }",
"product_page": {
"form": "form[action*=\"/cart/add\"]",
"add_to_cart_button": "button[name=\"add\"]",
"add_to_cart_text": "span",
"original_price": ".price__regular .price-item"
},
"insertion_points": {
"disclaimer": {
"selector": ".product-form__buttons",
"insert_type": "afterend"
},
"payment_options": {
"selector": null,
"insert_type": "afterend"
},
"terms": {
"selector": null,
"insert_type": "afterend"
},
"badge": {
"selector": null,
"insert_type": "afterend"
},
"discounted_price": {
"selector": null,
"insert_type": "afterend"
},
"countdown_timer": {
"selector": null,
"insert_type": "afterend"
},
"progress_bar": {
"selector": null,
"insert_type": "beforebegin"
}
},
"collection": {
"form": "form[action*=\"/cart/add\"]",
"add_to_cart_button": "form[action*=\"/cart/add\"] button",
"badge": null,
"badge_insert_type": "afterend"
},
"home": {
"form": "form[action*=\"/cart/add\"]",
"add_to_cart_button": "form[action*=\"/cart/add\"] button",
"badge": null
},
"search": {
"form": "form[action*=\"/cart/add\"]",
"add_to_cart_button": "form[action*=\"/cart/add\"] button",
"badge": null
}
}{
"errors": [
"Invalid API key"
],
"code": "auth_invalid",
"details": [
{
"code": "auth_invalid",
"message": "Invalid API key",
"path": null,
"value": null,
"expected": null
}
]
}{
"errors": [
"A request with this Idempotency-Key is still running"
],
"code": "idempotency_key_in_progress",
"details": [
{
"code": "idempotency_key_in_progress",
"message": "A request with this Idempotency-Key is still running",
"path": null,
"value": null,
"expected": null
}
]
}{
"errors": [
"widget.button.text_color must be a hex color"
],
"code": "invalid_params",
"details": [
{
"code": "invalid_params",
"message": "must be a hex color",
"path": "widget.button.text_color",
"value": "blue",
"expected": {
"type": "string"
}
}
]
}{
"errors": [
"Rate limit exceeded"
],
"code": "rate_limited",
"details": [
{
"code": "rate_limited",
"message": "Rate limit exceeded",
"path": null,
"value": null,
"expected": null
}
]
}