The availability object
Availability comes in two shapes, one per endpoint on Availability. Both answer what was sellable at read time and neither is a promise: the create path re-checks every cap and table fit under a lock.
The availability object
Section titled “The availability object”GET /v1/availability returns this, for one service date and one party size.
The shifts, their slots and any card guarantee they carry are nested in place.
objectstring
Possible values: availability
The object type: always availability.
service_datestring (date)
The service day asked about, YYYY-MM-DD in the restaurant’s timezone.
party_sizeinteger
The party size asked about. Every slot, flag and guarantee below answers for it.
section_idstringnullable
The sec_… filter applied, if any.
day_messagestringnullable
A day-level note from the restaurant, shown as a banner. Independent of the shifts below — it can exist on a day where every service was removed.
display_onlyboolean
Nothing is bookable today and what remains to show is a display-only service’s message. Day-level: NOT the per-shift flag of the same name.
message_onlyboolean
No service runs today, but day_message carries the reason. Distinct from a closure.
closureAvailabilityClosurenullable
The closure covering this date, or null. When set the day takes no bookings and shifts is empty.
objectstring
Possible values: availability_closure
The object type: always availability_closure.
namestringnullable
The restaurant’s name for the closure, e.g. a holiday. null when it gave none.
guest_messagestringnullable
The restaurant’s own words for this closure. Show them.
start_datestring (date)
First day of the closure, YYYY-MM-DD in the restaurant’s timezone.
end_datestring (date)
Last day of the closure, inclusive, in the same form.
shiftsarray of AvailabilityShift
The services that run on this date. [] on a closed day or a day with no service.
objectstring
Possible values: availability_shift
The object type: always availability_shift.
idstringnullable
Opaque shf_… id, or null for a service that exists only as a date-scoped override.
namestringnullable
The service’s name, e.g. Dîner. A date override’s name wins over the service’s own. null when neither has one.
guest_messagestringnullable
The restaurant’s own note for this service. Show it.
start_timestringnullable
HH:MM, restaurant timezone.
end_timestringnullable
HH:MM, restaurant timezone.
effective_cutoff_minutesintegernullable
How many minutes before start_time online booking closes FOR THIS service on THIS
date — the value actually enforced, resolved through the restaurant’s rule cascade
(a date override beats this service’s own rule, which beats the house default). This
is the authoritative one: configuration.default_cutoff_minutes is only the house
default and a service may set its own.
0 means bookable right up to the start time, -1 means bookable during the
service, and null means the restaurant has no booking rule at all and booking
never closes.
Once it passes, this service lists no slots and a create is refused with
cutoff_passed — so treat it as the countdown to show a guest, never as permission
to book.
display_onlyboolean
The service is open and worth showing but takes NO online booking. Render its message, never a booking control.
booking_closedboolean
Online booking for this service on this date is over: effective_cutoff_minutes
has passed, or its last seating time is behind the clock. slots is then []
because booking for it has ended, not because it filled, so do not show it as full.
The widget leaves such a service out of the list entirely.
Computed in the restaurant’s timezone at the moment of the request, so it is only
ever true on today’s date — and on yesterday’s, which this API still serves while
an overnight service is seating past midnight: there the overnight service reads
false until its last seating has passed, and every other service true.
requires_approvalboolean
A booking here is a REQUEST: it lands as pending and staff decide. Never tell the guest they are booked.
waitlist_openboolean
A guest of this party size may join the queue for this service. Always false while the restaurant has its booking widget switched off, because that is what the join endpoint itself enforces.
guaranteeAvailabilityGuaranteenullable
The card guarantee a booking of the requested party size in this service will be asked for. null means no card will be asked for.
objectstring
Possible values: availability_guarantee
The object type: always availability_guarantee.
modestring
Possible values: imprint
Only card imprints are disclosed today.
currencystring
ISO 4217 currency code of both amounts, e.g. EUR.
per_guest_amountinteger
Minor units per guest.
amountinteger
Minor units for the requested party size.
cancel_hoursintegernullable
Hours before the seating after which a cancellation may be charged. Null means cancellation is always free and only a no-show is charged.
guarantee_from_party_sizeintegernullable
The smallest party this service asks for a card imprint on this date, whatever
party_size you queried with.
null is a promise: no booking on this service on this date is asked for a card, at
any party size. A number is exact: a party of that size or larger is asked, a
smaller one is not. So on a bookable service guarantee is non-null exactly when
party_size is at least this, and you can tell a guest at which size the card step
starts without querying every size. guarantee still carries the amounts.
Set on a display_only or marked-full service too, where guarantee is always
null: it is what a booking placed there with an override would be asked.
It follows the same rule as the create: an imprint the restaurant cannot currently
charge is not asked, and reads null.
configuration.card_guarantee_from_party_size summarises it across every service
and date.
slotsarray of AvailabilitySlot
The seating times still bookable for the requested party size. [] when none is — read the flags above for why.
objectstring
Possible values: availability_slot
The object type: always availability_slot.
timestring
Seating time as HH:MM in the restaurant timezone.
available_coversintegernullable
Covers still sellable at this time, or null when no covers cap is configured — meaning unlimited, NOT zero. Do not treat null as falsy.
max_covers_per_slotintegernullable
The per-slot pacing cap in force, or null when none is set.
unavailable_slotsarray of string
Times this service SELLS that this party cannot take right now — rejected by a covers cap or because no table fits. Render them greyed out and offer the queue; hiding them is what makes a booking UI feel broken at peak. Times staff never offered, and times that have simply elapsed, are not listed here.
section_idsarray of string
The rooms this service can be booked WHOLE in on this date: the group_id of every
section group with a row drawn on the floor plan this service uses on this date (a
date override may swap the plan). Pass one as entire_section_id.
Absence is a promise: a group not listed here is refused with
no_table_available_in_section for this service on this date. Presence is only a
maybe: a listed room can still be taken, and is then refused with section_occupied
and its conflicts.
It does not depend on party_size or section_id, and it ignores
bookable_online, which a whole-room booking does not read. Empty when the plan in
use has no sections.
The availability month object
Section titled “The availability month object”GET /v1/availability/months returns this. It is filter-independent on purpose
— no party size, no section — so one read paints a whole calendar.
objectstring
Possible values: availability_month
The object type: always availability_month.
monthstring
YYYY-MM.
daysarray of AvailabilityDay
Every day of the month, in order — never a sparse list.
objectstring
Possible values: availability_day
The object type: always availability_day.
service_datestring (date)
The day, YYYY-MM-DD in the restaurant’s timezone.
pastboolean
Already gone, allowing for an overnight service still seating.
outside_windowboolean
Beyond how far ahead this restaurant takes bookings.
closedboolean
A closure covers this date.
closure_messagestringnullable
The closure’s message to guests, in the restaurant’s own words, when closed is true. null when the day is not closed or the restaurant wrote no message.
no_shiftsboolean
No service runs — closed, not sold out.
message_onlyboolean
No service runs, but staff left a note to read. Open the day; do not offer times.
display_onlyboolean
Only a display-only service remains. Selectable, but it takes no online booking.
reservation_closedboolean
Every service is past its booking cutoff or simply over. Not the same as sold out.
party_sizesarray of integer
Party sizes that could be seated somewhere on this day. EMPTY with every flag false means fully booked.
sectionsarray of object
Per-seating-area breakdown; empty when the restaurant offers no seating choice online.
objectstring
Possible values: availability_section
The object type: always availability_section.
idstring
The seating area, as its group_id from GET /v1/sections (sec_…). It can differ from the sec_… on a reservation’s table, which names one floor plan’s row.
party_sizesarray of integer
Party sizes that could be seated in this area on this day. [] when none.
waitlist_party_sizesarray of integer
Party sizes that may join the queue for this day. Independent of whether any slot survives. Always empty while the booking widget is switched off.
Null is not zero
Section titled “Null is not zero”available_covers and max_covers_per_slot are null when the restaurant sets
no cap, which means unlimited. Reading null as zero closes a slot that is open.
The same shape appears on guarantee_from_party_size and
effective_cutoff_minutes: null is the absence of a rule, not a rule set to
nothing.
An empty day is not one situation
Section titled “An empty day is not one situation”A day on GET /v1/availability/months carries at most one of these flags.
Service tests them in this order and stops at the first that applies:
past— the date has gone, allowing for an overnight service still seating after midnight.outside_window— the date is beyond how far ahead the restaurant takes bookings.closed— a closure covers the date.closure_messagecarries its text when the restaurant wrote one.message_only— no service runs, and staff left a note to show.no_shifts— no service runs.display_only— a service that takes no online booking runs, and no bookable service has anything left.reservation_closed— every bookable service is past its booking cutoff or its last seating time. The day is over for online booking, not sold out.
With every flag false, empty party_sizes means fully booked. A funnel that
tests only for “no slots” collapses eight answers into one, and tells the guest
the wrong thing for seven of them.
The same holds for one service. A service whose slots are empty carries
booking_closed when online booking for it is over on this date, and
display_only when it takes none at all. With both false, the service is
running and has nothing left for this party size: only then is it full.
No endpoint writes this
Section titled “No endpoint writes this”Availability is derived from the restaurant’s services, tables and bookings. There is nothing to create, and nothing here arrives by webhook.