TableCheck reservations API

openapi: 3.2.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:
    ReservationSingleResponse:
      type: object
      properties:
        reservation:
          $ref: '#/components/schemas/Reservation_3'
    ReservationCancelParams:
      type: object
      properties:
        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
    Event:
      type: object
      example:
        date: 01-01-2020
        tag: anniversary
      properties:
        id:
          description: The database ID of the Event.
          type: string
          format: bson-id
        tag:
          type: string
          enum:
          - anniversary
          - birthday
          - single
          - 1_month
          - 2_month
          - 3_month
          - 6_month
          - 1_year
        date:
          description: '[PII] The first occurrence date of the event. Note the year value 9996 means the year is unspecified.'
          type: string
          format: date
        months:
          description: The integer month(s) in which the event occurs, with January = 1, February = 2, etc.
          type: array
          items:
            type: number
            format: integer
        day:
          description: The day on which the event occurs.
          type: number
          format: integer
        memo:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Emails:
      description: '[PII] A list of Email objects.'
      type: array
      items:
        $ref: '#/components/schemas/Email'
    ReservationsListResponse:
      type: object
      properties:
        reservations:
          type: array
          items:
            $ref: '#/components/schemas/Reservation'
        pagination:
          $ref: '#/components/schemas/PaginationData'
    ReservationFlag:
      type: object
      properties:
        id:
          description: TableCheck's database ID of the Reservation Flag.
          type: string
          format: bson-id
          example: ae5355ca1fd337ed5d6893e2
        franchise_id:
          description: The ID of Franchise to which the Reservation Flag belongs.
          type: string
          format: bson-id
        shop_ids:
          description: 'Constrains the Shops for which the Reservation Flag will be applied.

            An empty array means "all Shops" (no restriction).

            '
          type: array
          default: []
          items:
            type: string
            format: bson-id
            example: ae5355ca1fd337ed5d6893e2
        all_shops:
          description: Apply the Reservation Flag to all shops.
          type: boolean
        name:
          description: Reservation Flag name.
          type: string
        description:
          description: Reservation Flag description.
          type: string
        icon:
          description: Reservation Flag icon name.
          type: string
        color:
          description: Reservation Flag icon color.
          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'
    MenuItemEmbed:
      type: object
      properties:
        id:
          type: string
          format: bson-id
        name_translations:
          type: string
        internal_name:
          type: string
    ReservationShowResponse_2:
      type: object
      properties:
        reservation:
          $ref: '#/components/schemas/Reservation_2'
        reservation_flags:
          type: array
          items:
            $ref: '#/components/schemas/ReservationFlag'
    ReservationUpdateParams_2:
      type: object
      properties:
        customer_ref:
          description: The identifier you supplied for an existing customer.
          type: string
        customer_id:
          description: The identifier of an existing customer.
          type: string
        ref:
          description: Your identifier for the reservation.
          type: string
        pax:
          description: The total party size of the Reservation. May be specified as an alternative to pax_adult.
          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
        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. It is recommended not to set this parameter, as the system will determine duration automatically. If you have previously set duration, transmitting duration as null will revert to the auto-set state.
          type: number
          format: seconds
          example: 7200
        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 web site or sales channel by which the Reservation was made.
          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.
          type: string
        memo2:
          description: Secondary free-text internal memo for the Reservation used only by merchant staff.
          type: string
        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'
        status:
          description: The status of the Reservation. It is recommended not to set this parameter, as the system will assign status automatically.
          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
        points:
          description: The number of reward points redeemed by the customer via the provider system.
          type: number
          format: integer
          example: 200
        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 email notifications to the Customer for this Reservation. Default false.
          type: boolean
        send_texts:
          description: Indicates whether to send text message notifications to the Customer for this Reservation. Requires phone parameter to be a mobile number. Default false.
          type: boolean
        email:
          description: The email address designated by the customer to receive notifications for this reservation.
          type: string
          format: email
        phone:
          description: The phone number designated by the customer to receive text messages and calls regarding this reservation.
          type: string
          format: phone-e164
        reservation_flag_ids:
          description: The reservation flags ids.
          type: array
          items:
            type: string
            example: 64ddfe5b6ff2a916b29dc902
        images:
          description: Images
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/ImageEmbedCreate'
            - $ref: '#/components/schemas/ImageEmbedDestroy'
    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.
    Phone:
      type: object
      required:
      - number
      properties:
        id:
          description: The database ID of the Phone object.
          type: string
          format: bson-id
        number:
          description: '[PII] The phone number in E.164 format.'
          type: string
          format: phone-e164
        tag:
          type: string
          enum:
          - none
          - home
          - work
          - mobile
          - assistant
          - fax
          - other
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    MenuItemNameTranslation:
      type: object
      properties:
        translation:
          type: string
          example: sushi
        locale:
          type: string
          example: en
    ShopEmbed:
      type: object
      properties:
        id:
          description: ID of the Shop to which the Reservation belongs.
          type: string
          format: bson-id
          example: ede535ea33fd275ca15d6893
        name_translations:
          description: The name of the Shop where the reservation was booked.
          type: object
          format: translations
          example:
            en: Paris Cafe
            fr: Café de Paris
            ja: カフェデパリ
        internal_name:
          description: The shorthand name of the Shop where the reservation was booked.
          type: object
          format: string
          example: Paris Cafe
        slug:
          description: The web ID of the Shop where the reservation was booked.
          type: string
          example: my-shop-slug
        country:
          description: The country where the Shop is located.
          type: string
          format: country
          example: JP
        currency:
          description: The monetary currency used by the Shop.
          type: string
          format: currency
          example: JPY
        time_zone:
          description: The time zone used by the Shop.
          type: string
          format: time-zone
          example: Asia/Tokyo
    Reservation_3:
      type: object
      properties:
        id:
          descripti

# --- 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