Skip to content

Notify variant waitlists

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

POST/back_in_stock/signups/notify_variants

Costs 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-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

  • shopify_variant_idsarray of stringsRequired

    Shopify variant gids whose pending signups to notify, up to 10.

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
    • channelnull

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

  • errorsarray of anys

    Why 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

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
invalid_params

One or more fields failed the action's schema.

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_variants
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"
    ]
  }'
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": null,
      "status": "pending",
      "limit": 42,
      "signups_count": 42,
      "sent_count": 0,
      "created_at": "2026-06-25T14:02:11Z"
    }
  ],
  "providers": {
    "email": "stoq",
    "sms": "stoq"
  },
  "errors": []
}