Overview

The back-in-stock API covers everything around restock alerts: who is waiting, what was sent, how sends behave, and how it all performed.

Path prefix: /back_in_stock, under the v2 base URL https://app.stoqapp.com/api/v2/external. For example, the waitlist is https://app.stoqapp.com/api/v2/external/back_in_stock/signups; leaving out /external returns an HTML 404.

The signup form is already provided

You do not build a signup form. The STOQ app already puts a Notify me when available button and signup form on your product pages. The theme app extension renders them, and customers sign up through them with no API call from you.

What you can do over the API:

• Configure the form and the emails: the widget text and colours, which channels send, and the alert, reminder and thank-you emails are all settings. Start with GET /back_in_stock/settings and GET /back_in_stock/settings/widget.
• Read who has signed up: GET /back_in_stock/signups. See Signups.
• Add a signup yourself: POST /back_in_stock/signups is for admin-side creation, such as importing a list. It is not how shoppers sign up, and it is not a form to put on a storefront.

Vocabulary

Term	Meaning
Signup	One customer waiting on one variant over one channel — a waitlist entry. v1 called this an intent.
Notification	One delivery attempt of a back-in-stock alert (including sends blocked by plan limits).
Settings	The shop-level configuration that governs sends — a singleton, not a list.

The four resources

Resource	Path	What it covers
Signups	/back_in_stock/signups	The waitlist: list/read/create/delete, notify now, notify the waitlist or variants, bulk delete, transfer between variants
Notifications	/back_in_stock/notifications	Read-only send log — one entry per delivery attempt
Settings	/back_in_stock/settings	Shop-level singleton with five capabilities: channels, delivery, compliance, tagging, alerts
Reports	/back_in_stock/reports	Five reports, each readable as JSON and exportable as CSV

Authentication

Identical to the rest of v2 — the X-Auth-Token header carrying the shop’s API key. See Getting Started.

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

Granularity convention

The back-in-stock surface follows the rule learned from the preorders prune: named actions exist only where there are side effects beyond writing settings — sending notifications (notify, notify_variants), destroying rows (bulk_delete), moving signups between variants (transfer), creating customers (create).

Plain settings — including every boolean toggle — are PATCH on the owning capability. There are no enable_sms or set_batch_size named actions; you send PATCH /back_in_stock/settings/channels with { "sms": { "enabled": true } }.

v1 → v2 parity

v1 endpoint	v2
GET /api/v1/external/intents	GET /back_in_stock/signups
GET /api/v1/external/intents/:id	GET /back_in_stock/signups/:id
POST /api/v1/external/intents	POST /back_in_stock/signups
POST …/notify_intent	POST /back_in_stock/signups/:id/notify
POST …/bulk_notify_intent	POST /back_in_stock/signups/notify_variants (up to 10 variants) or POST /back_in_stock/signups/notify (every signup matching the waitlist filters)
DELETE …/bulk_destroy	POST /back_in_stock/signups/bulk_delete
POST …/transfer_signups	POST /back_in_stock/signups/transfer
GET …/products_in_demand	GET /back_in_stock/reports/products_in_demand

Note

v1 stays generally available through the deprecation window — nothing breaks the day you start using v2. Migrate at your own pace; the parity table above maps every v1 call to its v2 home.

MCP

Every back-in-stock action is also exposed as an MCP tool, generated from the same registry that powers /help — same names, same schemas, same behavior. See MCP.