Get Waitlists

Retrieve a paginated list of product waitlists from your store.

A waitlist exists for each product that has ever had the waitlist turned on, newest first. Products that never had it turned on do not appear. Omitting status returns both active and inactive waitlists. A waitlist whose product no longer exists is omitted. Narrow the list with the optional filters below. All filters combine with AND.

Request

GET /waitlists

Query Parameters

Parameter	Type	Required	Default	Description
page	integer	No	1	Page number for pagination.
per_page	integer	No	10	Items per page (min: 1, max: 100).
sort	string	No	-created_at	Sort field: product_name, members_count, or created_at. Prefix with - for descending. product_name sorts by the current product name.
status	string	No	—	One status: active or inactive. Omit it to return both.
product	string	No	—	Filter by product UUID. A UUID that is not a product in this store matches nothing (an empty list), not 404.
query	string	No	—	Partial match on the current product name (product_name).

Omitting a filter or passing it empty means no filter on that field. A present but unparseable value returns 400 (see Bad Request). That includes an unknown status, a malformed product UUID, an out-of-range per_page, or an unknown sort field. The query search term is free text and is always accepted.

Ordering: Waitlists default to created_at descending (newest first) unless sort is supplied. Equal values are ordered most recently created first.

Counting matches: every response includes the filtered total in pagination.total. To get only a count, request per_page=1 with your filters and read pagination.total.

Example Request

curl -X GET "https://cart.easy.tools/api/v1/waitlists" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

Success Response (200)

Returns a paginated list of waitlists.

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "active",
      "product_id": "6a7fdc8a-73c4-40bb-9996-16bc86486830",
      "product_name": "Workshop",
      "members_count": 1,
      "created_at": "2026-09-01T10:15:30+00:00"
    },
    {
      "id": "3f8c1a27-6b4e-4d91-8c55-2e7a9f0b14d6",
      "status": "active",
      "product_id": "b7e4d2a1-8c3f-4a56-9e10-6d4f8a2c1b90",
      "product_name": "Starter Workshop",
      "members_count": 0,
      "created_at": "2026-04-09T13:59:58+00:00"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 1,
    "per_page": 10,
    "total": 2
  }
}

Response Fields

Field reference: Waitlist object.

Field	Type	Nullable	Description
id	string	No	Waitlist UUID.
status	string	No	Waitlist status (see Status).
product_id	string	No	Product UUID.
product_name	string	No	Current product name.
members_count	integer	No	Number of signups. Zero when nobody has joined.
created_at	string	No	When the waitlist was created (ISO 8601).

Pagination Object

Field	Type	Description
current_page	integer	Current page number.
total_pages	integer	Total number of pages.
per_page	integer	Effective page size (echoes the per_page request parameter).
total	integer	Total number of waitlists matching the applied filters, across all pages.

Error Responses

Bad Request (400)

Returned when a filter has a non-empty but unparseable value. The message names the offending field and the value received.

{
  "message": "Invalid value for 'status': 'enabled'"
}

Unauthorized Error (401)

{
  "message": "Unauthenticated."
}

Forbidden Error (403)

Returned when your API key has not been granted access to the requested store.

{
  "message": "You do not have API access to the requested store."
}

Rate Limit Error (429 Too Many Requests)

Returned when you exceed the rate limit. The Retry-After response header gives the number of seconds to wait.

{
  "message": "Too many requests. Please retry after 60 seconds."
}