For the complete documentation index, see llms.txt. This page is also available as Markdown.

/waitlists

List Waitlists

get

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

Authorizations
X-Purple-Dot-Access-TokenstringRequired

Your store's private access token. It can also be sent as Authorization: Bearer <token>.

Query parameters
limitintegerOptional

Number of Waitlists to return. Defaults to 10, maximum 100.

Default: 10Example: 10
created_at_minstring · date-timeOptional

Waitlists created at or after this time.

Example: 2025-01-01T00:00:00.000Z
updated_at_minstring · date-timeOptional

Waitlists updated at or after this time.

Example: 2025-01-01T00:00:00.000Z
updated_at_maxstring · date-timeOptional

Waitlists updated at or before this time.

Example: 2025-12-31T23:59:59.000Z
starting_afterstring · uuidOptional

Returns Waitlists after the given Waitlist ID.

Example: a2aecc56-ce64-49da-8ce6-099e664d85fd
Responses
200

A page of Waitlists.

application/json
get/waitlists
GET /admin/api/v1/waitlists HTTP/1.1
Host: www.purpledotprice.com
X-Purple-Dot-Access-Token: YOUR_API_KEY
Accept: */*
{
  "meta": {
    "result": "success"
  },
  "data": {
    "waitlists": [
      {
        "id": "a2aecc56-ce64-49da-8ce6-099e664d85fd",
        "created_at": "2023-10-27T14:44:09.726Z",
        "updated_at": "2023-11-02T09:12:41.203Z",
        "earliest_ship_date": "2023-11-25T05:00:00.000Z",
        "latest_ship_date": "2023-12-10T04:59:59.999Z",
        "state": "Live",
        "launch_date": "2023-10-27T00:00:00.000Z",
        "scheduled_pause_date": "2023-11-20T00:00:00.000Z",
        "labels": [
          "holiday"
        ],
        "availability": {
          "product": {
            "product_id": "7257265143861",
            "buy_size": 10,
            "committed": 3,
            "available": 7
          },
          "variants": [
            {
              "variant_id": "42662551519285",
              "sku": "ZTEST",
              "buy_size": 10,
              "committed": 3,
              "available": 7
            }
          ]
        }
      }
    ],
    "has_more": true,
    "starting_after": "a2aecc56-ce64-49da-8ce6-099e664d85fd",
    "previous_cursor": "0c34fc59-8a99-427f-a340-857e1eb9b6d2"
  }
}

Create a Waitlist

post

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

Authorizations
X-Purple-Dot-Access-TokenstringRequired

Your store's private access token. It can also be sent as Authorization: Bearer <token>.

Body
product_idstring · min: 1Required

The product ID in the connected store.

Example: 7257265143861
earliest_ship_datestringRequired

The earliest ship date, as an ISO 8601 date or timestamp.

Example: 2025-03-01
latest_ship_datestringRequired

The latest ship date, as an ISO 8601 date or timestamp.

Example: 2025-03-15
statestring · enumRequiredExample: OPENPossible values:
labelsstring[]RequiredExample: spring-2025
Responses
200

The Waitlist.

application/json
post/waitlists
POST /admin/api/v1/waitlists HTTP/1.1
Host: www.purpledotprice.com
X-Purple-Dot-Access-Token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 236

{
  "product_id": "7257265143861",
  "earliest_ship_date": "2025-03-01",
  "latest_ship_date": "2025-03-15",
  "max_units": [
    {
      "sku_id": "42662551519285",
      "max_units": 50
    },
    {
      "sku_id": "42662551552053",
      "max_units": 30
    }
  ],
  "state": "OPEN",
  "labels": [
    "spring-2025"
  ]
}
{
  "meta": {
    "result": "success"
  },
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "product_id": "7257265143861",
    "state": "OPEN",
    "earliest_ship_date": "2025-03-01T00:00:00Z",
    "latest_ship_date": "2025-03-15T00:00:00Z",
    "max_units": [
      {
        "sku_id": "42662551519285",
        "max_units": 50
      },
      {
        "sku_id": "42662551552053",
        "max_units": 30
      }
    ]
  }
}

Create or update a Waitlist

put

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

Authorizations
X-Purple-Dot-Access-TokenstringRequired

Your store's private access token. It can also be sent as Authorization: Bearer <token>.

Body
product_idstring · min: 1Required

The product ID in the connected store.

Example: 7257265143861
earliest_ship_datestringRequired

The earliest ship date, as an ISO 8601 date or timestamp.

Example: 2025-03-01
latest_ship_datestringRequired

The latest ship date, as an ISO 8601 date or timestamp.

Example: 2025-03-15
statestring · enumRequiredExample: OPENPossible values:
labelsstring[]RequiredExample: spring-2025
Responses
200

The Waitlist.

application/json
put/waitlists
PUT /admin/api/v1/waitlists HTTP/1.1
Host: www.purpledotprice.com
X-Purple-Dot-Access-Token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 236

{
  "product_id": "7257265143861",
  "earliest_ship_date": "2025-03-01",
  "latest_ship_date": "2025-03-15",
  "max_units": [
    {
      "sku_id": "42662551519285",
      "max_units": 50
    },
    {
      "sku_id": "42662551552053",
      "max_units": 30
    }
  ],
  "state": "OPEN",
  "labels": [
    "spring-2025"
  ]
}
{
  "meta": {
    "result": "success"
  },
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "product_id": "7257265143861",
    "state": "OPEN",
    "earliest_ship_date": "2025-03-01T00:00:00Z",
    "latest_ship_date": "2025-03-15T00:00:00Z",
    "max_units": [
      {
        "sku_id": "42662551519285",
        "max_units": 50
      },
      {
        "sku_id": "42662551552053",
        "max_units": 30
      }
    ]
  }
}

Update a Waitlist

put

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

Authorizations
X-Purple-Dot-Access-TokenstringRequired

Your store's private access token. It can also be sent as Authorization: Bearer <token>.

Path parameters
releaseIdstring · uuidRequired

The Waitlist ID.

Example: 550e8400-e29b-41d4-a716-446655440000
Body
product_idstring · min: 1Required

The product ID in the connected store.

Example: 7257265143861
earliest_ship_datestringRequired

The earliest ship date, as an ISO 8601 date or timestamp.

Example: 2025-03-01
latest_ship_datestringRequired

The latest ship date, as an ISO 8601 date or timestamp.

Example: 2025-03-15
statestring · enumRequiredExample: OPENPossible values:
labelsstring[]RequiredExample: spring-2025
Responses
200

The Waitlist.

application/json
put/waitlists/{releaseId}
PUT /admin/api/v1/waitlists/{releaseId} HTTP/1.1
Host: www.purpledotprice.com
X-Purple-Dot-Access-Token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 205

{
  "product_id": "7257265143861",
  "earliest_ship_date": "2025-03-01",
  "latest_ship_date": "2025-03-20",
  "max_units": [
    {
      "sku_id": "42662551519285",
      "max_units": 75
    }
  ],
  "state": "PAUSED",
  "labels": [
    "spring-2025",
    "delayed"
  ]
}
{
  "meta": {
    "result": "success"
  },
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "product_id": "7257265143861",
    "state": "OPEN",
    "earliest_ship_date": "2025-03-01T00:00:00Z",
    "latest_ship_date": "2025-03-15T00:00:00Z",
    "max_units": [
      {
        "sku_id": "42662551519285",
        "max_units": 50
      },
      {
        "sku_id": "42662551552053",
        "max_units": 30
      }
    ]
  }
}

Last updated