Book reservations directly into TableCheck's inventory backend. Create, read, update, and cancel reservations; manage blockages and reservation flags; and list shops. Available by special arrangement with TableCheck - in most cases the Web Booking API is used instead.
# Test and edit this file at https://editor.swagger.io/
openapi: 3.0.0
info:
version: 1.0.1
title: TableCheck API - Booking V1
description: The Booking API is used to book reservations directly into TableCheck's inventory backend.
termsOfService: https://tablecheck.atlassian.net/wiki/spaces/API/pages/61571353/TableCheck+API+Terms+of+Service
externalDocs:
description: Implementation Guide
url: https://tablecheck.atlassian.net/wiki/spaces/API/pages/160334455/Booking+v1
servers:
- url: https://api.tablecheck.com/api/booking/v1/
description: Production (uses live data)
paths:
/blockages:
post:
summary: Create Blockage
operationId: createBlockage
tags:
- blockages
requestBody:
required: true
content:
application/json:
schema:
'$ref': "#/components/schemas/BlockageCreateParams"
responses:
'200':
description: The Blockage which was created
content:
application/json:
schema:
$ref: "#/components/schemas/BlockageShowResponse"
'400': &BadRequest
description: Bad Request
content:
application/json:
schema:
$ref: "#/components/schemas/BadRequestError"
'403': &ForbiddenError
description: Forbidden
content:
application/json:
schema:
$ref: "#/components/schemas/ForbiddenError"
'422': &UnprocessableEntityError
description: Unprocessable Entity
content:
application/json:
schema:
'$ref': "#/components/schemas/UnprocessableEntityError"
/blockages/{blockage_id}:
get:
summary: Fetch a specific Blockage
operationId: showBlockageById
tags:
- blockages
parameters:
- name: blockage_id
in: path
required: true
description: The ID or ref of the Blockage to retrieve
schema:
type: string
- $ref: '#/components/parameters/IncludeFields'
- $ref: '#/components/parameters/ExcludeFields'
responses:
'200':
description: The specified Blockage
content:
application/json:
schema:
$ref: "#/components/schemas/BlockageShowResponse"
'400': *BadRequest
'403': *ForbiddenError
'404': &NotFoundError
description: Not Found
content:
application/json:
schema:
$ref: "#/components/schemas/NotFoundError"
'410': &ExpiredError
description: Expired
content:
application/json:
schema:
$ref: "#/components/schemas/ExpiredError"
'422': *UnprocessableEntityError
put:
summary: Update Blockage
operationId: updateBlockage
tags:
- blockages
parameters:
- name: blockage_id
in: path
required: true
description: The ID of the Blockage to update
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
'$ref': "#/components/schemas/BlockageUpdateParams"
responses:
'200':
description: The Blockage which was updated
content:
application/json:
schema:
$ref: "#/components/schemas/BlockageShowResponse"
'400': *BadRequest
'403': *ForbiddenError
'404': *NotFoundError
'410': *ExpiredError
'422': *UnprocessableEntityError
delete:
summary: Delete Blockage
operationId: deleteBlockage
tags:
- blockages
parameters:
- name: blockage_id
in: path
required: true
description: The ID or ref of the Blockage to delete
schema:
type: string
responses:
'200':
description: The Blockage was deleted
'400': *BadRequest
'403': *ForbiddenError
'404': *NotFoundError
'410': *ExpiredError
'422': *UnprocessableEntityError
/reservations:
get:
summary: List all Reservations
operationId: listReservations
tags:
- reservations
parameters:
- name: ids
in: query
description: Array or comma-separated list of specific reservation IDs to return.
required: false
schema:
type: string
format: bson-id
example: ae5355ca1fd337ed5d6893e2
- name: shop_ids
in: query
description: Array or comma-separated list of shop IDs to filter reservations.
required: false
schema:
type: string
format: bson-id
example: ae5355ca1fd337ed5d6893e2
- name: created_at_min
in: query
description: Search lower bound of created_at field (ISO timestamp).
required: false
schema:
type: string
format: date-time
example: '2020-01-29T19:00:00Z'
- name: created_at_max
in: query
description: Search upper bound of created_at field (ISO timestamp).
required: false
schema:
type: string
format: date-time
example: '2020-01-29T19:00:00Z'
- name: updated_at_min
in: query
description: Search lower bound of updated_at field (ISO timestamp).
required: false
schema:
type: string
format: date-time
example: '2020-01-29T19:00:00Z'
- name: updated_at_max
in: query
description: Search upper bound of updated_at field (ISO timestamp).
required: false
schema:
type: string
format: date-time
example: '2020-01-29T19:00:00Z'
- name: start_at_min
in: query
description: Search lower bound of start_at field (ISO timestamp).
required: false
schema:
type: string
format: date-time
example: '2020-01-29T19:00:00Z'
- name: start_at_max
in: query
description: Search upper bound of start_at field (ISO timestamp).
required: false
schema:
type: string
format: date-time
example: '2020-01-29T19:00:00Z'
- name: page
in: query
description: The zero-based page number. Used for pagination.
required: false
schema:
type: number
format: integer
minimum: 0
- name: per_page
in: query
description: Number of items to return at once. Used for pagination.
required: false
schema:
type: number
format: integer
default: 100
minimum: 1
maximum: 200
- name: sort
in: query
description: The field by which to sort the results.
required: false
schema:
type: string
default: start_at
enum: ["created_at","updated_at","start_at"]
- name: sort_order
in: query
description: The direction to sort the results (asc or desc.)
required: false
schema:
default: asc
enum: ["asc","desc"]
type: string
- name: customer_ids
in: query
description: Array or comma-separated list of customer IDs to filter reservations.
required: false
schema:
type: string
format: bson-id
example: f2ab06ff5d03d98e316513e1
- name: service_category_ids
in: query
description: Array or comma-separated list of service category IDs to filter reservations.
required: false
schema:
type: string
format: bson-id
example: 6513e1b06ff2a98e31f5d03d
responses:
'200':
description: A paged array of reservations
content:
application/json:
schema:
$ref: "#/components/schemas/ReservationsListResponse"
'400': *BadRequest
'403': *ForbiddenError
'422': *UnprocessableEntityError
post:
summary: Create Reservation
operationId: createReservation
tags:
- reservations
requestBody:
required: true
content:
application/json:
schema:
'$ref': "#/components/schemas/ReservationCreateParams"
responses:
'200':
description: The Reservation which was created
content:
application/json:
schema:
$ref: "#/components/schemas/ReservationShowResponse"
'400': *BadRequest
'403': *ForbiddenError
'422': *UnprocessableEntityError
/reservations/{reservation_id_or_ref}:
get:
summary: Fetch a specific Reservation
operationId: showReservationById
tags:
- reservations
parameters:
- name: reservation_id_or_ref
in: path
required: true
description: The ID or ref of the Reservation to retrieve
schema:
type: string
- $ref: '#/components/parameters/IncludeFields'
- $ref: '#/components/parameters/ExcludeFields'
responses:
'200':
description: The specified Reservation
content:
application/json:
schema:
$ref: "#/components/schemas/ReservationShowResponse"
'400': *BadRequest
'403': *ForbiddenError
'404': *NotFoundError
'422': *UnprocessableEntityError
put:
summary: Update Reservation
operationId: updateReservation
tags:
- reservations
parameters:
- name: reservation_id_or_ref
in: path
required: true
description: The ID or ref of the Reservation to update
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
'$ref': "#/components/schemas/ReservationUpdateParams"
responses:
'200':
description: The Reservation which was updated
content:
application/json:
schema:
$ref: "#/components/schemas/ReservationShowResponse"
'400': *BadRequest
'403': *ForbiddenError
'404': *NotFoundError
'422': *UnprocessableEntityError
/reservations/{reservation_id_or_ref}/cancel:
put:
summary: Cancel Reservation
operationId: cancelReservation
tags:
- reservations
parameters:
- name: reservation_id_or_ref
in: path
required: true
description: The ID or ref of the Reservation to cancel
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
'$ref': "#/components/schemas/ReservationCancelParams"
responses:
'200':
description: The Reservation which was cancelled
content:
application/json:
schema:
$ref: "#/components/schemas/ReservationShowResponse"
'400': *BadRequest
'403': *ForbiddenError
'404': *NotFoundError
'422': *UnprocessableEntityError
/reservation_flags:
get:
summary: List all Reservation Flags
operationId: listReservationFlags
tags:
- reservation_flags
parameters:
- name: ids
in: query
description: Array or comma-separated list of specific reservation flag IDs to return.
required: false
schema:
type: string
format: bson-id
example: ae5355ca1fd337ed5d6893e2
- name: shop_ids
in: query
description: Array or comma-separated list of shop IDs to filter reservation flags.
required: false
schema:
type: string
format: bson-id
example: ae5355ca1fd337ed5d6893e2
- name: created_at_min
in: query
description: Search lower bound of created_at field (ISO timestamp).
required: false
schema:
type: string
format: date-time
example: '2020-01-29T19:00:00Z'
- name: created_at_max
in: query
description: Search upper bound of created_at field (ISO timestamp).
required: false
schema:
type: string
format: date-time
example: '2020-01-29T19:00:00Z'
- name: updated_at_min
in: query
description: Search lower bound of updated_at field (ISO timestamp).
required: false
schema:
type: string
format: date-time
example: '2020-01-29T19:00:00Z'
- name: updated_at_max
in: query
description: Search upper bound of updated_at field (ISO timestamp).
required: false
schema:
type: string
format: date-time
example: '2020-01-29T19:00:00Z'
- name: page
in: query
description: The zero-based page number. Used for pagination.
required: false
schema:
type: number
format: integer
minimum: 0
- name: per_page
in: query
description: Number of items to return at once. Used for pagination.
required: false
schema:
type: number
format: integer
default: 100
minimum: 1
maximum: 1000
responses:
'200':
description: A paged array of reservation flags
content:
application/json:
schema:
$ref: "#/components/schemas/ReservationFlagsListResponse"
'400': *BadRequest
'403': *ForbiddenError
'422': *UnprocessableEntityError
/reservation_flags/{reservation_flag_id}:
get:
summary: Fetch a specific Reservation Flag
operationId: showReservationFlagById
tags:
- reservation_flags
parameters:
- name: reservation_flag_id
in: path
required: true
description: The ID of the Reservation Flag to retrieve
schema:
type: string
responses:
'200':
description: The specified Reservation Flag
content:
application/json:
schema:
$ref: "#/components/schemas/ReservationFlagShowResponse"
'400': *BadRequest
'403': *ForbiddenError
'404': *NotFoundError
'422': *UnprocessableEntityError
/shops:
get:
summary: List all shops
operationId: listShops
tags:
- shops
parameters:
- name: ids
in: query
description: Array or comma-separated list of specific IDs to return.
required: false
schema:
type: string
format: bson-id
- name: slugs
in: query
description: Array or comma-separated list of specific slugs to return.
required: false
schema:
type: string
- name: page
in: query
description: The zero-based page number. Used for pagination.
required: false
schema:
type: number
format: integer
minimum: 0
- name: per_page
in: query
description: Number of items to return at once. Used for pagination.
required: false
schema:
type: number
format: integer
default: 20
minimum: 1
maximum: 100
- name: sort
in: query
description: The field by which to sort the results. Distance sort is applied only if geo parameters are present.
required: false
schema:
type: string
default: distance
enum:
- distance
- slug
- name
- budget_lunch
- budget_dinner
- name: sort_order
in: query
description: asc or desc.
required: false
schema:
default: asc
enum:
- asc
- desc
type: string
- name: name
in: query
description: Filter by the shop name.
required: false
schema:
type: string
- name: geo_latitude
in: query
description: The latitude of the geocode center point used to evaluate distance query.
required: false
schema:
type: number
format: float
- name: geo_longitude
in: query
description: The longitude of the geocode center point used to evaluate distance query.
required: false
schema:
type: number
format: float
- name: geo_distance
in: query
description: The maximum distance in meters from the geocode center point from which to return results.
required: false
schema:
type: number
format: float
- name: cuisines
in: query
description: Array or comma-separated list of cuisine keys to return.
required: false
schema:
type: string
- name: tags
in: query
description: Array or comma-separated list of tag keys to return.
required: false
schema:
type: string
- name: service_modes
in: query
description: Service mode selection of dining, pickup, etc. (array or comma-separated list)
required: false
schema:
type: string
enum:
- dining
- pickup
- delivery
- voucher
- name: budget_lunch_min
in: query
description: Minimum of lunch budget range filter.
required: false
schema:
type: number
format: float
minimum: 0
- name: budget_lunch_max
in: query
description: Maximum of lunch budget range filter.
required: false
schema:
type: number
format: float
minimum: 0
- name: budget_dinner_min
in: query
description: Minimum of dinner budget range filter.
required: false
schema:
type: number
format: float
minimum: 0
- name: budget_dinner_max
in: query
description: Maximum of dinner budget range filter.
required: false
schema:
type: number
format: float
minimum: 0
- name: address_city
in: query
description: Filter by the shop's address city, ward, or municipality.
required: false
schema:
type: string
- name: address_region
in: query
description: Filter by the shop's address region, state, or province.
required: false
schema:
type: string
- name: address_postal_code
in: query
description: Filter by the shop's address postal code.
required: false
schema:
type: string
- name: address_country
in: query
description: Filter by the shop's address country.
required: false
schema:
type: string
responses:
'200':
description: A paged array of shops
content:
application/json:
schema:
$ref: "#/components/schemas/ShopsListResponse"
default:
description: Error response
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/shops/{shop_id}:
get:
summary: Fetch a specific shop
operationId: showShopById
tags:
- shops
parameters:
- name: shop_id
in: path
required: true
description: The id or slug of the shop to retrieve
schema:
type: string
responses:
'200':
description: Expected response to a valid request
content:
application/json:
schema:
$ref: "#/components/schemas/ShopShowResponse"
default:
description: Error response
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: AUTHORIZATION
parameters:
IncludeFields:
name: include_fields
in: query
description: Comma-separated list of fields to include in the response (whitelist). If specified, only the listed fields will be returned. Supports dot notation for nested fields.
required: false
schema:
type: string
example: id,name,addresses.city
ExcludeFields:
name: exclude_fields
in: query
description: Comma-separated list of fields to exclude from the response (blacklist). All fields except the given ones will be returned. Supports dot notation for nested fields.
required: false
schema:
type: string
example: created_at,socials.username
schemas:
BlockageUpdateParams:
type: object
properties:
start_at:
description: The time at which the party wishes to arrive. If blank, will be unchanged.
type: string
format: date-time
example: '2020-01-29T19:15:00Z'
expires_at:
description: The timestamp for when the blockage will expire. The valid range is from 59 seconds into the future until 1 day and 1 second ahead of the current time.
type: string
format: date-time
example: '2020-01-29T19:20:00Z'
expiry_ttl:
description: The time-to-live in seconds for the Blockage (from 59 to 86401). If expires_at is set, this will be ignored.
type: number
format: integer
example: 300
pax:
description: The party size. If blank, will be unchanged.
type: number
format: integer
example: 3
seat_types:
description: Indicates what kind of seating the customer would like to receive, e.g. table, counter, private room, etc. (array or comma-separated list)
type: array
items:
type: string
enum: ["open","counter","outside","curtain","private","tatami"]
smoking:
description: The customer's smoking preference.
type: string
enum: ["none","true","false"]
service_category_id:
description: The Service Category ID of the table.
type: string
format: bson-id
example: 63ac197654cef38651ccd896
WebTrackingParams:
type: object
properties: &WebTrackingParams
user_agent:
description: The browser user agent string of the end user.
type: string
example: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.77 Safari/537.36"
user_ip:
description: The IP address of the end user.
type: string
format: ip-address
example: 145.0.34.255
utm_id:
description: Aggregate identifier for all UTM parameters.
type: string
example: my-id-124723
utm_source:
description: Identifies which site sent the traffic.
type: string
example: google
utm_medium:
description: Identifies what type of link was used, such as cost per click or email.
type: string
example: cpc
utm_campaign:
description: Identifies a specific product promotion or strategic campaign.
type: string
example: spring_sale
utm_term:
description: Identifies search terms.
type: string
example: ginza+italian
utm_content:
description: Identifies what specifically was clicked to bring the user to the site, such as a banner ad or a text link. It is often used for A/B testing and content-targeted ads.
type: string
example: logolink
BlockageSharedParams:
type: object
properties: &BlockageSharedParams
shop_id:
description: The ID of Shop where the Blockage should be created.
type: string
format: bson-id
example: ae5355ca1fd337ed5d6893e2
reservation_id:
description: The Reservation ID in TableCheck or reservation ref in your system. Use only when updating a Reservation.
type: string
format: bson-id
example: "Use only if amending reservation"
start_at:
description: The time at which the party wishes to arrive.
type: string
format: date-time
example: '2020-01-29T19:15:00Z'
expires_at:
description: The timestamp at which the Blockage will expire.
type: string
format: date-time
example: '2020-01-29T19:20:00Z'
pax:
description: The party size.
type: number
format: integer
example: 3
seat_types:
description: Indicates what kind of seating the customer would like to receive, e.g. table, counter, private room, etc. (array or comma-separated list)
type: array
items:
type: string
enum: ["open","counter","outside","curtain","private","tatami"]
smoking:
description: The customer's smoking preference.
type: string
enum: ["none","true","false"]
table_ids:
description: The IDs of the Tables assigned to the Blockage.
type: array
items:
type: string
format: bson-id
example: 641d4902bc54f4a840119a49
BlockageCreateParams:
type: object
required:
- description
- start_at
- pax
properties: &BlockageCreateParams
<<: *BlockageSharedParams
expires_at:
description: The timestamp for when the blockage will expire. The valid range is from 59 seconds into the future until 1 day and 1 second ahead of the current time.
type: string
format: date-time
example: '2020-01-29T19:20:00Z'
expiry_ttl:
description: The time-to-live in seconds for the Blockage (from 59 to 86401). If expires_at is set, this will be ignored.
type: number
format: integer
example: 300
service_category_id:
description: The Service Category ID of the table.
type: string
format: bson-id
example: 63ac197654cef38651ccd896
Blockage:
type: object
properties:
id:
description: TableCheck's database ID of the Blockage. Needed for Reservation creation and updating.
type: string
format: bson-id
example: ae5355ca1fd337ed5d6893e2
created_at:
description: The timestamp of when the Blockage was created.
type: string
format: date-time
example: '2020-01-29T19:12:34Z'
updated_at:
description: The timestamp of when the Blockage was last updated.
type: string
format: date-time
example: '2020-01-29T19:12:34Z'
<<: *BlockageSharedParams
expires_at:
description: The timestamp at which the Blockage will expire.
type: string
format: date-time
example: '2020-01-29T19:12:34Z'
<<: *WebTrackingParams
BlockageShowResponse:
type: object
properties:
blockage:
$ref: "#/components/schemas/Blockage"
ReservationSharedParams:
type: object
properties: &ReservationSharedParams
blockage_id:
description: A non-expired Blockage ID obtained via API (see /blockages/ endpoint). The Blockage will be deleted once the Reservation is created/updated. This parameter is used only when creating/updating Reservations and is not included in the Reservation response.
type: string
format: bson-id
example: ae5355ca1fd337ed5d6893e2
source:
description: The general method by which the Reservation was made ("web", "phone", etc.) If not set, when creating a Reservation it will be defaulted to source "web" to indicate an online booking.
type: string
enum: ["phone","ivrs","sms","web","email","in_person","walk_in","app","other"]
channel:
description: The website or sales channel by which the Reservation was made. Can be modified by the merchant.
type: string
example: instagram
special_request:
description: Free-text additional request made by the customer at time of booking. May be used to include special requests, dietary restrictions, etc.
type: string
memo:
description: A free-text internal memo for the Reservation used only by merchant staff. Contains notes about the reservation, customer, or other details. If special_request is not set, memo will be automatically copied to special_request.
type: string
memo2:
description: Secondary free-text internal memo for the Reservation used only by merchant staff.
type: string
purpose:
description: The occasion for which customer booked.
type: string
example: birthday
enum: ["birthday","birthday_self","birthday_friends","birthday_couple","birthday_spouse","birthday_family","group","group_women","group_farewell","group_holiday","group_reunion","group_wedding","group_travel","business","business_internal","business_farewell","business_holiday","family","family_celebration","family_baby","family_kids","family_intro","family_engagement","family_memorial","date","date_group","date_proposal","date_anniversary","date_celebration","event","event_seminar","event_recital","event_expo","event_film","other"]
seat_types:
description: Indicates what kind of seating the customer would like to receive, e.g. table, counter, private room, etc. (array or comma-separated list)
type: array
items:
type: string
enum: ["open","counter","outside","curtain","private","tatami"]
smoking:
description: The customer's smoking preference.
type: string
enum: ["none","true","false"]
ref:
description: Your identifier for the Reservation.
type: string
pax_adult:
description: The number of adults attending the Reservation.
type: number
format: integer
example: 3
pax_senior:
description: The number of senior citizens attending the Reservation.
type: number
format: integer
example: 2
pax_child:
description: The number of children attending the Reservation.
type: number
format: integer
example: 0
pax_baby:
description: The number of babies attending the Reservation.
type: number
format: integer
example: 1
reservation_flag_ids:
description: The IDs of the ReservationFlags assigned to the Reservation.
type: array
items:
type: string
format: bson-id
<<: *WebTrackingParams
ReservationUpdateParams:
type: object
properties: &ReservationUpdateParam
# --- truncated at 32 KB (58 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tablecheck/refs/heads/main/openapi/tablecheck-booking.yml