# Ordering API

This is the API for Apps to create food orders on Tyro Connect, and for POS partners to fulfil them.

Version: 1.0

## Servers

Production
```
https://api.tyro.com/connect
```

## Security

### JWT

Type: openIdConnect
OpenID Connect URL: https://auth.connect.tyro.com/.well-known/openid-configuration

## Download OpenAPI description

[Ordering API](https://docs.connect.tyro.com/_bundle/api-explorer/ordering/1.0/index.yaml)

## Other

### New order

 - [POST /orders](https://docs.connect.tyro.com/api-explorer/ordering/1.0/other/create-order.md): App only.

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.

### Get order

 - [GET /orders/{orderId}](https://docs.connect.tyro.com/api-explorer/ordering/1.0/other/get-order.md): This endpoint is for fetching 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.

### Update order

 - [PATCH /orders/{orderId}](https://docs.connect.tyro.com/api-explorer/ordering/1.0/other/update-order.md): 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).

App only may send:
 - CANCELLED_BY_CUSTOMER - customer has cancelled the order.
 - FULFILLED - The order was completed successfully.

POS only may send, as mandatory status updates that indicate whether the POS was able to successfully handle the order:
 - 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 POS may also optionally send:
 - 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