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/

Scope Required: products:read

Query Parameters

Parameter	Type	Description
`search`	string	Case-insensitive substring match on the product name. Omitted or empty returns every waitlisted product
`after`	string	Cursor for pagination. Product public ID of the last item on the previous page. Omit to start from the top of the ranking
`before`	string	Cursor for pagination. Product public ID of the first item on the current page, for paging back up the ranking
`limit`	integer	Number of products to return (default 10, max 100)

Pagination follows the same cursor rules as the product list: after is the id of the last item from the previous page, before is the id of the first item to page back, and the response reports has_more in the direction of travel. 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",
      "taken_down_at": null,
      "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 or before, both at once, 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/

Scope Required: products:read

Path Parameters

Parameter	Type	Description
`product_id`	string	Product public ID (e.g., `pro_d0b6fmv28q6vn14peun0`)

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:

Field	Type	Description
`waiting_count`	integer	Number of active waitlist entries for the product across all of its variants

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.