# /waitlists

#### GET /admin/api/v1/waitlists <a href="#get-pre-orders" id="get-pre-orders"></a>

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: <access_token>'
```

<details>

<summary>This is what a per-variant waitlist response would look like:</summary>

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

</details>

<details>

<summary>This is what a per-product waitlist response would look like:</summary>

```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
  }
}
```

</details>

#### 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.getpurpledot.com/docs/purple-dot-apis/private-api/waitlists.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.