Version 1.1 Changes
The following changes were introduced to support Pay at Table scenarios.
-
Added the update sale endpoint to allow both the POS and partner App to update the
OPENsale. -
Added the
SALE_UPDATEDwebhook event for the POS to be notified when changes are made to the sale. -
Added the
SALE_CLOSEDwebhook event for the POS to be notified when the sale status changes fromOPENtoCLOSED.
The following change was introduced to support reopened sales.
-
Added the
SALE_REOPENEDwebhook event for the POS to be notified when a new sale has been created with statusREOPENED.
Sale Entity
| New/updated Field | Description | Change | Change Description |
|---|---|---|---|
| version | 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. | New | Added to handle accidental overwrites for the PATCH request since multiple partners can modify the same sale. |
| status | An enum describing the status of the sale | Updated | New status enum values OPEN and REOPENED added |
| closedZonedDateTime | The time local time the sale was closed on the partner. | Updated | This value is now optional for OPEN sales |
| parentSaleId | The original sale id referencing the previous sale that was reopened | New | This attribute can only be set when creating a REOPENED sale |
| items.hidden | This can be set by the POS to indicate that this item should be hidden by the partner App | New | Added new optional hidden field to items |
| payments.method | The payment method | Updated | New payment enum added called ONLINE for sales made via partner App |
| payments.items | Optional list that indicates which line items this payment is for | New | Added optional items array to payments. This allows partners to track which items are fully or partially paid for |
| payments | Payments made for the sale | Updated | Payments is now optional for OPEN sales |
| tax | The total amount (in cents) of tax collected for this sale by the merchant. | Updated | Tax is now optional for OPEN sales |
| customer.name | Name of the customer | Removed | Customer name has been removed as it was deprecated in version 1.0 |
| customer.id | Id of the customer | Updated | Customer id is now optional |
| register | Information about which register in the venue was used | Updated | Register fields are now optional |
Version 1.0 Changes
The following changes were made since the 'experimental' version released in 2018.
Sale Entity
| Experimental Field | Description | Changes | New Field Name |
|---|---|---|---|
| transactionId | POS generated ID of the sale | Moved | origin.saleId |
| merchantId | POS generated customer ID | Moved | customer.id |
| merchantName | POS generated customer name | Moved | customer.name |
| transactionType | The type of the sale (SALE, REFUND, VOID) | Moved | type |
| transactionDateTime | The local date and time of the sale | Split | saleOpenedDateTime & saleCompletedDateTime (RFC 3339 - section 5.6) |
| storeName | POS generated name of the store / location / venue | Removed | Now added automatically by Tyro Connect |
| staffId | The ID of the staff member entering in the sale | Moved | staff.id |
| staffName | The name of the staff member | Removed | |
| posName | The name of the register | Moved | register.name |
| posId | The ID of the register | Moved | register.id |
| tableNumber | The table number where the guests were seated | Moved | table.number |
| seats | The number of guests that were seated at the table | Moved | table.seats |
| section | The name of the section that the guests were seated in | Split | section.id & section.name |
| tipAmount | The total tip amount included in the sale | Moved | Money object (amount, currency) |
| discount | The discount applied at the basket level (over and above item level discount/s) | Split | discounts[] - array of Money object (amount, currency, description) |
| totalExTax | The total of the sale excluding tax | Removed | |
| tax | The tax collected as part of the sale | Split | Money object (amount, currency) |
| total | The total of the sale (sum of items - discounts + surcharges) | Split | Money object (amount, currency) |
| status | The status of the sale | No change | |
| payment[] | An array of payment objects contained in the sale | Moved | payments[] |
| items[] | An array of item objects contained in the sale | No change | |
| experimental[] | An array of experimental objects | Removed |
New fields added to the Sale Object
| New Field Name | Description |
|---|---|
| surcharges[] | An array of surcharges applied to the sale (amount, currency, description) |
Payment Entity
| Experimental Field | Description | Changes | New Field Name |
|---|---|---|---|
| terminalId | The ID of the acquirer's terminal | Split | Now an acquirer object (name, transactionReference, terminalId) |
| paymentTransactionId | The acquirer's transaction reference | Moved | acquirer.transactionReference (for Tyro use integratedTransactionId) |
| type | The type of payment (SALE, REFUND, VOID) | No change | |
| surchargeAmount | The surcharge charged by the acquirer for the payment | Split | Money object (amount, currency) |
| tipAmount | The tip amount made above the payment amount | Split | Money object (amount, currency) |
| amount | The amount of the payment related to the goods and services purchased | Moved | goodsAndServicesAmount |
| status | The status of the payment | Removed |
New fields added to the Payment Object
| New Field Name | Description |
|---|---|
| cashoutAmount | The cashout amount requested over the goodsAndServices amount |
| method | An enum set (EFTPOS, CASH, GIFT_CARD, POINTS) |
Item Entity
| Experimental Field | Description | Changes | New Field Name |
|---|---|---|---|
| sku | The Stock Keeping Unit (SKU or PLU) | No change | |
| productId | The product ID | Moved | id |
| productName | The product name | Moved | name |
| description | The product description | No change | |
| quantity | The quantity involved | Now a float | |
| discountAmount | The discount applied to this line item | Moved | discounts[] - array of Money object (amount, currency, description) |
| unitPrice | The unit price of each item (including tax but excluding discounts) | Split | Money object (amount, currency) |
| unitPriceExTax | The unit price of each item (excluding tax and excluding discounts) | Removed | |
| unitPriceTax | The tax component of the unit price | Split | Money object (amount, currency) |
| barcode | The barcode for the item | No change | |
| salesCategoryName | The category that the item is in | Moved | category |
New fields added to the Item Entity
| New Field Name | Description |
|---|---|
| unitCost | The unit cost of each (paid by the merchant) (including tax) |
| unitCostTax | The tax component of the unit cost (paid by the merchant - input tax credit) |
| modifiers | Nested array of Items used as modifiers of the Item they are connected to (useful for restaurants looking to capture modifications made to the item) |
| tax | The amount of tax collected by the merchant for this item |
| surcharges | Array of Money object (amount, currency, description) |
| total | The total price for this line item. Expected to be equal to (unitPrice * quantity) - sum(discounts) - sum(surcharges) + sum(modifiers[].total) |