TableCheck reservations API

openapi: 3.0.0
info:
  version: 1.0.0
  title: TableCheck API - V1 availability reservations API
  description: The Availability API is used to obtain near real-time table availability for online reservation booking.
  termsOfService: https://tablecheck.atlassian.net/wiki/spaces/API/pages/61571353/TableCheck+API+Terms+of+Service
servers:
- url: https://api.tablecheck.com/api/availability/v1/
  description: Production (uses live data)
security:
- ApiKeyAuth: []
tags:
- name: reservations
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
      responses:
        '200':
          description: A paged array of reservations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReservationsListResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '422':
          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':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityError'
  /reservations/{reservation_id}:
    get:
      summary: Fetch a specific Reservation
      operationId: showReservationById
      tags:
      - reservations
      parameters:
      - name: reservation_id
        in: path
        required: true
        description: The ID or slug of the Reservation to retrieve
        schema:
          type: string
      - $ref: '#/components/parameters/IncludeFields'
      - $ref: '#/components/parameters/ExcludeFields'
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReservationShowResponse_2'
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      summary: Update Reservation
      operationId: updateReservation
      tags:
      - reservations
      parameters:
      - name: reservation_id
        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_2'
      responses:
        '200':
          description: The Reservation which was updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReservationShowResponse_2'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '404':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityError'
  /shops/{shop_id}/reservations:
    get:
      summary: List all Reservations
      operationId: listReservations
      tags:
      - reservations
      parameters:
      - name: shop_id
        in: path
        required: true
        description: The ID, slug or ref of the Shop
        schema:
          type: string
      - 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: customer_name
        in: query
        description: The name of the customer to search for reservations. Can be full name, first name, or last name.
        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
      - $ref: '#/components/parameters/IncludeFields'
      - $ref: '#/components/parameters/ExcludeFields'
      responses:
        '200':
          description: A paged array of reservations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReservationsListResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/UnprocessableEntityError'
                - $ref: '#/components/schemas/ShopNotFoundError'
  /shops/{shop_id}/reservations/{reservation_id}:
    get:
      summary: Get Reservation information
      operationId: showReservation
      tags:
      - reservations
      parameters:
      - name: shop_id
        in: path
        required: true
        description: The ID, slug or ref of the Shop
        schema:
          type: string
      - name: reservation_id
        in: path
        required: true
        description: The ID or code of the Reservation
        schema:
          type: string
      - $ref: '#/components/parameters/IncludeFields'
      - $ref: '#/components/parameters/ExcludeFields'
      responses:
        '200':
          description: The Reservation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReservationSingleResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
    put:
      summary: Update Reservation
      operationId: updateReservation
      tags:
      - reservations
      parameters:
      - name: shop_id
        in: path
        required: true
        description: The ID, slug or ref of the Shop
        schema:
          type: string
      - name: reservation_id
        in: path
        required: true
        description: The ID or code of the Reservation
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReservationUpdateParams_3'
      responses:
        '200':
          description: The Reservation which was updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReservationSingleResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/UnprocessableEntityError'
                - $ref: '#/components/schemas/ShopNotFoundError'
components:
  schemas:
    ReservationShowResponse:
      type: object
      properties:
        reservation:
          $ref: '#/components/schemas/Reservation'
    ReservationShowResponse_2:
      type: object
      properties:
        reservation:
          $ref: '#/components/schemas/Reservation_2'
        reservation_flags:
          type: array
          items:
            $ref: '#/components/schemas/ReservationFlag'
    Reservation_3:
      type: object
      properties:
        id:
          description: TableCheck's database ID of the Reservation.
          type: string
          format: bson-id
          example: ae5355ca1fd337ed5d6893e2
        franchise_id:
          description: The ID of the Franchise to which the Reservation belongs.
          type: string
          format: bson-id
          example: ae5355ca1fd337ed5d6893e2
        shop_id:
          description: The ID of Shop to which the Reservation belongs.
          type: string
          format: bson-id
          example: ae5355ca1fd337ed5d6893e2
        cancel_reason:
          description: Free-text reason for cancellation.
          type: string
          example: Cancelled due to weather
        cancel_reason_type:
          description: The enumerated reason for cancellation.
          type: string
          enum:
          - mistake
          - shop
          - travel
          - deal
          - delay
          - personal
          - covid
          - other
        channel:
          description: The website or sales channel by which the Reservation was made.
          type: string
          example: instagram
        code:
          description: TableCheck's short code for the Reservation. May be displayed to user.
          type: string
          example: ABC123
        customer_name:
          description: '[PII] The customer''s name.'
          type: string
        duration:
          description: The anticipated seating duration of the reservation, in seconds.
          type: number
          format: seconds
          example: 7200
        locale:
          description: The customer's preferred language.
          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
        memo:
          description: Free-text memo which may include payment info, special requests, allergies, etc.
          type: string
        party_name:
          description: The party or group name for the reservation.
          type: string
        pax:
          description: The party size, i.e. number of people dining.
          type: number
          format: integer
          example: 3
        points:
          description: The number of reward points redeemed by the customer via the provider system.
          type: number
          format: integer
          example: 200
        provider:
          description: The system used to process the reservation (tablecheck, etc.)
          type: string
          example: tablecheck
        provider_ref:
          description: The Reservation ID according to the system which processed the Reservation.
          type: string
          example: ABC123DEF
        purpose:
          description: The reason or occasion for booking, e.g. "birthday".
          type: string
          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
        room_name:
          description: The hotel room number associated with the reservation.
          type: string
        seat_types:
          description: Indicates the seating preference(s) of the customer, e.g. private room.
          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'
        source:
          description: The general method by which the reservation was made ("web", "phone", etc.)
          type: string
          enum:
          - phone
          - ivrs
          - sms
          - web
          - email
          - in_person
          - walk_in
          - app
          - other
        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'
        status:
          description: The status of the Reservation.
          type: string
          enum:
          - tentative
          - pending
          - request
          - accepted
          - confirmed
          - attended
          - cancelled
          - noshow
          - rejected
          - iou_prepay
          - iou_auth
        table_names:
          description: The names of the table(s) at which the party is seated. This is derived from the table objects in TableCheck.
          type: array
          items:
            type: string
        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'
    Reservation_2:
      properties:
        id:
          description: Database ID of the Reservation.
          type: string
          format: bson-id
          example: ae5355ca1fd337ed5d6893e2
        ref:
          type: string
          description: Your identifier for the Reservation.
        franchise_id:
          description: The ID of Franchise to which the Reservation belongs.
          type: string
          format: bson-id
        shop_id:
          description: The ID of Shop to which the Reservation belongs.
          type: string
          format: bson-id
        customer_ids:
          description: The IDs of the Customers to which the Reservation belongs.
          type: array
          items:
            type: string
            format: bson-id
        primary_customer_id:
          description: The ID of primary Customer of Reservation. Refer to "customers" array.
          type: string
          format: bson-id
          example: ede535ea33fd275ca15d6893
        table_ids:
          description: The IDs of the Tables where the Reservation will be seated.
          type: array
          items:
            type: string
            format: bson-id
        service_category_id:
          description: The database ID of the ServiceCategory assigned to the Reservation.
          type: string
          format: bson-id
        promo_id:
          description: The database ID of the Promo assigned to the Reservation.
          type: string
          format: bson-id
        created_at:
          description: The timestamp of when the Reservation was created.
          type: string
          format: date-time
        updated_at:
          description: The timestamp of when the Reservation was last updated.
          type: string
          format: date-time
        start_at:
          description: The time at which the party is scheduled to arrive for the Reservation.
          type: string
          format: date-time
          example: '2020-01-29T19:15:00Z'
        duration:
          description: The planned duration of the Reservation in seconds.
          type: number
          format: seconds
          example: 7200
        pax:
          description: The total party size of the Reservation. This is the sum of the other pax fields.
          type: number
          format: integer
          example: 6
        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
        status:
          description: The status of the Reservation.
          type: string
          enum:
          - tentative
          - pending
          - request
          - accepted
          - confirmed
          - delay
          - call_absent
          - call_message
          - call_wrong
          - cancelled
          - noshow
          - rejected
          - arrived
          - arrived_part
          - waiting
          - waitlist_called
          - seated
          - seated_part
          - service_drink
          - service_main
          - service_dessert
          - check_req
          - paid
          - turnover
          - turned_over
        source:
          description: The general method by which the Reservation was made (web, phone, etc.)
          type: string
          example: web
        channel:
          description: The web site or sales channel by which the Reservation was made.
          type: string
          example: instagram
        provider:
          description: The system used to process the Reservation (tablecheck, etc.)
          type: string
          example: tablecheck
        provider_ref:
          description: The Reservation ID according to the system which processed the Reservation.
          type: string
          example: ABC123DEF
        points:
          description: The number of reward points redeemed by the customer via the provider system.
          type: number
          format: integer
          example: 200
        seat_types:
          description: The seating or table type(s) requested by the customer.
          type: array
          items:
            type: string
            enum:
            - open
            - counter
            - outside
            - curtain
            - private
            - tatami
        smoking:
          description: Indicates whether the customer has requested smoking or non-smoking seats.
          type: string
          enum:
          - none
          - 'true'
          - 'false'
        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.
          type: string
        memo2:
          description: Secondary free-text internal memo for the Reservation used only by merchant staff.
          type: string
        visit_history:
          description: An enumeration indicating roughly how many times the customer has visited the restaurant.
          type: string
          enum:
          - new
          - visit2
          - visit3
          - repeater
          - walk_in
          - no_customer
        party_name:
          description: The party or group name for the reservation.
          type: string
        room_name:
          description: The hotel room number associated with the reservation.
          type: string
        cancel_reason_type:
          description: The enumerated reason for cancellation, if the reservation was cancelled.
          type: string
          enum:
          - mistake
          - shop
          - travel
          - deal
          - delay
          - personal
          - covid
          - other
        cancel_reason:
          description: The memo explaining the reason for cancellation, if the reservation was cancelled.
          type: string
        cancelled_by_customer:
          description: If the reservation was cancelled, this flag if true indicates the cancellation action was performed by the customer (diner) via the web. A false value indicates the cancellation was performed either by the merchant or (in rare cases) automatically by the system.
          type: boolean
        send_emails:
          description: Indicates whether to send the customer email notifications for this reservation.
          type: boolean
        send_texts:
          description: Indicates whether to send 

# --- truncated at 32 KB (105 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tablecheck/refs/heads/main/openapi/tablecheck-reservations-api-openapi.yml