Back in stock API for developers
STOQ has an API you can use to build custom back in stock integrations, for example reading waitlist signups into your own systems or triggering restock notifications from code you write. This article covers where to find your API key and what the API is for. For the full endpoint reference, see the developer docs linked below.
Use this guide if you or a developer are integrating STOQ's back in stock data with your own tools or scripts, beyond what the dashboard already does.
Before you begin
| Requirement | Detail |
|---|---|
| API key | Generated automatically per shop. Find it on the Integrations page, see Set it up below. |
| Developer resources | The API is for developers comfortable making authenticated HTTP requests. If you just need to move a one-time list of waiting customers into STOQ, use Import your waitlist instead, no code required. |
What the API is for
The same STOQ API key gives you programmatic access to your shop's back in stock signups: list and filter them, read a single signup, trigger or bulk-trigger a restock notification, transfer signups between variants, delete signups, and pull aggregated demand counts per variant. It's the same API used for preorder integrations, so if you're already calling STOQ's preorder API, you're using the same key.
Signup endpoints live in the API v1 reference, where each one lists its parameters, response schema, and a Test it button you can call with your own key. Start at the developer docs home to pick an integration path, and check Rate Limits before building anything that polls or bulk-loads.
Which tool should you use?
| You're building | Use |
|---|---|
| A headless or Hydrogen storefront | The JavaScript SDK, which authenticates with your shop's public Storefront API token so your secret key never reaches browser code |
| Customization on a themed store running the app embed | The on-page JavaScript API and custom events, no SDK needed |
| A server or backend integration | This REST API, referenced at API v1 |
| An AI agent | The MCP server, which exposes every v2 action as a tool |
Never put your API key in browser or client-side code. The one exception is creating a signup, which uses the shop domain header instead of a key. For storefront work, use the SDK or the on-page JavaScript API.
Set it up
Open the Integrations page
- In the left menu bar of the STOQ app, click Back in stock alerts.
- Click the Settings tab.
- Open the Integrations sub-tab, then open the full Integrations page.
Open the API card
Scroll to the API card and open it. Your key is shown in the API Key field under Access key (shown as a password field).
Copy the key
Click Copy to copy the key to your clipboard. Keep this key secure, it grants full access to your shop's STOQ data. See API Key in the developer docs.
Reset the key if needed
If you suspect the key has been exposed, click Reset. This generates a new key and invalidates the current one, so any integrations using the old key, including preorder integrations, will need to be updated.
Check your setup
Send a request to the endpoint you're integrating with, using your key in the X-Auth-Token header. A successful response confirms your key and header are set up correctly; a 401 response means the header name, key, or format is wrong.
Troubleshooting
- If you get a
401 Unauthorizedresponse: check that you're sending theX-Auth-Tokenheader with a valid key. Reset and re-copy the key from the Integrations page if you're not sure it's current. - If your integration stopped working after a key reset: any integration using the old key stops immediately, including preorder integrations built on the same key. Update it with the new key from the Integrations page.
FAQ
Is the back in stock API key different from the preorder API key?
No. STOQ generates one API key per shop, and it authenticates both the back in stock and preorder APIs. Resetting it from either the back in stock or preorder Integrations page invalidates it everywhere.
Where do I find the full list of endpoints?
In the API v1 reference for the signup endpoints, or the developer docs home for everything else: the v2 API, the MCP server, and the storefront SDK.
Does calling the API notify customers automatically?
Only when you call a notify action, like triggering a single or bulk notification for pending signups. Reading signup or demand data doesn't send anything to customers.
Does resetting my API key affect alerts already scheduled to send?
No. Resetting the key only breaks custom integrations built on the old key. Restock alerts sent through STOQ's built-in delivery settings keep working normally.
Do I need to write code to move my existing waitlist into STOQ?
No. For a one-time move from another app, use Import your waitlist to upload a CSV instead. The API is for ongoing, custom integrations.
Related guides
Import your waitlist from another app
Move an existing waitlist into STOQ with a CSV, no code required.
Set up alerts
Turn on the Notify me widget and place your first test signup.
Channels and notifications
Choose how customers sign up and how they're alerted, from the dashboard.
Preorder API for developers
The same API key's full endpoint reference, including back in stock signup endpoints.
