# Test and edit this file at https://editor.swagger.io/ openapi: 3.0.0 info: version: 1.0.0 title: TableCheck API - Web Booking V1 description: The Web Booking API allows you to query reservations which your diner users booked via the TableCheck website. 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/48595292/Web+Booking+v1 servers: - url: https://api.tablecheck.com/api/web_booking/v1/ description: Production (uses live data) paths: /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 - $ref: '#/components/parameters/IncludeFields' - $ref: '#/components/parameters/ExcludeFields' responses: '200': description: A paged array of reservations content: application/json: schema: $ref: "#/components/schemas/ReservationsListResponse" '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" /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 description: Not Found content: application/json: schema: $ref: "#/components/schemas/NotFoundError" '422': *UnprocessableEntityError 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: Reservation: type: object required: - start_at - pax - last_name - locale - phone properties: id: description: TableCheck's database ID of the Reservation. type: string format: bson-id example: ae5355ca1fd337ed5d6893e2 ref: description: The Reservation ID according to your system. type: string example: AbC123DeF code: description: TableCheck's short code for the Reservation. May be displayed to user. type: string example: ABC123 url: description: TableCheck's short URL to manage the Reservation. May be displayed to user. type: string format: url example: https://tblc.hk/rABC123 created_at: description: The timestamp of when the Reservation was created. type: string format: date-time example: '2020-01-29T19:12:34Z' updated_at: description: The timestamp of when the Reservation was last updated. type: string format: date-time example: '2020-01-29T19:12:34Z' shop_slug: description: TableCheck's web ID of Shop to which the Reservation belongs. type: string example: my-shop-slug shop_id: description: The ID of Shop to which the Reservation belongs. type: string format: bson-id example: ae5355ca1fd337ed5d6893e2 start_at: description: The time at which the party wishes to arrive for the Reservation. Must match the Blockage start_at value. type: string format: date-time example: '2020-01-29T19:15:00Z' pax: description: The party size of the Reservation. Must match the Blockage pax value. type: number format: integer example: 3 memo: description: Free-text memo which may include payment info, special requests, allergies, etc. type: string customer_ref: description: Your identifier for the Customer, which you may set via the URL parameter "customer_ref" when linking to the booking form. This field will be null if you do not set "customer_ref" in the URL. type: string first_name: description: The Customer's given name. Preferred to be in English. type: string last_name: description: The Customer's family name. Preferred to be in English. type: string alt_first_name: description: An alternate given name for the Customer, e.g. in Chinese characters. type: string alt_last_name: description: An alternate family name for the Customer, e.g. in Chinese characters. type: string gender: description: The Customer's gender. type: string enum: ["male","female"] locale: description: The language in which Customer should receive messages. type: string enum: ["en","ja","ko","zh-CN","zh-TW","de","es","fr","nl","it","pt","tr","ru","id","ms","tl","th","lo","km","vi","ar","he","hi"] email: description: The Customer's email address. type: string format: email phone: description: The Customer's phone number, which may be either a landline or mobile number. type: string format: phone-e164 example: '+81312345678' sms_number: description: The Customer's mobile phone number for SMS notifications. type: string format: phone-e164 example: '+818012345678' enable_sms: description: Indicates whether the Customer would like to receive SMS notifications for this reservation. Default false. type: boolean allow_marketing: description: Indicates whether the restaurant is allowed to do direct marketing to the Customer's email or phone. Default false. type: boolean customer_id: description: TableCheck's database ID of the Customer. type: string format: bson-id example: ae5355ca1fd337ed5d6893e2 status: description: The status of the Reservation. type: string enum: ["tentative","pending","request","accepted","confirmed","attended","cancelled","noshow","rejected","iou_prepay","iou_auth"] cancel_reason_type: description: The enumerated reason for cancellation. type: string enum: ["mistake","shop","travel","deal","delay","personal","covid","other"] cancel_reason: description: Free-text reason for cancellation. type: string example: 'Cancelled due to weather' cancel_policy_html: description: HTML representation of the venue's cancellation policy, including any applicable cancel fee rules. type: string format: html is_tablecheck: description: Indicates whether the reservation was booked through via the TableCheck online booking page. type: boolean can_cancel: description: Indicates whether the end user should be allowed to cancel the reservation. type: boolean can_amend: description: Indicates whether the end user should be allowed to amend the reservation. type: boolean can_confirm: description: Indicates whether the end user should be allowed to set the reservation status to "confirmed". type: boolean # booking_fee_amt: # description: Special charge collected by TableCheck which is separate from all other payment amounts. It is not reflected in payment_total_amt, grand_total_amt or other fields. # type: string # format: amt allow_provider_marketing: description: Whether the diner has opted-in to receive the provider's (i.e. your) marketing mails. type: boolean currency: description: The ISO currency code of the reservation's payment transactions. type: string format: currency payment_type: description: The type of payment action. type: string enum: ['prepay', 'auth', 'store', 'none'] payment_group_fee_amt: description: The table charge (per-group fee) used for payment, if applicable. type: string format: amt payment_pax_fee_amt: description: The cover charge (per-pax fee) used for payment, if applicable. type: string format: amt payment_subtotal_amt: description: The subtotal for online payment, which includes order amounts, per-group fee, and per-pax fee. It does not include discount, service fee, delivery fee or tax. type: string format: amt payment_discount_amt: description: The discount amount applicable to online payment, e.g. from an applied promo code. type: string format: amt payment_service_fee_amt: description: The service fee applicable to online payment. type: string format: amt payment_total_amt: description: The final total amount to be charged as an online payment. If this amount is zero, then there is no payment to be charged. type: string format: amt payment_tax_amt: description: The tax fee applicable to online payment. type: string format: amt cash_subtotal_amt: description: The portion of the order total which is due at the venue. type: string format: amt cash_discount_amt: description: The discount amount applicable to the amount due at the venue, e.g. from an applied promo code. type: string format: amt cash_service_fee_amt: description: The service fee applicable to the amount due at the venue. type: string format: amt cash_tax_amt: description: The tax applicable to the amount due at the venue. type: string format: amt cash_total_amt: description: The final amount due at the venue, i.e. not to be charged by online payment. type: string format: amt grand_total_amt: description: The sum of cash_total_amt and payment_total_amt, which represents the total monetary amount for the booking. type: string format: amt orders: description: The ordered items in the reservation. type: array items: $ref: "#/components/schemas/ReservationOrder" ReservationOrder: type: object properties: id: description: TableCheck's database ID of the Order. type: string format: bson-id example: ae5355ca1fd337ed5d6893e2 menu_item_name_translations: description: An array of translation strings of the menu item name. type: array items: type: object example: en: Sushi ja: 寿司 price: description: The price of a single menu item within the order. type: string format: decimal qty: description: The quantity of the Order, i.e. the number of menu item to purchase. type: number format: integer ReservationsListResponse: type: object properties: reservations: type: array items: $ref: "#/components/schemas/Reservation" pagination: $ref: "#/components/schemas/PaginationData" ReservationShowResponse: type: object properties: reservation: $ref: "#/components/schemas/Reservation" PaginationData: type: object properties: page: type: number format: integer example: 3 per_page: type: number format: integer example: 100 # page_count: # type: number # format: integer # example: 8 # item_count: # type: number # format: integer # example: 742 BadRequestError: required: - errors properties: errors: type: array items: type: object properties: code: type: string example: parameter_missing message: type: string example: Required parameter is missing. ForbiddenError: required: - errors properties: errors: type: array items: type: object properties: code: type: string example: api_key_invalid message: type: string example: Your API key is invalid. NotFoundError: required: - errors properties: errors: type: array items: type: object properties: code: type: string example: resource_not_found message: type: string example: Resource not found. UnprocessableEntityError: required: - errors properties: errors: type: array items: type: object properties: code: type: string example: not_created message: type: string example: Could not create resource due to missing parameter. security: - ApiKeyAuth: []