Skip to content
CibusyDevelopers
TREN
Get an API key

Reservations

Cancel a reservation

Call off the reservation of a guest who changes their mind on your site. It is the guest's cancellation, and the venue is told.

POST/public/v1/reservations/{reservationId}/cancel
Authentication

An API key in the X-Api-Key header

Permission
Can take reservations
Rate limit
About 30 requests a minute per key

For a guest who changes their mind on your site. It is the guest's cancellation, the same as one made on the reservation's page on cibusy.com: cancelledBy reads Customer, and the venue is told, with the reason when one was given. The body is optional; reason is for the venue to read.

A reservation can be called off while it stands (Pending or Confirmed), the guest has not been checked in and its time has not come; canCancel on the reservation says so beforehand. Otherwise the answer is RESERVATION_NOT_CANCELLABLE. Calling off a reservation that is already cancelled, by anybody, answers 200 with it as it stands, so a request that was cut off can be sent again.

The API does not change a reservation's time or its number of guests: cancel it and take a new one.

Guide: Taking reservations

Parameters

reservationIdstring · uuidPath parameterrequired

The reservation's id, from the answer to taking it.

Accept-LanguagestringHeader

The language of userMessage in an error: tr (the default), en, de, fr, it, es, ar or ru. The first language in the header decides, without its region (en-US reads as en) and without weighing q values; a language Cibusy does not offer is answered in Turkish. It does not choose the language of a menu: that is lang on the menu call.

Request body

Why a reservation is being called off. The body is optional.

reasonstringnullable

What the guest said, for the venue to read, at most 250 characters.

Responses

200

The reservation, cancelled.

400

PUBLIC_API_RESERVATION_INVALID: the reason is longer than 250 characters.

401

The X-Api-Key header is missing (PUBLIC_API_KEY_MISSING), or the key is invalid or has been revoked (PUBLIC_API_KEY_INVALID).

403

PUBLIC_API_SCOPE_MISSING: the key was not made with the "Can take reservations" permission.

404

PUBLIC_API_RESERVATION_NOT_FOUND.

409

RESERVATION_NOT_CANCELLABLE: the reservation can no longer be called off.

429

The key's budget of about 30 orders, reservations and tests a minute is spent; wait Retry-After seconds.

Retry-After

Seconds to wait. The next one-minute window opens within it.

The data of a successful answer

A reservation taken through the API, as the venue has it right now. The same body GET /reservations/{reservationId} returns and the webhook's reservation.updated event carries.

idstring · uuid

The reservation's id. Use it with GET /reservations/{reservationId}.

venueIdstring · uuid

The venue the table is booked at.

statusstring

Where the reservation has got to, worked out on every read, so the list, a read of one reservation and a webhook event cannot say different things about the same booking.

Pending
The venue has not answered yet. A venue that confirms bookings as they are made never shows this.
Confirmed
The venue accepted it, or confirms bookings as they are made. The table is expected.
Declined
The venue declined the request.
Cancelled
It was called off. `cancelledBy` says by whom.
Seated
The guest has arrived and was checked in at the door.
Completed
The visit is over.
NoShow
The venue accepted it and nobody came.
startsAtstring · date-time

When the table is for, as an instant in UTC.

guestsinteger

How many people are coming.

customerobject

Who the table is for, as the venue has it.

Fields of Reservation guest
namestringnullable

The guest's name.

phonestringnullable

The guest's phone number, in international form.

notestringnullable

The note the reservation was made with. null when there was none.

codestringnullable

The code the venue checks the guest in with at the door: eight characters the guest can read out, or show as the QR on pageUrl. Whoever holds it can see and cancel the booking, so give it to the guest and to nobody else.

pageUrlstringnullable

The reservation's own page on cibusy.com, which shows the booking and, once it is confirmed, the QR the venue scans at the door. Link to it or send it to the guest. null for a venue with no public address.

canCancelboolean

Whether the reservation can still be cancelled through the API: it stands, the guest has not been checked in and its time has not come.

checkedInAtstring · date-timenullable

When the guest was checked in at the door, in UTC. null until then.

cancelledAtstring · date-timenullable

When the reservation was called off, in UTC. null unless status is Cancelled.

cancelledBystringnullable

Who called it off. null unless status is Cancelled.

Customer
The guest: through this API, on the reservation's own page, or in the Cibusy app.
Venue
The venue.
System
Cibusy, when the venue had not answered a request by the time it was for.
cancellationReasonstringnullable

What was given as the reason for calling it off, in the words of whoever gave it. null unless status is Cancelled.

createdAtstring · date-time

When the reservation was made, in UTC.