TableCheck pos_journals API

openapi: 3.0.0
info:
  version: 1.0.0
  title: TableCheck API - V1 availability pos_journals 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: pos_journals
paths:
  /shops/{shop_id}/pos_journals:
    get:
      summary: List all PosJournals
      operationId: listPosJournals
      tags:
      - pos_journals
      parameters:
      - name: shop_id
        in: path
        required: true
        description: The ID, slug or ref of the Shop
        schema:
          type: string
      responses:
        '200':
          description: A list of PosJournals
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PosJournalsListResponse'
        '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'
    post:
      summary: Create PosJournal
      operationId: createPosJournal
      tags:
      - pos_journals
      parameters:
      - name: shop_id
        in: path
        required: true
        description: The ID, slug or ref of the Shop
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PosJournalCreateParams'
      responses:
        '200':
          description: The PosJournal which was created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PosJournalSingleResponse'
        '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:
                anyOf:
                - $ref: '#/components/schemas/UnprocessableEntityError'
                - $ref: '#/components/schemas/ShopNotFoundError'
  /shops/{shop_id}/pos_journals/{pos_journal_id}:
    get:
      summary: Get PosJournal information
      operationId: showPosJournal
      tags:
      - pos_journals
      parameters:
      - name: shop_id
        in: path
        required: true
        description: The ID, slug or ref of the Shop
        schema:
          type: string
      - name: pos_journal_id
        in: path
        required: true
        description: The ID of the PosJournal
        schema:
          type: string
      responses:
        '200':
          description: The PosJournal
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PosJournalSingleResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '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'
    put:
      summary: Update PosJournal
      operationId: updatePosJournal
      tags:
      - pos_journals
      parameters:
      - name: shop_id
        in: path
        required: true
        description: The ID, slug or ref of the Shop
        schema:
          type: string
      - name: pos_journal_id
        in: path
        required: true
        description: The ID of the PosJournal
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PosJournalUpdateParams'
      responses:
        '200':
          description: The PosJournal which was updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PosJournalSingleResponse'
        '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'
    delete:
      summary: Delete PosJournal
      operationId: deletePosJournal
      tags:
      - pos_journals
      parameters:
      - name: shop_id
        in: path
        required: true
        description: The ID, slug or ref of the Shop
        schema:
          type: string
      - name: pos_journal_id
        in: path
        required: true
        description: The ID of the PosJournal
        schema:
          type: string
      responses:
        '200':
          description: The PosJournal was successfully deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
        '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'
  /shops/{shop_id}/pos_journals/void:
    post:
      summary: Void PosJournal (Check Void)
      operationId: voidPosJournal
      description: Voids a check by adding a '--VOID--' marker, setting total_price to 0, and preserving original line items for audit purposes. Used by POS integrations to handle check cancellations.
      tags:
      - pos_journals
      parameters:
      - name: shop_id
        in: path
        required: true
        description: The ID, slug or ref of the Shop
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - receipt_num
              properties:
                receipt_num:
                  description: The receipt number of the check to void
                  type: string
                  example: '12345'
                void_reason:
                  description: Optional reason for voiding the check
                  type: string
                  example: customer_cancellation
                voided_at:
                  description: Optional timestamp of when the void occurred. Defaults to current time if not provided.
                  type: string
                  format: date-time
                  example: '2026-01-29T19:30:00Z'
      responses:
        '200':
          description: The PosJournal was successfully voided
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  pos_journal:
                    $ref: '#/components/schemas/PosJournal'
                  voided_at:
                    type: string
                    format: date-time
                    example: '2026-01-29T19:30:00Z'
        '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:
    ShopNotFoundError:
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
                example: Venue not found.
    Reservation:
      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'
    PosOrder:
      type: object
      properties:
        id:
          description: TableCheck's database ID of the PosOrder object.
          type: string
          format: bson-id
        menu_category_name:
          description: The human-readable name of the category of the order's menu item.
          type: string
          example: Appetizer
        menu_category_ref:
          description: The identifier (as used by the POS system database) of the category of the order's menu item.
          type: string
          example: ABC123DEF
        menu_item_name:
          description: The human-readable name of the order's menu item. This should match the line item displayed on the receipt.
          type: string
          example: Chicken Soup
        menu_item_ref:
          description: The identifier (as used by the POS system database) of the order's menu item.
          type: string
          example: ABC123DEF
        order_at:
          description: The timestamp of when the order was entered into the POS system.
          type: string
          format: date-time
          example: '2020-01-29T19:12:34Z'
        qty:
          description: The order quantity, i.e. how many units are ordered.
          type: number
          format: integer
        ref:
          description: The identifier (as used by the POS system database) of the order.
          type: string
        sku:
          description: The Stock Keeping Unit identifier for the order's menu item. This may differ from menu_item_ref (the POS system database ID).
          type: string
        unit_price:
          description: The price of a single unit within the order. (The unit_price is multiplied by qty to obtain the total price.)
          type: string
          format: decimal
    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.
    PosJournalSingleResponse:
      type: object
      properties:
        pos_journal:
          $ref: '#/components/schemas/PosJournal'
        reservations:
          type: array
          items:
            $ref: '#/components/schemas/Reservation'
    PosJournal:
      type: object
      properties:
        batch_date:
          description: The local date on which the check was processed. Used for tracking nightly batch jobs.
          type: string
          format: date
          example: '2020-01-01'
        change_amt:
          description: The amount of the settlement payment returned as change in a cash transaction. Calculate "change_amt" as "settle_amt" less "total_amt".
          type: string
          format: decimal
        country:
          description: The country of the venue (ISO 3166-1 alpha-2).
          type: string
          format: country
          enum:
          - AD
          - AE
          - AF
          - AG
          - AI
          - AL
          - AM
          - AO
          - AQ
          - AR
          - AS
          - AT
          - AU
          - AW
          - AX
          - AZ
          - BA
          - BB
          - BD
          - BE
          - BF
          - BG
          - BH
          - BI
          - BJ
          - BL
          - BM
          - BN
          - BO
          - BQ
          - BR
          - BS
          - BT
          - BV
          - BW
          - BY
          - BZ
          - CA
          - CC
          - CD
          - CF
          - CG
          - CH
          - CI
          - CK
          - CL
          - CM
          - CN
          - CO
          - CR
          - CU
          - CV
          - CW
          - CX
          - CY
          - CZ
          - DE
          - DJ
          - DK
          - DM
          - DO
          - DZ
          - EC
          - EE
          - EG
          - EH
          - ER
          - ES
          - ET
          - FI
          - FJ
          - FK
          - FM
          - FO
          - FR
          - GA
          - GB
          - GD
          - GE
          - GF
          - GG
          - GH
          - GI
          - GL
          - GM
          - GN
          - GP
          - GQ
          - GR
          - GS
          - GT
          - GU
          - GW
          - GY
          - HK
          - HM
          - HN
          - HR
          - HT
          - HU
          - ID
          - IE
          - IL
          - IM
          - IN
          - IO
          - IQ
          - IR
          - IS
          - IT
          - JE
          - JM
          - JO
          - JP
          - KE
          - KG
          - KH
          - KI
          - KM
          - KN
          - KP
          - KR
          - KW
          - KY
          - KZ
          - LA
          - LB
          - LC
          - LI
          - LK
          - LR
          - LS
          - LT
          - LU
          - LV
          - LY
          - MA
          - MC
          - MD
          - ME
          - MF
          - MG
          - MH
          - MK
          - ML
          - MM
          - MN
          - MO
          - MP
          - MQ
          - MR
          - MS
          - MT
          - MU
          - MV
          - MW
          - MX
          - MY
          - MZ
          - NA
          - NC
          - NE
          - NF
          - NG
          - NI
          - NL
          - 'NO'
          - NP
          - NR
          - NU
          - NZ
          - OM
          - PA
          - PE
          - PF
          - PG
          - PH
          - PK
          - PL
          - PM
          - PN
          - PR
          - PS
          - PT
          - PW
          - PY
          - QA
          - RE
          - RO
          - RS
          - RU
          - RW
          - SA
          - SB
          - SC
          - SD
          - SE
          - SG
          - SH
          - SI
          - SJ
          - SK
          - SL
          - SM
          - SN
          - SO
          - SR
          - SS
          - ST
          - SV
          - SX
          - SY
          - SZ
          - TC
          - TD
          - TF
          - TG
          - TH
          - TJ
          - TK
          - TL
          - TM
          - TN
          - TO
          - TR
          - TT
          - TV
          - TW
          - TZ
          - UA
          - UG
          - UM
          - US
          - UY
          - UZ
          - VA
          - VC
          - VE
          - VG
          - VI
          - VN
          - VU
          - WF
          - WS
          - YE
          - YT
          - ZA
          - ZM
          - ZW
          example: JP
        coupon_amt:
          description: The amount of coupons applied to the check. The "coupon_amt" should be applied against the "total_amt", i.e. before settlement.
          type: string
          format: decimal
        currency:
          description: The currency of the check transaction.
          type: string
          enum:
          - AED
          - AFN
          - ALL
          - AMD
          - ANG
          - AOA
          - ARS
          - AUD
          - AWG
          - AZN
          - BAM
          - BBD
          - BDT
          - BGN
          - BHD
          - BIF
          - BMD
          - BND
          - BOB
          - BRL
          - BSD
          - BTN
          - BWP
          - BYN
          - BYR
          - BZD
          - CAD
          - CDF
          - CHF
          - CLF
          - CLP
          - CNY
          - COP
          - CRC
          - CUC
          - CUP
          - CVE
          - CZK
          - DJF
          - DKK
          - DOP
          - DZD
          - EGP
          - ERN
          - ETB
          - EUR
          - FJD
          - FKP
          - GBP
          - GEL
          - GHS
          - GIP
          - GMD
          - GNF
          - GTQ
          - GYD
          - HKD
          - HNL
          - HTG
          - HUF
          - IDR
          - ILS
          - INR
          - IQD
          - IRR
          - ISK
          - JMD
          - JOD
          - JPY
          - KES
          - KGS
          - KHR
          - KMF
          - KPW
          - KRW
          - KWD
          - KYD
          - KZT
          - LAK
          - LBP
          - LKR
          - LRD
          - LSL
          - LYD
          - MAD
          - MDL
          - MGA
          - MKD
          - MMK
          - MNT
          - MOP
          - MRU
          - MUR
          - MVR
          - MWK
          - MXN
          - MYR
          - MZN
          - NAD
          - NGN
          - NIO
          - NOK
          - NPR
          - NZD
          - OMR
          - PAB
          - PEN
          - PGK
          - PHP
          - PKR
          - PLN
          - PYG
          - QAR
          - RON
          - RSD
          - RUB
          - RWF
          - SAR
          - SBD
          - SCR
          - SDG
          - SEK
          - SGD
          - SHP
          - SKK
          - SLE
          - SOS
          - SRD
          - SSP
          - STN
          - SVC
          - SYP
          - SZL
          - THB
          - TJS
          - TMT
          - TND
          - TOP
          - TRY
          - TTD
          - TWD
          - TZS
          - UAH
          - UGX
          - USD
          - UYU
          - UZS
          - VES
          - VND
          - VUV
          - WST
          - XAF
          - XCD
          - XCG
          - XOF
          - XPF
          - YER
          - ZAR
          - ZMW
          example: JPY
        customer_name:
          description: '[PII] The name of the customer appearing on the check, if any.'
          type: string
        discount_amt:
          description: The amount of discounts applied to the check. The "discount_amt" should be applied against the "total_amt", i.e. before settlement.
          type: string
          format: decimal
        membership_code:
          description: The membership number of the customer. Used for loyalty program integration.
          type: string
        order_at:
          description: The timestamp of when the first order of the check occurred. If any PosOrder objects are present, this field will be auto-calculated.
          type: string
          format: date-time
          example: '2020-01-29T19:12:34Z'
        original_receipt_num:
          description: Receipt number of the original or linked receipt. This can be used if a "parent" check is split into multiple "child" checks, for example.
          type: string
        pax:
          description: The party size of the check, i.e. number of people dining.
          type: number
          format: integer
        payment_at:
          description: The timestamp of when the payment of the check occurred. If any PosPayment objects are present, this field will be auto-calculated.
          type: string
          format: date-time
          example: '2020-01-29T19:12:34Z'
        pos_discounts:
          type: array
          items:
            $ref: '#/components/schemas/PosDiscount'
        pos_orders:
          type: array
          items:
            $ref: '#/components/schemas/PosOrder'
        pos_payments:
          type: array
          items:
            $ref: '#/components/schemas/PosPayment'
        receipt_num:
          description: Receipt Number
          type: string
        revenue_center:
          description: Optional. The revenue center or identifier code (as used in the POS system) of the venue. Used for tracking/audit purposes only.
          type: string
          example: MyRestaurant/1
        room_name:
          description: The room number at which the customer is staying, as used by hotels. Note that this is not used to indicate the dining room name at the venue.
          type: string
        service_fee_amt:
          description: The applicable service fees and surcharges applied to the check.
          type: string
          format: decimal
        service_fee_rate:
          description: The service fee or surcharge applied to the check, as a decimal value (the value "1.0" means "100%".)
          type: string
          format: decimal
          example: '0.15'
        settle_amt:
          description: The amount of money used to pay (i.e. settle) the check. May be greater than "total_amt" when cash is used.
          type: string
          format: decimal
        site_name:
          description: Optional. The identifier code (as used in the POS system) of the restaurant chain or hotel property. Used for tracking/audit purposes only.
          type: string
          example: MyHotel
        staff_name:
          description: The name of the staff who served the meal and/or handled the check.
          type: string
        staff_ref:
          description: The identifier code (as used in the POS system) of the staff who served the meal and/or handled the check.
          type: string
        subtotal_amt:
          description: The check subtotal, i.e. including orders but not including "service_fee_amt", "coupon_amt", "discount_amt", "tax_amt".
          type: string
          format: decimal
        system_api_provider:
          description: The name of the company who is the integrator of the POS API (i.e. your company, if you are connecting to this API.)
          type: string
          example: acme
        system_maker:
          description: The name of the company who makes the POS system.
          type: string
          example: oracle
        system_model:
          description: The model of the POS system.
          type: string
          example: micros9700
        system_version:
          description: The version number of the software used in the POS system.
          type: string
          example: 12.1.0
        table_names:
          description: The names of the table(s) at which the party is seated. This should exactly match the table name(s) as they appear in TableCheck.
          type: array
          items:
            type: string
        tax_amt:
          description: The amount of tax applied to the check in addition to the "subtotal_amt".
          type: string
          format: decimal
        tax_included_amt:
          description: The amount of tax already included in the "subtotal_amt", in the case that order prices are shown including tax.
          type: string
          format: decimal
        tax_rate:
          description: The applicable tax rate to the check, as a decimal value (the value "1.0" means "100%".)
          type: string
          format: decimal
          example: '0.08'
        terminal_name:
          description: The name, identifier, or serial number of the POS terminal used to process the check.
          type: string
        total_amt:
          description: The total check payable amount, i.e. the "subtotal_amt" plus "service_fee_amt" and "tax_amt", less "coupon_amt" and "discount_amt".
          type: string
          format: decimal
        id:
          description: TableCheck's database ID of the PosJournal object.
          type: string
          format: bson-id
          example: ae5355ca1fd337ed5d6893e2
        franchise_id:
          description: TableCheck's database ID of the Franchise to which the PosJournal belongs.
          type: string
          format: bson-id
          example: d337ed5d6ae5355ca1f893e2
        ref:
          description: The POS system's identifier of the check object.
          type: string
        reservation_id:
          description: TableCheck's database ID of the Reservation with which the PosJournal is linked.
          type: string
          format: bson-id
          example: 55ca1fd33ae537ede25d6893
        shop_id:
          description: TableCheck's database ID of the Shop to which the PosJournal belongs.
          type: string
          format: bson-id
          example: 37ed555ca1fd3d6893e2ae53
        created_at:
          description: The timestamp of when the PosJournal was cre

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