---
title: "Update widget"
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/
api: "API v2 reference"
method: PATCH
path: "/back_in_stock/settings/widget"
---

# Update widget

`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 "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.

**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): e.g. `fr`
- `button` (string): e.g. `string`
- `placement` (string): e.g. `string`
- `form` (string): e.g. `string`
- `optin` (string): e.g. `string`
- `branding` (string): e.g. `string`
- `custom` (string): e.g. `string`

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 '{
    "locale": "fr",
    "button": "string",
    "placement": "string",
    "form": "string",
    "optin": "string",
    "branding": "string",
    "custom": "string"
  }'
```

## 200

Success: the updated resource.

## 202

Accepted: async/bulk work was queued. Poll the returned job.

```json
{
  "job_id": "job_a1b2c3",
  "status_url": "/api/v2/external/jobs/job_a1b2c3"
}
```

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