Settings

Back-in-stock settings are a shop-level singleton — there is no :id in any path. The surface is split into five capabilities, and everything is GET + PATCH; there are no named actions (no setting here has side effects beyond writing configuration, so the granularity convention means no enable_x/set_y endpoints).

These settings configure the signup form and emails the STOQ app already provides on your storefront. There is nothing to build. To read who signed up, use Signups.

Path prefix: /back_in_stock/settings, under the base URL https://app.stoqapp.com/api/v2/external.

Endpoints

Method	Path	Capability
GET	/back_in_stock/settings	All five blocks in one response
PATCH	/back_in_stock/settings	Any combination of capability blobs
GET / PATCH	/back_in_stock/settings/channels	Which channels send (email, SMS)
GET / PATCH	/back_in_stock/settings/delivery	Batching, stock threshold, locations, any-variant
GET / PATCH	/back_in_stock/settings/compliance	GDPR double opt-in
GET / PATCH	/back_in_stock/settings/tagging	Order tag on recovered orders
GET / PATCH	/back_in_stock/settings/alerts	Merchant alerts + scheduled report emails

PATCH semantics

Every PATCH is deep partial — send only the keys you want to change, nested however deep. The top-level PATCH /back_in_stock/settings accepts any combination of capability blobs and delegates each to the capability’s own update; validation errors from all blobs are accumulated into one response.

curl -X PATCH 'https://app.stoqapp.com/api/v2/external/back_in_stock/settings' \
  -H "X-Auth-Token: $STOQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channels":{"sms":{"enabled":true}},"compliance":{"optin_required":true}}'

Each capability PATCH returns the capability’s full block after the write; the top-level PATCH returns all five.

Channels

Which notification channels are enabled.

{
  "email": { "enabled": true },
  "sms": { "enabled": false }
}

Turning automatic back-in-stock alerts on or off is PATCH /back_in_stock/notification_settings/restock_alert with {"enabled": false}, not a channel.

PATCH — “enable SMS”:

{ "sms": { "enabled": true } }

Enabling SMS for the first time triggers a restricted-content verification check — sends may be held until the shop is verified.

Delivery

How and when notifications go out. Four sub-concerns, plus the password-protected storefront switch:

{
  "batching": {
    "enabled": false,
    "mode": "multiplier",
    "multiplier": 3,
    "batch_size": 100,
    "wait_hours": 24
  },
  "stock_threshold": 1,
  "locations": { "filter_enabled": false, "shopify_location_ids": [] },
  "any_variant": { "enabled": false, "product_ids": [] },
  "send_while_password_protected": false
}

Field	Notes
batching.enabled	Send in batches instead of all at once
batching.mode	multiplier — batch size = restocked quantity × multiplier; fixed — batch size = batch_size
batching.wait_hours	Wait between batches
stock_threshold	Minimum restocked quantity before notifications send at all (≥ 1)
locations.filter_enabled	Only count inventory at the listed locations
locations.shopify_location_ids	Shopify location gids (gid://shopify/Location/<id>) — replaced wholesale when present. Anything else is 422
any_variant.enabled	Notify signups when any variant of the product restocks
any_variant.product_ids	Products the any-variant behavior applies to — replaced wholesale when present
send_while_password_protected	false (default): no back-in-stock alerts go out while the storefront password is on, and signups wait for the next restock. true: send anyway

PATCH — “batch notifications” (fixed batches of 100, 24h apart):

{ "batching": { "enabled": true, "mode": "fixed", "batch_size": 100, "wait_hours": 24 } }

Compliance

GDPR double opt-in. When enabled, signups must confirm via email before they are eligible for notifications.

{ "optin_required": false }

PATCH — “require double opt-in”:

{ "optin_required": true }

The per-signup confirmation state surfaces on the signup’s optin block.

Tagging

The tag applied to Shopify orders attributed to a back-in-stock notification.

{
  "order_tags": { "enabled": false, "tag": "STOQ-back-in-stock" }
}

PATCH — “tag recovered orders”:

{ "order_tags": { "enabled": true, "tag": "restock-recovered" } }

tag is a single tag (default STOQ-back-in-stock).

Alerts

Merchant-facing alerting and scheduled report emails. Two sub-concerns:

{
  "signups_threshold": { "count": 10, "notify": true },
  "scheduled_reports": { "daily": false, "weekly": true, "monthly": false }
}

Field	Notes
signups_threshold.count	Per-variant pending-signup count that triggers the merchant alert email
signups_threshold.notify	Whether the threshold alert sends at all
scheduled_reports.daily / weekly / monthly	Summary report emails on each cadence

PATCH — weekly report on, threshold alert at 25 signups:

{ "signups_threshold": { "count": 25, "notify": true }, "scheduled_reports": { "weekly": true } }

Full settings shape

GET /back_in_stock/settings returns all five blocks under their capability keys:

{
  "channels": { "email": { "enabled": true }, "sms": { "enabled": false } },
  "delivery": {
    "batching": { "enabled": false, "mode": "multiplier", "multiplier": 3, "batch_size": 100, "wait_hours": 24 },
    "stock_threshold": 1,
    "locations": { "filter_enabled": false, "shopify_location_ids": [] },
    "any_variant": { "enabled": false, "product_ids": [] },
    "send_while_password_protected": false
  },
  "compliance": { "optin_required": false },
  "tagging": { "order_tags": { "enabled": false, "tag": "STOQ-back-in-stock" } },
  "alerts": {
    "signups_threshold": { "count": 10, "notify": true },
    "scheduled_reports": { "daily": false, "weekly": false, "monthly": false }
  }
}

Languages

The signup widget’s text and the alert email and SMS templates are stored per language. Every read and write of them takes an optional locale (fr, de, pt-BR): in the query string on GET, in the body on PATCH. Omit it for the shop’s default language. A write in another language changes only that language. Colours, toggles and other untranslated fields ignore locale. A value that is not a language tag returns 422 naming locale (keyed widget.locale inside a widget PATCH).

Method	Path	locale
GET	/back_in_stock/settings	?locale=fr
GET	/back_in_stock/settings/widget	?locale=fr
PATCH	/back_in_stock/settings (with a widget block)	{"locale": "fr", ...}
PATCH	/back_in_stock/settings/widget	{"locale": "fr", ...}
GET	/back_in_stock/templates/{key}	?locale=fr
PATCH	/back_in_stock/templates/{key}	{"locale": "fr", ...}

key is signup_thank_you, restock_alert or reminder. A template response names its language in locale. The language is never part of the path.

curl 'https://app.stoqapp.com/api/v2/external/back_in_stock/templates/restock_alert?locale=fr' \
  -H "X-Auth-Token: $STOQ_API_KEY"

Notification templates and notification settings

The three back-in-stock notifications are addressed by name, in send order: signup_thank_you, restock_alert, reminder, the names the dashboard’s Notifications card uses. The same key addresses a notification’s copy (templates) and whether and when it sends (notification_settings).

Method	Path	What
GET	/back_in_stock/templates	All three templates
GET / PATCH	/back_in_stock/templates/{key}	One notification’s email and SMS copy
POST	/back_in_stock/templates/{key}/send_test	Send it to yourself
POST	/back_in_stock/templates/{key}/verify_flow	Check its Klaviyo or Postscript flow ({"channel": "email" | "sms"})
GET	/back_in_stock/templates/{key}/translations	Its translations, keyed by the same paths
GET	/back_in_stock/notification_settings	Each notification’s on/off, and the reminder’s timing
GET / PATCH	/back_in_stock/notification_settings/{key}	enabled; after_n_days on reminder only

A template has email{} and sms{}, the same shape as the preorder confirmation notification:

{
  "key": "restock_alert",
  "locale": "en",
  "email": {
    "subject": "It's back!", "preheader": "", "heading": "Good news", "body": "...", "footer": "...",
    "button": { "text": "Buy now", "destination": "checkout", "background_color": "#202223", "text_color": "#FFFFFF", "radius": 4 },
    "colors": { "background": "#FFFFFF", "section": "#FFFFFF", "text": "#202223" },
    "radius": 8, "css": "",
    "html": { "enabled": false, "template": "" },
    "reviews": { "enabled": false, "count": 3, "min_rating": 4, "title": "What customers are saying" },
    "social": { "facebook": "", "instagram": "", "pinterest": "", "twitter": "", "tiktok": "", "whatsapp": "", "youtube": "", "icon_color": "#000000" },
    "unsubscribe_text": "Unsubscribe", "consent_text": "", "klaviyo_flow_name": "", "klaviyo_flow_verified": false
  },
  "sms": { "body": "{{product.title}} is back: {{link}}", "link_destination": "checkout", "klaviyo_flow_name": "", "klaviyo_flow_verified": false, "postscript_flow_verified": false }
}

signup_thank_you has no email.button.destination or sms.link_destination. Templates hold copy only. Turning a notification on or off, and the reminder’s wait, is PATCH /back_in_stock/notification_settings/{key}:

curl -X PATCH https://app.stoqapp.com/api/v2/external/back_in_stock/notification_settings/restock_alert \
  -H "X-Auth-Token: $STOQ_API_KEY" -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

enabled: false on restock_alert stops automatic back-in-stock alerts, like the dashboard’s “Send automatic notification” switch.

Verify a Klaviyo or Postscript flow

When a notification goes out through Klaviyo or Postscript, STOQ only hands it over once the flow is verified. Until then, STOQ sends it itself. verify_flow runs the same check as the template page’s Verify flow button:

curl -X POST https://app.stoqapp.com/api/v2/external/back_in_stock/templates/restock_alert/verify_flow \
  -H "X-Auth-Token: $STOQ_API_KEY" -H "Content-Type: application/json" \
  -d '{ "channel": "email" }'

{ "key": "restock_alert", "channel": "email", "provider": "klaviyo", "flow_verified": false, "reason": "Flow verification failed: Flow not found" }

Klaviyo is checked for a flow named by the template’s email.klaviyo_flow_name or sms.klaviyo_flow_name. Postscript has no flows API, so for Postscript this call records your confirmation that the flow exists. The result shows on the template as email.klaviyo_flow_verified, sms.klaviyo_flow_verified and sms.postscript_flow_verified. These flags are read-only. You get a 422 when that channel’s provider is not Klaviyo or Postscript, or is not connected. Sender-level checks (the DKIM domain check, and whether STOQ allows the shop to send email or SMS) are on /account/sending.