Skip to content

Bulk 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

    Send to signups not notified yet (pending) or re-send to signups already notified. Default pending.

    One of pendingnotified
    Default "pending"
  • shopify_market_idsarray of strings

    Only signups from these Shopify markets, as gids.

  • without_ordersboolean, nullable

    When true, only notified signups that led to no order. Ignored for pending signups.

  • channelstring

    Send on this channel only. Default both.

    One of emailsms
  • limitinteger

    Send to at most this many matching signups. Default all of them.

  • shopify_product_idstring

    Only signups for this Shopify product, as a gid.

  • shopify_variant_idstring

    Only signups for this Shopify variant, as a gid.

  • customer_idstring

    Only signups of this customer, by STOQ customer id.

  • titlestring

    Only signups whose product title or SKU contains this text.

  • skustring

    Only signups whose product title or SKU contains this text.

  • fromstring

    First day, in the shop's time zone, of the signup date (pending) or notified date (notified).

  • tostring

    Last 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 objects

    One queued send per variant; follow each with GET /back_in_stock/sending_history/:id.

    Show 13 child attributesHide child attributes
    • idstring

      Send id; also the job id for GET /back_in_stock/sending_history/:id.

    • shopify_product_idstring

      Shopify product gid of the variant being notified.

    • shopify_variant_idstring

      Shopify variant gid whose waitlist this send works through.

    • product_titlestring

      Product title; null when the variant is not synced.

    • variant_titlestring

      Variant title; null for a product's only (default) variant or when the variant is not synced.

    • shopify_location_idnull

      Shopify location gid of the restock that started the send; null for manual sends.

    • sourcestring

      What 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 of webhookbulk_sendbulk_resendflow_actionevents_inventoryevents_productsreconciliation
    • channelstring, nullable

      Only signups on this channel (email or sms) are sent; null means every channel.

    • statusstring

      active is sending, waiting is paused between batches, completed is done.

      One of activewaitingcompleted
    • limitinteger

      Most signups this send notifies; null means the whole waitlist.

    • signups_countinteger

      Signups attached to this send so far.

    • sent_countinteger

      Notifications this send has created so far; with signups_count, its progress.

    • created_atstring

      When the send was queued (ISO 8601).

  • providersobject

    Who delivers each channel being sent, keyed by channel.

    Show 1 child attributeHide child attributes
    • emailstring

      Email sender: stoq for STOQ's own sender, else the integration (klaviyo, flow).

Errors

409
idempotency_key_in_progress

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

422
validation_failed

The 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.

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