| Previous Topic | Next Topic | |
|---|---|---|
| POS Module 8a: Receipt Details - Concepts | POS Module 8b: Updating/Voiding Transactions - Concepts |
POS API Certification Tutorial - Module 8a: Receipt Details - Example Scenarios
Prerequisites
- You must have read the scenario assumptions.
- Review Module 8a: Receipt Details - Concepts
- Review Module 7: Check-in - Example Scenarios
General Tasks for Performing Receipt Details
After a check is closed and paid, do one of the following:
-
If the guest is a loyalty member, first create a check-in for the guest (so that the guest earns loyalty points) by sending the check details to the Punchh server using the Create Checkin API. After a successful check-in, submit the transaction details to Punchh using the Receipt Details API.
-
If the transaction is not a loyalty transaction, and the guest is not a loyalty member, skip the create check-in step and directly submit the transaction details to Punchh using the Receipt Details API.
Possible Scenario 1
The following scenario is based on the assumptions here.
Story Line
It is Mike’s first time at Central Punchh Coffee, and he wants to try a Mocha worth $5. He orders his drink, and Rachel asks if he has a loyalty account. He says he does not have a loyalty account, and he does not want to create one because he is running late for work. Rachel processes his order and sends the details from the order (transaction number, punchh key, amount, receipt date and time, subtotal amount, payable amount, and menu items) in a Receipt Details call in order to save the transaction in the Punchh system. Rachel generates a receipt for the transaction and gives it to Mike.
Note: If Mike wants to earn loyalty points on this transaction, Mike can install the brand’s mobile app and sign up using his phone number or email address to create a loyalty account with the brand. The receipt that he received from the store has a barcode printed on it. Mike needs to sign in to his account on the brand’s app and scan the barcode printed on the receipt to earn loyalty points for the transaction.
Code Sample (Direct API Integration)
The following code sample contains the API request and response for the transactions between the POS and Punchh based on this story line. Because Mike is a non-loyalty customer, Rachel skips the check-in for the order and sends the check details in the Receipt Details call with these parameters:
-
POS version: V03
-
Transaction number: 3948
-
Receipt date and time: 2023-01-03T08:59:18Z
-
Menu items
-
Subtotal amount: $5
-
Receipt amount: $5
-
Payable: $5.20
-
Punchh key: PUNCHH_KEY_GOES_HERE
-
POS type: Micros
| Request Body | Response Body |
| API endpoint name: Receipt Details POST {server-name}/receipt_details { "pos_version": "V03", "transaction_no": "3948", "receipt_datetime": "2023-01-03T08:59:18Z", "revenue_id": "Dine In", "revenue_code": "4", "menu_items": [ { "item_name": "Mocha", "item_qty": 1, "item_amount": 5, "menu_item_type": "M", "menu_item_id": 8, "menu_family": "800", "menu_major_group": "152", "serial_number": "1.0" }, { "item_name": "Tax", "item_qty": 1, "item_amount": 0.20, "menu_item_type": "T", "menu_item_id": "8888", "menu_family": "", "menu_major_group": "", "serial_number": "2.0" }, { "item_name": "Credit Card", "item_qty": 1, "item_amount": 5.20, "menu_item_type": "P", "menu_item_id": "7777", "menu_family": "", "menu_major_group": "", "serial_number": "3.0" } ], "employee_id": "7", "employee_name": "Rachel Green", "subtotal_amount": 5, "receipt_amount": 5, "payable": 5.20, "cc_last4": "3453", "punchh_key": "PUNCHH_KEY_GOES_HERE", "pos_type": "micros", "channel": "pos" } |
{} |
Possible Scenario 2
The following scenario is based on the assumptions here.
Story Line
Next in line is Ross, who orders a Matcha Latte worth $5. Rachel takes his order and phone number to check for any rewards he may have. Rachel does a look-up to assign the transaction to his account. The POS shows that Ross has $10 of banked rewards in his account. Ross asks Rachel to redeem $2 from his account. Rachel enters the discount amount on the POS and presses Redeem. Internally, the POS sends the redemption request with the redemption amount, discount type, and menu items to the Punchh server using the Create Redemption API. Upon successful redemption, Rachel tells Ross that he has an $8 balance in his loyalty account. Ross makes the payment for the $3 balance.
Because Ross is a loyalty customer, Rachel first creates a check-in so that Ross earns loyalty points on the order. The POS sends the check-in request with the receipt details including the $2 discount to the Punchh server using the Create Checkin API. Punchh deducts $2 from the total order amount, and Ross earns loyalty on the $3 payment. After the check-in is successful, Rachel makes a Receipt Details call to save this transaction in the Punchh system. Rachel generates a receipt for the transaction and gives it to Ross.
Note: For this scenario, the POS does not need to print the barcode on the receipt because Ross has already earned the loyalty points for the transaction when Rachel sent the Create Checkin request to Punchh.
Code Sample (Direct API Integration)
The following code sample contains the API request and response for the transactions between the POS and Punchh based on this story line. Because Ross is a loyalty customer, Rachel first creates a check-in for the order. After the check-in call returns a success response, the POS makes a Receipt Details call with these parameters:
-
POS version: V03
-
Transaction number: 3948
-
Receipt date and time: 2023-01-03T08:59:18Z
-
Menu items
-
Subtotal amount: $3
-
Receipt amount: $3
-
Payable: $3.20
-
Punchh key: PUNCHH_KEY_GOES_HERE
-
POS type: Micros
| Request Body | Response Body |
| API endpoint name: Receipt Details POST {server-name}/receipt_details { "pos_version": "V03", "transaction_no": "3948", "receipt_datetime": "2023-01-09T08:59:18Z", "revenue_id": "Dine In", "revenue_code": "4", "menu_items": [ { "item_name": "Matcha Latte", "item_qty": 1, "item_amount": 5, "menu_item_type": "M", "menu_item_id": 9, "menu_family": "800", "menu_major_group": "152", "serial_number": "1.0" }, { "item_name": "Matcha Latte", "item_qty": 1, "item_amount": 2, "menu_item_type": "D", "menu_item_id": 111, "menu_family": "", "menu_major_group": "", "serial_number": "1.1" }, { "item_name": "Tax", "item_qty": 1, "item_amount": 0.20, "menu_item_type": "T", "menu_item_id": "8888", "menu_family": "", "menu_major_group": "", "serial_number": "2.0" }, { "item_name": "Credit Card", "item_qty": 1, "item_amount": 3.20, "menu_item_type": "P", "menu_item_id": "7777", "menu_family": "", "menu_major_group": "", "serial_number": "3.0" } ], "employee_id": "7", "employee_name": "Rachel Green", "subtotal_amount": 3, "receipt_amount": 3, "payable": 3.20, "cc_last4": "3453", "punchh_key": "PUNCHH_KEY_GOES_HERE", "pos_type": "micros", "channel": "pos" } |
{} |