Tyro Payments Bookings API

openapi: 3.2.0
info:
  title: Bookings API
  version: '1.0'
  contact: {}
  description: The API allows the APP and POS to send and receive information about bookings. Currently the API supports creating, updating and retrieving bookings in the POS or the booking system.
servers:
- url: https://api.tyro.com/connect
  description: Production
tags:
- name: Bookings
paths:
  /bookings:
    post:
      summary: Create Booking
      operationId: create-booking-request
      responses:
        '201':
          description: Created
          content:
            application/vnd.tyro.connect+json;version=1.0:
              schema:
                $ref: '#/components/schemas/booking'
              examples:
                Created Booking:
                  value:
                    id: 2688fcf2-44dd-4c72-88ac-79d0910f2983
                    locationId: merchant:abc123
                    bookingStatus: CREATED
                    origin:
                      bookingReference: some-booking-reference
                    asset:
                      type: TABLE
                      tables:
                      - number: '1'
                    numberOfPeople: 2
                    payments:
                    - amount: 4321
                      currency: AUD
                      description: Reservation payment
                    startTime: '2020-03-01T18:00:00Z'
          links:
            GetBooking:
              operationId: get-booking
              description: Retrieve the booking details
          headers: {}
        '400':
          description: When the provided payload is not valid.
          content:
            application/vnd.tyro.connect+json;version=1.0:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The validation error message.
              examples:
                Bad Status:
                  value:
                    error: '"asset.tableStatus" must be [SEATED]'
                Missing property:
                  value:
                    error: '"origin.bookingReference" is required'
        '403':
          description: When you don't have the right permissions to seat a booking for the provided location.
      description: 'This endpoint is used to create a booking within Tyro Connect. This call will create a booking in the POS system.


        The id that is returned as a part of the response should be used to identify the booking for subsequent events or retrieving the details via the `GET` endpoint.'
      security:
      - JWT: []
      requestBody:
        content:
          application/vnd.tyro.connect+json;version=1.0:
            schema:
              $ref: '#/components/schemas/new-booking-request'
            examples:
              New Booking:
                value:
                  locationId: merchant:abc123
                  origin:
                    bookingReference: some-booking-reference
                  asset:
                    type: TABLE
                    tables:
                    - number: '1'
                  numberOfPeople: 2
                  startTime: '2020-03-01T18:00:00Z'
                  bookingStatus: CREATED
        description: ''
      parameters:
      - $ref: '#/components/parameters/header-bearer-token'
      - schema:
          $ref: '#/components/schemas/acceptHeaderBooking1_0'
        in: header
        name: Accept
        required: true
      - $ref: '#/components/parameters/header-content-json'
      tags:
      - Bookings
  /bookings/{bookingId}:
    get:
      responses:
        '200':
          description: The booking response
          content:
            application/vnd.tyro.connect+json;version=1.0:
              schema:
                $ref: '#/components/schemas/booking'
              examples:
                Simple Booking:
                  value:
                    id: 2688fcf2-44dd-4c72-88ac-79d0910f2983
                    locationId: merchant:abc123
                    bookingStatus: CREATED
                    origin:
                      bookingReference: some-booking-reference
                    asset:
                      type: TABLE
                      tables:
                      - number: '1'
                    numberOfPeople: 2
                    startTime: '2020-03-01T18:00:00Z'
        '403':
          description: When you don't have the right permissions to create a booking for the provided location.
        '404':
          description: When the provided `bookingId` does not match a booking stored in the system.
          content:
            application/vnd.tyro.connect+json;version=1.0:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The validation error message.
              examples:
                Bad Request:
                  value:
                    error: No booking found for 2688fcf2-44dd-4c72-88ac-79d0910f2983
      description: This endpoint is for fetching the details of a booking.
      parameters:
      - in: path
        description: Id of the booking in Tyro Connect that should be retrieved
        name: bookingId
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/header-bearer-token'
      - schema:
          $ref: '#/components/schemas/acceptHeaderBooking1_0'
        in: header
        name: Accept
        required: true
      operationId: get-booking
      summary: Get Booking
      security:
      - JWT: []
      tags:
      - Bookings
    patch:
      responses:
        '204':
          description: No body content
        '400':
          description: When the provided request is not valid.
          content:
            application/vnd.tyro.connect+json;version=1.0:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The validation error message.
              examples:
                Bad Request:
                  value:
                    error: '"asset.tableStatus" must be one of [SEATED, DINING, FINALISED, CLOSING]'
        '403':
          description: When you don't have the right permissions to update the booking.
        '404':
          description: When the provided `bookingId` does not match a booking stored in the system.
          content:
            application/vnd.tyro.connect+json;version=1.0:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The validation error message.
              examples:
                Bad Request:
                  value:
                    error: No booking found for 2688fcf2-44dd-4c72-88ac-79d0910f2983
      requestBody:
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/update-booking-request'
            examples:
              Customer cancelled booking:
                value:
                  bookingStatus: CANCELLED_BY_CUSTOMER
                  reason: Illness
              Update Booking details:
                value:
                  numberOfPeople: 3
        description: ''
      description: This endpoint is for updating a booking.
      parameters:
      - in: path
        description: Id of the booking in Tyro Connect that should be updated
        name: bookingId
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/header-bearer-token'
      - schema:
          $ref: '#/components/schemas/acceptHeaderBooking1_0'
        in: header
        name: Accept
        required: true
      - $ref: '#/components/parameters/header-content-json'
      operationId: patch-booking
      summary: Update Booking
      security:
      - JWT: []
      tags:
      - Bookings
components:
  schemas:
    payments:
      type: array
      description: A list of payments applied to the booking.
      items:
        $ref: '#/components/schemas/payment-with-description'
    new-booking-request:
      title: New booking request
      type: object
      description: The message to be sent to Tyro Connect in order to mark the booking as seated.
      properties:
        locationId:
          type: string
          description: The id of the location as specified by the Tyro Connect system.
        origin:
          type: object
          description: Information relevant to the booking partner that this booking was created with
          properties:
            bookingReference:
              $ref: '#/components/schemas/bookingReference'
          required:
          - bookingReference
        bookingStatus:
          $ref: '#/components/schemas/bookingStatus'
        numberOfPeople:
          $ref: '#/components/schemas/numberOfPeople'
        payments:
          $ref: '#/components/schemas/payments'
        startTime:
          type: string
          description: The date and time the booking starts at the venue. The format of the date time is the notation as defined by [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6)
          example: '2018-05-02T17:30:00.000Z'
          format: date-time
        endTime:
          type: string
          description: The date and time the booking ends at the venue. The format of the date time is the notation as defined by [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6)
          example: '2018-05-02T18:30:00.000Z'
          format: date-time
        customer:
          $ref: '#/components/schemas/customer'
        notes:
          type: string
          minLength: 1
          maxLength: 500
          description: 'Notes specific to the booking. Example: ''Window seat please'''
        asset:
          description: Contains asset information of the booking
          oneOf:
          - $ref: '#/components/schemas/roomAsset'
          - $ref: '#/components/schemas/tableAsset'
      required:
      - locationId
      - numberOfPeople
      - startTime
      - asset
    time:
      type: string
      description: The format of the date time is the notation as defined by [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6)
      example: '2018-05-02T17:30:00.000Z'
      format: date-time
    origin:
      type: object
      description: Information relevant to the booking partner that this booking was created with
      properties:
        name:
          type: string
          description: Name of the booking app
        bookingReference:
          $ref: '#/components/schemas/bookingReference'
      required:
      - bookingReference
    bookingStatus:
      type: string
      description: The current status of the booking
      enum:
      - CREATED
      - ACCEPTED
      - CANCELLED_BY_CUSTOMER
      - CANCELLED_BY_MERCHANT
      - REJECTED
      default: CREATED
    assetUpdate:
      type: object
      properties:
        tableStatus:
          $ref: '#/components/schemas/tableStatus'
        arrivalStatus:
          $ref: '#/components/schemas/arrivalStatus'
        tables:
          type: array
          minItems: 1
          description: The tables used for the booking
          items:
            $ref: '#/components/schemas/table'
        section:
          $ref: '#/components/schemas/section'
        rooms:
          type: array
          minItems: 1
          description: The rooms in the booking
          items:
            $ref: '#/components/schemas/room'
        discounts:
          type: array
          minItems: 1
          items:
            type: string
        preOrders:
          type: array
          minItems: 1
          items:
            type: string
    address:
      title: address
      type: object
      description: The customer address
      properties:
        line1:
          type: string
        line2:
          type: string
        suburb:
          type: string
        state:
          type: string
        postcode:
          type: string
        country:
          type: string
    bookingReference:
      type: string
      description: Reference for the booking. It is used to facilitate identification of the booking in the app and pos systems and must be unique per location and booking partner.
    acceptHeaderBooking1_0:
      type: string
      enum:
      - application/vnd.tyro.connect+json;version=1.0
      - application/vnd.tyro.connect+json;version=0.1
      default: application/vnd.tyro.connect+json;version=0.1
      description: Specifies which version of the API to use. If no value is provided then 0.1 version will be used
    update-booking-request:
      title: Update booking request
      type: object
      description: The message to be sent to Tyro Connect in order to update the booking
      properties:
        asset:
          $ref: '#/components/schemas/assetUpdate'
        bookingStatus:
          $ref: '#/components/schemas/bookingStatus'
        numberOfPeople:
          $ref: '#/components/schemas/numberOfPeople'
        payments:
          $ref: '#/components/schemas/payments'
        reason:
          $ref: '#/components/schemas/reason'
        customer:
          $ref: '#/components/schemas/customer'
        notes:
          type: string
          minLength: 1
          maxLength: 500
          description: 'Notes specific to the booking. Example: ''Window seat please'''
        startTime:
          $ref: '#/components/schemas/time'
        endTime:
          $ref: '#/components/schemas/time'
        origin:
          $ref: '#/components/schemas/origin'
    room:
      type: object
      properties:
        number:
          type: string
          description: The room number or room id. This field accepts alphanumeric characters e.g `MAIN-33`
          example: MAIN-33
      required:
      - number
    booking:
      title: Booking
      type: object
      properties:
        id:
          type: string
          description: The id of the booking in the Tyro Connect system
          example: 0f448ac1-862a-4c7b-bdb4-a3b7cdbf6149
        locationId:
          type: string
          description: The id of the location as specified by the Tyro Connect system
        origin:
          $ref: '#/components/schemas/origin'
        asset:
          oneOf:
          - $ref: '#/components/schemas/tableAsset'
          - $ref: '#/components/schemas/roomAsset'
        bookingStatus:
          $ref: '#/components/schemas/bookingStatus'
        numberOfPeople:
          $ref: '#/components/schemas/numberOfPeople'
        payments:
          $ref: '#/components/schemas/payments'
        startTime:
          type: string
          description: The date and time the booking starts at the venue. The format of the date time is the notation as defined by [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6)
          example: '2018-05-02T17:30:00.000Z'
          format: date-time
        endTime:
          type: string
          description: The date and time the booking ends at the venue. The format of the date time is the notation as defined by [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6)
          example: '2018-05-02T18:30:00.000Z'
          format: date-time
        customer:
          $ref: '#/components/schemas/customer'
        notes:
          type: string
          minLength: 1
          maxLength: 500
          description: 'Notes specific to the booking. Example: ''Window seat please'''
        reason:
          $ref: '#/components/schemas/reason'
      required:
      - id
      - locationId
      - numberOfPeople
      - asset
    table:
      type: object
      properties:
        number:
          type: string
          minLength: 1
          description: The table number or table id. This field accepts alphanumeric characters e.g `MAIN-33`
          example: MAIN-33
    reason:
      type: string
      maxLength: 50
      description: The reason the booking was rejected or cancelled. Provided only when bookingStatus is `REJECTED`, `CANCELLED_BY_MERCHANT` or `CANCELLED_BY_CUSTOMER`
    customer:
      type: object
      description: The customer making the booking
      properties:
        id:
          type: string
          minLength: 1
        name:
          type: string
          minLength: 1
          description: Customer's name
        notes:
          type: string
          minLength: 1
          maxLength: 500
          description: Notes specific to the customer. For example, 'Loves red wine'.
        email:
          type: string
          minLength: 1
          description: Customer's email address
        address:
          allOf:
          - $ref: '#/components/schemas/address'
          - minLength: 1
        phoneNumber:
          type: string
          minLength: 1
          description: Customer's phone number
        birthday:
          type: string
          minLength: 1
          description: Customer's birthday
    tableStatus:
      type: string
      description: 'The current table status of the booking

        The supported statuses are:

        * `SEATED` - indicates that the customer connected to the booking has been seated.

        * `DINING` - indicate that the customer connected to the booking has started dining.

        * `CLOSING` - indicates that the customer connected to the booking is close to finishing their meal (e.g. when the bill has been printed).

        * `FINALISED` - indicates that the booking has been finalised (e.g. when the bill has been finalised).'
      enum:
      - SEATED
      - DINING
      - CLOSING
      - FINALISED
    tableAsset:
      type: object
      properties:
        type:
          type: string
          enum:
          - TABLE
        tableStatus:
          $ref: '#/components/schemas/tableStatus'
        arrivalStatus:
          $ref: '#/components/schemas/arrivalStatus'
        tables:
          type: array
          minItems: 1
          description: The tables used for the booking
          items:
            $ref: '#/components/schemas/table'
        section:
          $ref: '#/components/schemas/section'
        discounts:
          type: array
          minItems: 1
          items:
            type: string
        preOrders:
          type: array
          minItems: 1
          items:
            type: string
      required:
      - type
    payment-with-description:
      title: Payment With Description
      allOf:
      - $ref: '#/components/schemas/payment'
      - properties:
          description:
            type: string
            description: A description of what this payment amount represents
            example: Deposit for booking
    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, womens shoes etc
    payment:
      title: Payment
      type: object
      properties:
        amount:
          type: integer
          description: This is the amount in cents. e.g 12520 is $125.20
          minimum: 0
        currency:
          type: string
          default: AUD
          enum:
          - AUD
          example: AUD
          description: This is always AUD
    roomAsset:
      type: object
      description: The section within the venue
      properties:
        type:
          type: string
          enum:
          - ROOM
        rooms:
          type: array
          minItems: 1
          description: The rooms used for the booking
          items:
            $ref: '#/components/schemas/room'
      required:
      - type
      - rooms
    numberOfPeople:
      type: number
      minimum: 1
      description: The number of expected guests
    arrivalStatus:
      type: string
      description: The customer's arrival status in relation to the booking
      enum:
      - ON_TIME
      - EARLY
      - RUNNING_LATE
      - NO_SHOW
  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