Update widget
API v2 is in public beta: endpoints and fields can change before general availability. See the changelog
/preorders/offers/{id}/widgetCosts 2 rate-limit points · Rate limits
Update any subset of the widget configuration on a preorder offer.
Deep partial: absent fields are unchanged. Text can be cleared with null. Button colors only show with button.custom_colors_enabled: true, so send both.
Also searched asedit widgetchange widget settingsmodify widgetupdate preorder uienable badgeshow badgeturn on badgemake badge visibledisable badgehide badgeturn off badgeremove badgeenable disclaimershow disclaimerturn on disclaimershow fine printshow shipping noticedisable disclaimerhide disclaimerturn off disclaimerhide fine printremove shipping noticeremove disclaimerenable custom button colorsuse custom button colorsturn on button colorsapply custom colorsdisable custom button colorsuse theme button colorsturn off button colorsrevert to theme colorschange badge colorsset badge colorcustomize badge colorschange badge backgroundchange badge textset badge labelrename badgechange preorder badge textupdate badge textchange button colorsset button colorcustomize button colorschange button textrename buttonset button labelchange preorder button labelupdate button textchange disclaimer colorsset disclaimer stylestyle the disclaimerset disclaimer border radiuschange disclaimer backgroundchange disclaimer textset disclaimer textedit disclaimerchange disclaimer messageset shipping disclaimer
Path parameters
idstringRequiredThe offer's ID, from
GET /preorders/offers.
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
buttonobjectText and colors of the preorder button.
Show 4 child attributesHide child attributes
button_textstring, nullableButton text -- the preorder call-to-action label.
text_colorstringThe button's Text color. Hex. Only shows when button.custom_colors_enabled is true; send it too.
background_colorstringThe button's Background color. Hex. Only shows when button.custom_colors_enabled is true; send it too.
custom_colors_enabledbooleanUse custom colors for button. False falls back to the theme's own button colors.
disclaimerobjectThe disclaimer line shown under the preorder button.
Show 5 child attributesHide child attributes
show_disclaimerbooleanAdd disclaimer -- shows or hides the disclaimer line under the button.
disclaimer_textstring, nullableDisclaimer -- the line shown under the preorder button.
text_colorstringThe disclaimer's Text color. Hex.
background_colorstringThe disclaimer's Background color. Hex.
border_radiusintegerThe disclaimer's Border radius in pixels.
badgeobjectThe preorder badge shown on product pages and product cards.
Show 4 child attributesHide child attributes
show_badgebooleanAdd badge -- shows or hides the preorder badge. On product pages it sits after the price by default. On home, collection and search pages it shows on the product card, only where Preorder pages turns the Preorder button on.
badge_textstring, nullableBadge -- the label printed on the preorder badge.
text_colorstringThe badge's Text color. Hex.
background_colorstringThe badge's Background color. Hex.
localestringLanguage the translated fields are written in, such as 'fr' or 'pt-BR'. Omitted: the shop's default language. Untranslated fields ignore it.
Returns
buttonobjectText and colors of the preorder button.
Show 4 child attributesHide child attributes
button_textstring, nullablePreorder button label.
custom_colors_enabledbooleantrue uses text_color and background_color; false uses the theme's own button colors.
text_colorstringButton text color, as hex. Used when custom_colors_enabled is true.
background_colorstringButton background color, as hex. Used when custom_colors_enabled is true.
disclaimerobjectThe disclaimer line shown under the preorder button.
Show 5 child attributesHide child attributes
show_disclaimerbooleanWhether the disclaimer line shows under the button.
disclaimer_textstring, nullableText of the disclaimer line.
text_colorstringDisclaimer text color, as hex.
background_colorstringDisclaimer background color, as hex.
border_radiusintegerDisclaimer corner radius in pixels.
badgeobjectThe preorder badge shown on product pages and product cards.
Show 4 child attributesHide child attributes
show_badgebooleanWhether the preorder badge shows.
badge_textstringLabel printed on the preorder badge.
text_colorstringBadge text color, as hex.
background_colorstringBadge background color, as hex.
Errors
not_foundThe path is valid but nothing with that id exists in this store.
idempotency_key_in_progressA request with the same Idempotency-Key has not finished yet.
idempotency_key_invalidThe Idempotency-Key header is empty, longer than 255 characters or has characters other than visible ASCII.
idempotency_key_reusedThe Idempotency-Key header was already used for a request with a different method, path or body. Keys are remembered for 1 hour.
invalid_paramsOne or more fields failed the action's schema.
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/offers/73a74948-2b57-4cc3-971f-2b441828c977/widget" \
-H "X-Auth-Token: $STOQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"button": {
"button_text": "Reserve Now"
}
}'const res = await fetch("https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/widget", {
method: "PATCH",
headers: {
"X-Auth-Token": process.env.STOQ_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"button": {
"button_text": "Reserve Now"
}
}),
});
const data = await res.json();import os
import requests
res = requests.patch(
"https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/widget",
headers={"X-Auth-Token": os.environ["STOQ_API_KEY"]},
json={
"button": {
"button_text": "Reserve Now"
}
},
)
data = res.json()require "net/http"
require "json"
uri = URI("https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/widget")
req = Net::HTTP::Patch.new(uri, "X-Auth-Token" => ENV["STOQ_API_KEY"], "Content-Type" => "application/json")
req.body = {
button: {
button_text: "Reserve Now"
}
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body){
"button": {
"button_text": "Reserve Now",
"custom_colors_enabled": true,
"text_color": "#FFFFFF",
"background_color": "#1a1a1a"
},
"disclaimer": {
"show_disclaimer": true,
"disclaimer_text": "Expected to ship by August 2026",
"text_color": "#000000",
"background_color": "#FFFFFF",
"border_radius": 4
},
"badge": {
"show_badge": true,
"badge_text": "Pre-Order",
"text_color": "#000000",
"background_color": "#FFFFFF"
}
}{
"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": [
"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
}
]
}