# /waitlists
#### GET /admin/api/v1/waitlists
Request:
* `limit` (number) - Optional. The number of waitlists to retrieve. Set to 10 by default but can be set up to 100
* `created_at_min` (ISO8610 timestamp) - Optional. List waitlists created since the given time
* `updated_at_min` (ISO8610 timestamp) - Optional. List waitlists updated since the given time
* `starting_after` (UUID) - Optional. Paginate pre-orders after the given waitlist ID
Headers:
* `Link` - An IETF [RFC 8288](https://datatracker.ietf.org/doc/html/rfc8288#section-2) compliant header with links to previous and next page of results for the preorder query.
Body:
* `waitlists` - An array containing waitlists
* `id` - ID used to identify the waitlist inside Purple Dot
* `created_at` - ISO8610 timestamp of when the waitlist was created
* `updated_at` - ISO8610 timestamp of when the waitlist was last updated
* `earliest_ship_date` - ISO8610 timestamp of the earliest date the waitlisted product can ship
* `latest_ship_date` - ISO8610 timestamp of the latest date the waitlisted product can ship
* `state` - The state of the waitlist. This can be one of the following:
* `LIVE` - Shoppers can start placing preorders for this product if there is no stock in Shopify
* `PAUSED` - Shoppers cannot place preorders for this product until the waitlist is unpaused
* `CLOSED` - Waitlist is now closed
* `SCHEDULED` - Waitlist will be live on the launch date
* `DRAFT` - Waitlist is in draft state and needs approval before going live
* `launch_date` - ISO8610 timestamp of when the waitlist will be live
* `scheduled_pause_date` - ISO8610 timestamp of when the waitlist will be paused
* `labels` - Labels associated with the waitlist
* `availability` - A map of the product & variant-wise sales data
* `product` - Sales data for the product
* `product_id` - Shopify ID for the product
* `buy_size` - Total number of units allocated for preorder
* `committed` - Total number of preorder units sold
* `available` - Total number of preorder units available for sale
* `variants` - An array of the sales data for all the product variants
* `variant_id` - Shopify ID of the product variant
* `sku` - SKU code of the product variant
* `buy_size` - Total number of units of the product variant allocated for preorder (this will be null in the case of a per-product waitlist)
* `committed` - Total number of preorder units of the product variant sold
* `available` - Total number of preorder units available of the product variant for sale (this will be null in the case of a per-product waitlist)
* `starting_after` - The ID of the last waitlist in the list which can then be used in the next request
* `has_more` - Indicates whether there are more orders available to page through
Examples:
```bash
curl --request GET \
--url 'https://www.purpledotprice.com/admin/api/v1/waitlists?limit=1&created_at_min=2023-08-17T00:00:00.000Z' \
--header 'X-Purple-Dot-Access-Token: '
```
This is what a per-variant waitlist response would look like:
```json
{
"meta":{
"result":"success"
},
"data":{
"waitlists":[
{
"id":"a2aecc56-ce64-49da-8ce6-099e664d85fd",
"created_at":"2023-10-27T14:44:09.726Z",
"earliest_ship_date":"2023-11-25T05:00:00.000Z",
"latest_ship_date":"2023-12-10T04:59:59.999Z",
"state":"CLOSED",
"launch_date":"2023-12-10T00:00:00.000Z",
"labels":[
],
"availability":{
"product":{
"product_id":"7257265143861",
"buy_size":10,
"committed":3,
"available":10
},
"variants":[
{
"variant_id":"42662551519285",
"sku":"ZTEST",
"buy_size":10,
"committed":3,
"available":10
}
]
}
}
],
"has_more":true,
"starting_after":"a2aecc56-ce64-49da-8ce6-099e664d85fd",
"previous_cursor":"0c34fc59-8a99-427f-a340-857e1eb9b6d2"
}
}
```
This is what a per-product waitlist response would look like:
```json
{
"meta":{
"result":"success"
},
"data":{
"waitlists":[
{
"id":"c657585b-bfe0-4aca-867d-e2c3399969a3",
"created_at":"2023-09-20T16:57:55.928Z",
"earliest_ship_date":"2024-04-08T04:00:00.000Z",
"latest_ship_date":"2024-04-19T04:00:00.000Z",
"state":"CLOSED",
"launch_date":null,
"labels":[
],
"availability":{
"product":{
"product_id":"7233472626741",
"buy_size":10,
"committed":4,
"available":10
},
"variants":[
{
"variant_id":"42591503876149",
"sku":"TEST-S",
"buy_size":null,
"committed":2,
"available":null
},
{
"variant_id":"42591503843381",
"sku":"TEST-M",
"buy_size":null,
"committed":1,
"available":null
},
{
"variant_id":"42591503777845",
"sku":"TEST-L",
"buy_size":null,
"committed":1,
"available":null
}
]
}
}
],
"has_more":true,
"starting_after":"c657585b-bfe0-4aca-867d-e2c3399969a3",
"previous_cursor":null
}
}
```
#### POST /admin/api/v1/waitlists (Preview)
Creates a new waitlist. Fails with `409 Conflict` if a waitlist already exists for the same product and ship date range.
**Request Body**
* `product_id` (string, required) — External product ID; the numeric suffix as a string (e.g. `"123"`)
* `earliest_ship_date` (string, required) — ISO 8601 date; earliest expected ship date
* `latest_ship_date` (string, required) — ISO 8601 date; latest expected ship date
* `max_units` (array, required) — Per-SKU max units; at least one entry required. Each entry:
* `sku_id` (string, required) — External SKU/variant ID; the numeric suffix as a string (e.g. `"456"`)
* `max_units` (number, required) — Maximum units for this SKU (non-negative integer)
* `state` (string, required) — One of: `OPEN`, `PAUSED`, `CLOSED`, `DRAFT`
* `labels` (array, required) — Array of label strings (can be empty)
**Example Request**
```json
{
"product_id": "123",
"earliest_ship_date": "2025-03-01",
"latest_ship_date": "2025-03-15",
"max_units": [
{ "sku_id": "456", "max_units": 50 },
{ "sku_id": "789", "max_units": 30 }
],
"state": "OPEN",
"labels": ["spring-2025"]
}
```
**Response** `201 Created`
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"product_id": "123",
"state": "OPEN",
"earliest_ship_date": "2025-03-01T00:00:00.000Z",
"latest_ship_date": "2025-03-15T00:00:00.000Z",
"max_units": [
{ "sku_id": "456", "max_units": 50 },
{ "sku_id": "789", "max_units": 30 }
],
}
```
**Errors**
* `400 Bad Request` — Invalid or missing required fields
* `404 Not Found` — Product or variant not found for the store
* `409 Conflict` — A waitlist already exists for this product and ship dates
***
#### PUT /admin/api/v1/waitlists (Preview)
Creates a new waitlist or updates an existing one, matched by product and ship date range. If a matching waitlist exists, it is updated; otherwise a new one is created.
**Request Body**
Same as Create Waitlist.
**Response** `200 OK`
Same structure as the Create response. Returns the created or updated waitlist.
**Errors**
* `400 Bad Request` — Invalid or missing required fields
* `404 Not Found` — Product or variant not found for the store
***
#### PUT /admin/api/v1/waitlists/:releaseId (Preview)
Updates an existing waitlist by its ID. Use this when you know the waitlist's `id` (e.g. from a previous create/upsert or list response).
**URL Parameters**
* `releaseId` (string) — UUID of the waitlist to update
**Request Body**
Same as Create Waitlist. The `product_id` in the body must match the waitlist's current product.
**Example Request**
```
PUT /waitlists/550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json
```
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"product_id": "123",
"earliest_ship_date": "2025-03-01",
"latest_ship_date": "2025-03-20",
"max_units": [
{ "sku_id": "456", "max_units": 75 }
],
"state": "PAUSED",
"labels": ["spring-2025", "delayed"]
}
```
**Response** `200 OK`
Same structure as the Create response.
**Errors**
* `400 Bad Request` — Invalid fields or `product_id` does not match the waitlist
* `404 Not Found` — Waitlist not found, or belongs to another store