Check a variant's waitlist
API v2 is in public beta: endpoints and fields can change before general availability. See the changelog
/back_in_stock/signups/notification_statusCosts 1 rate-limit point · Rate limits
Notification/waitlist status for one product variant: pending signups (count_by as on the dashboard), total alerts sent, the 5 most recent send batches (each with what triggered it), and the shop's delivery settings -- the usual reason a restock produced no send yet.
Use it when shoppers say they weren't alerted after a restock: delivery.alerts_enabled false, a restock smaller than minimum_restock_quantity, or batching explain most gaps. shopify_variant_id must be a gid (a bare number gives 422 validation_failed); an unknown or deleted variant gives 404 not_found. count_by defaults to customers when both email and SMS are on, else signups. recent_sends holds at most 5 batches; recent_sends_note appears when there are more. To send now, use POST /back_in_stock/signups/notify.
Also searched asnotification statusrestock alert statushas this been notifiedwaitlist status for a variant
Query parameters
shopify_variant_idstringRequiredShopify variant gid to report on.
count_bystringCount pending shoppers once per customer or once per signup. Default is the shop's dashboard setting.
One ofcustomerssignups
Returns
product_titlestringProduct title of the variant.
variant_titlestringVariant title; null for a product's only (default) variant.
count_bystringHow pending_signups counts: customers counts a shopper on email and SMS once, signups counts each channel.
One ofcustomerssignupspending_signupsintegerCustomers or signups (see count_by) still waiting on this variant.
last_sent_atstringWhen the latest send batch went out. Absent when nothing was ever sent.
total_notifications_sentintegerNotifications sent for this variant, all time and all channels.
total_send_batchesintegerDistinct send batches for this variant, all time.
blocked_by_plan_limitintegerNotifications for this variant held back by the plan's notification limit.
recent_sendsarray of objectsThe 5 most recent send batches, newest first; recent_sends_note says when there are more.
Show 3 child attributesHide child attributes
sent_atstringWhen the batch went out.
countintegerNotifications in the batch.
triggered_byobjectThe restock or bulk send behind the batch. Absent for single sends.
Show 6 child attributesHide child attributes
restock_detected_atstringWhen the send was created: the restock was detected or the bulk send was started.
sourcestringWhat started the send: bulk_send and bulk_resend are manual; webhook, events_inventory, events_products and reconciliation are detected restocks; flow_action is Shopify Flow.
One ofwebhookbulk_sendbulk_resendflow_actionevents_inventoryevents_productsreconciliationstatusstringactive is sending, waiting is paused between batches, completed is done.
One ofactivewaitingcompletedsignups_at_triggerintegerSignups attached to that send.
sent_in_batchesbooleanWhether that send notified the waitlist in batches.
batch_limitintegerMost signups that send notifies; null means the whole waitlist.
deliveryobjectThe shop's delivery settings, the usual reason a restock has not sent yet. Absent when the shop has no settings.
Show 5 child attributesHide child attributes
batchingobjectHow a restock notifies the waitlist in batches.
Show 5 child attributesHide child attributes
enabledbooleanWhether the waitlist is notified in batches instead of all at once.
modestringmultiplier sends restocked quantity times multiplier per batch; fixed sends fixed_batch_size per batch.
One ofmultiplierfixedmultiplierintegerSignups notified per restocked unit, used while mode is multiplier.
fixed_batch_sizeintegerSignups notified per batch, used while mode is fixed.
wait_hoursintegerHours to wait between batches.
minimum_restock_quantityintegerMinimum restocked quantity before an automatic alert sends.
location_filter_enabledbooleanWhether only stock at the chosen locations counts as a restock.
any_variant_alerts_enabledbooleanWhether a restock of any variant of a product notifies everyone waiting on that product.
alerts_enabledbooleanWhether automatic back-in-stock alerts are on. False means restocks send nothing.
Errors
not_foundThe path is valid but nothing with that id exists in this store.
invalid_paramsOne or more fields failed the action's schema.
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 "https://app.stoqapp.com/api/v2/external/back_in_stock/signups/notification_status?shopify_variant_id=45000000001" \
-H "X-Auth-Token: $STOQ_API_KEY"const res = await fetch("https://app.stoqapp.com/api/v2/external/back_in_stock/signups/notification_status?shopify_variant_id=45000000001", {
headers: {
"X-Auth-Token": process.env.STOQ_API_KEY,
},
});
const data = await res.json();import os
import requests
res = requests.get(
"https://app.stoqapp.com/api/v2/external/back_in_stock/signups/notification_status?shopify_variant_id=45000000001",
headers={"X-Auth-Token": os.environ["STOQ_API_KEY"]},
)
data = res.json()require "net/http"
require "json"
uri = URI("https://app.stoqapp.com/api/v2/external/back_in_stock/signups/notification_status?shopify_variant_id=45000000001")
req = Net::HTTP::Get.new(uri, "X-Auth-Token" => ENV["STOQ_API_KEY"])
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)curl "https://app.stoqapp.com/api/v2/external/back_in_stock/signups/notification_status?shopify_variant_id=45000000001&count_by=customers" \
-H "X-Auth-Token: $STOQ_API_KEY"const res = await fetch("https://app.stoqapp.com/api/v2/external/back_in_stock/signups/notification_status?shopify_variant_id=45000000001&count_by=customers", {
headers: {
"X-Auth-Token": process.env.STOQ_API_KEY,
},
});
const data = await res.json();import os
import requests
res = requests.get(
"https://app.stoqapp.com/api/v2/external/back_in_stock/signups/notification_status?shopify_variant_id=45000000001&count_by=customers",
headers={"X-Auth-Token": os.environ["STOQ_API_KEY"]},
)
data = res.json()require "net/http"
require "json"
uri = URI("https://app.stoqapp.com/api/v2/external/back_in_stock/signups/notification_status?shopify_variant_id=45000000001&count_by=customers")
req = Net::HTTP::Get.new(uri, "X-Auth-Token" => ENV["STOQ_API_KEY"])
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body){
"product_title": "Trail Shoe",
"variant_title": "Blue / Medium",
"count_by": "signups",
"pending_signups": 22,
"last_sent_at": "2026-06-25T15:02:11.000Z",
"total_notifications_sent": 40,
"total_send_batches": 2,
"blocked_by_plan_limit": 0,
"recent_sends": [
{
"sent_at": "2026-06-25T15:02:11.000Z",
"count": 20,
"triggered_by": {
"restock_detected_at": "2026-06-25T14:02:11.000Z",
"source": "webhook",
"status": "waiting",
"signups_at_trigger": 42,
"sent_in_batches": true,
"batch_limit": 42
}
},
{
"sent_at": "2026-06-25T14:02:11.000Z",
"count": 20,
"triggered_by": {
"restock_detected_at": "2026-06-25T14:02:11.000Z",
"source": "webhook",
"status": "waiting",
"signups_at_trigger": 42,
"sent_in_batches": true,
"batch_limit": 42
}
}
],
"delivery": {
"batching": {
"enabled": true,
"mode": "fixed",
"multiplier": 100,
"fixed_batch_size": 20,
"wait_hours": 1
},
"minimum_restock_quantity": 1,
"location_filter_enabled": false,
"any_variant_alerts_enabled": false,
"alerts_enabled": true
}
}{
"errors": [
"Invalid API key"
],
"code": "auth_invalid",
"details": [
{
"code": "auth_invalid",
"message": "Invalid API key",
"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
}
]
}