---
title: "Update widget settings"
description: "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 wi"
url: https://docs.stoqapp.com/v2-reference/back-in-stock-settings/update-widget-settings/
api: "API v2 reference"
method: PATCH
path: "/back_in_stock/settings/widget"
---

# Update widget settings

`PATCH https://app.stoqapp.com/api/v2/external/back_in_stock/settings/widget`

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 &quot;auto&quot; (in-flow, directly below the sold-out add-to-cart button), &quot;float-right&quot; or &quot;float-left&quot; (a floating tab pinned to that edge of the page) or &quot;specific&quot; (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. &quot;us&quot;, &quot;gb&quot;, &quot;ca&quot;, &quot;au&quot;). 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. &quot;fr&quot;) to write the text fields for that language only.

**Note:** 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.

## Headers

- `Idempotency-Key` (string): 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

- `locale` (string): Optional language tag (&quot;fr&quot;, &quot;de&quot;, &quot;pt-BR&quot;). Scopes TEXT fields to that language; omit for the shop default. Colors, radii, toggles, position and SMS country settings ignore it.
- `button` (object): The notify-me button's text, colours, corner radius, font and position.
  - `text` (string): Button text on the notify-me button.
  - `text_color` (string): Notify-me button text colour. Hex, e.g. &quot;#1A73E8&quot;.
  - `background_color` (string): Notify-me button background colour. Hex.
  - `border_radius` (integer): Notify-me button corner radius, in whole pixels.
  - `position` (string): &quot;auto&quot; = in-flow directly below the sold-out add-to-cart button; &quot;float-right&quot;/&quot;float-left&quot; = floating tab pinned to that edge; &quot;specific&quot; = right after the element placement.selectors.product finds. One of: `float-right`, `float-left`, `auto`, `specific`.
  - `font_family` (string): Font of the signup form popup, set on every part of it (text, select, submit button). &quot;inherit&quot; 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_color` (string): Collection page -- button text colour. Hex.
  - `collection_background_color` (string): Collection page -- button background colour. Hex.
- `placement` (object): Where the widget shows (enabled, product, collection, home, search and preorder pages), its CSS selectors, and the hide-by-tag rule.
  - `enabled` (boolean): The 'Notify me' widget itself. False hides it everywhere.
  - `show_on_collection` (boolean): Show 'Notify me' on collection pages.
  - `show_on_home` (boolean): Show 'Notify me' on the home page.
  - `show_on_search` (boolean): Show 'Notify me' on the search page.
  - `show_on_preorder` (boolean): 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_stock` (boolean): 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_stock` (boolean): Show the 'Notify me' button on a collection card if any variant is out of stock.
  - `availability_check_enabled` (boolean): Quick resubscribe: a customer who follows an alert to a sold-out product gets a pre-filled 'Notify me' popup.
  - `merchant_managed_position` (boolean): Dev mode. Shared with the preorder developer settings.
  - `selectors` (object)
    - `product` (string): CSS selector of the sold-out button on the product page. Used while button.position is &quot;specific&quot;: the notify-me button goes right after the element it finds.
    - `collection` (string): CSS selector on each collection-page product card to put the button after.
    - `collection_insertion` (string): Where the collection-page button goes relative to that element: beforebegin, afterbegin, beforeend or afterend. One of: `beforebegin`, `afterbegin`, `beforeend`, `afterend`.
    - `collection_container` (string): CSS selector of the collection-page products container. Optional.
    - `home` (string): CSS selector on each home-page product card to put the button after.
    - `home_container` (string): CSS selector of the home-page products container. Optional.
    - `search` (string): CSS selector on each search-result product card to put the button after.
    - `search_container` (string): CSS selector of the search-results products container. Optional.
    - `restock_note` (string): Dev mode: CSS selector of the element the restock note goes next to. Empty shows it below the 'Notify me' button.
    - `restock_note_insertion` (string): Where the restock note goes relative to that element: beforebegin, afterbegin, beforeend or afterend. One of: `beforebegin`, `afterbegin`, `beforeend`, `afterend`.
  - `hide_by_tag` (object)
    - `enabled` (boolean): True applies the widget to specific products picked by product tag; false to all out-of-stock products.
    - `tags` (string): Product tags the rule looks for, comma separated.
    - `hides_button` (boolean): True hides the widget on products with those tags; false shows it only on them.
- `form` (object): The signup form's copy, success and error messages, style, collected fields and on-page (inline) mode.
  - `copy` (object)
    - `header` (string): Header of the signup form.
    - `description` (string): Description under the form header.
    - `button_text` (string): Button text on the signup form.
    - `email_label` (string): Email channel label.
    - `email_placeholder` (string): Form email field placeholder.
    - `phone_label` (string): SMS channel label.
    - `phone_placeholder` (string): Form phone number field placeholder.
    - `quantity_label` (string): Quantity field label.
    - `customer_name_placeholder` (string): Name field placeholder.
    - `terms` (string): Terms message under the form.
    - `promotion_consent_label` (string): Marketing consent label.
    - `resubscribe_text` (string): Resubscribe form description -- the banner on the quick-resubscribe popup.
  - `messages` (object)
    - `success` (string): Success message shown after a signup.
    - `error` (string): Form email error message.
    - `empty_error` (string): Form empty registration error message.
    - `duplicate_error` (string): Form duplicate registration error message.
    - `customer_name_error` (string): Name error message.
    - `phone_error` (string): Form phone number error message.
    - `did_you_mean_error` (string): The email suggestion shown for a likely typo in the email address. %{suggested_email} and %{current_email} are filled in.
  - `style` (object)
    - `background_color` (string): Form background colour. Hex.
    - `text_color` (string): Form text colour. Hex.
    - `border_radius` (integer): Form corner radius, in whole pixels.
    - `button_background_color` (string): Form button background colour. Hex.
    - `button_text_color` (string): Form button text colour. Hex.
    - `show_image` (boolean): Show the product image on the form.
    - `note_background_color` (string): Restock note background colour. Hex.
    - `note_text_color` (string): Restock note text colour. Hex.
    - `note_border_radius` (integer): Restock note corner radius, in whole pixels.
  - `fields` (object)
    - `customer_name_enabled` (boolean): Collect the customer's name.
    - `customer_name_required` (boolean): Make the name field mandatory.
    - `quantity_required` (boolean): Let customers specify a quantity.
    - `collect_promotion_consent` (boolean): Get marketing consent on the form.
    - `collect_promotion_consent_default` (boolean): Enroll customers by default -- the consent box starts ticked.
    - `sms_first` (boolean): true shows the SMS field before the email field.
    - `sms_default_country` (string): Default country selected on the phone field. Lowercase ISO 3166-1 alpha-2 code, e.g. &quot;us&quot;, &quot;gb&quot;, &quot;ca&quot;, &quot;au&quot;, &quot;de&quot;.
    - `sms_restrict_country` (boolean): Restrict SMS registration to the default country.
    - `shop_sign_in` (boolean): Show a Continue with Shop button under the Notify me button. Needs email alerts on.
    - `sms_allowed_countries` (object): 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.
      - `add` (array of strings)
      - `remove` (array of strings)
  - `inline` (object)
    - `enabled` (boolean): True shows the signup form on the product page (at form.inline.selector) instead of a button and popup.
    - `selector` (string): CSS selector of the element the on-page form is placed next to.
    - `insertion` (string): Where the on-page form goes relative to that element: beforebegin, afterbegin, beforeend or afterend. One of: `beforebegin`, `afterbegin`, `beforeend`, `afterend`.
- `optin` (object): The double opt-in confirmation email and link.
  - `email_subject` (string): Double opt-in confirmation email subject.
  - `email_body` (string): Double opt-in confirmation email body.
  - `success_text` (string): Confirmation success message.
  - `custom_domain_enabled` (boolean): Use the store domain in the confirmation link.
  - `app_proxy_path_prefix` (string): App proxy path used in the store-domain confirmation link: &quot;/apps/&lt;suffix&gt;&quot; or &quot;/a/&lt;suffix&gt;&quot;, as set in the Shopify app proxy settings.
- `branding` (object): The STOQ watermark on the widget.
  - `powered_by` (boolean): Show the 'Powered by STOQ' watermark.
- `custom` (object): Custom CSS for the widget.
  - `css` (string): 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. &quot;&quot; clears it. Shared with the preorder developer settings.

## Returns

- `button` (object)
  - `text` (string): e.g. `Notify me when it's back`
  - `text_color` (string): e.g. `#FFFFFF`
  - `background_color` (string): e.g. `#111111`
  - `border_radius` (integer): e.g. `4`
  - `position` (string): e.g. `float-right`
  - `font_family` (string): e.g. `OpenSans`
  - `collection_text_color` (string): e.g. `#FFFFFF`
  - `collection_background_color` (string): e.g. `#202223`
- `placement` (object)
  - `enabled` (boolean): e.g. `true`
  - `show_on_collection` (boolean): e.g. `false`
  - `show_on_home` (boolean): e.g. `false`
  - `show_on_search` (boolean): e.g. `false`
  - `show_on_preorder` (boolean): e.g. `false`
  - `show_if_any_variant_out_of_stock` (boolean): e.g. `false`
  - `show_on_collection_if_any_variant_out_of_stock` (boolean): e.g. `false`
  - `availability_check_enabled` (boolean): e.g. `true`
  - `merchant_managed_position` (boolean): e.g. `false`
  - `selectors` (object)
    - `product` (string, nullable)
    - `collection` (string, nullable)
    - `collection_insertion` (string): e.g. `afterend`
    - `collection_container` (string, nullable)
    - `home` (string, nullable)
    - `home_container` (null)
    - `search` (string, nullable)
    - `search_container` (null)
    - `restock_note` (string, nullable)
    - `restock_note_insertion` (string): e.g. `afterend`
  - `hide_by_tag` (object)
    - `enabled` (boolean): e.g. `false`
    - `tags` (string): e.g. `rocket-hide`
    - `hides_button` (boolean): e.g. `true`
- `form` (object)
  - `copy` (object)
    - `header` (string): e.g. `Get restock alerts`
    - `description` (string): e.g. `Get a notification as soon as this product is back in sto…`
    - `button_text` (string): e.g. `Notify me when it's back`
    - `email_label` (string): e.g. `Email`
    - `email_placeholder` (string): e.g. `Email address`
    - `phone_label` (string): e.g. `Phone number`
    - `phone_placeholder` (string): e.g. `SMS`
    - `quantity_label` (string): e.g. `Quantity`
    - `customer_name_placeholder` (string): e.g. `Name`
    - `terms` (string): e.g. `Promise we won't spam. You'll only receive notifications …`
    - `promotion_consent_label` (string): e.g. `Notify me about other news, sales, discounts & offers too!`
    - `resubscribe_text` (string): e.g. `This product is out of stock. Get notified when it’s rest…`
  - `messages` (object)
    - `success` (string): e.g. `Thank you! We will notify you when the product is available.`
    - `error` (string): e.g. `Please enter a valid email address`
    - `empty_error` (string): e.g. `Please fill in one or more of the options above`
    - `duplicate_error` (string): e.g. `You've already subscribed for alerts to this product.`
    - `customer_name_error` (string): e.g. `Please enter your name`
    - `phone_error` (string): e.g. `Please enter a valid phone number`
    - `did_you_mean_error` (string): e.g. `Did you mean %{suggested_email}? Or use %{current_email}`
  - `style` (object)
    - `background_color` (string): e.g. `#FFFFFF`
    - `text_color` (string): e.g. `#202223`
    - `border_radius` (integer): e.g. `8`
    - `button_background_color` (string): e.g. `#111111`
    - `button_text_color` (string): e.g. `#FFFFFF`
    - `show_image` (boolean): e.g. `false`
    - `note_background_color` (string): e.g. `#f3f4f6`
    - `note_text_color` (string): e.g. `#202223`
    - `note_border_radius` (integer): e.g. `4`
  - `fields` (object)
    - `customer_name_enabled` (boolean): e.g. `false`
    - `customer_name_required` (boolean): e.g. `false`
    - `quantity_required` (boolean): e.g. `false`
    - `collect_promotion_consent` (boolean): e.g. `false`
    - `collect_promotion_consent_default` (boolean): e.g. `true`
    - `sms_first` (boolean): e.g. `true`
    - `sms_default_country` (string): e.g. `us`
    - `sms_restrict_country` (boolean): e.g. `false`
    - `shop_sign_in` (boolean): e.g. `false`
    - `sms_allowed_countries` (array of strings)
  - `inline` (object)
    - `enabled` (boolean): e.g. `false`
    - `selector` (string, nullable)
    - `insertion` (string): e.g. `afterend`
- `optin` (object)
  - `email_subject` (string): e.g. `Confirm your back in stock alert registration`
  - `email_body` (string): e.g. `You recently registered to receive a back in stock email …`
  - `success_text` (string): e.g. `Registration confirmed! You'll receive an alert when the …`
  - `custom_domain_enabled` (boolean): e.g. `false`
  - `app_proxy_path_prefix` (string): e.g. `/apps/restockrocket-production`
- `branding` (object)
  - `powered_by` (boolean): e.g. `true`
- `custom` (object)
  - `css` (string, nullable)
  - `javascript` (string, nullable)
- `locale` (string): e.g. `en`

Rate limit: this call costs 2 points ([rate limits](https://docs.stoqapp.com/docs/rate-limits/)).

## Example request

```sh
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
    }
  }'
```

## 202

Success: example response shown.

```json
{
  "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"
}
```

## 401

Missing or invalid `X-Auth-Token`.

```json
{
  "errors": [
    "Invalid API key"
  ],
  "code": "auth_invalid",
  "details": [
    {
      "code": "auth_invalid",
      "message": "Invalid API key",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}
```

## 409

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

```json
{
  "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
    }
  ]
}
```

## 422

The request failed validation.

```json
{
  "errors": [
    "name is required"
  ],
  "code": "validation_failed",
  "details": [
    {
      "code": "validation_failed",
      "message": "name is required",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}
```

## 429

Rate limited: cost-weighted per token (read 1, write 2; 360 points / 60s). Check `Retry-After`.

```json
{
  "errors": [
    "Rate limit exceeded"
  ],
  "code": "rate_limited",
  "details": [
    {
      "code": "rate_limited",
      "message": "Rate limit exceeded",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}
```

