/
Booking v1

Booking v1

This API is Live and ready to use in production.

The Booking API is used to book reservations directly into TableCheck's inventory backend. The Booking API is available by special arrangement with TableCheck. In most cases, the Web Booking API should be used instead. This API has a number of limitations, including:

  • Payments are not supported.

  • Menu item (dining experience) booking is not supported. As a workaround, free text can be added to a memo field.

  • If you are a booking aggregator site (i.e. not a restaurant/hospitality brand), TableCheck must approve each venue individually for access.

Target Audience

The Booking API may be useful in the following cases:

  • Merchant-owned booking sites or brand apps.

  • Pre-paid voucher systems, i.e. where payments are not necessary.

Endpoint

The Booking API allows the implementer to modify data. Please request the TableCheck API Team to prepare test data to facilitate your development.

https://api.tablecheck.com/api/booking/v1/...

Interactive API console

https://api.tablecheck.com/api/booking/v1/docs

Refer to Using the API Console for help.

Rate Limits

Implementation Workflow

The following is a general outline of how to implement this API:

  1. Please request access for specific Shops by contacting api@tablecheck.com. (Access requests will be moved to an API in the future.)

  2. Search for available booking times across Shops using the Availability API.

  3. (Optional but recommend) If you are doing a checkout process, before creating a reservation, use the POST /blockages endpoint to make a "Blockage" object which locks the table until the end user completes checkout. This Blockage will expire after 5 minutes, however you can do PUT /blockage/{id} to renew the 5-minute expiry.

  4. Use POST /reservations to make a reservation. You must pass the Blockage ID to the reservation in this API call.

  5. To amend an existing reservation use PUT /reservations/{id}. If you are changing the time or party size, you must first create a Blockage.

  6. To cancel the reservation, use PUT /reservations/{id}/cancel. You may optionally specify cancel reason.

  7. Get updates to reservations using the Sync API.

  8. To fetch a list of all reservations, use GET /reservations/ with various query parameters.

Creating a Blockage

Before creating a reservation, you must first create a Blockage object which locks the table for booking based on time and party size. Creating blockages should be integrated into your end-user's reservation workflow. We recommend to create the blockage when the user arrives at the "Confirmation Page" (i.e. when date, time, and party size are known), and then finalize the reservation when the user clicks "Confirm". 

🔗 API Console

POST /ts_api/booking/v1/blockages { "shop_id": "chez-vesper", "start_at": "2020-02-12T19:00:00+0900", "pax": 2 }

Amending Blockage and/or Extending Blockage Lifetime

By default Blockages will expire after 5 minutes, however you can update the Blockage to renew the 5-minute expiry. You may also amend a Blockage with a new time and party size, however, this amendment may be rejected if no table is available for the new values.

🔗 API Console

PUT /ts_api/booking/v1/blockages/5e4014ae801a0a5efc000137 { "start_at": "2020-02-12T19:30:00+0900", "pax": 3 }

Creating/Finalizing a Reservation

The API will try to create a Reservation even if the Blockage has expired, but is not guaranteed to succeed in this case.

🔗 API Console

POST /ts_api/booking/v1/reservations { "shop_id": "chez-vesper", "blockage_id": "5e4014ae801a0a5efc000137", "start_at": "2020-02-12T19:30:00+0900", "pax": 3 }

Amending a Reservation

Only a subset of the parameters can be amended.

🔗 API Console

PUT /ts_api/booking/v1/reservations/ae801a0a55e4014efc000137 { "blockage_id": "5e4014ae801a0a5efc000137", "start_at": "2020-02-12T19:30:00+0900", "pax": 3 }

Cancelling a Reservation

🔗 API Console

PUT /ts_api/booking/v1/reservations/ae801a0a55e4014efc000137/cancel { "cancel_reason_type": "mistake", "cancel_reason": "Cancelled due to weather" }

Reservation Cancellation Limitations

When using PUT /ts_api/booking/v1/reservations/{id}/cancel , be aware of the following limitations:

  • Reservations cannot be cancelled if they are in the past (i.e., the reservation time has already passed)

  • Reservations cannot be cancelled if they are in "seated" status (e.g., when customers have already arrived at the venue)

If a cancellation is attempted under these conditions, the API will respond with an error code reservation_cannot_be_cancelled_by_user and provide specific validation messages explaining why the cancellation failed.

{ "error": { "code": "reservation_cannot_be_cancelled_by_user", "message": "Reservation cancellation failed: reservation is in the past" } }

Fetching a List of Reservations

The following query will fetch all reservations for one day. The result will be paginated. Refer to API Console for full list of available query parameters.

🔗 API Console

GET /ts_api/booking/v1/reservations?start_at_min=2020-01-01T0:00:00Z&start_at_max=2020-01-02T0:00:00Z&page=3

 

For further inquiries and assistance, please contact api@tablecheck.com