Tyro Payments Tables API

openapi: 3.2.0
info:
  title: Tables API
  version: '1.0'
  contact: {}
  description: 'The API allows the APP and POS to send and receive information about tables. Currently the API supports creating, updating and retrieving tables.

    '
servers:
- url: https://api.tyro.com/connect
  description: Production
tags:
- name: Tables
paths:
  /tables:
    post:
      summary: Create Table
      operationId: create-table-request
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/table'
              examples:
                Created Table:
                  value:
                    id: 2688fcf2-44dd-4c72-88ac-79d0910f2983
                    number: table-1
                    locationId: tc-cool-3000
                    section:
                      id: section-id
                      name: awesome section
                    openSales: []
          headers: {}
        '400':
          description: When the provided payload is not valid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The validation error message.
              examples:
                Missing property:
                  value:
                    error: '"locationId" is required'
        '403':
          description: When you don't have the right permissions to create a table for the provided location.
      description: 'This endpoint is used to create a table within Tyro Connect.


        The id that is returned as a part of the response should be used to identify the table for subsequent events or retrieving the details.'
      security:
      - JWT: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/new-table-request'
            examples:
              New Table:
                value:
                  number: table-1
                  locationId: tc-cool-3000
                  section:
                    id: section-id
                    name: awesome section
      parameters:
      - $ref: '#/components/parameters/header-bearer-token'
      - $ref: '#/components/parameters/header-content-json'
      tags:
      - Tables
    get:
      summary: List Tables
      operationId: list-tables
      description: 'This endpoint returns all the tables of a given location. It is possible to apply filters to the tables being fetched.


        ## Filtering

        The following `locationId=tc-cool-3000&openSales=true` will return all tables with open sales for location `tc-cool-3000`.'
      parameters:
      - schema:
          type: string
        in: query
        name: locationId
        example: 2688fcf2-44dd-4c72-88ac-79d0910f2983
        required: true
        description: The Tyro Connect Location Id of the tables to be retrieved. This parameter is required.
      - schema:
          type: boolean
        in: query
        name: openSales
        example: true
        description: Returns only tables that contain at least one open sale.
      - $ref: '#/components/parameters/header-bearer-token'
      security:
      - JWT: []
      responses:
        '200':
          description: The list of tables
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    description: The results for the location that satisfy the filtering criteria
                    items:
                      $ref: '#/components/schemas/table'
                required:
                - results
              examples:
                openSales=true&locationId=tc-cool-300:
                  value:
                    results:
                    - id: 2688fcf2-44dd-4c72-88ac-79d0910f2983
                      locationId: tc-iscool-3000
                      section:
                        id: section-id
                        name: awesome section1
                      openSales:
                      - 3288fcf2-44dd-4c72-88ac-79d0910f1234
                      - 8788fcf2-44dd-8c72-88ac-79d0910f1678
                    - id: 432423f3-54dd-6c72-88ac-79d0910f2984
                      locationId: tc-iscool-3000
                      openSales:
                      - 6969fcf2-44dd-4c72-88ac-79d0910f6969
                openSales=false&locationId=tc-cool-300:
                  value:
                    results:
                    - id: empty-sales-1
                      locationId: tc-iscool-3000
                      section:
                        id: section-id
                        name: awesome section1
                      openSales: []
                    - id: empty-sales-2
                      locationId: tc-iscool-3000
                      openSales: []
                locationId=tc-cool-300:
                  value:
                    results:
                    - id: empty-sales-1
                      locationId: tc-iscool-3000
                      section:
                        id: section-id
                        name: awesome section1
                      openSales: []
                    - id: non-empty-sales-1
                      locationId: tc-iscool-3000
                      openSales:
                      - 6969fcf2-44dd-4c72-88ac-79d0910f6969
        '403':
          description: When you don't have the right permissions to fetch the tables for the provided location
        '404':
          description: When the provided `locationId` does not exist in our system
      tags:
      - Tables
  /tables/{tableId}:
    get:
      responses:
        '200':
          description: The table response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/table'
              examples:
                Simple Table:
                  value:
                    id: 2688fcf2-44dd-4c72-88ac-79d0910f2983
                    number: table-1
                    locationId: tc-iscool-3000
                    section:
                      id: section-id
                      name: awesome section
                    openSales: []
        '403':
          description: When you don't have the right permissions to get a table for the provided location.
        '404':
          description: When the provided `tableId` does not match a table stored in the system.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The validation error message.
              examples:
                Bad Request:
                  value:
                    error: No table found for 2688fcf2-44dd-4c72-88ac-79d0910f2983
      description: This endpoint is for fetching the details of a table.
      parameters:
      - in: path
        description: Id of the table in Tyro Connect that should be retrieved
        name: tableId
        required: true
        schema:
          type: string
          example: 2688fcf2-44dd-4c72-88ac-79d0910f2983
      - $ref: '#/components/parameters/header-bearer-token'
      operationId: get-table
      summary: Get Table
      security:
      - JWT: []
      tags:
      - Tables
    patch:
      responses:
        '204':
          description: No body content
        '400':
          description: When the provided request is not valid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The validation error message.
        '403':
          description: When you don't have the right permissions to update the table.
        '404':
          description: When the provided `tableId` does not match a table stored in the system.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The validation error message.
              examples:
                Bad Request:
                  value:
                    error: No table found for 2688fcf2-44dd-4c72-88ac-79d0910f2983
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update-table-request'
            examples:
              Update table number:
                value:
                  number: new-table-id
              Update table section:
                value:
                  section:
                    id: new-section-id
                    name: Smoker section
        description: ''
      description: This endpoint is for updating a table. Please note table update will not be allowed if the table has open sales.
      parameters:
      - in: path
        description: Id of the table in Tyro Connect that should be updated
        name: tableId
        required: true
        schema:
          type: string
          example: 2688fcf2-44dd-4c72-88ac-79d0910f2983
      - $ref: '#/components/parameters/header-bearer-token'
      - $ref: '#/components/parameters/header-content-json'
      operationId: patch-table
      summary: Update Table
      security:
      - JWT: []
      tags:
      - Tables
    delete:
      responses:
        '200':
          description: The table was successfully deleted
        '403':
          description: When you don't have the right permissions to delete a table for the provided location.
        '404':
          description: When the provided `tableId` does not match a table stored in the system.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The validation error message.
              examples:
                Bad Request:
                  value:
                    error: No table found for 2688fcf2-44dd-4c72-88ac-79d0910f2983
      description: This endpoint is for deleting a table. Please note table delete will not be allowed if the table has open sales.
      parameters:
      - in: path
        description: Id of the table in Tyro Connect that should be deleted
        name: tableId
        required: true
        schema:
          type: string
          example: 2688fcf2-44dd-4c72-88ac-79d0910f2983
      - $ref: '#/components/parameters/header-bearer-token'
      operationId: delete-table
      summary: Delete Table
      security:
      - JWT: []
      tags:
      - Tables
components:
  schemas:
    section:
      title: Section
      type: object
      description: The section within the venue
      properties:
        id:
          type: string
          description: The POS system's Id of the section
        name:
          type: string
          description: The readable name of the section. E.g. Front bar, drive through for hospitality or for retail men's clothes, women's shoes etc
    new-table-request:
      title: New table request
      type: object
      description: The request sent to Tyro Connect to add a new table
      properties:
        number:
          type: string
          description: This value must be unique and represents the table number or table id. This field accepts alphanumeric characters e.g `MAIN-33`.
          example: MAIN-33
        locationId:
          type: string
          description: The id of the location as specified by the Tyro Connect system
        section:
          $ref: '#/components/schemas/section'
      required:
      - number
      - locationId
    update-table-request:
      title: Update table request
      type: object
      description: The request to be sent to Tyro Connect in order to update the table
      properties:
        number:
          type: string
          description: This value must be unique and represents the table number or table id. This field accepts alphanumeric characters e.g `MAIN-33`
          example: MAIN-33
        section:
          $ref: '#/components/schemas/section'
    table:
      title: Table
      type: object
      properties:
        id:
          type: string
          description: The id of the table in the Tyro Connect system
          example: 0f448ac1-862a-4c7b-bdb4-a3b7cdbf6149
        number:
          type: string
          description: This value must be unique and represents the table number or table id. This field accepts alphanumeric characters e.g `MAIN-33`
          example: MAIN-33
        locationId:
          type: string
          description: The id of the location as specified by the Tyro Connect system
        section:
          $ref: '#/components/schemas/section'
        openSales:
          type: array
          description: A list of sale ids that are open in the Tyro Connect system attached to the table.
          items:
            type: string
      required:
      - id
      - number
      - locationId
      - openSales
  parameters:
    header-bearer-token:
      schema:
        type: string
        default: Bearer {$$.env.access_token}
      in: header
      name: Authorization
      required: true
    header-content-json:
      schema:
        type: string
        enum:
        - application/json
      in: header
      name: Content-Type
      required: true
  securitySchemes:
    JWT:
      type: openIdConnect
      openIdConnectUrl: https://auth.connect.tyro.com/.well-known/openid-configuration