Notify

POST

/back_in_stock/signups/notify

curl --request POST \
  --url https://app.stoqapp.com/api/v2/external/back_in_stock/signups/notify \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: <X-Auth-Token>' \
  --data '{ "shopify_variant_id": "gid://shopify/ProductVariant/47284734423096", "channel": "email" }'

• Production

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.

Note: 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.

Authorizations

• ApiKeyAuth

Request Body^required

Media typeapplication/json

object

status

Allowed values: pending notified

shopify_market_ids

Array<string>

channel

Allowed values: email sms

limit

integer

> 0

shopify_product_id

shopify_variant_id

customer_id

title

sku

without_orders

from

to

Example

{
  "shopify_variant_id": "gid://shopify/ProductVariant/47284734423096",
  "channel": "email"
}

Responses

200

Success — example response shown.

Media typeapplication/json

object

Example

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

202

Accepted — async/bulk work was queued. Poll the returned job.

Media typeapplication/json

Returned for async/bulk work — poll the job until it reaches a terminal state.

object

job_id

string

status_url

string

Example

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

401

Missing or invalid X-Auth-Token.

Media typeapplication/json

Error envelope returned by every failed request.

object

errors

required

Array<string>

Example

{
  "errors": [
    "Unauthorized"
  ]
}

422

The request failed validation.

Media typeapplication/json

Error envelope returned by every failed request.

object

errors

required

Array<string>

Example

{
  "errors": [
    "name is required"
  ]
}

429

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

Media typeapplication/json

Error envelope returned by every failed request.

object

errors

required

Array<string>

Example

{
  "errors": [
    "Rate limit exceeded"
  ]
}