---
title: "Check a variant's waitlist"
description: "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 -- t"
url: https://docs.stoqapp.com/v2-reference/back-in-stock-signups/check-a-variants-waitlist/
api: "API v2 reference"
method: GET
path: "/back_in_stock/signups/notification_status"
---

# Check a variant's waitlist

`GET https://app.stoqapp.com/api/v2/external/back_in_stock/signups/notification_status`

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.

**Note:** 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`](https://docs.stoqapp.com/v2-reference/back-in-stock-signups/bulk-notify-signups/).

## Query parameters

- `shopify_variant_id` (string, required): Shopify variant gid to report on.
- `count_by` (string): Count pending shoppers once per customer or once per signup. Default is the shop's dashboard setting. One of: `customers`, `signups`.

## Returns

- `product_title` (string): Product title of the variant.
- `variant_title` (string): Variant title; null for a product's only (default) variant.
- `count_by` (string): How pending_signups counts: customers counts a shopper on email and SMS once, signups counts each channel. One of: `customers`, `signups`.
- `pending_signups` (integer): Customers or signups (see count_by) still waiting on this variant.
- `last_sent_at` (string): When the latest send batch went out. Absent when nothing was ever sent.
- `total_notifications_sent` (integer): Notifications sent for this variant, all time and all channels.
- `total_send_batches` (integer): Distinct send batches for this variant, all time.
- `blocked_by_plan_limit` (integer): Notifications for this variant held back by the plan's notification limit.
- `recent_sends` (array of objects): The 5 most recent send batches, newest first; recent_sends_note says when there are more.
  - `sent_at` (string): When the batch went out.
  - `count` (integer): Notifications in the batch.
  - `triggered_by` (object): The restock or bulk send behind the batch. Absent for single sends.
    - `restock_detected_at` (string): When the send was created: the restock was detected or the bulk send was started.
    - `source` (string): 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: `webhook`, `bulk_send`, `bulk_resend`, `flow_action`, `events_inventory`, `events_products`, `reconciliation`.
    - `status` (string): active is sending, waiting is paused between batches, completed is done. One of: `active`, `waiting`, `completed`.
    - `signups_at_trigger` (integer): Signups attached to that send.
    - `sent_in_batches` (boolean): Whether that send notified the waitlist in batches.
    - `batch_limit` (integer): Most signups that send notifies; null means the whole waitlist.
- `delivery` (object): The shop's delivery settings, the usual reason a restock has not sent yet. Absent when the shop has no settings.
  - `batching` (object): How a restock notifies the waitlist in batches.
    - `enabled` (boolean): Whether the waitlist is notified in batches instead of all at once.
    - `mode` (string): multiplier sends restocked quantity times multiplier per batch; fixed sends fixed_batch_size per batch. One of: `multiplier`, `fixed`.
    - `multiplier` (integer): Signups notified per restocked unit, used while mode is multiplier.
    - `fixed_batch_size` (integer): Signups notified per batch, used while mode is fixed.
    - `wait_hours` (integer): Hours to wait between batches.
  - `minimum_restock_quantity` (integer): Minimum restocked quantity before an automatic alert sends.
  - `location_filter_enabled` (boolean): Whether only stock at the chosen locations counts as a restock.
  - `any_variant_alerts_enabled` (boolean): Whether a restock of any variant of a product notifies everyone waiting on that product.
  - `alerts_enabled` (boolean): Whether automatic back-in-stock alerts are on. False means restocks send nothing.

Rate limit: this call costs 1 point ([rate limits](https://docs.stoqapp.com/docs/rate-limits/)).

## Examples

### Check a variant's waitlist

```sh
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"
```

### Check a variant's waitlist filtered by count_by

```sh
curl "https://app.stoqapp.com/api/v2/external/back_in_stock/signups/notification_status?shopify_variant_id=45000000001&count_by=customers" \
  -H "X-Auth-Token: $STOQ_API_KEY"
```

## 200

Success: example response shown.

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

## 401

Missing or invalid `X-Auth-Token`.

```json
{
  "errors": [
    "Invalid API key"
  ],
  "code": "auth_invalid",
  "details": [
    {
      "code": "auth_invalid",
      "message": "Invalid API key",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}
```

## 422

The request failed validation.

```json
{
  "errors": [
    "name is required"
  ],
  "code": "validation_failed",
  "details": [
    {
      "code": "validation_failed",
      "message": "name is required",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}
```

## 429

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

```json
{
  "errors": [
    "Rate limit exceeded"
  ],
  "code": "rate_limited",
  "details": [
    {
      "code": "rate_limited",
      "message": "Rate limit exceeded",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}
```

