The following guide show the Aloha POS system items that are mapped to the Punchh POS API data fields. These Data Elements will assist in setting up Punchh Portal settings by being able to speak the “Aloha” language to the manager of the Aloha POS database when setting up Qualifying Criteria in the Punchh Portal.
POS Type: | Aloha POS | |||||
Punchh POS API Value | Punchh API description | Punchh Notes | POS Data Element Mapping | POS Data Element Notes | Status | Meets Punchh Requirement Definition |
cc_last4 | The last 4 digits of the cc number for use to allow associating of non-punchh users with transactions for future linking when the user joins loyalty | Last 4 digits of all CC types | 1.POS status confirmed | The POS passes accurate Employee ID for every API call, when applicable (i.e. not for online or kiosk orders but for all other POS transactions performed by an employee) | ||
employee_id | The employee ID in the POS that serviced the check for that transaction. | The employee may change over the life of the transaction (Example bartender transfers check to server then a cashier closes the check). The currently active employee servicing the POS order when the Punchh API call is made is the value that should be sent to Punchh in the API call | ID.EMP.DBF Aloha Employees | 1.POS status confirmed | The POS passes accurate Employee Name for every API call, when applicable (i.e. not for online or kiosk orders but for all other POS transactions performed by an employee) | |
employee_name | The employee name in the POS that serviced the check for that transaction. | The employee may change over the life of the transaction (Example bartender transfers check to server then a cashier closes the check). The currently active employee servicing the POS order when the Punchh API call is made is the value that should be sent to Punchh in the API call | Firstname.EMP.DBF Aloha Employees | 1.POS status confirmed | ||
menu_items: | JSON Item containing details for a single menu item. Menu items may reflect a sales item in the POS (Type M), a Discount (Type D or Type M with a negative item_amount, a Payment (Type P) or Taxes (Type T) | It is important when sending check details that all available items when totaled follow the punchh balancing formula | The POS passes accurate Item Alpha name without any special characters (ex. ½, ",",etc) for all menu items | |||
item_name | Text value of item name as sent to the Guest Check | Longname.ITM.DBF Aloha Menu Items | 1.POS status confirmed | The POS passes accurate QTY of items ordered for all menu items, discounts, credit card payments as well as for parent or modifier check line items | ||
item_qty | Numeric value of the qty of the item as represented on this single menu item on the guest check | (If item is type D, this qty will ALWAYS be evaluated as a negative value.
| Qty of items on the POS receipt | 1.POS status confirmed | TBD | |
item_amount | Price of the item as represented on the POS guest check | (If item is type D, this qty will ALWAYS be evaluated as a negative value.
| Sales price of item on receipt. | 1.POS status confirmed | All line items on the POS check (including $0.00 parent and $0.00 modifier items) are included and represented in the details passed via API with the appropriate menu item type identifier | |
menu_item_type | M = Menu item. May also represent a line item that is a discount. | M, D, T, S and P | 1.POS status confirmed | The correct POS ID identifier for the specific line item is passed to Punchh | ||
menu_item_id | Menu item ID as represented in the item database on the POS | ITM.DBF.ID | For Aloha Promo of type Combo, the parent menu item will be of type D with the menu item ID set to the PROMO ID | 1.POS status confirmed | The menu item is systematically prevented in the POS from belonging to more than a single POS group from which this value is being obtained. | |
menu_family | A menu item MUST have enforced singular membership in the POS data group type that is passed in the menu_family field to Punchh. This ensures that every time a menu item is sent to Punchh, it will ALWAYS have the same value passed in the menu_family field. | In the event that there is not a group ing data element on the POS that enforces that each menu item is member of ONLY one group, then this Punchh data field should be populated with the same value that is passed to the Punchh menu_major_group field. | CAT.DBF.ID | Aloha cannot use non-sales category types because menu items may belong to one or more Non-Sales categories. The value here = the ITEM's assigned assigned Sales/Retail Category | 1.POS status confirmed | The menu item is systematically prevented in the POS from belonging to more than a single POS group from which this value is being obtained. |
menu_major_group | A menu item MUST have singular membership in the POS group that is passed in the menu_major_group field to Punchh. This ensures that every time a menu item is sent to Punchh, it will ALWAYS have the same value passed in the menu_major_group field. | In the event that there is not a group paradigm on the POS that enforces that each menu item is member of ONLY one group, then this Punchh data field should be left empty. | CAT.DBF.ID | 1.POS status confirmed | Menu items include the serial no which indicates the check line item order of the item. The value is in the format of | |
serial_number | Serial Numbers are assigned to Menu Items on a receipt. A Main Item (such as pizza) may have serial number "1.0" and the associated modifiers (such as "Extra Cheese", "Olives" and "Jalapenos") may have serial numbers "1.1", "1.2" and "1.3" respectively. The numbering explains that particular items are modifiers associated with the main one. | Single Level of Modifier | 1.POS status confirmed | subtotal_amount = subtotal_amount + Sum of (S) + Sum (T) = Sum (P) | ||
subtotal_amount | Same as receipt_amount. For historical reasons, send this parameter along with receipt_amount in API requests. | POS status not yet confirmed | = Subtotal_Amount | |||
receipt_amount | Order amount before any taxes (Sum of all amounts minus any discounts). This is the amount upon which loyalty points/visits are granted when there are not any earning qualification critera rules in place in the Punchh portal. | Value to this parameter should be same as that of subtotal_amount. E.g., order amount is $10, parameters receipt_amount and subtotal_amount will hold the value 10. Say if $2 discount has been applied on the same order, subtotal_amount will become 8. | POS status not yet confirmed | subtotal_amount = Sum(M) - Sum (D) (Punchh and Internal) | ||
payable | Final amount that user actually pays including taxes will be sent as payable | POS status not yet confirmed | The complete transaction number of the system that is submitting the details to Punchh | |||
transaction_no | POS Transacation Number | POS check number | Check numbers repeat daily | 1.POS status confirmed | ||
external_uid | Unique UID generated by your system, we use this to prevent duplicates in case same transaction get triggered twice. | N/A | 1.POS status confirmed | These Channels are Punchh Defined channels assigned to the integration | ||
channel | Possible values: online_order, pos,web, mobile, dashboard, chatbot | This is the source of where the order originated when it was received by Punchh API | Harcodd to POS | 1.POS status confirmed | Value here should represent the way the order is fulfilled for the customer, not the area in the restaurant where the order is placed. i.e. Not Bar, Patio, Dining Room. | |
revenue_id | This should be a reference to the type of order. | Example dine-in, to-go, call-in pickup, call-in deliver, etc. Some POS call this Revenue Center, Order Method, Order Mode, etc. | TRM.DBF.ID | POS status not yet confirmed | Value here should represent the way the order is fulfilled for the customer, not the area in the restaurant where the order is placed. i.e. Not Bar, Patio, Dining Room. | |
revenue_code | This should be a reference to the type of order. | Example dine-in, to-go, call-in pickup, call-in deliver, etc | TRM.DBF.ID | POS status not yet confirmed | ||
store_number | Location's Store identification number | This ID should match the Punchh location POS ID as set in Punchh portal | Read from the aloha.ini file | 1.POS status confirmed | ||
state | POS status not yet confirmed | The type should include sub version such as Aloha Table Service or Quick Service | ||||
pos_type | Type of POS integration is running on | Harcodes to | 1.POS status confirmed | |||
punchh_key | Punchh Key / Bar Code | For each transaction (check/ticket/etc.) this unique number must not repeat for a min of 90 days, ideally 180 days or forever. | Aloha Secure barcode algorithm value less barcode check digit | 1.POS status confirmed | ||
pos_version | Version of the POS. May also include integration version information too | V3 | 1.POS status confirmed |