Notify variant waitlists
API v2 is in public beta: endpoints and fields can change before general availability. See the changelog
/back_in_stock/signups/notify_variantsCosts 2 rate-limit points · Rate limits
Send back-in-stock notifications to everyone waiting on up to 10 variants, as the products table's Send notifications bulk action does.
Sends to pending signups only, on every channel, regardless of stock. A variant whose channel cannot send (plan limit, channel off, awaiting review, or a provider that cannot deliver) is skipped and its reason listed in errors; the others still send. 202 with one send per variant queued (its id is the job id for GET /back_in_stock/sending_history/:id) and providers per channel. 422 when nothing was queued.
Also searched asnotify these variantssend notifications for these variantsbulk send for variantsnotify waitlists for several productssend restock alerts for selected variants
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
shopify_variant_idsarray of stringsRequiredShopify variant gids whose pending signups to notify, up to 10.
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_productsreconciliationchannelnullOnly 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).
errorsarray of anysWhy a variant was skipped, one message each (plan limit, channel off, awaiting review, or a provider that cannot deliver). The other variants still send.
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.
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 -X POST "https://app.stoqapp.com/api/v2/external/back_in_stock/signups/notify_variants" \
-H "X-Auth-Token: $STOQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"shopify_variant_ids": [
"gid://shopify/ProductVariant/47284734423096",
"gid://shopify/ProductVariant/47284734455864"
]
}'const res = await fetch("https://app.stoqapp.com/api/v2/external/back_in_stock/signups/notify_variants", {
method: "POST",
headers: {
"X-Auth-Token": process.env.STOQ_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"shopify_variant_ids": [
"gid://shopify/ProductVariant/47284734423096",
"gid://shopify/ProductVariant/47284734455864"
]
}),
});
const data = await res.json();import os
import requests
res = requests.post(
"https://app.stoqapp.com/api/v2/external/back_in_stock/signups/notify_variants",
headers={"X-Auth-Token": os.environ["STOQ_API_KEY"]},
json={
"shopify_variant_ids": [
"gid://shopify/ProductVariant/47284734423096",
"gid://shopify/ProductVariant/47284734455864"
]
},
)
data = res.json()require "net/http"
require "json"
uri = URI("https://app.stoqapp.com/api/v2/external/back_in_stock/signups/notify_variants")
req = Net::HTTP::Post.new(uri, "X-Auth-Token" => ENV["STOQ_API_KEY"], "Content-Type" => "application/json")
req.body = {
shopify_variant_ids: [
"gid://shopify/ProductVariant/47284734423096",
"gid://shopify/ProductVariant/47284734455864"
]
}.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": null,
"status": "pending",
"limit": 42,
"signups_count": 42,
"sent_count": 0,
"created_at": "2026-06-25T14:02:11Z"
}
],
"providers": {
"email": "stoq",
"sms": "stoq"
},
"errors": []
}{
"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
}
]
}