Update widget settings
API v2 is in public beta: endpoints and fields can change before general availability. See the changelog
/back_in_stock/settings/widgetCosts 2 rate-limit points · Rate limits
Update the storefront back-in-stock signup widget: the notify-me button (text, colors, corner radius, font, position), where the button appears (product, collection, home, search, preorder pages, and whether the whole widget is enabled), and the signup form's copy, success/error messages, colors, which inputs are collected and the double opt-in email text. button.position is "auto" (in-flow, directly below the sold-out add-to-cart button), "float-right" or "float-left" (a floating tab pinned to that edge of the page) or "specific" (after the element placement.selectors.product finds). placement.selectors holds the CSS selectors that place the button on product, collection, home and search pages; placement.hide_by_tag limits the widget by product tag; form.inline shows the form on the page instead of a popup; custom.css runs on every storefront page. form.fields.sms_first is a boolean: true shows the SMS field before email. form.fields.sms_default_country is a lowercase ISO 3166-1 alpha-2 code (e.g. "us", "gb", "ca", "au"). form.fields.sms_allowed_countries takes { add: [...], remove: [...] } of those same codes and edits the stored list in place: it never replaces it, so one country can be added or dropped without resending the rest; an empty allowed list means every country is allowed. Colors must be hex (#RRGGBB); radii are integers in pixels. Pass an optional top-level locale (e.g. "fr") to write the text fields for that language only.
Deep partial. Groups: button, placement (with selectors and hide_by_tag), form.copy, form.messages, form.style, form.fields, form.inline, optin, branding, custom. Selectors, the on-page form, custom CSS and the app proxy path change what every shopper sees; a wrong value can hide the widget. Channel enables (email/sms), optin_required and the merchant signup alert live on the other settings sections. custom.javascript is read-only: STOQ support sets it.
Also searched asedit signup widgetchange notify me buttonmove the notify me buttonput the notify me button below the sold out buttonchange button textrename the notify me buttonchange button colorchange button colourround the button cornerschange the widget fontshow the notify me button on collection pagesshow button on search resultshide the notify me buttonturn off the signup widgetturn on the signup widgetchange the signup form headingchange the signup form wordingchange the signup success messagechange the signup error messagechange form colorscollect customer nameask for quantityask for marketing consentshow the channel selectorrestrict sms signups to certain countriesallow sms from another countryset the default phone countrychange double opt in emailhide powered bytranslate the signup form
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
localestringOptional language tag ("fr", "de", "pt-BR"). Scopes TEXT fields to that language; omit for the shop default. Colors, radii, toggles, position and SMS country settings ignore it.
buttonobjectThe notify-me button's text, colours, corner radius, font and position.
Show 8 child attributesHide child attributes
textstringButton text on the notify-me button.
text_colorstringNotify-me button text colour. Hex, e.g. "#1A73E8".
background_colorstringNotify-me button background colour. Hex.
border_radiusintegerNotify-me button corner radius, in whole pixels.
positionstring"auto" = in-flow directly below the sold-out add-to-cart button; "float-right"/"float-left" = floating tab pinned to that edge; "specific" = right after the element placement.selectors.product finds.
One offloat-rightfloat-leftautospecificfont_familystringFont of the signup form popup, set on every part of it (text, select, submit button). "inherit" uses the theme font: to match the theme, set this, not CSS on the container. The notify-me button itself always uses the theme font; this does not change it.
collection_text_colorstringCollection page -- button text colour. Hex.
collection_background_colorstringCollection page -- button background colour. Hex.
placementobjectWhere the widget shows (enabled, product, collection, home, search and preorder pages), its CSS selectors, and the hide-by-tag rule.
Show 11 child attributesHide child attributes
enabledbooleanThe 'Notify me' widget itself. False hides it everywhere.
show_on_collectionbooleanShow 'Notify me' on collection pages.
show_on_homebooleanShow 'Notify me' on the home page.
show_on_searchbooleanShow 'Notify me' on the search page.
show_on_preorderbooleanShow the 'Notify me' widget on preorder products: on a preorder offer or set to continue selling when out of stock.
show_if_any_variant_out_of_stockbooleanShow the 'Notify me' widget on a product page if any variant is out of stock, even while an in-stock variant is selected. Off, the widget follows the selected variant: it still shows whenever that variant is sold out, so Off never means every variant must be sold out.
show_on_collection_if_any_variant_out_of_stockbooleanShow the 'Notify me' button on a collection card if any variant is out of stock.
availability_check_enabledbooleanQuick resubscribe: a customer who follows an alert to a sold-out product gets a pre-filled 'Notify me' popup.
merchant_managed_positionbooleanDev mode. Shared with the preorder developer settings.
selectorsobjectShow 10 child attributesHide child attributes
productstringCSS selector of the sold-out button on the product page. Used while button.position is "specific": the notify-me button goes right after the element it finds.
collectionstringCSS selector on each collection-page product card to put the button after.
collection_insertionstringWhere the collection-page button goes relative to that element: beforebegin, afterbegin, beforeend or afterend.
One ofbeforebeginafterbeginbeforeendafterendcollection_containerstringCSS selector of the collection-page products container. Optional.
homestringCSS selector on each home-page product card to put the button after.
home_containerstringCSS selector of the home-page products container. Optional.
searchstringCSS selector on each search-result product card to put the button after.
search_containerstringCSS selector of the search-results products container. Optional.
restock_notestringDev mode: CSS selector of the element the restock note goes next to. Empty shows it below the 'Notify me' button.
restock_note_insertionstringWhere the restock note goes relative to that element: beforebegin, afterbegin, beforeend or afterend.
One ofbeforebeginafterbeginbeforeendafterend
hide_by_tagobjectShow 3 child attributesHide child attributes
enabledbooleanTrue applies the widget to specific products picked by product tag; false to all out-of-stock products.
tagsstringProduct tags the rule looks for, comma separated.
hides_buttonbooleanTrue hides the widget on products with those tags; false shows it only on them.
formobjectThe signup form's copy, success and error messages, style, collected fields and on-page (inline) mode.
Show 5 child attributesHide child attributes
copyobjectShow 12 child attributesHide child attributes
headerstringHeader of the signup form.
descriptionstringDescription under the form header.
button_textstringButton text on the signup form.
email_labelstringEmail channel label.
email_placeholderstringForm email field placeholder.
phone_labelstringSMS channel label.
phone_placeholderstringForm phone number field placeholder.
quantity_labelstringQuantity field label.
customer_name_placeholderstringName field placeholder.
termsstringTerms message under the form.
promotion_consent_labelstringMarketing consent label.
resubscribe_textstringResubscribe form description -- the banner on the quick-resubscribe popup.
messagesobjectShow 7 child attributesHide child attributes
successstringSuccess message shown after a signup.
errorstringForm email error message.
empty_errorstringForm empty registration error message.
duplicate_errorstringForm duplicate registration error message.
customer_name_errorstringName error message.
phone_errorstringForm phone number error message.
did_you_mean_errorstringThe email suggestion shown for a likely typo in the email address. %{suggested_email} and %{current_email} are filled in.
styleobjectShow 9 child attributesHide child attributes
background_colorstringForm background colour. Hex.
text_colorstringForm text colour. Hex.
border_radiusintegerForm corner radius, in whole pixels.
button_background_colorstringForm button background colour. Hex.
button_text_colorstringForm button text colour. Hex.
show_imagebooleanShow the product image on the form.
note_background_colorstringRestock note background colour. Hex.
note_text_colorstringRestock note text colour. Hex.
note_border_radiusintegerRestock note corner radius, in whole pixels.
fieldsobjectShow 10 child attributesHide child attributes
customer_name_enabledbooleanCollect the customer's name.
customer_name_requiredbooleanMake the name field mandatory.
quantity_requiredbooleanLet customers specify a quantity.
collect_promotion_consentbooleanGet marketing consent on the form.
collect_promotion_consent_defaultbooleanEnroll customers by default -- the consent box starts ticked.
sms_firstbooleantrue shows the SMS field before the email field.
sms_default_countrystringDefault country selected on the phone field. Lowercase ISO 3166-1 alpha-2 code, e.g. "us", "gb", "ca", "au", "de".
sms_restrict_countrybooleanRestrict SMS registration to the default country.
shop_sign_inbooleanShow a Continue with Shop button under the Notify me button. Needs email alerts on.
sms_allowed_countriesobjectEdits the SMS allow-list IN PLACE. add/remove are lowercase ISO 3166-1 alpha-2 codes; the rest of the list is left untouched. Empty list = all countries allowed.
Show 2 child attributesHide child attributes
addarray of stringsremovearray of strings
inlineobjectShow 3 child attributesHide child attributes
enabledbooleanTrue shows the signup form on the product page (at form.inline.selector) instead of a button and popup.
selectorstringCSS selector of the element the on-page form is placed next to.
insertionstringWhere the on-page form goes relative to that element: beforebegin, afterbegin, beforeend or afterend.
One ofbeforebeginafterbeginbeforeendafterend
optinobjectThe double opt-in confirmation email and link.
Show 5 child attributesHide child attributes
email_subjectstringDouble opt-in confirmation email subject.
email_bodystringDouble opt-in confirmation email body.
success_textstringConfirmation success message.
custom_domain_enabledbooleanUse the store domain in the confirmation link.
app_proxy_path_prefixstringApp proxy path used in the store-domain confirmation link: "/apps/<suffix>" or "/a/<suffix>", as set in the Shopify app proxy settings.
brandingobjectThe STOQ watermark on the widget.
Show 1 child attributeHide child attributes
powered_bybooleanShow the 'Powered by STOQ' watermark.
customobjectCustom CSS for the widget.
Show 1 child attributeHide child attributes
cssstringCustom CSS for the button and signup form, added on every storefront page. Plain CSS only: no HTML; url() only from the shop's domains, Shopify, STOQ or font hosts; @import only font stylesheets or the shop's own. "" clears it. Shared with the preorder developer settings.
Returns
buttonobjectShow 8 child attributesHide child attributes
textstringExample:Notify me when it's backtext_colorstringExample:#FFFFFFbackground_colorstringExample:#111111border_radiusintegerExample:4positionstringExample:float-rightfont_familystringExample:OpenSanscollection_text_colorstringExample:#FFFFFFcollection_background_colorstringExample:#202223
placementobjectShow 11 child attributesHide child attributes
enabledbooleanExample:trueshow_on_collectionbooleanExample:falseshow_on_homebooleanExample:falseshow_on_searchbooleanExample:falseshow_on_preorderbooleanExample:falseshow_if_any_variant_out_of_stockbooleanExample:falseshow_on_collection_if_any_variant_out_of_stockbooleanExample:falseavailability_check_enabledbooleanExample:truemerchant_managed_positionbooleanExample:falseselectorsobjectShow 10 child attributesHide child attributes
productstring, nullablecollectionstring, nullablecollection_insertionstringExample:afterendcollection_containerstring, nullablehomestring, nullablehome_containernullsearchstring, nullablesearch_containernullrestock_notestring, nullablerestock_note_insertionstringExample:afterend
hide_by_tagobjectShow 3 child attributesHide child attributes
enabledbooleanExample:falsetagsstringExample:rocket-hidehides_buttonbooleanExample:true
formobjectShow 5 child attributesHide child attributes
copyobjectShow 12 child attributesHide child attributes
headerstringExample:Get restock alertsdescriptionstringExample:Get a notification as soon as this product is back in sto…button_textstringExample:Notify me when it's backemail_labelstringExample:Emailemail_placeholderstringExample:Email addressphone_labelstringExample:Phone numberphone_placeholderstringExample:SMSquantity_labelstringExample:Quantitycustomer_name_placeholderstringExample:NametermsstringExample:Promise we won't spam. You'll only receive notifications …promotion_consent_labelstringExample:Notify me about other news, sales, discounts & offers too!resubscribe_textstringExample:This product is out of stock. Get notified when it’s rest…
messagesobjectShow 7 child attributesHide child attributes
successstringExample:Thank you! We will notify you when the product is available.errorstringExample:Please enter a valid email addressempty_errorstringExample:Please fill in one or more of the options aboveduplicate_errorstringExample:You've already subscribed for alerts to this product.customer_name_errorstringExample:Please enter your namephone_errorstringExample:Please enter a valid phone numberdid_you_mean_errorstringExample:Did you mean %{suggested_email}? Or use %{current_email}
styleobjectShow 9 child attributesHide child attributes
background_colorstringExample:#FFFFFFtext_colorstringExample:#202223border_radiusintegerExample:8button_background_colorstringExample:#111111button_text_colorstringExample:#FFFFFFshow_imagebooleanExample:falsenote_background_colorstringExample:#f3f4f6note_text_colorstringExample:#202223note_border_radiusintegerExample:4
fieldsobjectShow 10 child attributesHide child attributes
customer_name_enabledbooleanExample:falsecustomer_name_requiredbooleanExample:falsequantity_requiredbooleanExample:falsecollect_promotion_consentbooleanExample:falsecollect_promotion_consent_defaultbooleanExample:truesms_firstbooleanExample:truesms_default_countrystringExample:ussms_restrict_countrybooleanExample:falseshop_sign_inbooleanExample:falsesms_allowed_countriesarray of strings
inlineobjectShow 3 child attributesHide child attributes
enabledbooleanExample:falseselectorstring, nullableinsertionstringExample:afterend
optinobjectShow 5 child attributesHide child attributes
email_subjectstringExample:Confirm your back in stock alert registrationemail_bodystringExample:You recently registered to receive a back in stock email …success_textstringExample:Registration confirmed! You'll receive an alert when the …custom_domain_enabledbooleanExample:falseapp_proxy_path_prefixstringExample:/apps/restockrocket-production
brandingobjectShow 1 child attributeHide child attributes
powered_bybooleanExample:true
customobjectShow 2 child attributesHide child attributes
cssstring, nullablejavascriptstring, nullable
localestringExample:en
Errors
not_foundThe path is valid but nothing with that id exists in this store.
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.
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 -X PATCH "https://app.stoqapp.com/api/v2/external/back_in_stock/settings/widget" \
-H "X-Auth-Token: $STOQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"button": {
"text": "Notify me when it'\''s back",
"background_color": "#111111",
"border_radius": 4
}
}'const res = await fetch("https://app.stoqapp.com/api/v2/external/back_in_stock/settings/widget", {
method: "PATCH",
headers: {
"X-Auth-Token": process.env.STOQ_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"button": {
"text": "Notify me when it's back",
"background_color": "#111111",
"border_radius": 4
}
}),
});
const data = await res.json();import os
import requests
res = requests.patch(
"https://app.stoqapp.com/api/v2/external/back_in_stock/settings/widget",
headers={"X-Auth-Token": os.environ["STOQ_API_KEY"]},
json={
"button": {
"text": "Notify me when it's back",
"background_color": "#111111",
"border_radius": 4
}
},
)
data = res.json()require "net/http"
require "json"
uri = URI("https://app.stoqapp.com/api/v2/external/back_in_stock/settings/widget")
req = Net::HTTP::Patch.new(uri, "X-Auth-Token" => ENV["STOQ_API_KEY"], "Content-Type" => "application/json")
req.body = {
button: {
text: "Notify me when it's back",
background_color: "#111111",
border_radius: 4
}
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body){
"button": {
"text": "Notify me when it's back",
"text_color": "#FFFFFF",
"background_color": "#111111",
"border_radius": 4,
"position": "float-right",
"font_family": "OpenSans",
"collection_text_color": "#FFFFFF",
"collection_background_color": "#202223"
},
"placement": {
"enabled": true,
"show_on_collection": false,
"show_on_home": false,
"show_on_search": false,
"show_on_preorder": false,
"show_if_any_variant_out_of_stock": false,
"show_on_collection_if_any_variant_out_of_stock": false,
"availability_check_enabled": true,
"merchant_managed_position": false,
"selectors": {
"product": null,
"collection": null,
"collection_insertion": "afterend",
"collection_container": null,
"home": null,
"home_container": null,
"search": null,
"search_container": null,
"restock_note": null,
"restock_note_insertion": "afterend"
},
"hide_by_tag": {
"enabled": false,
"tags": "rocket-hide",
"hides_button": true
}
},
"form": {
"copy": {
"header": "Get restock alerts",
"description": "Get a notification as soon as this product is back in stock by signing up below!",
"button_text": "Notify me when it's back",
"email_label": "Email",
"email_placeholder": "Email address",
"phone_label": "Phone number",
"phone_placeholder": "SMS",
"quantity_label": "Quantity",
"customer_name_placeholder": "Name",
"terms": "Promise we won't spam. You'll only receive notifications for this product.",
"promotion_consent_label": "Notify me about other news, sales, discounts & offers too!",
"resubscribe_text": "This product is out of stock. Get notified when it’s restocked again by entering your details below!"
},
"messages": {
"success": "Thank you! We will notify you when the product is available.",
"error": "Please enter a valid email address",
"empty_error": "Please fill in one or more of the options above",
"duplicate_error": "You've already subscribed for alerts to this product.",
"customer_name_error": "Please enter your name",
"phone_error": "Please enter a valid phone number",
"did_you_mean_error": "Did you mean %{suggested_email}? Or use %{current_email}"
},
"style": {
"background_color": "#FFFFFF",
"text_color": "#202223",
"border_radius": 8,
"button_background_color": "#111111",
"button_text_color": "#FFFFFF",
"show_image": false,
"note_background_color": "#f3f4f6",
"note_text_color": "#202223",
"note_border_radius": 4
},
"fields": {
"customer_name_enabled": false,
"customer_name_required": false,
"quantity_required": false,
"collect_promotion_consent": false,
"collect_promotion_consent_default": true,
"sms_first": true,
"sms_default_country": "us",
"sms_restrict_country": false,
"shop_sign_in": false,
"sms_allowed_countries": []
},
"inline": {
"enabled": false,
"selector": null,
"insertion": "afterend"
}
},
"optin": {
"email_subject": "Confirm your back in stock alert registration",
"email_body": "You recently registered to receive a back in stock email alert for {{product.title_incl_variant}} from our store - {{shop.name}}. Please confirm your alert registration by <a href=\"{{request.activation_link}}\">clicking this link</a>",
"success_text": "Registration confirmed! You'll receive an alert when the product is restocked.",
"custom_domain_enabled": false,
"app_proxy_path_prefix": "/apps/restockrocket-production"
},
"branding": {
"powered_by": true
},
"custom": {
"css": null,
"javascript": null
},
"locale": "en"
}{
"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": [
"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
}
]
}