POS Ticket

Overview

Aggregate and indexed Ticket information. Tickets are marked sale, void, or refund, reflected in the type attribute.

Tickets include information about purchased items, modifications to those items, discounts, surcharges, and payments.

Models

Developers can:

  • retrieve aggregated tickets information using the export ticket functionality.
  • submit new Ticket using the online ordering open ticket functionality.

Dependencies 0-* 0-* 0-* 0-* 0-* 0-* 0-* 0-* 0-* Ticket TicketSurcharge TicketPayment TicketDiscount (ticketId) TicketDiscount (ticketItemId) TicketGratuity TicketTax TicketItem TicketMetadata TicketItemModifier

Ticket & Item/Modifier level types

Open tickets (ticket.type:open)

Open tickets are in case "completedAt" is NULL and "open": true then type: "open". Type "open" may cover a case like:

Open Item or items on entire check

Use case: ticket is not closed.

SaleRef: #1 (Ticket.type:open)
+ Item #1 qty: 1 $5.00 (TicketItem.type:open) 
+ Item #2 qty: 2 $7.00 (TicketItem.type:open)
ItemTotal: $19.00
PaymentTotal: $0.00

Sale records (ticket.type:sale)

Sale records represent a regular "sale" when a check is already finalized and closed in POS. Some POS brands allow adjustments of the closed checks, so the data should be re-synced at the end of the business day/session.

Regular "sale" may cover a few more cases like:

Void Item or items on entire check

Voids an item or items from the check. Use case: The server made a mistake, added the item/modifier to the check, then sent them to the kitchen, and then understood that it was a mistake.

  • "VOID" items/modifiers are not included in sale-level totals;
  • "VOID" may happen on item or modifier level;
  • Those items are sent to the kitchen;
  • Such items may have a "voidReason"
SaleRef: #1 (Ticket.type:sale)
+ Item #1 qty: 1 $5.00 (TicketItem.type:void) 
+ Item #2 qty: 2 $7.00 (TicketItem.type:sale)
ItemTotal: $7.00
PaymentTotal: $7.00
Negative Sale

The server wants to give the money back after the day/session is closed.

The server may add an "Open Item" and put a negative amount. This negative item will be marked as "REFUND".

SaleRef: #1 (Ticket.type:sale)
+ Item #1 qty:-1 $-10.00 (TicketItem.type:refund)
+ Item #2 qty:2 $5.00 (TicketItem.type:sale)
+ Item #3 qty:1 $7.00 (TicketItem.type:void)
ItemTotal: $-5.00
PaymentTotal: $-5.00 (etc VISA)

Overring records (ticket.type:overring)

These records are to reverse the original sales in order to balance it if the server/manager made a mistake and wants to adjust it. Some POS brands don't allow adjustments of the original sale - instead they create an "overring" record to reverse and balance the original sale to 0. The check adjustment piece will be represented by a new "sale" record.

  • Overring records are taken as a "mistake" for the finalized checks;
  • Overring records may have only items/modifiers that are marked as "overring"
  • Overring records mostly balance the original sale to zero in (Original Sale + Overring record = 0), however, this is not a rule and in some cases, they can be partially balanced;
  • Some brands generate three records (Original Sale, Overring Record, Adjusted Sale) if the check has been re-opened and adjusted in POS;
  • To know "How many sales were there during the day?", the 3rd-party should subtract the "overring" records count from a "sale" records count;
  • Overring records will generally have a negative number like "guestCount", total of amounts, they can simply be aggregated across "sale" and "refund" records;
Item adjustment

The server/manager made an item adjustment same-day on the finalized check.

###
### Original Sale
###
SaleRef: #1 (Ticket.type:sale)
+ Item #1 qty:1 $1.00 (TicketItem.type:sale)
+ Item #2 qty:2 $4.00 (TicketItem.type:sale)
ItemTotal: $5.00
PaymentTotal: $5.00 (etc VISA)

###
### Overring record
###
SaleRef: #2 (Ticket.type:overring)
+ Item #1 qty:-1 $-1.00 (TicketItem.type:overring)
+ Item #2 qty:-2 $-4.00 (TicketItem.type:overring)
ItemTotal: $-5.00
PaymentTotal: $-5.00 (etc VISA)

###
### Adjusted sale
###
SaleRef: #3 (Ticket.type:sale)
+ Item #1 qty:1 $1.00 (TicketItem.type:sale)
ItemTotal: $1.00
PaymentTotal: $1.00 (CASH)
Void a transaction

The server paid the "wrong check" with diners' CC.

###
### Original Sale
###
SaleRef: #1 (Ticket.type:sale)
+ Item #1 qty:1 $1.00 (TicketItem.type:sale)
+ Item #2 qty:2 $4.00 (TicketItem.type:sale)
ItemTotal: $5.00
PaymentTotal: $5.00 (etc VISA)

###
### Overring record
###
SaleRef: #2 (Ticket.type:overring)
+ Item #1 qty:-1 $-1.00 (TicketItem.type:overring)
+ Item #2 qty:-2 $-4.00 (TicketItem.type:overring)
ItemTotal: $-5.00
PaymentTotal: $-5.00 (etc VISA)

###
### Adjusted sale
###
SaleRef: #3 (Ticket.type:sale)
+ Item #1 qty:1 $1.00 (TicketItem.type:sale)
+ Item #2 qty:2 $4.00 (TicketItem.type:sale)
ItemTotal: $5.00
PaymentTotal: $5.00 (CASH)

Refund records (ticket.type:refund)

The "refund" sale type is used to reverse the original check by items that should be refunded.

  • Refund records will generally have a negative number like a total of amounts, they can simply be aggregated across "sale" and "overring" records;
Partial refund

The diner paid for the check, and later requested their money back for some items.

###
### Original Sale
###
SaleRef: #1 (Ticket.type:sale)
+ Item #1 qty:1 $1.00 (TicketItem.type:sale)
+ Item #2 qty:2 $4.00 (TicketItem.type:sale)
+ Item #3 qty:1 $5.00 (TicketItem.type:sale)
ItemTotal: $10.00
PaymentTotal: $10.00 (etc VISA)

###
### Refund record
###
SaleRef: #2 (Ticket.type:refund)
+ Item #1 qty:-1 $-1.00 (TicketItem.type:refund)
+ Item #2 qty:-2 $-4.00 (TicketItem.type:refund)
ItemTotal: $-5.00
PaymentTotal: $-5.00 (etc VISA)
Full refund

The diner paid for the check and then requested their money back for all of the items

###
### Original Sale
###
SaleRef: #1 (Ticket.type:sale)
+ Item #1 qty:1 $1.00 (TicketItem.type:sale)
+ Item #2 qty:2 $4.00 (TicketItem.type:sale)
+ Item #3 qty:1 $5.00 (TicketItem.type:sale)
ItemTotal: $10.00
PaymentTotal: $10.00 (etc VISA)

###
### Refund record
###
SaleRef: #2 (Ticket.type:refund)
+ Item #1 qty:-1 $-1.00 (TicketItem.type:refund)
+ Item #2 qty:-2 $-4.00 (TicketItem.type:refund)
+ Item #3 qty:-1 $-5.00 (TicketItem.type:refund)
ItemTotal: $-10.00
PaymentTotal: $-10.00 (etc VISA)

Definitions

Ticket

Purchase information

Name Type Description
posRef* string POS ticket reference ID. Unique per location.
type* string Ticket type. One of: sale, refund, void, or overring
voidReason string Only for void tickets, describes the void reason (e.g., "Employee Error" or "Test")
customerName string Ticket customer first name and last name
customerRef string Ticket customer external reference
orderTypeName string The order type name of the ticket
orderNumber string In most cases same as ticket number
revenueCenterName string Revenue center name. E.g.: Dinning Room, Bar.
tableName string Revenue center table name. E.g.: Table #86
guestCount* integer Number of guests on the ticket
totalItems* number Sum of total price on ticket-level items in US cents
totalSurcharges* number Sum of all surcharges applied on ticket-level for the ticket in US cents
totalTax* number Sum of all ticket-level taxes in US cents. Formula: SUM(all TicketSurcharges.tax) + SUM(all TicketItems.tax)
totalGrand* number Final amount in decimal format to be paid in US cents. Formula: (totalItems + totalSurcharges + tax).
totalTips* number Total tips paid for this ticket in US cents
totalDiscounts* number Sum of all discounts applied to this ticket in US cents. Positive decimal in case if discount was applied for sale ticket, for refund discount is negative.
totalGratuities* number The ticket gratuities total amount in US cents
metadata* array Collection of additional metadata properties that describe this Ticket. Returns empty if this Ticket does not have any additional metadata to describe it.
openedAt* string Date and time in UTC at which the ticket was opened
openedByEmployee string Name of the employee who opened the ticket
openedByEmployeeRef string External reference of the employee who opened the ticket
closedAt* string Date and time in UTC at which the ticket was closed
closedByEmployee string Name of the employee who closed the ticket
closedByEmployeeRef string External reference of the employee who closed the ticket
ticketItems array Ticket items
ticketDiscounts array TicketLevel discounts
ticketPayments array Ticket payments
ticketSurcharges array Ticket surcharges
ticketGratuities array Ticket gratuities
ticketTaxes array The collection of ticket taxes

Ticket V2

Purchase information

Name Type Description
posRef* string POS ticket reference ID. Unique per location.
type* string Ticket type. One of: sale, refund, void, overring, or `open
voidReason string Only for void tickets, describes the void reason (e.g., "Employee Error" or "Test")
customerName string Ticket customer first name and last name
customerRef string Ticket customer external reference
orderTypeName string The order type name of the ticket
orderNumber string In most cases same as ticket number
revenueCenterName string Revenue center name. E.g.: Dinning Room, Bar.
tableName string Revenue center table name. E.g.: Table #86
guestCount* integer Number of guests on the ticket
totalItems* number Sum of total price on ticket-level items in US cents
totalSurcharges* number Sum of all surcharges applied on ticket-level for the ticket in US cents
totalTax* number Sum of all ticket-level taxes in US cents. Formula: SUM(all TicketSurcharges.tax) + SUM(all TicketItems.tax)
totalGrand* number Final amount in decimal format to be paid in US cents. Formula: (totalItems + totalSurcharges + tax).
totalTips* number Total tips paid for this ticket in US cents
totalDiscounts* number Sum of all discounts applied to this ticket in US cents. Positive decimal in case if discount was applied for sale ticket, for refund discount is negative.
totalGratuities* number The ticket gratuities total amount in US cents
metadata* array Collection of additional metadata properties that describe this Ticket. Returns empty if this Ticket does not have any additional metadata to describe it.
openedAt* string Date and time in UTC at which the ticket was opened
openedByEmployee string Name of the employee who opened the ticket
openedByEmployeeRef string External reference of the employee who opened the ticket
closedAt* string Date and time in UTC at which the ticket was closed
closedByEmployee string Name of the employee who closed the ticket
closedByEmployeeRef string External reference of the employee who closed the ticket
locationId* integer Location ID. This field is available only in the Batch Tickets Lookup endpoint.
orderTypeRef string The order type reference. Note: This field is available only in the Batch Tickets Lookup endpoint.
tableRef string The table reference. Note: This field is available only in the Batch Tickets Lookup endpoint.
displayTaxTotal* integer The tax amount printed on the check. Note: This field is available only in the Batch Tickets Lookup endpoint.
onlineOrderAppRef string Associated online ordering app reference. Note: This field is available only in the Batch Tickets Lookup endpoint.
onlineOrderAppKey string Associated online ordering app key value. Note: This field is available only in the Batch Tickets Lookup endpoint.
saleTicketParentRef string The reference to the "SALE" record. Available only for "REFUND" type records. Note: This field is available only in the Batch Tickets Lookup endpoint.
splitTicketParentRef string The reference to the parent Ticket. Available only for records that were created in POS during a "split" check feature. Note: This field is available only in the Batch Tickets Lookup endpoint.
combinedTicketParentRef string The reference to the parent Ticket. Available only for records that were created in POS during a "combine" feature. Note: This field is available only in the Batch Tickets Lookup endpoint.
ticketItems array Ticket items
ticketDiscounts array TicketLevel discounts
ticketPayments array Ticket payments
ticketSurcharges array Ticket surcharges
ticketGratuities array Ticket gratuities
ticketTaxes array The collection of ticket taxes

TicketSurcharge

Other applicable charges

Name Type Description
posRef* string POS ticket surcharge reference GUID/ID. Combination of (locationId + posRef) is unique
name* string Name of the surcharge. Like: Gratuity, Delivery Fee
surchargeAmount* number Surcharge amount in US cents
discountAmount* number Full amount of the surcharge-level discounts in US cents. Positive number in case of a discount, negative in case of a refund.
price* number Full cost of the surcharges in US cents excluding tax. Formula: surchargeAmount - discountAmount.
tax* number Tax amount applied for the surcharge in US cents. For non taxable surcharge is zero
addedAt* string Date and time in UTC when the surcharge was added
ticketDiscounts array Discounts applied on ticket level

TicketPayment

Registered payments

Name Type Description
posRef* string POS ticket payment reference GUID/ID. Combination of (locationId + posRef) is unique
type* string One of: sale, refund.
tenderName* string Tender type name, e.g. cash, credit, gift card
cardType string Not null in case of credit card payment. Defines credit card type, e.g. Visa, Amex, Mastercard
amount* number Money amount paid in US cents, tips are not included.
Important: this amount is reported as 0 by POSitouch, FuturePOS and Restaurant Manager point of sale, please reach out to your technical representative for more details.
tipAmount* number The total value of charged tips from the transaction in US cents.
total* number The total transaction amount for the payment, including all tips, taxes, sales and discounts.This is the full value that was charged to the card or tendered in cash.
addedAt* string Date and time in UTC when the payment was added

TicketDiscount

Ticket discount

Name Type Description
posRef* string POS ticket discount reference GUID/ID. Combination of (locationId + posRef) is unique
name* string The name of the discount
amount* number The money amount of the discount in US cents. Positive decimal in case discount is applied
addedAt* string Date and time in UTC at which the discount was added

TicketGratuity

Ticket gratuity

Name Type Description
posRef* string Ticket Gratuity POS reference GUID/ID. Combination of (locationId + posRef) is unique
name string Gratuity name only if it's supported by POS, otherwise returns null.
amount* number Gratuity amount in US cents
price* number Gratuity base price without inclusive taxes
type* string Gratuity type, one of: auto, manual
addedAt* string Date and time when gratuity was added

TicketItem

Items on a ticket are ordered menu items. Modifiers must be added with the item, and cannot be added afterwards.

Name Type Description
posRef* string POS ticket item reference GUID/ID. Combination of (locationId + posRef) is unique
type* string Ticket item type. One of: sale, refund, void, or overring
voidReason string Only for void ticket items, describes the void reason (e.g., "Employee Error" or "Test")
name* string Name of the menu item
itemRef string The reference to Menu Item
revenueClassRef string Nullable. The reference to Revenue Class if it exists. Revenue classes are similar to what are considered major groups for menu items departments. For example, Food, Beverages, etc.
isNonSalesRevenue* boolean Boolean used to distingish non-sales revenue sales like gift cards from regular sales
departmentName string Department (category) name of the menu item
quantity* number The numerator of the quantity of items on the ticket
unitPrice* number Menu item unit price excluding modifiers, discounts in US cents
itemAmount* number Money amount of the item in US cents for corresponding quantity
modifierAmount* number Full amount of the item-level modifiers in US cents format for corresponding quantity
discountAmount* number Full amount of the item-level discounts in US cents, including quantity. Positive decimal in case discount is applied, for refund define negative discount.
price* number Full cost of the item in US cents format excluding tax. Formula: itemAmount + modifierAmount - discountAmount
tax* number Full amount of the item-level taxes in US cents. For not taxable items is zero
addedAt* string Date and time in UTC when the item was added in Ticket
upc string Unique product code (UPC) assigned to the menu item for scanning and lookup.
ticketItemModifiers array Applied modifiers
ticketItemDiscounts array Applied discounts
ticketItemTaxes array Applied taxes

TicketItem V2

Items on a ticket are ordered menu items. Modifiers must be added with the item, and cannot be added afterwards.

Name Type Description
posRef* string POS ticket item reference GUID/ID. Combination of (locationId + posRef) is unique
type* string Ticket item type. One of: sale, refund, void, or overring
voidReason string Only for void ticket items, describes the void reason (e.g., "Employee Error" or "Test")
name* string Name of the menu item
itemRef string The reference to Menu Item
revenueClassRef string Nullable. The reference to Revenue Class if it exists. Revenue classes are similar to what are considered major groups for menu items departments. For example, Food, Beverages, etc.
isNonSalesRevenue* boolean Boolean used to distingish non-sales revenue sales like gift cards from regular sales
departmentName string Department (category) name of the menu item
quantity* number The numerator of the quantity of items on the ticket
unitPrice* number Menu item unit price excluding modifiers, discounts in US cents
itemAmount* number Money amount of the item in US cents for corresponding quantity
modifierAmount* number Full amount of the item-level modifiers in US cents format for corresponding quantity
discountAmount* number Full amount of the item-level discounts in US cents, including quantity. Positive decimal in case discount is applied, for refund define negative discount.
price* number Full cost of the item in US cents format excluding tax. Formula: itemAmount + modifierAmount - discountAmount
tax* number Full amount of the item-level taxes in US cents. For not taxable items is zero
addedAt* string Date and time in UTC when the item was added in Ticket
upc string Unique product code (UPC) assigned to the menu item for scanning and lookup.
displayPrice* string Full order line item price displayed/printed on the check in US cents. Note: This field is available only in the Batch Tickets Lookup endpoint.
specialRequests* array Item special requests. Note: This field is available only in the Batch Tickets Lookup endpoint.
kitchenSentAt string When the item has been sent to the kitchen. Note: This field is available only in the Batch Tickets Lookup endpoint.
isOnHold* boolean Note: This field is available only in the Batch Tickets Lookup endpoint.
departmentRef string POS department (category) reference ID. Note: This field is available only in the Batch Tickets Lookup endpoint.
item* object The POS Menu item. Note: This field is available only in the Batch Tickets Lookup endpoint.
ticketItemModifiers array Applied modifiers
ticketItemDiscounts array Applied discounts
ticketItemTaxes array Applied taxes

TicketItemModifier

Modifier applied to ticket item

Name Type Description
posRef* string POS ticket item modifier reference GUID/ID. Combination (locationId + posRef) is unique
type* string Ticket item modifier type. One of: sale, refund, void, or overring
voidReason string Only for void ticket item modifiers, describes the void reason (e.g., "Employee Error" or "Test")
name* string Modifier name
resourceType* string Important: Defines a menu reference type. Either item or modifier
itemRef string The reference to Menu Item
revenueClassRef string Nullable. The reference to Revenue Class if it exists. Revenue classes are similar to what are considered major groups for menu items departments. For example, Food, Beverages, etc.
isNonSalesRevenue* boolean Boolean used to distingish non-sales revenue sales like gift cards from regular sales
modifierRef string The reference to Menu Modifier
quantity* number The numerator of the quantity of items on the ticket
unitPrice* number Price per modifier unit in US cents
price* number Full cost of the modifier and all sub modifiers in US cents for requested quantity and modifier-level discounts applied
addedAt* string Date and time in UTC when the modifier was added to the ticket item

TicketItemModifier V2

Modifier applied to ticket item

Name Type Description
posRef* string POS ticket item modifier reference GUID/ID. Combination (locationId + posRef) is unique
type* string Ticket item modifier type. One of: sale, refund, void, or overring
voidReason string Only for void ticket item modifiers, describes the void reason (e.g., "Employee Error" or "Test")
name* string Modifier name
resourceType* string Important: Defines a menu reference type. Either item or modifier
itemRef string The reference to Menu Item
revenueClassRef string Nullable. The reference to Revenue Class if it exists. Revenue classes are similar to what are considered major groups for menu items departments. For example, Food, Beverages, etc.
isNonSalesRevenue* boolean Boolean used to distingish non-sales revenue sales like gift cards from regular sales
modifierRef string The reference to Menu Modifier
quantity* number The numerator of the quantity of items on the ticket
unitPrice* number Price per modifier unit in US cents
price* number Full cost of the modifier and all sub modifiers in US cents for requested quantity and modifier-level discounts applied
addedAt* string Date and time in UTC when the modifier was added to the ticket item

TicketMetadata

Name Type Description
name string Name of the metadata property describing this Ticket.
value string Value of the metadata property describing this Ticket.
type string ENUM of supported types:
  • STRING
  • BOOLEAN

TicketTax

Ticket Taxes

Name Type Description
taxRef* string POS Tax reference (unique per location)
amount* number Tax amount in US cents

results matching ""

    No results matching ""