Create signups

POST

/back_in_stock/signups

curl --request POST \
  --url https://app.stoqapp.com/api/v2/external/back_in_stock/signups \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: <X-Auth-Token>' \
  --data '{ "channel": "email", "shopify_variant_id": 47284734423096, "shopify_product_id": 8784906035384, "email": "john@example.com", "quantity": 2, "name": "John Doe" }'

• Production

Create a back-in-stock signup (add a customer to the waitlist for a variant).

Note: email is required for the email channel, phone for sms. shopify_product_id is resolved from the variant when omitted. Returns 409 when a pending signup already exists for the same contact + variant + channel.

Authorizations

• ApiKeyAuth

Request Body^required

Media typeapplication/json

object

channel

required

Allowed values: email sms

shopify_variant_id

required

quantity

integer

shopify_product_id

email

phone

name

Example

{
  "channel": "email",
  "shopify_variant_id": 47284734423096,
  "shopify_product_id": 8784906035384,
  "email": "john@example.com",
  "quantity": 2,
  "name": "John Doe"
}

Responses

200

Success — example response shown.

Media typeapplication/json

object

Example

{
  "id": 5847392,
  "status": "pending",
  "channel": "email",
  "contact": "john@example.com",
  "quantity": 2,
  "variant": {
    "shopify_variant_id": 47284734423096,
    "shopify_product_id": 8784906035384,
    "title": "Blue / Medium"
  },
  "customer": {
    "id": 9284756,
    "email": "john@example.com",
    "name": "John Doe"
  },
  "optin": {
    "required": false,
    "confirmed": null
  },
  "notifications_sent": 0,
  "last_notified_at": null,
  "created_at": "2026-06-25T13:45:30Z"
}

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