Bulk notify signups
API v2 is in public beta: endpoints and fields can change before general availability. See the changelog
/back_in_stock/signups/notifyCosts 2 rate-limit points · Rate limits
Send back-in-stock notifications to every signup matching the waitlist filters, or only the first N, as the dashboard's Send notifications and Re-send all buttons do.
status is pending (not notified yet) or notified; from/to are shop-local days matched against the signup date for pending and the notified date for notified. title and sku match the product title or SKU. without_orders keeps notified signups that led to no order. status pending sends to signups not notified yet; status notified re-sends to signups already notified, oldest notification first when limit is set. channel sends only email or only sms. Sends regardless of stock. 202 with one send per variant: its id is the job id for GET /back_in_stock/sending_history/:id. providers names who delivers each channel (stoq is STOQ's own sender). 422 when no signup matches, or a channel cannot send (plan limit, channel off, awaiting review, or a provider that cannot deliver), and nothing is queued.
Also searched asnotify the waitlistnotify everyone waitingsend notificationsbulk sendsend restock emails to the whole waitlistresend to everyone notifiedsend to the waitlist
Headers
Idempotency-KeystringA fresh unique key for every write (a new UUID, say); reuse it only to retry that write. Keys are remembered for 1 hour: the same key and the same request within that hour returns the first result, with
Idempotent-Replayed: true, without running again; the same key with a different method, path or body is refused (422idempotency_key_reused); a retry while the first is still running gets 409idempotency_key_in_progress. Keys are per store. Server errors and rate limits are not kept, so their retry runs.
Request body
statusstringSend to signups not notified yet (pending) or re-send to signups already notified. Default pending.
One ofpendingnotifiedDefault"pending"shopify_market_idsarray of stringsOnly signups from these Shopify markets, as gids.
without_ordersboolean, nullableWhen true, only notified signups that led to no order. Ignored for pending signups.
channelstringSend on this channel only. Default both.
One ofemailsmslimitintegerSend to at most this many matching signups. Default all of them.
shopify_product_idstringOnly signups for this Shopify product, as a gid.
shopify_variant_idstringOnly signups for this Shopify variant, as a gid.
customer_idstringOnly signups of this customer, by STOQ customer id.
titlestringOnly signups whose product title or SKU contains this text.
skustringOnly signups whose product title or SKU contains this text.
fromstringFirst day, in the shop's time zone, of the signup date (pending) or notified date (notified).
tostringLast day, in the shop's time zone, of the signup date (pending) or notified date (notified). Default today when from is given.
Returns
sendsarray of objectsOne queued send per variant; follow each with GET /back_in_stock/sending_history/:id.
Show 13 child attributesHide child attributes
idstringSend id; also the job id for GET /back_in_stock/sending_history/:id.
shopify_product_idstringShopify product gid of the variant being notified.
shopify_variant_idstringShopify variant gid whose waitlist this send works through.
product_titlestringProduct title; null when the variant is not synced.
variant_titlestringVariant title; null for a product's only (default) variant or when the variant is not synced.
shopify_location_idnullShopify location gid of the restock that started the send; null for manual sends.
sourcestringWhat started the send: bulk_send and bulk_resend are sends from the dashboard or API; webhook, events_inventory, events_products and reconciliation are detected restocks; flow_action is Shopify Flow.
One ofwebhookbulk_sendbulk_resendflow_actionevents_inventoryevents_productsreconciliationchannelstring, nullableOnly signups on this channel (email or sms) are sent; null means every channel.
statusstringactive is sending, waiting is paused between batches, completed is done.
One ofactivewaitingcompletedlimitintegerMost signups this send notifies; null means the whole waitlist.
signups_countintegerSignups attached to this send so far.
sent_countintegerNotifications this send has created so far; with signups_count, its progress.
created_atstringWhen the send was queued (ISO 8601).
providersobjectWho delivers each channel being sent, keyed by channel.
Show 1 child attributeHide child attributes
emailstringEmail sender: stoq for STOQ's own sender, else the integration (klaviyo, flow).
Errors
idempotency_key_in_progressAn earlier request with the same Idempotency-Key is still running. Wait, then resend the same request with the same key.
validation_failedThe action refused the request for a reason that is not a single bad field.
Any request can also fail with auth_invalid (401) or rate_limited (429).
Every error has the same shape: see Errors and the list of error codes.
curl -X POST "https://app.stoqapp.com/api/v2/external/back_in_stock/signups/notify" \
-H "X-Auth-Token: $STOQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"shopify_variant_id": "gid://shopify/ProductVariant/47284734423096",
"channel": "email"
}'const res = await fetch("https://app.stoqapp.com/api/v2/external/back_in_stock/signups/notify", {
method: "POST",
headers: {
"X-Auth-Token": process.env.STOQ_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"shopify_variant_id": "gid://shopify/ProductVariant/47284734423096",
"channel": "email"
}),
});
const data = await res.json();import os
import requests
res = requests.post(
"https://app.stoqapp.com/api/v2/external/back_in_stock/signups/notify",
headers={"X-Auth-Token": os.environ["STOQ_API_KEY"]},
json={
"shopify_variant_id": "gid://shopify/ProductVariant/47284734423096",
"channel": "email"
},
)
data = res.json()require "net/http"
require "json"
uri = URI("https://app.stoqapp.com/api/v2/external/back_in_stock/signups/notify")
req = Net::HTTP::Post.new(uri, "X-Auth-Token" => ENV["STOQ_API_KEY"], "Content-Type" => "application/json")
req.body = {
shopify_variant_id: "gid://shopify/ProductVariant/47284734423096",
channel: "email"
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body){
"sends": [
{
"id": "c3e8a1f4-7b2d-4e9a-8c51-0f6d2b9e7a13",
"shopify_product_id": "gid://shopify/Product/8784906035384",
"shopify_variant_id": "gid://shopify/ProductVariant/47284734423096",
"product_title": "Trail Shoe",
"variant_title": "Blue / Medium",
"shopify_location_id": null,
"source": "bulk_send",
"channel": "email",
"status": "pending",
"limit": 42,
"signups_count": 42,
"sent_count": 0,
"created_at": "2026-06-25T14:02:11Z"
}
],
"providers": {
"email": "stoq"
}
}{
"errors": [
"Invalid API key"
],
"code": "auth_invalid",
"details": [
{
"code": "auth_invalid",
"message": "Invalid API key",
"path": null,
"value": null,
"expected": null
}
]
}{
"errors": [
"A request with this Idempotency-Key is still running"
],
"code": "idempotency_key_in_progress",
"details": [
{
"code": "idempotency_key_in_progress",
"message": "A request with this Idempotency-Key is still running",
"path": null,
"value": null,
"expected": null
}
]
}{
"errors": [
"name is required"
],
"code": "validation_failed",
"details": [
{
"code": "validation_failed",
"message": "name is required",
"path": null,
"value": null,
"expected": null
}
]
}{
"errors": [
"Rate limit exceeded"
],
"code": "rate_limited",
"details": [
{
"code": "rate_limited",
"message": "Rate limit exceeded",
"path": null,
"value": null,
"expected": null
}
]
}limit caps the send at the first 20 matching signups; the rest stay on the waitlist.
curl -X POST "https://app.stoqapp.com/api/v2/external/back_in_stock/signups/notify" \
-H "X-Auth-Token: $STOQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"shopify_variant_id": "gid://shopify/ProductVariant/47284734423096",
"channel": "sms",
"limit": 20
}'const res = await fetch("https://app.stoqapp.com/api/v2/external/back_in_stock/signups/notify", {
method: "POST",
headers: {
"X-Auth-Token": process.env.STOQ_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"shopify_variant_id": "gid://shopify/ProductVariant/47284734423096",
"channel": "sms",
"limit": 20
}),
});
const data = await res.json();import os
import requests
res = requests.post(
"https://app.stoqapp.com/api/v2/external/back_in_stock/signups/notify",
headers={"X-Auth-Token": os.environ["STOQ_API_KEY"]},
json={
"shopify_variant_id": "gid://shopify/ProductVariant/47284734423096",
"channel": "sms",
"limit": 20
},
)
data = res.json()require "net/http"
require "json"
uri = URI("https://app.stoqapp.com/api/v2/external/back_in_stock/signups/notify")
req = Net::HTTP::Post.new(uri, "X-Auth-Token" => ENV["STOQ_API_KEY"], "Content-Type" => "application/json")
req.body = {
shopify_variant_id: "gid://shopify/ProductVariant/47284734423096",
channel: "sms",
limit: 20
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body){
"sends": [
{
"id": "7d2f9b4e-1a6c-4e83-b5d0-2c8a6f1e9b37",
"shopify_product_id": "gid://shopify/Product/8784906035384",
"shopify_variant_id": "gid://shopify/ProductVariant/47284734423096",
"product_title": "Trail Shoe",
"variant_title": "Blue / Medium",
"shopify_location_id": null,
"source": "bulk_send",
"channel": "sms",
"status": "pending",
"limit": 20,
"signups_count": 20,
"sent_count": 0,
"created_at": "2026-06-25T14:05:47Z"
}
],
"providers": {
"sms": "stoq"
}
}{
"errors": [
"Invalid API key"
],
"code": "auth_invalid",
"details": [
{
"code": "auth_invalid",
"message": "Invalid API key",
"path": null,
"value": null,
"expected": null
}
]
}{
"errors": [
"A request with this Idempotency-Key is still running"
],
"code": "idempotency_key_in_progress",
"details": [
{
"code": "idempotency_key_in_progress",
"message": "A request with this Idempotency-Key is still running",
"path": null,
"value": null,
"expected": null
}
]
}{
"errors": [
"name is required"
],
"code": "validation_failed",
"details": [
{
"code": "validation_failed",
"message": "name is required",
"path": null,
"value": null,
"expected": null
}
]
}{
"errors": [
"Rate limit exceeded"
],
"code": "rate_limited",
"details": [
{
"code": "rate_limited",
"message": "Rate limit exceeded",
"path": null,
"value": null,
"expected": null
}
]
}status: notified with without_orders re-sends to shoppers who were notified but haven't bought.
curl -X POST "https://app.stoqapp.com/api/v2/external/back_in_stock/signups/notify" \
-H "X-Auth-Token: $STOQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"shopify_variant_id": "gid://shopify/ProductVariant/47284734423096",
"status": "notified",
"without_orders": true,
"channel": "email"
}'const res = await fetch("https://app.stoqapp.com/api/v2/external/back_in_stock/signups/notify", {
method: "POST",
headers: {
"X-Auth-Token": process.env.STOQ_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"shopify_variant_id": "gid://shopify/ProductVariant/47284734423096",
"status": "notified",
"without_orders": true,
"channel": "email"
}),
});
const data = await res.json();import os
import requests
res = requests.post(
"https://app.stoqapp.com/api/v2/external/back_in_stock/signups/notify",
headers={"X-Auth-Token": os.environ["STOQ_API_KEY"]},
json={
"shopify_variant_id": "gid://shopify/ProductVariant/47284734423096",
"status": "notified",
"without_orders": True,
"channel": "email"
},
)
data = res.json()require "net/http"
require "json"
uri = URI("https://app.stoqapp.com/api/v2/external/back_in_stock/signups/notify")
req = Net::HTTP::Post.new(uri, "X-Auth-Token" => ENV["STOQ_API_KEY"], "Content-Type" => "application/json")
req.body = {
shopify_variant_id: "gid://shopify/ProductVariant/47284734423096",
status: "notified",
without_orders: true,
channel: "email"
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body){
"sends": [
{
"id": "e5a1c7d3-9b2f-4d60-8a4e-6f3b1d9c2e05",
"shopify_product_id": "gid://shopify/Product/8784906035384",
"shopify_variant_id": "gid://shopify/ProductVariant/47284734423096",
"product_title": "Trail Shoe",
"variant_title": "Blue / Medium",
"shopify_location_id": null,
"source": "bulk_send",
"channel": "email",
"status": "pending",
"limit": 15,
"signups_count": 15,
"sent_count": 0,
"created_at": "2026-06-26T09:30:02Z"
}
],
"providers": {
"email": "stoq"
}
}{
"errors": [
"Invalid API key"
],
"code": "auth_invalid",
"details": [
{
"code": "auth_invalid",
"message": "Invalid API key",
"path": null,
"value": null,
"expected": null
}
]
}{
"errors": [
"A request with this Idempotency-Key is still running"
],
"code": "idempotency_key_in_progress",
"details": [
{
"code": "idempotency_key_in_progress",
"message": "A request with this Idempotency-Key is still running",
"path": null,
"value": null,
"expected": null
}
]
}{
"errors": [
"name is required"
],
"code": "validation_failed",
"details": [
{
"code": "validation_failed",
"message": "name is required",
"path": null,
"value": null,
"expected": null
}
]
}{
"errors": [
"Rate limit exceeded"
],
"code": "rate_limited",
"details": [
{
"code": "rate_limited",
"message": "Rate limit exceeded",
"path": null,
"value": null,
"expected": null
}
]
}