The waitlist entry object

A waitlist entry is a guest waiting for a table on a service date. It comes back from Waitlist entries and from every waitlist_entry.* webhook.

Fields

objectstring

Possible values: waitlist_entry

The object type: always waitlist_entry.

idstring

The entry’s id, wl_…. Opaque and permanent.

statusstring

Possible values: active offered suggested promoted cancelled expired

Where the entry is in the queue.

• active: waiting.
• offered: a place has been offered to the guest and the offer is still open.
• suggested: a booking has been proposed to the restaurant’s staff, who decide.
• promoted: it became a booking — see reservation.
• cancelled: the guest or the restaurant withdrew it.
• expired: it ran out of time: the service passed, or the offers ran out.

joined_viastring

Possible values: widget staff partner_platform

How the guest joined the queue. Not called source, which means something else on a reservation and on a guest.

• widget: in the restaurant’s booking widget.
• staff: added by the restaurant’s staff.
• partner_platform: in the booking widget embedded on a partner’s page.

service_datestring (date)

The service day the guest wants a table on, YYYY-MM-DD in the restaurant’s timezone.

party_sizeinteger

How many guests the entry is for.

window_startstring

The earliest start time the guest will take a table at, HH:MM on service_date in the restaurant’s timezone. With window_end it is the range the matching engine may offer inside — a slot outside it is never offered to this entry. Read it with window_start_day_offset, which says whether the clock time belongs to the service date or to its post-midnight tail.

window_endstring

The latest start time the guest will take, HH:MM on service_date in the restaurant’s timezone, read with window_end_day_offset. Always at or after window_start once both offsets are applied, so a window that runs past midnight — 23:30 to 00:30 — is window_end_day_offset: 1, not a wrapped clock time.

window_start_day_offsetinteger

0 = the service date, 1 = its post-midnight tail.

window_end_day_offsetinteger

0 = the service date, 1 = its post-midnight tail.

shift_namestringoptionalnullable

The name of the service the guest joined for, as it was shown to them when they joined — a later rename does not change it. null when that service had no name.

shift_start_timestringoptionalnullable

That service’s start, wall-clock HH:MM in the restaurant’s timezone, as it was when the guest joined. null when not recorded.

shift_end_timestringoptionalnullable

That service’s end, in the same form. null when not recorded.

notesstringoptionalnullable

The guest’s own request, as they typed it when joining. Guest data: present only when your key carries guests:read; otherwise the field is absent, not null. Every webhook delivery carries it.

reservationstringoptionalnullable

The booking this entry became, once it is one a consumer can fetch. Null while an offer is still open — that hold is not a published booking.

gueststring or Guestoptional

The guest waiting. By default their id, gst_…; the full Guest object when you pass ?expand=guest, which needs the guests:read scope — without it the request is refused with 403 insufficient_scope, never downgraded to the id. Webhook deliveries always carry the id.

Every entry has a guest, so in practice the field is always present; it would be absent, not null, on an entry without one.

created_atstring (date-time)

When the guest joined: ISO 8601 with the restaurant’s UTC offset.

updated_atstring (date-time)

When the entry last changed, in the same format. The value updated_since compares against.

The window is not two clock times

window_start and window_end are wall-clock times on service_date, and each carries its own day offset. A window that runs past midnight is window_end_day_offset: 1, never a wrapped clock time, so window_end is always at or after window_start once both offsets are applied. Apply the offsets before you compare or display them.

The shift fields are a snapshot. shift_name, shift_start_time and shift_end_time are what the guest was shown when they joined, and a later rename does not change them.

Statuses, and the one that leaves an id behind

An entry waits (active), is offered a place (offered) or proposed to staff (suggested), and ends up promoted, cancelled or expired. Only promoted produces a booking, and reservation names it. That field is null while an offer is still open — the table an offer holds is not a published booking, and the glossary has what that means.

What your key can read

notes is the guest’s own request and needs guests:read; without it the field is absent, not null. guest is the gst_… id, and ?expand=guest replaces it with the whole guest object — also guests:read, and refused rather than downgraded without it. Webhook deliveries carry the id and carry notes whatever the key holds, exactly as they do on a reservation.