Skip to content

Check a variant's waitlist

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

GET/back_in_stock/signups/notification_status

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

    Shopify variant gid to report on.

  • count_bystring

    Count pending shoppers once per customer or once per signup. Default is the shop's dashboard setting.

    One of customerssignups

Returns

  • product_titlestring

    Product title of the variant.

  • variant_titlestring

    Variant title; null for a product's only (default) variant.

  • count_bystring

    How pending_signups counts: customers counts a shopper on email and SMS once, signups counts each channel.

    One of customerssignups
  • pending_signupsinteger

    Customers or signups (see count_by) still waiting on this variant.

  • last_sent_atstring

    When the latest send batch went out. Absent when nothing was ever sent.

  • total_notifications_sentinteger

    Notifications sent for this variant, all time and all channels.

  • total_send_batchesinteger

    Distinct send batches for this variant, all time.

  • blocked_by_plan_limitinteger

    Notifications for this variant held back by the plan's notification limit.

  • recent_sendsarray of objects

    The 5 most recent send batches, newest first; recent_sends_note says when there are more.

    Show 3 child attributesHide child attributes
    • sent_atstring

      When the batch went out.

    • countinteger

      Notifications in the batch.

    • triggered_byobject

      The restock or bulk send behind the batch. Absent for single sends.

      Show 6 child attributesHide child attributes
      • restock_detected_atstring

        When the send was created: the restock was detected or the bulk send was started.

      • sourcestring

        What 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 of webhookbulk_sendbulk_resendflow_actionevents_inventoryevents_productsreconciliation
      • statusstring

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

        One of activewaitingcompleted
      • signups_at_triggerinteger

        Signups attached to that send.

      • sent_in_batchesboolean

        Whether that send notified the waitlist in batches.

      • batch_limitinteger

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

  • deliveryobject

    The 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
    • batchingobject

      How a restock notifies the waitlist in batches.

      Show 5 child attributesHide child attributes
      • enabledboolean

        Whether the waitlist is notified in batches instead of all at once.

      • modestring

        multiplier sends restocked quantity times multiplier per batch; fixed sends fixed_batch_size per batch.

        One of multiplierfixed
      • multiplierinteger

        Signups notified per restocked unit, used while mode is multiplier.

      • fixed_batch_sizeinteger

        Signups notified per batch, used while mode is fixed.

      • wait_hoursinteger

        Hours to wait between batches.

    • minimum_restock_quantityinteger

      Minimum restocked quantity before an automatic alert sends.

    • location_filter_enabledboolean

      Whether only stock at the chosen locations counts as a restock.

    • any_variant_alerts_enabledboolean

      Whether a restock of any variant of a product notifies everyone waiting on that product.

    • alerts_enabledboolean

      Whether automatic back-in-stock alerts are on. False means restocks send nothing.

Errors

404
not_found

The path is valid but nothing with that id exists in this store.

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.

GET/back_in_stock/signups/notification_status
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"
Response
{
  "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
  }
}