List reservation lifecycle events
const url = 'https://api.useservice.app/v1/reservations/example/events';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url https://api.useservice.app/v1/reservations/example/events \ --header 'Authorization: Bearer <token>'Lists one reservation’s lifecycle events, oldest first. Requires the reservations:read
scope. 404 for any id GET /v1/reservations/{id} would also 404. A booking still
awaiting its card guarantee resolves here, and its list is empty until the guest saves
the card: that step emits reservation.created.
A change to contact_email, contact_phone or guest_notes appears in data.changes
only when your key could read that field on the booking.
Order: oldest first (created_at ascending; events recorded in the same instant in the
order they were written).
Authorizations
Section intitulée « Authorizations »Parameters
Section intitulée « Parameters »Path Parameters
Section intitulée « Path Parameters »Reservation public id (resv_…)
Query Parameters
Section intitulée « Query Parameters »How many objects to return: 1 to 100, default 20. A larger value is lowered to 100 rather than refused; 0, a negative number or anything that is not an integer is a 400.
The id of an object in this list — normally the last one on the page you have. Returns the objects that come after it, in the order the operation description gives. has_more: false means you have reached the end. An id this list cannot find is a 400.
The id of an object in this list — normally the first one on the page you have. Returns the objects that come just before it, walking the same order backwards; the page itself still reads in list order. Ignored when starting_after is also sent. An id this list cannot find is a 400.
Header Parameters
Section intitulée « Header Parameters »Pin this request to a dated version of the contract, e.g. 2026-09-01. Omit it and the version pinned on the API key applies. A version we do not publish is a 400 bad_request with param: "Service-Version". The version that was applied comes back on the Service-Version response header, always.
Responses
Section intitulée « Responses »Events listed
object
object
The object type: always reservation_event.
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.
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_reasonsays how.reservation.no_show: the party did not come.
When it happened: ISO 8601 with the restaurant’s UTC offset.
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, insidechangeswhen one of them is edited.submitted_guest_name,submitted_email,submitted_phone— on thereservation.createdevent, 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_apiis a cancel YOU made throughPOST /v1/reservations/{id}/cancel.guest_self_serviceis the guest cancelling from their own manage link.guarantee_expiredis a card request that lapsed unpaid.
Anything else was typed by the restaurant; match on the three named values and pass the rest through.
object
Example
{ "object": "list", "data": [ { "object": "reservation_event", "type": "reservation.created" } ]}Dated API version applied to this response
The Service-Version header names a version we do not publish
The envelope every public-API error answers with, whatever the status.
object
Every error response carries this one object.
object
The broad class of the error, from the HTTP status.
invalid_request_error: a400,403,404,409or422— something about the request to change.authentication_error: a401— the key is missing, invalid, revoked or expired.rate_limit_error: a429— slow down and retry.api_error: any other status, a fault on our side.
The specific error, stable and machine-readable, e.g. not_found. Branch on this, not on message.
A human-readable explanation for the developer. Its wording can change.
The request parameter the error is about, when there is one — e.g. expand or limit. Absent — not null — when the error names no field.
A link to this code in the errors reference. Always present.
Example
{ "error": { "type": "invalid_request_error" }}Unique id for this request. Quote it to support: it is how a specific call is found in our logs. Generated per request, or echoed from the X-Request-Id you sent.
No API key, or not a live one
The envelope every public-API error answers with, whatever the status.
object
Every error response carries this one object.
object
The broad class of the error, from the HTTP status.
invalid_request_error: a400,403,404,409or422— something about the request to change.authentication_error: a401— the key is missing, invalid, revoked or expired.rate_limit_error: a429— slow down and retry.api_error: any other status, a fault on our side.
The specific error, stable and machine-readable, e.g. not_found. Branch on this, not on message.
A human-readable explanation for the developer. Its wording can change.
The request parameter the error is about, when there is one — e.g. expand or limit. Absent — not null — when the error names no field.
A link to this code in the errors reference. Always present.
Example
{ "error": { "type": "invalid_request_error" }}Unique id for this request. Quote it to support: it is how a specific call is found in our logs. Generated per request, or echoed from the X-Request-Id you sent.
The API key does not carry the reservations:read scope
The envelope every public-API error answers with, whatever the status.
object
Every error response carries this one object.
object
The broad class of the error, from the HTTP status.
invalid_request_error: a400,403,404,409or422— something about the request to change.authentication_error: a401— the key is missing, invalid, revoked or expired.rate_limit_error: a429— slow down and retry.api_error: any other status, a fault on our side.
The specific error, stable and machine-readable, e.g. not_found. Branch on this, not on message.
A human-readable explanation for the developer. Its wording can change.
The request parameter the error is about, when there is one — e.g. expand or limit. Absent — not null — when the error names no field.
A link to this code in the errors reference. Always present.
Example
{ "error": { "type": "invalid_request_error" }}Unique id for this request. Quote it to support: it is how a specific call is found in our logs. Generated per request, or echoed from the X-Request-Id you sent.
No such reservation
The envelope every public-API error answers with, whatever the status.
object
Every error response carries this one object.
object
The broad class of the error, from the HTTP status.
invalid_request_error: a400,403,404,409or422— something about the request to change.authentication_error: a401— the key is missing, invalid, revoked or expired.rate_limit_error: a429— slow down and retry.api_error: any other status, a fault on our side.
The specific error, stable and machine-readable, e.g. not_found. Branch on this, not on message.
A human-readable explanation for the developer. Its wording can change.
The request parameter the error is about, when there is one — e.g. expand or limit. Absent — not null — when the error names no field.
A link to this code in the errors reference. Always present.
Example
{ "error": { "type": "invalid_request_error" }}Too many requests on the read budget
The envelope every public-API error answers with, whatever the status.
object
Every error response carries this one object.
object
The broad class of the error, from the HTTP status.
invalid_request_error: a400,403,404,409or422— something about the request to change.authentication_error: a401— the key is missing, invalid, revoked or expired.rate_limit_error: a429— slow down and retry.api_error: any other status, a fault on our side.
The specific error, stable and machine-readable, e.g. not_found. Branch on this, not on message.
A human-readable explanation for the developer. Its wording can change.
The request parameter the error is about, when there is one — e.g. expand or limit. Absent — not null — when the error names no field.
A link to this code in the errors reference. Always present.
Example
{ "error": { "type": "invalid_request_error" }}Requests permitted in the read burst
Requests remaining in the read burst
Seconds until the read bucket refills
Which budget the numbers describe. read here.
Seconds to wait before retrying
Unique id for this request. Quote it to support: it is how a specific call is found in our logs. Generated per request, or echoed from the X-Request-Id you sent.