Food Ordering API (1.0)

This is the API for POSes looking to implement food ordering on Tyro Connect

Overview

Servers

Production

https://api.tyro.com/connect

Get Order

Request

This endpoint is used to fetch the details of an order. It can be used when a new webhook event is received. It can also be used to fetch the order at a later date if required.

Note: For the best end user experience, we recommend to include the following fields when showing the order to the user (eg. on a docket, bump screen):
origin.name - this displays the name of the App the order originated from,
origin.orderReference - this displays the order reference that allows its easy identification,
customers.firstName - this displays the name of the customer.

Please keep in mind that those fields do not have restrictions on length and might need to be handled appropriately on your end to be displayed correctly to the end user.

Security

JWT

Path

idstringrequired

Headers

Authorizationstringrequired

Default Bearer {$$.env.access_token}

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

Responses

The order response

Bodyapplication/json

idstring<= 50 charactersrequired

Order Id generated by Tyro Connect.

locationIdstring<= 50 charactersrequired

This is the Tyro Connect defined location Id. It is a globally unique identifier that is used to identify a merchants individual site

originobjectrequired

Contains information about the food ordering partner that created the order.

origin.orderIdstring<= 50 charactersrequired

An id that has been generated by the origin. This can be used for reconciliation of orders in the app partner's system.

origin.orderReferencestringrequired

A reference number provided by the app partner that allows for easy identification of an order by the restaurant staff and eaters.

origin.namestringrequired

The name of the food ordering partner where the order originated from. e.g ubereats, meandu

statusstringrequired

The status that the order is currently in

Enum"CREATED""ACCEPTED""REJECTED""BEING_PREPARED""READY""OUT_FOR_DELIVERY""CANCELLED_BY_MERCHANT""CANCELLED_BY_CUSTOMER""FULFILLED"

statusInfostring

This field provides additional information about the status of the order

Value"AUTO_REJECTED_BY_TIMEOUT"

fulfilmentobjectrequired

Details about how the customers expect to receive the order

fulfilment.typestring

Type of fulfilment the customer expects

Enum"PICK_UP""DINE_IN""DELIVERY"

notesstring

A free text field with instructions from the food recipient.

itemsArray of objects(Order Item)required

A list of all the items in the order.

items[].idstringrequired

It is unique for a given orderId and represents the item within the overall order, i.e. 2 of the same items will have unique ids.

items[].unitPriceobject(Money)required

The basic price of a single item in cents excluding discounts (if any).

items[].unitPrice.amountintegerrequired

This is the amount in smallest currency unit. e.g 12520 (in cents) is $125.20

Example: 12520

items[].unitPrice.currencystringrequired

Default "AUD"

Enum"AUD""EUR""NZD""GBP""USD"

Example: "AUD"

items[].discountsArray of objects(Money with Itemisation)

Each entry in the discounts array will apply to each single item - it represents unit discounts (eg. if the quantity of this object is defined as 2 and the discounts array contains one $1 entry, each of the 2 items should be discounted by $1). item.total = (item.unitPrice - item.discounts) * item.quantity

items[].skustringrequired

Id of the item that is aligned with the Id of the item in the POS.

items[].descriptionstringrequired

A human readable description of the item that can be used to resolve mismatches between the app and the POS.

items[].quantityinteger>= 0required

The number of units of this item required to fulfil the order. Please note that items with different modifiers or surcharges should be split into separate item objects.

items[].allergensArray of objects

Allergens that need to be removed from the parent item.

items[].modifiersArray of objects(Order Item)

A list of modifications to be made to the parent item. Each entry in this array will apply to each single item - it represents unit modifiers (eg. if the quantity of this object is defined as 2 and the modifiers array contains one $1 entry, each of the 2 items should be modified by $1). item.total = (item.unitPrice + item.modifiersTotal - item.discounts) * item.quantity'

items[].notesstring

A free text field with instructions about this order item.

tableobject

This object is optional, and if present will only have information about the table identifier and the section.

paymentStatusstring

Current payment status of the order. Can be either OPEN or CLOSED. OPEN payment status is only applicable for orders with fulfilment type of DINE_IN.

Default "CLOSED"

customersArray of objects

The object only has a single field firstName.

discountsArray of objects(Money)

Each entry in the discounts array will apply to the whole order and is included in the order total value.

surchargesArray of objects(Money)

Each entry in the surcharges array will apply to the whole order and is included in the order total value.

tipobject(Money Positive Amount)

This value will apply to the whole order and is included in the order total value.

totalobject(Money Positive Amount)required

The order total is calculated as order.total = (item.unitPrice - item.discounts) * item.quantity + order.surcharges - order.discounts + order.tip. Please note that TyroConnect does not enforce this calculation on the app side to allow flexibility and the provided total should always be used.

total.amountinteger>= 0required

This is the amount in smallest currency unit. e.g 12520 (in cents) is $125.20

Example: 12520

total.currencystringrequired

Default "AUD"

Enum"AUD""EUR""NZD""GBP""USD"

Example: "AUD"

Response

application/json

{
  "id": "uuid-1001",
  "locationId": "tc-location-1001",
  "origin": {
    "name": "UberEats",
    "orderId": "order-1001",
    "orderReference": "Order for Tom"
  },
  "status": "ACCEPTED",
  "notes": "Support it, but plenty of Merchants want it disabled. This would be an app setting",
  "items": [
    { … },
    { … },
    { … }
  ],
  "discounts": [
    { … }
  ],
  "surcharges": [
    { … },
    { … }
  ],
  "total": {
    "amount": 3344,
    "currency": "AUD"
  },
  "table": {
    "id": "B1"
  },
  "customers": [
    { … }
  ],
  "paymentStatus": "CLOSED",
  "fulfilment": {
    "type": "PICK_UP"
  }
}

Update Order

Request

There are two kinds of status updates that you can send to Tyro Connect to indicate how the order is progressing: mandatory status updates (that allow us to track order properly) and optional status updates (that will positively impact user experience if the connected App can handle such status update).

The mandatory status updates that you must send to indicate if the POS was able to successfully handle the order are:

ACCEPTED - POS accepted the order and it will be fulfilled.
REJECTED - POS failed to handle the order and the order will not be fulfilled.
READY - The order is ready to be picked up by the customer.

Orders that stay in the CREATED state for longer than two minutes will be automatically rejected and no further update is possible.

The optional status updates are:

BEING_PREPARED - order is being prepared
OUT_FOR_DELIVERY - order was dispatched for delivery (where applicable)
FULFILLED - The order has been picked up by the customer and is fulfilled (this will not apply if the order was dispatched for delivery).
CANCELLED_BY_MERCHANT - the merchant cancelled the order and it will not be fulfilled
CANCELLED_BY_CUSTOMER - customer contacted merchant and cancelled the order

Security

JWT

Path

idstringrequired

Headers

Authorizationstringrequired

Default Bearer {$$.env.access_token}

Bodyapplication/merge-patch+json

statusstringrequired

Enum"ACCEPTED""REJECTED""BEING_PREPARED""READY""OUT_FOR_DELIVERY""CANCELLED_BY_MERCHANT""CANCELLED_BY_CUSTOMER""FULFILLED"

reasonstring

Required only when status is REJECTED, CANCELLED_BY_MERCHANT or CANCELLED_BY_CUSTOMER. An empty string will be considered as invalid

curl -i -X PATCH \
  'https://api.tyro.com/connect/orders/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/merge-patch+json' \
  -d '{
    "status": "ACCEPTED"
  }'

Responses

No body content. Order updated successfully

Response

No content