Find and change a booking
These operations need the bookings.manage capability. Every one of them starts by proving the caller knows both the booking’s reference and the phone number on the booking, both sent in the body (never in the URL query).
Finding a booking
Section titled “Finding a booking”POST /public/v1/bookings/lookup (find_booking):
{ "reference": "4827 1936", "phone": "07911 123456" }Spaces in the reference are fine. A wrong reference, a wrong phone number, or a booking at a venue your key doesn’t cover all give the same 404 booking-not-found, so a lookup never reveals whether a reference exists.
Failed lookups are throttled: after 10 failures from a key in 10 minutes, or 5 against one reference in an hour, the answer is 429 lookup-throttled with Retry-After.
The answer has the booking’s date, time, party size, state and deposit, and the guest’s first name only.
Amending
Section titled “Amending”POST /public/v1/bookings/{reference}/amend (amend_booking) with the phone and only what changes: date, time, partySize or notes. The reference stays the same.
| Outcome | Meaning |
|---|---|
amended |
Done; read out the summary. A bigger party may owe a deposit top-up (depositTopUp). Offer to text the payment link. |
unavailable |
The new time is full. Nothing changed; offer the alternatives. |
needs_venue |
The venue doesn’t allow this change online: too many guests, too close to the booking, too far ahead, or a booking still waiting for its deposit. The request has gone to the venue’s team (enquiryId), who will be in touch. |
Cancelling
Section titled “Cancelling”POST /public/v1/bookings/{reference}/cancel (cancel_booking) cancels at once and frees the table. Confirm with the guest before you call it.
- A paid deposit is never refunded automatically. The venue’s team is told and will be in touch about it.
- Inside the venue’s notice period for cancellations, the request goes to the venue instead (
needs_venue). - A booking that’s already cancelled answers
already_cancelled.
Running late
Section titled “Running late”POST /public/v1/bookings/{reference}/running-late (report_running_late) with minutesLate, for a confirmed booking today.
- Up to 60 minutes: noted on the booking and the venue’s live diary, and the table is held until then plus the venue’s grace period (
noted). - More than an hour: passed to the venue’s team (
needs_venue). - A booking that isn’t today, or a guest who’s already seated, answers
409booking-not-changeable with a detail that says why.
When the venue needs to step in
Section titled “When the venue needs to step in”needs_venue always comes with an enquiry in the venue’s inbox, linked to the booking. Tell the guest the venue’s team will be in touch; don’t retry the change.