---
title: "Get widget settings"
description: "Read the storefront back-in-stock signup widget configuration: the notify-me button, where it appears, and the signup form's copy, styling and inputs. ?locale= picks the language of the copy (omit it for the shop default"
url: https://docs.stoqapp.com/v2-reference/back-in-stock-settings/get-widget-settings/
api: "API v2 reference"
method: GET
path: "/back_in_stock/settings/widget"
---

# Get widget settings

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

Read the storefront back-in-stock signup widget configuration: the notify-me button, where it appears, and the signup form's copy, styling and inputs. ?locale= picks the language of the copy (omit it for the shop default).

**Note:** Only the text fields follow `?locale=`: a language with no translation of its own returns the shop default text, and `locale` in the response echoes the language asked for. Colors, positions, switches and SMS countries are the same in every language. `optin` holds the double opt-in confirmation email, used while [`GET /back_in_stock/settings/compliance`](https://docs.stoqapp.com/v2-reference/back-in-stock-settings/get-compliance-settings/) has `optin_required` on. `custom.javascript` is read-only: STOQ support sets it. Change fields with [`PATCH /back_in_stock/settings/widget`](https://docs.stoqapp.com/v2-reference/back-in-stock-settings/update-widget-settings/), sending only those to change.

## Query parameters

- `locale` (string): Language tag for the widget text, e.g. &quot;fr&quot; or &quot;pt-BR&quot;. Omit it for the shop's default language.

## 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` (null)
    - `collection` (null)
    - `collection_insertion` (string): e.g. `afterend`
    - `collection_container` (null)
    - `home` (null)
    - `home_container` (null)
    - `search` (null)
    - `search_container` (null)
    - `restock_note` (null)
    - `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 anys)
  - `inline` (object)
    - `enabled` (boolean): e.g. `false`
    - `selector` (null)
    - `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 1 point ([rate limits](https://docs.stoqapp.com/docs/rate-limits/)).

## Examples

### Get widget settings

```sh
curl "https://app.stoqapp.com/api/v2/external/back_in_stock/settings/widget" \
  -H "X-Auth-Token: $STOQ_API_KEY"
```

### Get widget settings filtered by locale

```sh
curl "https://app.stoqapp.com/api/v2/external/back_in_stock/settings/widget?locale=fr" \
  -H "X-Auth-Token: $STOQ_API_KEY"
```

## 200

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
    }
  ]
}
```

## 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
    }
  ]
}
```

