Notify signups

API v2 is in public beta: endpoints and fields can change before general availability. See the changelog

POST/back_in_stock/signups/notify

Costs 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-Keystring
A 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 (422 idempotency_key_reused); a retry while the first is still running gets 409 idempotency_key_in_progress. Keys are per store. Server errors and rate limits are not kept, so their retry runs.

Request body

statusstring
One of pendingnotified
shopify_market_idsarray of strings
channelstring
Example: email
One of emailsms
limitinteger
shopify_product_idany
shopify_variant_idstring
Example: gid://shopify/ProductVariant/47284734423096
customer_idany
titleany
skuany
without_ordersany
fromany
toany

Returns

sendsarray of objects
Show 13 child attributesHide child attributes
- idstring
  Example: c3e8a1f4-7b2d-4e9a-8c51-0f6d2b9e7a13
- shopify_product_idstring
  Example: gid://shopify/Product/8784906035384
- shopify_variant_idstring
  Example: gid://shopify/ProductVariant/47284734423096
- product_titlestring
  Example: Trail Shoe
- variant_titlestring
  Example: Blue / Medium
- shopify_location_idany
- sourcestring
  Example: bulk_send
- channelstring
  Example: email
- statusstring
  Example: pending
- limitinteger
  Example: 42
- signups_countinteger
  Example: 42
- sent_countinteger
  Example: 0
- created_atstring
  Example: 2026-06-25T14:02:11Z
providersobject
Show 1 child attributeHide child attributes
- emailstring
  Example: stoq

Errors

401

Missing or invalid X-Auth-Token.

409

An earlier request with the same Idempotency-Key is still running. Wait, then resend the same request with the same key.

422

The request failed validation.

429

Rate limited: cost-weighted per token (read 1, write 2; 360 points / 60s). Check Retry-After.

Every error has the same shape: see Errors.

POST/back_in_stock/signups/notify

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)

Response

{
  "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"
  }
}

{
  "job_id": "job_a1b2c3",
  "status_url": "/api/v2/external/jobs/job_a1b2c3"
}

{
  "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
    }
  ]
}