Update widget

PATCH

/back_in_stock/settings/widget

curl --request PATCH \
  --url https://app.stoqapp.com/api/v2/external/back_in_stock/settings/widget \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: <X-Auth-Token>' \
  --data '{ "locale": "fr", "button": "string", "placement": "string", "form": "string", "optin": "string", "branding": "string", "custom": "string" }'

• Production

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 and custom.javascript run 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/JavaScript and the app proxy path change what every shopper sees; a wrong value can hide the widget. Channel enables (email/sms/push), optin_required and the merchant signup alert live on the other settings capabilities.

Authorizations

• ApiKeyAuth

Request Body^required

Media typeapplication/json

object

locale

button

placement

form

optin

branding

custom

Example

{
  "locale": "fr",
  "button": "string",
  "placement": "string",
  "form": "string",
  "optin": "string",
  "branding": "string",
  "custom": "string"
}

Responses

200

Success — the updated resource.

Media typeapplication/json

object

Example ^generated

{}

202

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

Media typeapplication/json

Returned for async/bulk work — poll the job until it reaches a terminal state.

object

job_id

string

status_url

string

Example

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

401

Missing or invalid X-Auth-Token.

Media typeapplication/json

Error envelope returned by every failed request.

object

errors

required

Array<string>

Example

{
  "errors": [
    "Unauthorized"
  ]
}

422

The request failed validation.

Media typeapplication/json

Error envelope returned by every failed request.

object

errors

required

Array<string>

Example

{
  "errors": [
    "name is required"
  ]
}

429

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

Media typeapplication/json

Error envelope returned by every failed request.

object

errors

required

Array<string>

Example

{
  "errors": [
    "Rate limit exceeded"
  ]
}