Waitlists

The Waitlists API lets you read product waitlists from your store, and the people who signed up.

Overview

The Waitlists API provides endpoints to:

• List waitlists
• Retrieve a waitlist
• List waitlist members
• Retrieve a waitlist member

These endpoints only read waitlists and signups. A waitlist is the signup list for one product. It exists once that product has had the waitlist turned on. A product that never had it turned on has no waitlist. Turning the waitlist off sets status to inactive and keeps the signups.

product_name is the product's current name. Get Waitlists query matches that name. A waitlist whose product no longer exists is omitted from the list and returns 404 on Get Waitlist, Get Waitlist Members, and Get Waitlist Member.

Each signup's answers are custom_field_answers on the member. The field definitions are a separate collection. See Custom Fields.

Endpoints

Method	Path	Description
GET	/waitlists	Paginated list. See Get Waitlists.
GET	/waitlists/{id}	One waitlist. See Get Waitlist.
GET	/waitlists/{id}/members	Paginated signups. See Get Waitlist Members.
GET	/waitlists/{id}/members/{memberId}	One signup. See Get Waitlist Member.

{id} is the waitlist id (a UUID). {memberId} is the signup id (a UUID).

Status

status is active or inactive. Omitting the list filter returns both.

Status	Meaning
active	The waitlist currently accepts signups.
inactive	The waitlist was turned off. Signups remain.

Waitlist Object

Get Waitlists and Get Waitlist return this object. Every field is always set.

Field	Type	Nullable	Description
id	string	No	Waitlist UUID.
status	string	No	One of the status slugs.
product_id	string	No	Product UUID. Pass it to Get Product.
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).

Waitlist Member Object

Get Waitlist Members and Get Waitlist Member return this object. first_name, last_name, and full_name are nullable. email, terms_accepted, joined_at, and custom_field_answers are always set.

Field	Type	Nullable	Description
id	string	No	Signup UUID.
email	string	No	Signup email.
first_name	string	Yes	First name. Null when the signup did not include one.
last_name	string	Yes	Last name. Null when the signup did not include one.
full_name	string	Yes	First and last name joined with a space, trimmed. Null only when both names are empty. A signup with only one name still has full_name set to that name. Name search is described on Get Waitlist Members.
terms_accepted	boolean	No	Whether the signup accepted the terms.
joined_at	string	No	When the person first signed up (ISO 8601). Signing up again with the same email does not change this.
custom_field_answers	object	No	Answers submitted with the signup, keyed by the custom field name. Always an object. {} when there are no answers. Definitions are on Custom Fields.