Restock Waitlist API

Shoppers can ask to be emailed when an out-of-stock variant is restocked. The
storefront records those requests and emails the shoppers once stock returns.
These read-only endpoints report the resulting waiting counts. Creating a
request is a storefront action and is not part of the API.

Related resources:

• Products for the product fields returned below
• Product Variants for the inventory updates that
  clear a waitlist

Endpoints

• List Waitlisted Products - GET /api/v1/products/waitlisted/
• Get Product Waitlist - GET /api/v1/products/{product_id}/waitlist/

Only counts are exposed. The individual email addresses on a waitlist are
never returned, to limit the impact of a leaked API key.

List Waitlisted Products

List the products that currently have at least one shopper waiting for a
restock, ranked by the highest waiting count and then by the most recently
created product. Products with no waiters are omitted. Once a restock email
is sent, those shoppers drop out of the ranking.

Endpoint: GET /api/v1/products/waitlisted/

Permission Required: Read

Query Parameters

Pagination follows the same cursor rules as the
product list: after is the id of the last
item from the previous page and the response reports has_more. An after ID
that no longer has any waiters (for example, the product was restocked between
requests) yields an empty page.

Request

curl -X GET "https://studio.easel.engineering/api/v1/products/waitlisted/?search=t-shirt&limit=20" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 200 OK

{
  "data": [
    {
      "id": "pro_d0b6fmv28q6vn14peun0",
      "name": "Blue T-Shirt",
      "status": "active",
      "description": "A soft cotton tee.",
      "delivery": "physical",
      "created_at": "2026-09-01T12:00:00Z",
      "updated_at": "2026-09-20T09:30:00Z",
      "waiting_count": 12
    }
  ],
  "has_more": false
}

Only products with at least one active waitlist entry are returned, so
waiting_count is always 1 or greater in this list. Use
Get Product Waitlist to check a product that may have
no waiters.

Error Responses

Invalid query parameter

Status: 400 Bad Request

A malformed after, a non-numeric or negative limit, or a limit over 100
returns INVALID_REQUEST_ERROR, with the offending parameter named in the
error message:

{
  "error": "Invalid 'limit' parameter: cannot exceed 100",
  "code": "INVALID_REQUEST_ERROR"
}

Failed to list waitlisted products

Status: 500 Internal Server Error

{
  "error": "Internal server error",
  "code": "INTERNAL_ERROR"
}

Get Product Waitlist

Report how many waitlist entries are active for one product. Each variant a
shopper signs up for adds one entry.

Endpoint: GET /api/v1/products/{product_id}/waitlist/

Permission Required: Read

Path Parameters

Request

curl -X GET "https://studio.easel.engineering/api/v1/products/pro_d0b6fmv28q6vn14peun0/waitlist/" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 200 OK

{
  "data": {
    "product_id": "pro_d0b6fmv28q6vn14peun0",
    "waiting_count": 3
  }
}

waiting_count is 0 when no one is waiting.

Error Responses

Product not found

Status: 404 Not Found

{
  "error": "Resource not found",
  "code": "NOT_FOUND"
}

Failed to get waitlist

Status: 500 Internal Server Error

{
  "error": "Internal server error",
  "code": "INTERNAL_ERROR"
}

Waitlisted Product Object

A waitlisted product is the standard
Product object with one extra field:

waiting_count counts each waiting (variant, email) pair once, so the same
address counts for every variant it is waiting on. Entries that already
received a restock email are not counted.