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
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, bulk operations, 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, bulk_notify), 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/bulk_notify |
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 |
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.
