Skip to content

Update widget settings

API v2 is in public beta: endpoints and fields can change before general availability. See the changelog

PATCH/back_in_stock/settings/widget

Costs 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-Keystring

    A 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 (422 idempotency_key_reused); a retry while the first is still running gets 409 idempotency_key_in_progress. Keys are per store. Server errors and rate limits are not kept, so their retry runs.

Request body

  • localestring

    Optional 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.

  • buttonobject

    The notify-me button's text, colours, corner radius, font and position.

    Show 8 child attributesHide child attributes
    • textstring

      Button text on the notify-me button.

    • text_colorstring

      Notify-me button text colour. Hex, e.g. "#1A73E8".

    • background_colorstring

      Notify-me button background colour. Hex.

    • border_radiusinteger

      Notify-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 of float-rightfloat-leftautospecific
    • font_familystring

      Font 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_colorstring

      Collection page -- button text colour. Hex.

    • collection_background_colorstring

      Collection page -- button background colour. Hex.

  • placementobject

    Where 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
    • enabledboolean

      The 'Notify me' widget itself. False hides it everywhere.

    • show_on_collectionboolean

      Show 'Notify me' on collection pages.

    • show_on_homeboolean

      Show 'Notify me' on the home page.

    • show_on_searchboolean

      Show 'Notify me' on the search page.

    • show_on_preorderboolean

      Show 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_stockboolean

      Show 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_stockboolean

      Show the 'Notify me' button on a collection card if any variant is out of stock.

    • availability_check_enabledboolean

      Quick resubscribe: a customer who follows an alert to a sold-out product gets a pre-filled 'Notify me' popup.

    • merchant_managed_positionboolean

      Dev mode. Shared with the preorder developer settings.

    • selectorsobject
      Show 10 child attributesHide child attributes
      • productstring

        CSS 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.

      • collectionstring

        CSS selector on each collection-page product card to put the button after.

      • collection_insertionstring

        Where the collection-page button goes relative to that element: beforebegin, afterbegin, beforeend or afterend.

        One of beforebeginafterbeginbeforeendafterend
      • collection_containerstring

        CSS selector of the collection-page products container. Optional.

      • homestring

        CSS selector on each home-page product card to put the button after.

      • home_containerstring

        CSS selector of the home-page products container. Optional.

      • searchstring

        CSS selector on each search-result product card to put the button after.

      • search_containerstring

        CSS selector of the search-results products container. Optional.

      • restock_notestring

        Dev mode: CSS selector of the element the restock note goes next to. Empty shows it below the 'Notify me' button.

      • restock_note_insertionstring

        Where the restock note goes relative to that element: beforebegin, afterbegin, beforeend or afterend.

        One of beforebeginafterbeginbeforeendafterend
    • hide_by_tagobject
      Show 3 child attributesHide child attributes
      • enabledboolean

        True applies the widget to specific products picked by product tag; false to all out-of-stock products.

      • tagsstring

        Product tags the rule looks for, comma separated.

      • hides_buttonboolean

        True hides the widget on products with those tags; false shows it only on them.

  • formobject

    The signup form's copy, success and error messages, style, collected fields and on-page (inline) mode.

    Show 5 child attributesHide child attributes
    • copyobject
      Show 12 child attributesHide child attributes
      • headerstring

        Header of the signup form.

      • descriptionstring

        Description under the form header.

      • button_textstring

        Button text on the signup form.

      • email_labelstring

        Email channel label.

      • email_placeholderstring

        Form email field placeholder.

      • phone_labelstring

        SMS channel label.

      • phone_placeholderstring

        Form phone number field placeholder.

      • quantity_labelstring

        Quantity field label.

      • customer_name_placeholderstring

        Name field placeholder.

      • termsstring

        Terms message under the form.

      • promotion_consent_labelstring

        Marketing consent label.

      • resubscribe_textstring

        Resubscribe form description -- the banner on the quick-resubscribe popup.

    • messagesobject
      Show 7 child attributesHide child attributes
      • successstring

        Success message shown after a signup.

      • errorstring

        Form email error message.

      • empty_errorstring

        Form empty registration error message.

      • duplicate_errorstring

        Form duplicate registration error message.

      • customer_name_errorstring

        Name error message.

      • phone_errorstring

        Form phone number error message.

      • did_you_mean_errorstring

        The email suggestion shown for a likely typo in the email address. %{suggested_email} and %{current_email} are filled in.

    • styleobject
      Show 9 child attributesHide child attributes
      • background_colorstring

        Form background colour. Hex.

      • text_colorstring

        Form text colour. Hex.

      • border_radiusinteger

        Form corner radius, in whole pixels.

      • button_background_colorstring

        Form button background colour. Hex.

      • button_text_colorstring

        Form button text colour. Hex.

      • show_imageboolean

        Show the product image on the form.

      • note_background_colorstring

        Restock note background colour. Hex.

      • note_text_colorstring

        Restock note text colour. Hex.

      • note_border_radiusinteger

        Restock note corner radius, in whole pixels.

    • fieldsobject
      Show 10 child attributesHide child attributes
      • customer_name_enabledboolean

        Collect the customer's name.

      • customer_name_requiredboolean

        Make the name field mandatory.

      • quantity_requiredboolean

        Let customers specify a quantity.

      • collect_promotion_consentboolean

        Get marketing consent on the form.

      • collect_promotion_consent_defaultboolean

        Enroll customers by default -- the consent box starts ticked.

      • sms_firstboolean

        true shows the SMS field before the email field.

      • sms_default_countrystring

        Default country selected on the phone field. Lowercase ISO 3166-1 alpha-2 code, e.g. "us", "gb", "ca", "au", "de".

      • sms_restrict_countryboolean

        Restrict SMS registration to the default country.

      • shop_sign_inboolean

        Show a Continue with Shop button under the Notify me button. Needs email alerts on.

      • sms_allowed_countriesobject

        Edits 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 strings
        • removearray of strings
    • inlineobject
      Show 3 child attributesHide child attributes
      • enabledboolean

        True shows the signup form on the product page (at form.inline.selector) instead of a button and popup.

      • selectorstring

        CSS selector of the element the on-page form is placed next to.

      • insertionstring

        Where the on-page form goes relative to that element: beforebegin, afterbegin, beforeend or afterend.

        One of beforebeginafterbeginbeforeendafterend
  • optinobject

    The double opt-in confirmation email and link.

    Show 5 child attributesHide child attributes
    • email_subjectstring

      Double opt-in confirmation email subject.

    • email_bodystring

      Double opt-in confirmation email body.

    • success_textstring

      Confirmation success message.

    • custom_domain_enabledboolean

      Use the store domain in the confirmation link.

    • app_proxy_path_prefixstring

      App proxy path used in the store-domain confirmation link: "/apps/<suffix>" or "/a/<suffix>", as set in the Shopify app proxy settings.

  • brandingobject

    The STOQ watermark on the widget.

    Show 1 child attributeHide child attributes
    • powered_byboolean

      Show the 'Powered by STOQ' watermark.

  • customobject

    Custom CSS for the widget.

    Show 1 child attributeHide child attributes
    • cssstring

      Custom 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

  • buttonobject
    Show 8 child attributesHide child attributes
    • textstring
      Example: Notify me when it's back
    • text_colorstring
      Example: #FFFFFF
    • background_colorstring
      Example: #111111
    • border_radiusinteger
      Example: 4
    • positionstring
      Example: float-right
    • font_familystring
      Example: OpenSans
    • collection_text_colorstring
      Example: #FFFFFF
    • collection_background_colorstring
      Example: #202223
  • placementobject
    Show 11 child attributesHide child attributes
    • enabledboolean
      Example: true
    • show_on_collectionboolean
      Example: false
    • show_on_homeboolean
      Example: false
    • show_on_searchboolean
      Example: false
    • show_on_preorderboolean
      Example: false
    • show_if_any_variant_out_of_stockboolean
      Example: false
    • show_on_collection_if_any_variant_out_of_stockboolean
      Example: false
    • availability_check_enabledboolean
      Example: true
    • merchant_managed_positionboolean
      Example: false
    • selectorsobject
      Show 10 child attributesHide child attributes
      • productstring, nullable
      • collectionstring, nullable
      • collection_insertionstring
        Example: afterend
      • collection_containerstring, nullable
      • homestring, nullable
      • home_containernull
      • searchstring, nullable
      • search_containernull
      • restock_notestring, nullable
      • restock_note_insertionstring
        Example: afterend
    • hide_by_tagobject
      Show 3 child attributesHide child attributes
      • enabledboolean
        Example: false
      • tagsstring
        Example: rocket-hide
      • hides_buttonboolean
        Example: true
  • formobject
    Show 5 child attributesHide child attributes
    • copyobject
      Show 12 child attributesHide child attributes
      • headerstring
        Example: Get restock alerts
      • descriptionstring
        Example: Get a notification as soon as this product is back in sto…
      • button_textstring
        Example: Notify me when it's back
      • email_labelstring
        Example: Email
      • email_placeholderstring
        Example: Email address
      • phone_labelstring
        Example: Phone number
      • phone_placeholderstring
        Example: SMS
      • quantity_labelstring
        Example: Quantity
      • customer_name_placeholderstring
        Example: Name
      • termsstring
        Example: Promise we won't spam. You'll only receive notifications …
      • promotion_consent_labelstring
        Example: Notify me about other news, sales, discounts & offers too!
      • resubscribe_textstring
        Example: This product is out of stock. Get notified when it’s rest…
    • messagesobject
      Show 7 child attributesHide child attributes
      • successstring
        Example: Thank you! We will notify you when the product is available.
      • errorstring
        Example: Please enter a valid email address
      • empty_errorstring
        Example: Please fill in one or more of the options above
      • duplicate_errorstring
        Example: You've already subscribed for alerts to this product.
      • customer_name_errorstring
        Example: Please enter your name
      • phone_errorstring
        Example: Please enter a valid phone number
      • did_you_mean_errorstring
        Example: Did you mean %{suggested_email}? Or use %{current_email}
    • styleobject
      Show 9 child attributesHide child attributes
      • background_colorstring
        Example: #FFFFFF
      • text_colorstring
        Example: #202223
      • border_radiusinteger
        Example: 8
      • button_background_colorstring
        Example: #111111
      • button_text_colorstring
        Example: #FFFFFF
      • show_imageboolean
        Example: false
      • note_background_colorstring
        Example: #f3f4f6
      • note_text_colorstring
        Example: #202223
      • note_border_radiusinteger
        Example: 4
    • fieldsobject
      Show 10 child attributesHide child attributes
      • customer_name_enabledboolean
        Example: false
      • customer_name_requiredboolean
        Example: false
      • quantity_requiredboolean
        Example: false
      • collect_promotion_consentboolean
        Example: false
      • collect_promotion_consent_defaultboolean
        Example: true
      • sms_firstboolean
        Example: true
      • sms_default_countrystring
        Example: us
      • sms_restrict_countryboolean
        Example: false
      • shop_sign_inboolean
        Example: false
      • sms_allowed_countriesarray of strings
    • inlineobject
      Show 3 child attributesHide child attributes
      • enabledboolean
        Example: false
      • selectorstring, nullable
      • insertionstring
        Example: afterend
  • optinobject
    Show 5 child attributesHide child attributes
    • email_subjectstring
      Example: Confirm your back in stock alert registration
    • email_bodystring
      Example: You recently registered to receive a back in stock email …
    • success_textstring
      Example: Registration confirmed! You'll receive an alert when the …
    • custom_domain_enabledboolean
      Example: false
    • app_proxy_path_prefixstring
      Example: /apps/restockrocket-production
  • brandingobject
    Show 1 child attributeHide child attributes
    • powered_byboolean
      Example: true
  • customobject
    Show 2 child attributesHide child attributes
    • cssstring, nullable
    • javascriptstring, nullable
  • localestring
    Example: en

Errors

404
not_found

The path is valid but nothing with that id exists in this store.

409
idempotency_key_in_progress

An earlier request with the same Idempotency-Key is still running. Wait, then resend the same request with the same key.

422
invalid_params

One or more fields failed the action's schema.

422
validation_failed

The 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.

PATCH/back_in_stock/settings/widget
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
    }
  }'
Response
{
  "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"
}