Skip to content
Service Developers

The reservation event object

A reservation event is one entry in a booking’s immutable history. It comes back from GET /v1/reservations/{id}/events and from ?expand=events on a read.

Fields

Section titled “Fields”

objectstring

Possible values: reservation_event

The object type: always reservation_event.

idstring

The event’s id, evt_…. Opaque and permanent. Not the id of the webhook event that announced the same change: the two are numbered separately.

typestring

Possible values: reservation.created reservation.confirmed reservation.declined reservation.updated reservation.pending reservation.partially_seated reservation.seated reservation.completed reservation.cancelled reservation.no_show

What happened, named like the webhook event for the same change.

  • reservation.created: the booking was made.
  • reservation.pending: it became a request awaiting the restaurant’s decision.
  • reservation.confirmed: the restaurant accepted it.
  • reservation.declined: the restaurant turned the request down.
  • reservation.updated: its details or its tables changed.
  • reservation.partially_seated: part of the party was seated.
  • reservation.seated: the party was seated.
  • reservation.completed: the party left.
  • reservation.cancelled: it was cancelled — data.cancellation_reason says how.
  • reservation.no_show: the party did not come.

created_atstring (date-time)

When it happened: ISO 8601 with the restaurant’s UTC offset.

dataobject

What changed, keyed per event type — statuses as from_status/to_status, field edits under changes. Internal ids, staff identity and the staff’s own notes are stripped. Treat the key set as open.

Six keys carry the guest’s own data and appear only when your key could read that field on the booking — that is, when it carries guests:read:

  • contact_email, contact_phone, guest_notes — the booking’s own contact details and the note the guest left, inside changes when one of them is edited.
  • submitted_guest_name, submitted_email, submitted_phone — on the reservation.created event, what the booker actually typed, recorded when it differs from the guest profile the booking was matched to.

On reservation.cancelled, cancellation_reason says who ended the booking and how:

  • partner_api is a cancel YOU made through POST /v1/reservations/{id}/cancel.
  • guest_self_service is the guest cancelling from their own manage link.
  • guarantee_expired is a card request that lapsed unpaid.

Anything else was typed by the restaurant; match on the three named values and pass the rest through.

It describes a change, not a state

Section titled “It describes a change, not a state”

An entry says what happened in that one moment. To learn what the booking is now, fetch the reservation. That is the difference from a webhook, whose data.object is the whole booking.

evt_… here is not the id of the webhook that announced the same change. The two are numbered separately, so deduplicate webhook deliveries on the webhook’s own id.

What data carries

Section titled “What data carries”

The key set is per event type and is open — read the keys you know and ignore the rest. Internal ids, staff identity and the staff’s own notes are stripped, which is why an update that only reassigned tables can yield an empty diff. Reservation events works through the shapes type by type.

Six keys are the guest’s own data and appear only when your key could read that field on the booking. The field above names them.