Ordering API for App Partners (1.0)

This is the API for Apps looking to implement Ordering on Tyro Connect

Overview

Servers

Production

https://api.tyro.com/connect

New Order

Request

This endpoint is for creating an order that Tyro Connect will deliver to a POS.

Make sure you create the order in one of the following statuses:

CREATED - the order has been created but not approved by the merchant.
ACCEPTED - the order has already been approved by the merchant (eg. via a separate app available to them).

Making identical requests with the same orderId and content does not create a new order. In this case, it returns the previously created order's details. This means every new order must have a different orderId.

Security

JWT

Headers

Authorizationstringrequired

Default Bearer {$$.env.access_token}

Bodyapplication/json

originobjectrequired

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

origin.orderIdstring<= 50 charactersrequired

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

origin.orderReferencestringrequired

Reference for the order. You should use it to facilitate the communication between the merchant and the eater during fulfillment by providing a short code that allows the order to be easily identifiable.

locationIdstring<= 50 charactersrequired

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

statusstringrequired

The current status of the order. When created, order status must be CREATED or ACCEPTED.

Default "CREATED"

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

notesstring

A free text field with instructions from the customer to the merchant.

itemsArray of objects(Order Item)required

A list of all the items in the order.

items[].idstringrequired

An id unique to the order, representing the item within the overall order. 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.modifiersTotal - item.discounts) * item.quantity

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[].allergensArray of objects

Allergens that need to be removed from the parent item.

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[].notesstring

An instruction or message about this order item.

tableobject

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

customersArray of objects

The object only has a single field firstName.

discountsArray of objects(Money Positive Amount)

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

surchargesArray of objects(Money Positive Amount)

Each entry in the surcharges array 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.modifiersTotal - item.discounts) * item.quantity + order.surcharges - order.discounts + order.tip. Please note that TyroConnect does not enforce this calculation to allow flexibility while creating an order.

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"

tipobject(Money Positive Amount)

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

fulfilmentobjectrequired

Details about how the customers expect to receive the order.

fulfilment.typestringrequired

Type of fulfilment the customer expects

Enum"PICK_UP""DINE_IN""DELIVERY"

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"

curl -i -X POST \
  https://api.tyro.com/connect/orders \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "locationId": "tc-merchant-2000",
    "origin": {
      "orderId": "2f8922fb-235f-40c6-af9a-3d6b46ce9635",
      "orderReference": "Order for Tom"
    },
    "items": [
      {
        "id": "unique-item-id",
        "sku": "sku-known-to-the-pos",
        "description": "Amazing cheese burger",
        "unitPrice": {
          "currency": "AUD",
          "amount": 2000
        },
        "discounts": [
          {
            "currency": "AUD",
            "amount": 1000,
            "description": "Half price cheese burgers on the first of the month"
          }
        ],
        "modifiers": [
          {
            "id": "uuid-3636-101",
            "sku": "634",
            "description": "Bacon",
            "unitPrice": {
              "amount": 0
            },
            "quantity": 1
          }
        ],
        "allergens": [
          {
            "description": "Fish"
          },
          {
            "description": "Nuts"
          }
        ],
        "quantity": 1
      }
    ],
    "discounts": [
      {
        "currency": "AUD",
        "amount": 200,
        "description": "Student discount"
      }
    ],
    "surcharges": [
      {
        "currency": "AUD",
        "amount": 200,
        "description": "Public Holiday"
      },
      {
        "currency": "AUD",
        "amount": 200,
        "description": "Plastic take away containers"
      }
    ],
    "tip": {
      "currency": "AUD",
      "amount": 150
    },
    "total": {
      "currency": "AUD",
      "amount": 1350
    },
    "table": {
      "id": "B1",
      "section": "Bar"
    },
    "status": "CREATED",
    "customers": [
      {
        "firstName": "Daniel"
      },
      {
        "firstName": "Elizabeth"
      }
    ],
    "fulfilment": {
      "type": "PICK_UP"
    },
    "paymentStatus": "CLOSED"
  }'

Responses

Created order

Bodyapplication/json

originobjectrequired

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

origin.orderIdstring<= 50 charactersrequired

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

origin.orderReferencestringrequired

origin.namestring

This will be your name. It is mostly used by POS's to identify where an order came from

locationIdstring<= 50 charactersrequired

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

statusstringrequired

The current status of the order. When created, order status must be CREATED or ACCEPTED.

Default "CREATED"

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

notesstring

A free text field with instructions from the customer to the merchant.

itemsArray of objects(Order Item)required

A list of all the items in the order.

items[].idstringrequired

An id unique to the order, representing the item within the overall order. 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)

items[].modifiersArray of objects(Order Item)

items[].allergensArray of objects

Allergens that need to be removed from the parent item.

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[].notesstring

An instruction or message about this order item.

tableobject

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

customersArray of objects

The object only has a single field firstName.

discountsArray of objects(Money Positive Amount)

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

surchargesArray of objects(Money Positive Amount)

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

totalobject(Money Positive Amount)required

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"

tipobject(Money Positive Amount)

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

fulfilmentobjectrequired

Details about how the customers expect to receive the order.

fulfilment.typestringrequired

Type of fulfilment the customer expects

Enum"PICK_UP""DINE_IN""DELIVERY"

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"

idstring

This is the Tyro Connect system order Id. It uniquely identifies the order.

Response

application/json

{
  "id": "order-identifier-in-tyro-connect",
  "locationId": "tc-merchant-2000",
  "origin": {
    "orderId": "2f8922fb-235f-40c6-af9a-3d6b46ce9635",
    "orderReference": "Order for Tom",
    "name": "Charlie's Preorder App"
  },
  "items": [
    { … }
  ],
  "discounts": [
    { … }
  ],
  "surcharges": [
    { … },
    { … }
  ],
  "tip": {
    "currency": "AUD",
    "amount": 150
  },
  "total": {
    "currency": "AUD",
    "amount": 1350
  },
  "table": {
    "id": "B1",
    "section": "Bar"
  },
  "status": "CREATED",
  "customers": [
    { … },
    { … }
  ],
  "fulfilment": {
    "type": "PICK_UP"
  },
  "paymentStatus": "CLOSED"
}

Get Order

Request

This endpoint is for fetching the details of an order.

Security

JWT

Path

orderIdstringrequired

ID of order to retrieve

Headers

Authorizationstringrequired

Default Bearer {$$.env.access_token}

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

Responses

The order response

Bodyapplication/json

originobjectrequired

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

origin.orderIdstring<= 50 charactersrequired

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

origin.orderReferencestringrequired

origin.namestring

This will be your name. It is mostly used by POS's to identify where an order came from

locationIdstring<= 50 charactersrequired

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

statusstringrequired

The current status of the order. When created, order status must be CREATED or ACCEPTED.

Default "CREATED"

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

notesstring

A free text field with instructions from the customer to the merchant.

itemsArray of objects(Order Item)required

A list of all the items in the order.

items[].idstringrequired

An id unique to the order, representing the item within the overall order. 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)

items[].modifiersArray of objects(Order Item)

items[].allergensArray of objects

Allergens that need to be removed from the parent item.

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[].notesstring

An instruction or message about this order item.

tableobject

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

customersArray of objects

The object only has a single field firstName.

discountsArray of objects(Money Positive Amount)

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

surchargesArray of objects(Money Positive Amount)

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

totalobject(Money Positive Amount)required

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"

tipobject(Money Positive Amount)

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

fulfilmentobjectrequired

Details about how the customers expect to receive the order.

fulfilment.typestringrequired

Type of fulfilment the customer expects

Enum"PICK_UP""DINE_IN""DELIVERY"

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"

idstring

This is the Tyro Connect system order Id. It uniquely identifies the order.

statusInfostring

This field provides additional information about the status of an order

Value"AUTO_REJECTED_BY_TIMEOUT"

Response

application/json

{
  "id": "order-identifier-in-tyro-connect",
  "locationId": "tc-merchant-2000",
  "origin": {
    "orderId": "2f8922fb-235f-40c6-af9a-3d6b46ce9635",
    "orderReference": "Order for Tom",
    "name": "Charlie's Preorder App"
  },
  "items": [
    { … }
  ],
  "discounts": [
    { … }
  ],
  "surcharges": [
    { … },
    { … }
  ],
  "tip": {
    "currency": "AUD",
    "amount": 150
  },
  "total": {
    "currency": "AUD",
    "amount": 1350
  },
  "table": {
    "id": "B1",
    "section": "Bar"
  },
  "status": "ACCEPTED",
  "customers": [
    { … },
    { … }
  ],
  "fulfilment": {
    "type": "PICK_UP"
  },
  "paymentStatus": "CLOSED"
}

Update Order

Request

In order to provide more information about the status changes to the order, you can send the following statuses:

CANCELLED_BY_CUSTOMER - customer has cancelled the order.
FULFILLED - The order was completed successfully.

Security

JWT

Path

orderIdstringrequired

Identifier of the order that needs to be updated

Headers

Authorizationstringrequired

Default Bearer {$$.env.access_token}

Bodyapplication/merge-patch+json

statusstringrequired

Enum"CANCELLED_BY_CUSTOMER""FULFILLED"

reasonstring

Required only when status is CANCELLED_BY_CUSTOMER. An empty string will be considered as invalid

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

Responses

No body content. Order updated successfully

Response

No content

Ordering API for App Partners (1.0)

New Order

RequestExpand all

Responses

Get Order

Request

Responses

Update Order

Request

Responses

Request