Sales Data API (1.1)

This is the API for POS's looking to implement sales data on Tyro Connect

Overview

Servers

Production

https://api.tyro.com/connect

Create Sale

Request

This endpoint is used to send open or closed Sales to Tyro Connect. Please note, all items in a sale must be of an identical currency.

Security

JWT

Headers

Authorizationstringrequired

Default Bearer {$$.env.access_token}

Bodyapplication/json

When creating a sale, please try to include all the optional fields that are available.

locationIdstringrequired

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

originobjectrequired

Identifiers and reference numbers that were generated by the partner.

origin.saleIdstringrequired

The Id of the sale generated by the partner. This value should allow for partner systems to reconcile this sale.

origin.locationIdstringrequired

The Id of the store according to the partner.

sourceobjectrequired

Information about the source of the sale.

source.typestringrequired

An enum describing the source type of the sale.

Enum"DELIVEROO""DOORDASH""GOOGLE""HEYYOU""HUNGRYHUNGRY""MEANDU""MENULOG""MRYUM""ORDERUP""OTHER"

source.otherstring

The source of the sale if the source type is OTHER.

typestringrequired

An enum describing what kind of sale took place.

Default "SALE"

Enum"SALE""REFUND""VOID""COMBINATION"

statusstring

An enum describing the status of the sale. A closed sale cannot be opened.

Default "CLOSED"

Enum"CLOSED""OPEN""REOPENED"

openedZonedDateTimestring(date-time)required

The time the sale was opened on the partner. The format of the date time is the notation as defined by RFC 3339, section 5.6

Example: "2018-05-02T08:28:13+10:00"

closedZonedDateTimestring(date-time)

The time the sale was closed on the partner. closedZonedDateTime is required when the status is CLOSED otherwise optional. The format of the date time is the notation as defined by RFC 3339, section 5.6.

Example: "2018-05-02T08:28:13+10:00"

parentSaleIdstring

The original sale id referencing the previous sale that was reopened. Only allowed if the status is REOPENED and it must reference an existing sale id.

customerobject

registerobject

Information about which register in the venue was used

staffobjectrequired

Details about the staff member who performed the transaction

staff.idstringrequired

The id of the staff member in the POS system. Please do not put the staff members name here

sectionobject

The section within the venue where the sale took place.

tableobject

Optional information about the table where in the venue the sale took place.

bookingIdstring

The booking ID defined by Tyro Connect to identify a reservation

itemsArray of objects(Line Item)

discountsArray of objects(Money Positive Amount)

surchargesArray of objects(Money Positive Amount)

taxobject(Money Positive Amount)

The total amount (in cents) of tax collected for this sale by the merchant.

paymentsArray of objects

totalobject(Money Positive Amount)

The total (in cents) of this sale after tax, discounts, modifiers and rounding have been applied.

curl -i -X POST \
  https://api.tyro.com/connect/sales \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "locationId": "luna-park",
    "origin": {
      "saleId": "SaleId",
      "locationId": "POS-0000001"
    },
    "source": {
      "type": "MEANDU"
    },
    "type": "SALE",
    "status": "CLOSED",
    "openedZonedDateTime": "2018-05-02T08:28:13+10:00",
    "closedZonedDateTime": "2018-05-02T08:28:13+10:00",
    "staff": {
      "id": "8675309"
    },
    "bookingId": "6dca53a9-04c7-46aa-991c-cfdf51a8f652",
    "items": [
      {
        "id": "DRINK-123",
        "name": "Diet Soda",
        "sku": "1123581321",
        "unitPrice": {
          "amount": 123,
          "currency": "AUD"
        },
        "unitPriceTax": {
          "amount": 123,
          "currency": "AUD"
        },
        "quantity": 3,
        "tax": {
          "amount": 369,
          "currency": "AUD"
        },
        "total": {
          "amount": 369,
          "currency": "AUD"
        }
      }
    ],
    "payments": [
      {
        "acquirer": {
          "name": "TYRO",
          "transactionReference": "88888888-4444-4444-4444-121212121212",
          "terminalId": "57"
        },
        "method": "EFTPOS",
        "type": "SALE",
        "goodsAndServicesAmount": {
          "amount": 123,
          "currency": "AUD"
        }
      }
    ],
    "tax": {
      "amount": 123,
      "currency": "AUD"
    },
    "total": {
      "amount": 369,
      "currency": "AUD"
    }
  }'

Responses

If the Sale was successfully saved on the server you will receive a 201 Created and the created Sale.

Bodyapplication/json

idstringrequired

The sale id provided by Tyro

versionnumberrequired

The current version of the Sale. The most update to date version needs to be provided when making updates.

locationIdstringrequired

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

originobjectrequired

Identifiers and reference numbers that were generated by the partner.

origin.saleIdstringrequired

The Id of the sale generated by the partner. This value should allow for partner systems to reconcile this sale.

origin.locationIdstringrequired

The Id of the store according to the partner.

sourceobjectrequired

Information about the source of the sale.

source.typestringrequired

An enum describing the source type of the sale.

Enum"DELIVEROO""DOORDASH""GOOGLE""HEYYOU""HUNGRYHUNGRY""MEANDU""MENULOG""MRYUM""ORDERUP""OTHER"

source.otherstring

The source of the sale if the source type is OTHER.

typestringrequired

An enum describing what kind of sale took place.

Default "SALE"

Enum"SALE""REFUND""VOID""COMBINATION"

statusstring

An enum describing the status of the sale. A closed sale cannot be opened.

Default "CLOSED"

Enum"CLOSED""OPEN""REOPENED"

openedZonedDateTimestring(date-time)required

The time the sale was opened on the partner. The format of the date time is the notation as defined by RFC 3339, section 5.6

Example: "2018-05-02T08:28:13+10:00"

closedZonedDateTimestring(date-time)

The time the sale was closed on the partner. The format of the date time is the notation as defined by RFC 3339, section 5.6

Example: "2018-05-02T08:28:13+10:00"

parentSaleIdstring

The original sale id referencing the previous sale that was reopened.

customerobject

registerobject

Information about which register in the venue was used

staffobjectrequired

Details about the staff member who performed the transaction

staff.idstringrequired

The id of the staff member in the POS system. Please do not put the staff members name here

sectionobject

The section within the venue where the sale took place.

tableobject

Optional information about the table where in the venue the sale took place.

bookingIdstring

The booking ID defined by Tyro Connect to identify a reservation

itemsArray of objects(Line Item)

discountsArray of objects(Money Positive Amount)

surchargesArray of objects(Money Positive Amount)

taxobject(Money Positive Amount)

The total amount (in cents) of tax collected for this sale by the merchant.

paymentsArray of objects

totalobject(Money Positive Amount)

The total (in cents) of this sale after tax, discounts, modifiers and rounding have been applied.

subtotalobject(Money Positive Amount)

The subtotal (in cents) of this sale.

Response

application/json

{
  "id": "string",
  "version": 0,
  "locationId": "string",
  "origin": {
    "saleId": "string",
    "locationId": "string"
  },
  "source": {
    "type": "DELIVEROO",
    "other": "string"
  },
  "type": "SALE",
  "status": "CLOSED",
  "openedZonedDateTime": "2018-05-02T08:28:13+10:00",
  "closedZonedDateTime": "2018-05-02T08:28:13+10:00",
  "parentSaleId": "string",
  "customer": {
    "id": "string"
  },
  "register": {
    "id": "string",
    "name": "string"
  },
  "staff": {
    "id": "string"
  },
  "section": {
    "id": "string",
    "name": "string"
  },
  "table": {
    "number": "MAIN-33",
    "seats": 0
  },
  "bookingId": "string",
  "items": [
    { … }
  ],
  "discounts": [
    { … }
  ],
  "surcharges": [
    { … }
  ],
  "tax": {
    "amount": 12520,
    "currency": "AUD"
  },
  "payments": [
    { … }
  ],
  "total": {
    "amount": 12520,
    "currency": "AUD"
  },
  "subtotal": {
    "amount": 12520,
    "currency": "AUD"
  }
}

Get Sales Data by SalesId

Request

This endpoint is for fetching the details of a sales.

Security

JWT

Path

saleIdstringrequired

Headers

Authorizationstringrequired

Default Bearer {$$.env.access_token}

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

Responses

The sales response

Bodyapplication/json

idstringrequired

The sale id provided by Tyro

versionnumberrequired

The current version of the Sale. The most update to date version needs to be provided when making updates.

locationIdstringrequired

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

originobjectrequired

Identifiers and reference numbers that were generated by the partner.

origin.saleIdstringrequired

The Id of the sale generated by the partner. This value should allow for partner systems to reconcile this sale.

origin.locationIdstringrequired

The Id of the store according to the partner.

sourceobjectrequired

Information about the source of the sale.

source.typestringrequired

An enum describing the source type of the sale.

Enum"DELIVEROO""DOORDASH""GOOGLE""HEYYOU""HUNGRYHUNGRY""MEANDU""MENULOG""MRYUM""ORDERUP""OTHER"

source.otherstring

The source of the sale if the source type is OTHER.

typestringrequired

An enum describing what kind of sale took place.

Default "SALE"

Enum"SALE""REFUND""VOID""COMBINATION"

statusstring

An enum describing the status of the sale. A closed sale cannot be opened.

Default "CLOSED"

Enum"CLOSED""OPEN""REOPENED"

openedZonedDateTimestring(date-time)required

The time the sale was opened on the partner. The format of the date time is the notation as defined by RFC 3339, section 5.6

Example: "2018-05-02T08:28:13+10:00"

closedZonedDateTimestring(date-time)

The time the sale was closed on the partner. The format of the date time is the notation as defined by RFC 3339, section 5.6

Example: "2018-05-02T08:28:13+10:00"

parentSaleIdstring

The original sale id referencing the previous sale that was reopened.

customerobject

registerobject

Information about which register in the venue was used

staffobjectrequired

Details about the staff member who performed the transaction

staff.idstringrequired

The id of the staff member in the POS system. Please do not put the staff members name here

sectionobject

The section within the venue where the sale took place.

tableobject

Optional information about the table where in the venue the sale took place.

bookingIdstring

The booking ID defined by Tyro Connect to identify a reservation

itemsArray of objects(Line Item)

discountsArray of objects(Money Positive Amount)

surchargesArray of objects(Money Positive Amount)

taxobject(Money Positive Amount)

The total amount (in cents) of tax collected for this sale by the merchant.

paymentsArray of objects

totalobject(Money Positive Amount)

The total (in cents) of this sale after tax, discounts, modifiers and rounding have been applied.

subtotalobject(Money Positive Amount)

The subtotal (in cents) of this sale.

Response

application/json

{
  "version": 69,
  "locationId": "luna-park",
  "origin": {
    "saleId": "SaleId"
  },
  "source": {
    "type": "MEANDU"
  },
  "type": "SALE",
  "status": "CLOSED",
  "openedZonedDateTime": "2018-05-02T08:28:13+10:00",
  "closedZonedDateTime": "2018-05-02T08:28:13+10:00",
  "staff": {
    "id": "8675309"
  },
  "bookingId": "6dca53a9-04c7-46aa-991c-cfdf51a8f652",
  "items": [
    { … }
  ],
  "payments": [
    { … }
  ],
  "tax": {
    "amount": 123,
    "currency": "AUD"
  },
  "total": {
    "amount": 369,
    "currency": "AUD"
  },
  "table": {
    "seats": 1,
    "number": "11"
  },
  "subtotal": {
    "amount": 369,
    "currency": "AUD"
  }
}

Update Sale

Request

This endpoint is used to updates Sales. Please note, updates with the same contents are ignored and all items in a sale must be of an identical currency.

Security

JWT

Headers

Authorizationstringrequired

Default Bearer {$$.env.access_token}

Bodyapplication/json

versionnumberrequired

Represents the last read version of the sale returned by the GET request. If this version is out of date, the request will fail with a 412. Get the latest sale and merge it with the values from this request, then retry with the latest version.

statusstring

An enum describing the status of the sale. Once the sale has been closed, it cannot be reopened.

Default "CLOSED"

Enum"CLOSED""OPEN"

closedZonedDateTimestring(date-time)

The time the sale was closed on the POS. closedZonedDateTime is required when the status is CLOSED otherwise optional. The format of the date time is the notation as defined by RFC 3339, section 5.6.

Example: "2018-05-02T08:28:13+10:00"

staffobject

Details about the staff member from the POS

sectionobject

The section within the venue where the sale took place.

tableobject

Optional information about the table where in the venue the sale took place.

itemsArray of objects(Line Item)

Provide existing & new item to be applied to the sale. The update will do a complete array replacement so any items not provided in this request will be removed.

discountsArray of objects(Money Positive Amount)

Provide existing & new discounts to be applied to the sale. The update will do a complete array replacement so any discounts not provided in this request will be removed.

surchargesArray of objects(Money Positive Amount)

Provide existing & new surcharges to be applied to the sale. The update will do a complete array replacement so any surcharges not provided in this request will be removed.

taxobject(Money Positive Amount)

The total amount (in cents) of tax collected for this sale by the merchant. This must be updated when the total changes.

paymentsArray of objects

Provide all existing & new payments to be applied to the sale. Existing payments cannot be removed.

totalobject(Money Positive Amount)

The total (in cents) of this sale. This must be updated when items, discounts or surcharges are added. It is expected to calculate to: sum(items[].total) - discounts + surcharges

curl -i -X PATCH \
  'https://api.tyro.com/connect/sales/{saleId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "version": 0,
    "status": "CLOSED",
    "closedZonedDateTime": "2018-05-02T08:28:13+10:00",
    "staff": {
      "id": "string"
    },
    "section": {
      "id": "string",
      "name": "string"
    },
    "table": {
      "number": "MAIN-33",
      "seats": 0
    },
    "items": [
      {
        "id": "string",
        "name": "string",
        "category": "string",
        "description": "string",
        "sku": "string",
        "barcode": "string",
        "modifiers": [
          {}
        ],
        "unitPrice": {
          "amount": 12520,
          "currency": "AUD"
        },
        "unitPriceTax": {
          "amount": 12520,
          "currency": "AUD"
        },
        "unitCost": {
          "amount": 12520,
          "currency": "AUD"
        },
        "unitCostTax": {
          "amount": 12520,
          "currency": "AUD"
        },
        "discounts": [
          {
            "amount": 12520,
            "currency": "AUD",
            "description": "Tuesday Happy Hour Discount"
          }
        ],
        "sale": {
          "type": "SALE"
        },
        "surcharges": [
          {
            "amount": 12520,
            "currency": "AUD",
            "description": "Tuesday Happy Hour Discount"
          }
        ],
        "quantity": 0,
        "tax": {
          "amount": 12520,
          "currency": "AUD"
        },
        "total": {
          "amount": 12520,
          "currency": "AUD"
        },
        "hidden": true
      }
    ],
    "discounts": [
      {
        "amount": 12520,
        "currency": "AUD",
        "description": "Tuesday Happy Hour Discount"
      }
    ],
    "surcharges": [
      {
        "amount": 12520,
        "currency": "AUD",
        "description": "Tuesday Happy Hour Discount"
      }
    ],
    "tax": {
      "amount": 12520,
      "currency": "AUD"
    },
    "payments": [
      {
        "acquirer": {
          "name": "TYRO",
          "transactionReference": "string",
          "terminalId": "string"
        },
        "method": "EFTPOS",
        "type": "SALE",
        "goodsAndServicesAmount": {
          "amount": 12520,
          "currency": "AUD"
        },
        "tipAmount": {
          "amount": 12520,
          "currency": "AUD"
        },
        "cashoutAmount": {
          "amount": 12520,
          "currency": "AUD"
        },
        "surchargeAmount": {
          "amount": 12520,
          "currency": "AUD"
        },
        "items": [
          {
            "itemId": "string",
            "total": {
              "amount": 12520,
              "currency": "AUD"
            }
          }
        ]
      }
    ],
    "total": {
      "amount": 12520,
      "currency": "AUD"
    }
  }'

Responses

If the Sale was successfully updated on the server you will receive a 200 OK and the updated Sale with a new version.

Bodyapplication/json

idstringrequired

The sale id provided by Tyro

versionnumberrequired

The current version of the Sale. The most update to date version needs to be provided when making updates.

locationIdstringrequired

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

originobjectrequired

Identifiers and reference numbers that were generated by the partner.

origin.saleIdstringrequired

The Id of the sale generated by the partner. This value should allow for partner systems to reconcile this sale.

origin.locationIdstringrequired

The Id of the store according to the partner.

sourceobjectrequired

Information about the source of the sale.

source.typestringrequired

An enum describing the source type of the sale.

Enum"DELIVEROO""DOORDASH""GOOGLE""HEYYOU""HUNGRYHUNGRY""MEANDU""MENULOG""MRYUM""ORDERUP""OTHER"

source.otherstring

The source of the sale if the source type is OTHER.

typestringrequired

An enum describing what kind of sale took place.

Default "SALE"

Enum"SALE""REFUND""VOID""COMBINATION"

statusstring

An enum describing the status of the sale. A closed sale cannot be opened.

Default "CLOSED"

Enum"CLOSED""OPEN""REOPENED"

openedZonedDateTimestring(date-time)required

The time the sale was opened on the partner. The format of the date time is the notation as defined by RFC 3339, section 5.6

Example: "2018-05-02T08:28:13+10:00"

closedZonedDateTimestring(date-time)

The time the sale was closed on the partner. The format of the date time is the notation as defined by RFC 3339, section 5.6

Example: "2018-05-02T08:28:13+10:00"

parentSaleIdstring

The original sale id referencing the previous sale that was reopened.

customerobject

registerobject

Information about which register in the venue was used

staffobjectrequired

Details about the staff member who performed the transaction

staff.idstringrequired

The id of the staff member in the POS system. Please do not put the staff members name here

sectionobject

The section within the venue where the sale took place.

tableobject

Optional information about the table where in the venue the sale took place.

bookingIdstring

The booking ID defined by Tyro Connect to identify a reservation

itemsArray of objects(Line Item)

discountsArray of objects(Money Positive Amount)

surchargesArray of objects(Money Positive Amount)

taxobject(Money Positive Amount)

The total amount (in cents) of tax collected for this sale by the merchant.

paymentsArray of objects

totalobject(Money Positive Amount)

The total (in cents) of this sale after tax, discounts, modifiers and rounding have been applied.

subtotalobject(Money Positive Amount)

The subtotal (in cents) of this sale.

Response

application/json

{
  "id": "string",
  "version": 0,
  "locationId": "string",
  "origin": {
    "saleId": "string",
    "locationId": "string"
  },
  "source": {
    "type": "DELIVEROO",
    "other": "string"
  },
  "type": "SALE",
  "status": "CLOSED",
  "openedZonedDateTime": "2018-05-02T08:28:13+10:00",
  "closedZonedDateTime": "2018-05-02T08:28:13+10:00",
  "parentSaleId": "string",
  "customer": {
    "id": "string"
  },
  "register": {
    "id": "string",
    "name": "string"
  },
  "staff": {
    "id": "string"
  },
  "section": {
    "id": "string",
    "name": "string"
  },
  "table": {
    "number": "MAIN-33",
    "seats": 0
  },
  "bookingId": "string",
  "items": [
    { … }
  ],
  "discounts": [
    { … }
  ],
  "surcharges": [
    { … }
  ],
  "tax": {
    "amount": 12520,
    "currency": "AUD"
  },
  "payments": [
    { … }
  ],
  "total": {
    "amount": 12520,
    "currency": "AUD"
  },
  "subtotal": {
    "amount": 12520,
    "currency": "AUD"
  }
}

Sales Data API (1.1)

Create Sale

RequestExpand all

Responses

Get Sales Data by SalesId

Request

Responses

Update Sale

RequestExpand all

Responses

Request

Request