Booking API (1.0)

The API allows the POS to send and receive information about bookings. Currently the API supports creating walk-in bookings, updating and retrieving existing bookings in the POS or the booking system.

Overview

Servers

Production

https://api.tyro.com/connect

Create booking

Request

This endpoint is used to notify Tyro Connect about a new walk-in booking and will create a booking in the App 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 or during updates via the PATCH endpoint

Security

JWT

Headers

Authorizationstringrequired

Default Bearer {$$.env.access_token}

Acceptstring(acceptHeaderBooking1_0)required

Specifies which version of the API to use. If no value is provided then 0.1 version will be used

Default application/vnd.tyro.connect+json;version=0.1

Enum"application/vnd.tyro.connect+json;version=1.0""application/vnd.tyro.connect+json;version=0.1"

Content-Typestringrequired

Value"application/json"

Bodyapplication/json

locationIdstringrequired

The id of the location as specified by the Tyro Connect system

assetobjectrequired

Contains asset information of the booking

asset.typestringrequired

Type of asset that has been booked.

Value"TABLE"

asset.tablesArray of objects(table)non-empty

The tables used for the booking

asset.sectionobject(section)

The section within the venue

asset.tableStatusstring

The current table status of the booking

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

Value"SEATED"

numberOfPeoplenumber(numberOfPeople)>= 1required

The number of guests

startTimestring(date-time)

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

Example: "2018-05-02T17:30:00Z"

bookingStatusstringrequired

The current status of the booking

Value"CREATED"

curl -i -X POST \
  https://api.tyro.com/connect/bookings \
  -H 'Accept: application/vnd.tyro.connect+json;version=1.0' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "locationId": "merchant:abc123",
    "asset": {
      "type": "TABLE",
      "tableStatus": "SEATED",
      "tables": [
        {
          "number": "1"
        }
      ]
    },
    "bookingStatus": "CREATED",
    "numberOfPeople": 2,
    "startTime": "2021-01-01T17:00:00Z"
  }'

Responses

Created

Bodyapplication/json

idstringrequired

The id of the booking in the Tyro Connect system

Example: "0f448ac1-862a-4c7b-bdb4-a3b7cdbf6149"

locationIdstringrequired

The id of the location as specified by the Tyro Connect system

bookingStatusstringrequired

The current status of the booking

Value"CREATED"

assetobject

numberOfPeoplenumber(numberOfPeople)>= 1

The number of guests

paymentsArray of objects(payments)

A list of payments applied to the booking.

startTimestring(date-time)

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

Example: "2018-05-02T17:30:00Z"

Response

application/json

{
  "id": "2688fcf2-44dd-4c72-88ac-79d0910f2983",
  "locationId": "merchant:abc123",
  "asset": {
    "type": "TABLE",
    "tableStatus": "SEATED",
    "tables": [ … ]
  },
  "bookingStatus": "CREATED",
  "numberOfPeople": 2,
  "startTime": "2021-01-01T17:00:00Z"
}

List Bookings

Request

This endpoint returns all the bookings of a given location. The list of bookings is paginated and it is possible to apply filters to the bookings being fetched.

Filtering

The filtering options use an "OR" clause within the same filter criteria and an "AND" clause between criteria.

This means that a request with bookingStatus=ACCEPTED&tableNumber=10 will return the bookings that were ACCEPTED and that have table 10 associated.

A request with tableNumber=22&tableNumber=10 will return the bookings that have either table 22 or table 10.

The paginated results are ordered using the sequence they were created in the Tyro Connect. For example results[0] on page 1 is the first matching booking that was created in the Tyro Connect system.

Please Note: Results are not sorted by date. If you require the results to be sorted make sure you fetch all the pages before applying a sort to the list of records.

Security

JWT

Query

locationIdstringrequired

The Tyro Connect Location Id of the bookings to be retrieved. This parameter is required.

assetTypestring(assetType)

Returns results for matching asset.type values

Enum"ROOM""TABLE"

Example: assetType=ROOM

tableNumberstring

Returns results based on the table.number of a booking.

Can be a single string or multi string value.

Example: tableNumber=outside-table-3

bookingStatusstring

Returns results based on the status of a booking.

Can be a single string or multi string value.

Enum"CREATED""ACCEPTED""CANCELLED_BY_CUSTOMER""CANCELLED_BY_MERCHANT""REJECTED"

fromDatestring(date)

Returns results that have a "startTime" later than or equal to the provided value.

Format: YYYY-MM-DD

Example: fromDate=2021-04-28

toDatestring

Returns results that have a "startTime" before than or equal to the provided value.

Format: YYYY-MM-DD

Example: toDate=2021-04-28

dateTypestring

Determines which booking date information to filter on when searching by date.

Default "START"

Enum"CREATED""UPDATED""START""END"

limitnumber[ 1 .. 50 ]

Specifies the amount of results to be retrieved.

A maximum of 50 results are returned if this value is not provided.

Example: limit=10

pagenumber>= 1

Specify the page to retrieve.

You will need to use this setting if you wish to retrieve specific pages.

Page-numbering is based on the value of "limit". If limit=5, then page=1 will display the hits from 1 to 5, page=3 will display the hits from 11 to 15.

Page numbers start at 1.

A request for a non-existing page will yield 0 results.

Example: page=2

Headers

Acceptstringrequired

Value"application/vnd.tyro.connect+json;version=1.0"

Example: application/vnd.tyro.connect+json;version=1.0

Authorizationstringrequired

Default Bearer {$$.env.access_token}

curl -i -X GET \
  'https://api.tyro.com/connect/bookings?locationId=string&assetType=ROOM&tableNumber=outside-table-3&bookingStatus=CREATED&fromDate=2021-04-28&toDate=2021-04-28&dateType=CREATED&limit=10&page=2' \
  -H 'Accept: application/vnd.tyro.connect+json;version=1.0' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The booking list

Bodyapplication/json

resultsArray of objects(Booking)required

The results for the location that satisfy the filtering criteria

results[].idstringrequired

The id of the booking in the Tyro Connect system

Example: "0f448ac1-862a-4c7b-bdb4-a3b7cdbf6149"

results[].locationIdstringrequired

The id of the location as specified by the Tyro Connect system

results[].originobject

Information relevant to the booking partner that this booking was created with

results[].bookingStatusstring(bookingStatus)

The status of the booking within the Booking system

Enum"CREATED""ACCEPTED""CANCELLED_BY_CUSTOMER""CANCELLED_BY_MERCHANT""REJECTED"

results[].numberOfPeoplenumber(numberOfPeople)>= 1

The number of guests

results[].paymentsArray of objects(payments)

A list of payments applied to the booking.

results[].startTimestring(date-time)

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

Example: "2018-05-02T17:30:00Z"

results[].endTimestring(date-time)

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

Example: "2018-05-02T18:30:00Z"

results[].assettableAsset (object) or roomAsset (object)

One of:

results[].customerobject(customer)

The customer making the booking

results[].notesstring

Notes specific to the booking. Example: 'Window seat please'

results[].reasonstring(reason)<= 50 characters

The reason the booking was rejected or cancelled. Provided only when bookingStatus is REJECTED, CANCELLED_BY_MERCHANT or CANCELLED_BY_CUSTOMER

results[].createdAtstring

The timestamp when the Booking was created

Example: "2022-11-23T22:39:54.931Z"

results[].updatedAtstring

The timestamp when the Booking was last updated

Example: "2022-11-23T22:40:48.237Z"

paginationobjectrequired

pagination.pageinteger>= 1required

pagination.sizeintegerrequired

pagination.limitintegerrequired

pagination.totalintegerrequired

Response

application/json

{
  "pagination": {
    "page": 1,
    "size": 2,
    "limit": 10,
    "total": 2
  },
  "results": [
    { … },
    { … }
  ]
}

Get Booking

Request

This endpoint is for fetching the details of a booking

Security

JWT

Path

bookingIdstringrequired

Id of the booking in Tyro Connect that should be retrieved

Headers

Authorizationstringrequired

Default Bearer {$$.env.access_token}

Acceptstring(acceptHeaderBooking1_0)required

Specifies which version of the API to use. If no value is provided then 0.1 version will be used

Default application/vnd.tyro.connect+json;version=0.1

Enum"application/vnd.tyro.connect+json;version=1.0""application/vnd.tyro.connect+json;version=0.1"

curl -i -X GET \
  'https://api.tyro.com/connect/bookings/{bookingId}' \
  -H 'Accept: application/vnd.tyro.connect+json;version=1.0' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The booking response

Bodyapplication/json

idstringrequired

The id of the booking in the Tyro Connect system

Example: "0f448ac1-862a-4c7b-bdb4-a3b7cdbf6149"

locationIdstringrequired

The id of the location as specified by the Tyro Connect system

originobject

Information relevant to the booking partner that this booking was created with

bookingStatusstring(bookingStatus)

The status of the booking within the Booking system

Enum"CREATED""ACCEPTED""CANCELLED_BY_CUSTOMER""CANCELLED_BY_MERCHANT""REJECTED"

numberOfPeoplenumber(numberOfPeople)>= 1

The number of guests

paymentsArray of objects(payments)

A list of payments applied to the booking.

startTimestring(date-time)

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

Example: "2018-05-02T17:30:00Z"

endTimestring(date-time)

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

Example: "2018-05-02T18:30:00Z"

assettableAsset (object) or roomAsset (object)

One of:

customerobject(customer)

The customer making the booking

notesstring

Notes specific to the booking. Example: 'Window seat please'

reasonstring(reason)<= 50 characters

The reason the booking was rejected or cancelled. Provided only when bookingStatus is REJECTED, CANCELLED_BY_MERCHANT or CANCELLED_BY_CUSTOMER

createdAtstring

The timestamp when the Booking was created

Example: "2022-11-23T22:39:54.931Z"

updatedAtstring

The timestamp when the Booking was last updated

Example: "2022-11-23T22:40:48.237Z"

Response

application/json

{
  "id": "2688fcf2-44dd-4c72-88ac-79d0910f2983",
  "locationId": "merchant:abc123",
  "origin": {
    "bookingReference": "some-booking-reference"
  },
  "customer": {
    "id": "85GFA95D",
    "name": "Jennifer Wicks",
    "notes": "Birthday breakfast"
  },
  "startTime": "2020-12-01T08:00:00+10:00",
  "endTime": "2020-12-01T10:00:00+10:00",
  "bookingStatus": "ACCEPTED",
  "numberOfPeople": 2,
  "payments": [
    { … }
  ],
  "asset": {
    "type": "TABLE",
    "tableStatus": "SEATED",
    "tables": [ … ],
    "discounts": [ … ],
    "preOrders": [ … ]
  },
  "createdAt": "2021-05-04T08:00:00+10:00",
  "updatedAt": "2021-05-04T10:00:00+10:00"
}

Update Booking

Request

This endpoint is for updating a booking

Security

JWT

Path

bookingIdstringrequired

Id of the booking in Tyro Connect that should be updated

Headers

Authorizationstringrequired

Default Bearer {$$.env.access_token}

Acceptstring(acceptHeaderBooking1_0)required

Specifies which version of the API to use. If no value is provided then 0.1 version will be used

Default application/vnd.tyro.connect+json;version=0.1

Enum"application/vnd.tyro.connect+json;version=1.0""application/vnd.tyro.connect+json;version=0.1"

Content-Typestringrequired

Value"application/merge-patch+json"

Bodyapplication/merge-patch+json

bookingStatusstring(bookingStatus)

The status of the booking within the Booking system

Enum"CREATED""ACCEPTED""CANCELLED_BY_CUSTOMER""CANCELLED_BY_MERCHANT""REJECTED"

assetobject

numberOfPeoplenumber(numberOfPeople)>= 1

The number of guests

reasonstring(reason)<= 50 characters

The reason the booking was rejected or cancelled. Provided only when bookingStatus is REJECTED, CANCELLED_BY_MERCHANT or CANCELLED_BY_CUSTOMER

curl -i -X PATCH \
  'https://api.tyro.com/connect/bookings/{bookingId}' \
  -H 'Accept: application/vnd.tyro.connect+json;version=1.0' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/merge-patch+json' \
  -d '{
    "asset": {
      "tableStatus": "FINALISED"
    }
  }'

Responses

No body content

Body

Response

No content

Get Booking Events

Request

This endpoint is for fetching the events associated with a booking. The events are ordered with the most recent event first.

Security

JWT

Path

bookingIdstringrequired

Id of the booking in Tyro Connect that should be retrieved

Headers

Authorizationstringrequired

Default Bearer {$$.env.access_token}

curl -i -X GET \
  'https://api.tyro.com/connect/bookings/{bookingId}/events' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The booking events response

Bodydata

eventsArray of objects(Booking Events)non-empty

The list of events associated with the booking

Response

data

{
  "events": [
    {
      "id": "a17a35ee-e275-4eac-9a8d-7c58c1dbab68",
      "locationId": "test-cafe",
      "type": "BOOKING_FINALISED",
      "sourceOfChange": "POS",
      "eventData": {
        "asset": {
          "tableStatus": "FINALISED"
        }
      },
      "outcome": {
        "asset": {
          "type": "TABLE",
          "tables": [
            {
              "number": "88B"
            }
          ],
          "tableStatus": "FINALISED"
        },
        "customer": {
          "name": "jerry seinfeld",
          "email": "jerry@seinfeld.com"
        },
        "startTime": "2018-05-02T17:30:00.000Z",
        "numberOfPeople": 3
      },
      "createdAt": "2021-04-21T05:52:17.222Z"
    },
    {
      "id": "a17a35ee-e275-4eac-9a8d-7c58c1dbab68",
      "locationId": "test-cafe",
      "type": "BOOKING_CLOSING",
      "sourceOfChange": "POS",
      "eventData": {
        "asset": {
          "tableStatus": "CLOSING"
        }
      },
      "outcome": {
        "asset": {
          "type": "TABLE",
          "tables": [
            {
              "number": "88B"
            }
          ],
          "tableStatus": "CLOSING"
        },
        "customer": {
          "name": "jerry seinfeld",
          "email": "jerry@seinfeld.com"
        },
        "startTime": "2018-05-02T17:30:00.000Z",
        "numberOfPeople": 3
      },
      "createdAt": "2021-04-21T05:52:13.339Z"
    },
    {
      "id": "a17a35ee-e275-4eac-9a8d-7c58c1dbab68",
      "locationId": "test-cafe",
      "type": "BOOKING_DINING",
      "sourceOfChange": "POS",
      "eventData": {
        "asset": {
          "tableStatus": "DINING"
        }
      },
      "outcome": {
        "asset": {
          "type": "TABLE",
          "tables": [
            {
              "number": "88B"
            }
          ],
          "tableStatus": "DINING"
        },
        "customer": {
          "name": "jerry seinfeld",
          "email": "jerry@seinfeld.com"
        },
        "startTime": "2018-05-02T17:30:00.000Z",
        "numberOfPeople": 3
      },
      "createdAt": "2021-04-21T05:52:08.322Z"
    },
    {
      "id": "a17a35ee-e275-4eac-9a8d-7c58c1dbab68",
      "locationId": "test-cafe",
      "type": "BOOKING_CREATED",
      "sourceOfChange": "APP",
      "eventData": {
        "asset": {
          "tables": [
            {
              "number": "88B"
            }
          ]
        },
        "customer": {
          "name": "jerry seinfeld",
          "email": "jerry@seinfeld.com"
        },
        "startTime": "2018-05-02T17:30:00.000Z",
        "numberOfPeople": 3
      },
      "outcome": {
        "asset": {
          "tables": [
            {
              "number": "88B"
            }
          ]
        },
        "customer": {
          "name": "jerry seinfeld",
          "email": "jerry@seinfeld.com"
        },
        "startTime": "2018-05-02T17:30:00.000Z",
        "numberOfPeople": 3
      },
      "createdAt": "2021-04-21T05:51:41.944Z"
    }
  ]
}

Booking API (1.0)

Create booking

RequestExpand all

Responses

List Bookings

Request

Filtering

Pagination

Responses

Get Booking

Request

Responses

Update Booking

RequestExpand all

Responses

Get Booking Events

Request

Responses

Request

Request