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

  • launch_date - ISO8610 timestamp of when the waitlist will be live

  • 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:

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

This is what a per-variant waitlist response would look like:

{
  "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:

{
  "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

• labels (array, required) — Array of label strings (can be empty)

Example Request

{
  "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

{
  "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

{
  "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