> For the complete documentation index, see [llms.txt](https://docs.getpurpledot.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.getpurpledot.com/docs/purple-dot-apis/private-api/waitlists.md).

# /waitlists

## List Waitlists

> Lists Waitlists for the store, with cursor pagination. Per-product Waitlists return \`null\` for variant-level allocation fields.

```json
{"openapi":"3.1.0","info":{"title":"Purple Dot Private API","version":"v1"},"tags":[{"name":"/waitlists"}],"servers":[{"url":"https://www.purpledotprice.com/admin/api/v1","description":"Production"}],"security":[{"accessToken":[]}],"components":{"securitySchemes":{"accessToken":{"type":"apiKey","in":"header","name":"X-Purple-Dot-Access-Token","description":"Your store's private access token. It can also be sent as `Authorization: Bearer <token>`."}},"schemas":{"Waitlist":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time","description":"When the Waitlist was created."},"updated_at":{"type":"string","format":"date-time","description":"When the Waitlist was last updated."},"earliest_ship_date":{"type":"string","format":"date-time","description":"The earliest ship date."},"latest_ship_date":{"type":"string","format":"date-time","description":"The latest ship date."},"state":{"type":"string","enum":["Live","Paused","Closed","Scheduled","Draft"],"description":"The Waitlist’s state."},"launch_date":{"type":["string","null"]},"scheduled_pause_date":{"type":["string","null"]},"labels":{"type":"array","items":{"type":"string"}},"availability":{"type":"object","properties":{"product":{"type":"object","properties":{"product_id":{"type":"string"},"buy_size":{"type":["number","null"]},"committed":{"type":"number","description":"Units sold."},"available":{"type":["number","null"],"description":"Units still available. `null` for variant-level figures a per-product Waitlist does not allocate."}},"required":["product_id","buy_size","committed","available"]},"variants":{"type":"array","items":{"type":"object","properties":{"variant_id":{"type":"string"},"sku":{"type":["string","null"]},"buy_size":{"type":["number","null"]},"committed":{"type":"number","description":"Units sold."},"available":{"type":["number","null"],"description":"Units still available. `null` for variant-level figures a per-product Waitlist does not allocate."}},"required":["variant_id","sku","buy_size","committed","available"]}}},"required":["product","variants"]}},"required":["id","created_at","updated_at","earliest_ship_date","latest_ship_date","state","launch_date","scheduled_pause_date","labels","availability"]},"AuthErrorResponse":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"ErrorResponse":{"type":"object","properties":{"meta":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message."},"errorData":{"type":"object","additionalProperties":{},"description":"Structured detail about the error."}},"required":["error","errorData"]},"data":{"type":"object","properties":{}}},"required":["meta","data"]}}},"paths":{"/waitlists":{"get":{"tags":["/waitlists"],"summary":"List Waitlists","description":"Lists Waitlists for the store, with cursor pagination. Per-product Waitlists return `null` for variant-level allocation fields.","parameters":[{"schema":{"type":"integer","default":10,"description":"Number of Waitlists to return. Defaults to 10, maximum 100."},"required":false,"description":"Number of Waitlists to return. Defaults to 10, maximum 100.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Waitlists created at or after this time."},"required":false,"description":"Waitlists created at or after this time.","name":"created_at_min","in":"query"},{"schema":{"type":"string","description":"Waitlists updated at or after this time."},"required":false,"description":"Waitlists updated at or after this time.","name":"updated_at_min","in":"query"},{"schema":{"type":"string","description":"Waitlists updated at or before this time."},"required":false,"description":"Waitlists updated at or before this time.","name":"updated_at_max","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Returns Waitlists after the given Waitlist ID."},"required":false,"description":"Returns Waitlists after the given Waitlist ID.","name":"starting_after","in":"query"},{"schema":{"type":"string","description":"Comma-separated states to filter by, ignoring case: `LIVE`, `SCHEDULED`, `PAUSED` or `CLOSED`. Omit it for every Waitlist except drafts, which are never returned."},"required":false,"description":"Comma-separated states to filter by, ignoring case: `LIVE`, `SCHEDULED`, `PAUSED` or `CLOSED`. Omit it for every Waitlist except drafts, which are never returned.","name":"state","in":"query"}],"responses":{"200":{"description":"A page of Waitlists.","headers":{"Link":{"description":"Links to the previous and next pages of results. For compatibility, relations use the legacy `rel={next}` and `rel={previous}` syntax.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"result":{"type":"string","enum":["success"]}},"required":["result"]},"data":{"type":"object","properties":{"waitlists":{"type":"array","items":{"$ref":"#/components/schemas/Waitlist"}},"has_more":{"type":"boolean","description":"Whether more results are available after this page."},"starting_after":{"type":["string","null"],"format":"uuid","description":"ID of the last item returned. Pass it as `starting_after`."},"previous_cursor":{"type":["string","null"],"format":"uuid"}},"required":["waitlists","has_more","starting_after","previous_cursor"]}},"required":["meta","data"]}}}},"400":{"description":"Missing access token. Invalid request, such as an unsupported `state` value.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/AuthErrorResponse"},{"$ref":"#/components/schemas/ErrorResponse"}]}}}},"401":{"description":"Access token not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"}}}}}}}}}
```

## Create a Waitlist

> Creates a Waitlist for a product and ship date range. Also served at \`/waitlist\`.

```json
{"openapi":"3.1.0","info":{"title":"Purple Dot Private API","version":"v1"},"tags":[{"name":"/waitlists"}],"servers":[{"url":"https://www.purpledotprice.com/admin/api/v1","description":"Production"}],"security":[{"accessToken":[]}],"components":{"securitySchemes":{"accessToken":{"type":"apiKey","in":"header","name":"X-Purple-Dot-Access-Token","description":"Your store's private access token. It can also be sent as `Authorization: Bearer <token>`."}},"schemas":{"WaitlistRequest":{"type":"object","properties":{"product_id":{"type":"string","minLength":1,"description":"The product ID in the connected store."},"earliest_ship_date":{"type":"string","description":"The earliest ship date, as an ISO 8601 date or timestamp."},"latest_ship_date":{"type":"string","description":"The latest ship date, as an ISO 8601 date or timestamp."},"max_units":{"type":"array","items":{"type":"object","properties":{"sku_id":{"type":"string","minLength":1,"description":"The external SKU (variant) ID."},"max_units":{"type":"integer","minimum":0,"description":"Maximum units for this SKU."}},"required":["sku_id","max_units"]},"minItems":1,"description":"The unit limit for each SKU on the Waitlist."},"state":{"type":"string","enum":["DRAFT","OPEN","PAUSED","CLOSED"]},"labels":{"type":"array","items":{"type":"string"}}},"required":["product_id","earliest_ship_date","latest_ship_date","max_units","state","labels"]},"WaitlistSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"product_id":{"type":"string"},"state":{"type":"string"},"earliest_ship_date":{"type":"string"},"latest_ship_date":{"type":"string"},"max_units":{"type":"array","items":{"type":"object","properties":{"sku_id":{"type":"string"},"max_units":{"type":"number"}},"required":["sku_id","max_units"]}}},"required":["id","product_id","state","earliest_ship_date","latest_ship_date","max_units"]},"AuthErrorResponse":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"ErrorResponse":{"type":"object","properties":{"meta":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message."},"errorData":{"type":"object","additionalProperties":{},"description":"Structured detail about the error."}},"required":["error","errorData"]},"data":{"type":"object","properties":{}}},"required":["meta","data"]}}},"paths":{"/waitlists":{"post":{"tags":["/waitlists"],"summary":"Create a Waitlist","description":"Creates a Waitlist for a product and ship date range. Also served at `/waitlist`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WaitlistRequest"}}}},"responses":{"200":{"description":"The Waitlist.","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"result":{"type":"string","enum":["success"]}},"required":["result"]},"data":{"$ref":"#/components/schemas/WaitlistSummary"}},"required":["meta","data"]}}}},"400":{"description":"Missing access token. Invalid or missing fields.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/AuthErrorResponse"},{"$ref":"#/components/schemas/ErrorResponse"}]}}}},"401":{"description":"Access token not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"}}}},"404":{"description":"The product or a variant was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"A Waitlist already exists for that product and ship date range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Create or update a Waitlist

> Upserts a Waitlist. Updates the Waitlist with the same product and ship date range, or creates one if none exists. Also served at \`/waitlist\`.

```json
{"openapi":"3.1.0","info":{"title":"Purple Dot Private API","version":"v1"},"tags":[{"name":"/waitlists"}],"servers":[{"url":"https://www.purpledotprice.com/admin/api/v1","description":"Production"}],"security":[{"accessToken":[]}],"components":{"securitySchemes":{"accessToken":{"type":"apiKey","in":"header","name":"X-Purple-Dot-Access-Token","description":"Your store's private access token. It can also be sent as `Authorization: Bearer <token>`."}},"schemas":{"WaitlistRequest":{"type":"object","properties":{"product_id":{"type":"string","minLength":1,"description":"The product ID in the connected store."},"earliest_ship_date":{"type":"string","description":"The earliest ship date, as an ISO 8601 date or timestamp."},"latest_ship_date":{"type":"string","description":"The latest ship date, as an ISO 8601 date or timestamp."},"max_units":{"type":"array","items":{"type":"object","properties":{"sku_id":{"type":"string","minLength":1,"description":"The external SKU (variant) ID."},"max_units":{"type":"integer","minimum":0,"description":"Maximum units for this SKU."}},"required":["sku_id","max_units"]},"minItems":1,"description":"The unit limit for each SKU on the Waitlist."},"state":{"type":"string","enum":["DRAFT","OPEN","PAUSED","CLOSED"]},"labels":{"type":"array","items":{"type":"string"}}},"required":["product_id","earliest_ship_date","latest_ship_date","max_units","state","labels"]},"WaitlistSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"product_id":{"type":"string"},"state":{"type":"string"},"earliest_ship_date":{"type":"string"},"latest_ship_date":{"type":"string"},"max_units":{"type":"array","items":{"type":"object","properties":{"sku_id":{"type":"string"},"max_units":{"type":"number"}},"required":["sku_id","max_units"]}}},"required":["id","product_id","state","earliest_ship_date","latest_ship_date","max_units"]},"AuthErrorResponse":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"ErrorResponse":{"type":"object","properties":{"meta":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message."},"errorData":{"type":"object","additionalProperties":{},"description":"Structured detail about the error."}},"required":["error","errorData"]},"data":{"type":"object","properties":{}}},"required":["meta","data"]}}},"paths":{"/waitlists":{"put":{"tags":["/waitlists"],"summary":"Create or update a Waitlist","description":"Upserts a Waitlist. Updates the Waitlist with the same product and ship date range, or creates one if none exists. Also served at `/waitlist`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WaitlistRequest"}}}},"responses":{"200":{"description":"The Waitlist.","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"result":{"type":"string","enum":["success"]}},"required":["result"]},"data":{"$ref":"#/components/schemas/WaitlistSummary"}},"required":["meta","data"]}}}},"400":{"description":"Missing access token. Invalid or missing fields.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/AuthErrorResponse"},{"$ref":"#/components/schemas/ErrorResponse"}]}}}},"401":{"description":"Access token not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"}}}},"404":{"description":"The product or a variant was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Update a Waitlist

> Updates a specific Waitlist. \`product\_id\` must match the Waitlist’s existing product. Also served at \`/waitlist/{releaseId}\`.

```json
{"openapi":"3.1.0","info":{"title":"Purple Dot Private API","version":"v1"},"tags":[{"name":"/waitlists"}],"servers":[{"url":"https://www.purpledotprice.com/admin/api/v1","description":"Production"}],"security":[{"accessToken":[]}],"components":{"securitySchemes":{"accessToken":{"type":"apiKey","in":"header","name":"X-Purple-Dot-Access-Token","description":"Your store's private access token. It can also be sent as `Authorization: Bearer <token>`."}},"schemas":{"WaitlistRequest":{"type":"object","properties":{"product_id":{"type":"string","minLength":1,"description":"The product ID in the connected store."},"earliest_ship_date":{"type":"string","description":"The earliest ship date, as an ISO 8601 date or timestamp."},"latest_ship_date":{"type":"string","description":"The latest ship date, as an ISO 8601 date or timestamp."},"max_units":{"type":"array","items":{"type":"object","properties":{"sku_id":{"type":"string","minLength":1,"description":"The external SKU (variant) ID."},"max_units":{"type":"integer","minimum":0,"description":"Maximum units for this SKU."}},"required":["sku_id","max_units"]},"minItems":1,"description":"The unit limit for each SKU on the Waitlist."},"state":{"type":"string","enum":["DRAFT","OPEN","PAUSED","CLOSED"]},"labels":{"type":"array","items":{"type":"string"}}},"required":["product_id","earliest_ship_date","latest_ship_date","max_units","state","labels"]},"WaitlistSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"product_id":{"type":"string"},"state":{"type":"string"},"earliest_ship_date":{"type":"string"},"latest_ship_date":{"type":"string"},"max_units":{"type":"array","items":{"type":"object","properties":{"sku_id":{"type":"string"},"max_units":{"type":"number"}},"required":["sku_id","max_units"]}}},"required":["id","product_id","state","earliest_ship_date","latest_ship_date","max_units"]},"AuthErrorResponse":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"ErrorResponse":{"type":"object","properties":{"meta":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message."},"errorData":{"type":"object","additionalProperties":{},"description":"Structured detail about the error."}},"required":["error","errorData"]},"data":{"type":"object","properties":{}}},"required":["meta","data"]}}},"paths":{"/waitlists/{releaseId}":{"put":{"tags":["/waitlists"],"summary":"Update a Waitlist","description":"Updates a specific Waitlist. `product_id` must match the Waitlist’s existing product. Also served at `/waitlist/{releaseId}`.","parameters":[{"schema":{"type":"string","format":"uuid","description":"The Waitlist ID."},"required":true,"description":"The Waitlist ID.","name":"releaseId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WaitlistRequest"}}}},"responses":{"200":{"description":"The Waitlist.","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"result":{"type":"string","enum":["success"]}},"required":["result"]},"data":{"$ref":"#/components/schemas/WaitlistSummary"}},"required":["meta","data"]}}}},"400":{"description":"Missing access token. Invalid or missing fields.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/AuthErrorResponse"},{"$ref":"#/components/schemas/ErrorResponse"}]}}}},"401":{"description":"Access token not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"}}}},"404":{"description":"The Waitlist was not found, or belongs to another store.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
