Module 8b: Updating/Voiding Transactions
Previous Topic Next Topic
POS Module 8b: Updating/Voiding Transactions - Concepts POS Module 9: Print Check - Concepts

POS API Certification Tutorial - Module 8b: Updating/Voiding Transactions - Example Scenarios

Prerequisites

General Tasks for Updating a Transaction

After completing a transaction and sending its receipt details in the Receipt Details API call to Punchh, you can update the details in the receipt by submitting another full Receipt Details call with the same transactional identifiers, such as the same values for Punchh key and transaction number, but reflecting the latest changes. Doing so adds another receipt to the Punchh database and an additional receipt in the Punchh platform under Diagnostic > Barcode Lookup > Barcode Search. For more information about the Punchh key, see Implement the Punchh Barcode and QR Code Algorithm.

Note: The Pending Points setting must be enabled for the business to update a receipt.

General Tasks for Voiding/Canceling a Transaction

After completing a transaction and sending its receipt details to Punchh, you can void the transaction by sending the status: void parameter in the Receipt Details API call. When you void a transaction, if any reward is redeemed through redemption, it is returned to the guest’s account; or if any points are earned during the check-in by the guest, they are reversed. When you send a void/cancel request, ALL other parameters related to the transaction you are voiding/canceling must remain the same.

Note: The Pending Points setting must be enabled for the business to void/cancel a receipt.

After voiding a receipt, the receipt will display with a red header in the Punchh platform under Diagnostic > Barcode Lookup > Barcode Search.

Possible Scenario 1

The following scenario is based on the assumptions here.

Story Line

After Ross provides his account information and finishes paying for his order (a latte worth $4), on his way out of the cafe, he checks his receipt and realizes he has been charged for a matcha latte worth $5 instead of a latte worth $4. Ross approaches Rachel and asks her to fix the mistake. Rachel can update a check on the POS only if the Pending Points setting is enabled on the Punchh platform for the business. Luckily, the Pending Points setting is enabled for Central Punchh Coffee and is set to 1 hour. Rachel provides the same transactional details, such as transaction number and Punchh key, from Ross's order and submits another Receipt Details call to the Punchh server, but with updated parameter values for the Menu Items object. Rachel prints a new receipt and gives the receipt to Ross, and she also refunds the overcharged amount. Now, the receipt shows the correct item and amount. Ross will receive points based on the receipt amount sent in the last Receipt Details call.

There are two code samples for this story line:

  • Sample 1 submits a Receipt Details call for Ross's order
  • Sample 2 submits another Receipt Details call to update the check for the same transaction

Code Sample 1 (Direct API Integration) - Initial Transaction

The following code sample contains the API request and response for the transactions between the POS and Punchh based on this story line. Ross orders a latte worth $4, but by mistake, Rachel adds a matcha latte worth $5 to the check instead. Rachel creates a check-in for the order, and the POS submits a Receipt Details call with these parameters:

  • POS version: V03

  • Transaction number: 3948

  • Receipt date and time: 2023-01-27T08: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-27T08: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": "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"
}		 {}

Code Sample 2 (Direct API Integration) - Updating the Transaction

Ross notices the mistake in the check and tells Rachel. As Central Punchh Coffee has enabled the Pending Points setting in the Punchh platform, Rachel modifies the check by submitting another Receipt Details call. Rachel provides the same transactional details, such as transaction number and Punchh key, from Ross's order but corrects the menu item name, ID, and price:

  • Receipt date and time: 2023-01-27T09:30:18Z
  • Menu items:
    • Item name: Latte
    • Item amount: $4
    • Menu item ID: 10
  • Subtotal amount: $4
  • Receipt amount: $4
  • Payable: $4.20
Request Body Response Body
API endpoint name: Receipt Details
POST {server-name}/receipt_details
{
"pos_version": "V03",
"transaction_no": "3948",
"receipt_datetime": "2023-01-27T09:30:18Z",
"revenue_id": "Dine In",
"revenue_code": "10",
"menu_items": [
{
"item_name": "Latte",
"item_qty": 1,
"item_amount": 4,
"menu_item_type": "M",
"menu_item_id": 10,
"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": 4.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": 4,
"receipt_amount": 4,
"payable": 4.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

Ross and his sister Monica decide to go to Central Punchh Coffee for brunch. Ross orders an Americano worth $3.50 and avocado toast worth $8 for his sister, and a matcha latte worth $5 and a chocolate chip cookie worth $2 for himself. Ross provides his phone number to Rachel, and Rachel looks up Ross’s account. The POS assigns the order to Ross, and Ross makes the payment for the order. Because Ross is a loyalty customer, Rachel first creates a check-in after the check is paid and closed so that Ross earns loyalty points on the order. The POS sends the check-in request with the receipt details to the Punchh server. Rachel then makes a Receipt Details call after the check-in is successful. There is a successful response, and this transaction is saved in the Punchh system.

Ross gets a call from his manager, who tells Ross that he wants to meet immediately as a business client wants to finalize a deal. Ross then tells Monica that he has to go to the office immediately for an important meeting. After Ross leaves, Monica asks Rachel to remove the matcha latte and chocolate chip cookie that Ross ordered for himself from the order. She asks Rachel to assign the check to her name. Rachel tells Monica that the entire check needs to be cancelled to assign the check to her name. Monica wants loyalty points for the order, so she approves. Rachel can update a check on the POS only if the Pending Points setting is enabled on the Punchh platform for the business. Luckily, the Pending Points setting is enabled for Central Punchh Coffee and is set to 1 hour. Rachel submits another Receipt Details call and provides the same transactional details, such as transaction number and Punchh key, from Ross's order using void as the value of the status parameter to void the entire check.

After the intitial check-in is successfully voided, Rachel asks Monica to provide her phone number. Rachel looks up Monica’s account and assigns the check to Monica. Rachel removes the matcha latte and the chocolate chip cookie from the check, and makes another Receipt Details call with the same transactional details, such as the transaction number and Punchh key, from Ross's order, but removes the matcha latte and the chocolate chip cookie from the Menu Items object. Rachel refunds the balance amount, and Monica receives the appropriate rewards for the Americano and the avocado toast.

There are three code samples for this story line:

  • Sample 1 is a Receipt Details call for Ross's order
  • Sample 2 voids the check-in per Monica's request
  • Sample 3 submits another Receipt Details to update the check for the same transaction

Code Sample 1 (Direct API Integration) - Initial Transaction

The following code sample contains the API request and response for the transactions between the POS and Punchh based on this story line. After Ross orders food for Monica and himself, Rachel performs a user look-up with his phone number and creates a check-in for the order as Ross is a loyalty member. After receiving a successful response from Punchh, the POS sends the Receipt Details request with the following parameters:

  • POS version: V03

  • Transaction number: 5148

  • Receipt date and time: 2023-01-29T08:59:18Z

  • Menu items

  • Subtotal amount: $18.50

  • Receipt amount: $18.50

  • Payable: $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": "5148",
"receipt_datetime": "2023-01-29T08:59:18Z",
"revenue_id": "Dine In",
"revenue_code": "10",
"menu_items": [
{
"item_name": "Americano",
"item_qty": 1,
"item_amount": 3.50,
"menu_item_type": "M",
"menu_item_id": 10,
"menu_family": "800",
"menu_major_group": "152",
"serial_number": "1.0"
},
{
"item_name": "Avocado Toast",
"item_qty": 1,
"item_amount": 8,
"menu_item_type": "M",
"menu_item_id": 2,
"menu_family": "801",
"menu_major_group": "153",
"serial_number": "2.0"
},
{
"item_name": "Matcha Latte",
"item_qty": 1,
"item_amount": 5,
"menu_item_type": "M",
"menu_item_id": 12,
"menu_family": "800",
"menu_major_group": "152",
"serial_number": "3.0"
},
{
"item_name": "Chocolate Chip Cookie",
"item_qty": 1,
"item_amount": 2,
"menu_item_type": "M",
"menu_item_id": 3,
"menu_family": "801",
"menu_major_group": "153",
"serial_number": "4.0"
},
{
"item_name": "Tax",
"item_qty": 1,
"item_amount": 1.50,
"menu_item_type": "T",
"menu_item_id": "8888",
"menu_family": "",
"menu_major_group": "",
"serial_number": "5.0"
},
{
"item_name": "Credit Card",
"item_qty": 1,
"item_amount": 20,
"menu_item_type": "P",
"menu_item_id": "7777",
"menu_family": "",
"menu_major_group": "",
"serial_number": "6.0"
}
],
"employee_id": "7",
"employee_name": "Rachel Green",
"subtotal_amount": 18.50,
"receipt_amount": 18.50,
"payable": 20,
"cc_last4": "3453",
"punchh_key": "PUNCHH_KEY_GOES_HERE",
"pos_type": "micros",
"channel": "pos"
}		 {}

Code Sample 2 (Direct API Integration) - Voiding the Check-in

After Ross cancels brunch with Monica due to an urgent meeting with his manager, Monica asks Rachel to assign the check to her and remove the items that Ross ordered for himself. To assign the check to Monica, Rachel first needs to void the check. Rachel knows that the Pending Points setting is enabled for Central Punchh Coffee, so she sends the status: void parameter in another Receipt Details API request with ALL other parameters related to the transaction the same to void the check-in. The Receipt Details call has the following parameters:

  • POS version: V03

  • Transaction number: 5148

  • Receipt date and time: 2023-01-29T09:05:18Z

  • Menu items

  • Subtotal amount: $18.50

  • Receipt amount: $18.50

  • Payable: $20

  • Punchh key: PUNCHH_KEY_GOES_HERE

  • POS type: Micros

  • Status: void
Request Body Response Body
API endpoint name: Receipt Details
POST {server-name}/receipt_details
{
"pos_version": "V03",
"transaction_no": "5148",
"receipt_datetime": "2023-01-29T09:05:18Z",
"revenue_id": "Dine In",
"revenue_code": "10",
"menu_items": [
{
"item_name": "Americano",
"item_qty": 1,
"item_amount": 3.50,
"menu_item_type": "M",
"menu_item_id": 10,
"menu_family": "800",
"menu_major_group": "152",
"serial_number": "1.0"
},
{
"item_name": "Avocado Toast",
"item_qty": 1,
"item_amount": 8,
"menu_item_type": "M",
"menu_item_id": 2,
"menu_family": "801",
"menu_major_group": "153",
"serial_number": "2.0"
},
{
"item_name": "Matcha Latte",
"item_qty": 1,
"item_amount": 5,
"menu_item_type": "M",
"menu_item_id": 12,
"menu_family": "800",
"menu_major_group": "152",
"serial_number": "3.0"
},
{
"item_name": "Chocolate Chip Cookie",
"item_qty": 1,
"item_amount": 2,
"menu_item_type": "M",
"menu_item_id": 3,
"menu_family": "801",
"menu_major_group": "153",
"serial_number": "4.0"
},
{
"item_name": "Tax",
"item_qty": 1,
"item_amount": 1.50,
"menu_item_type": "T",
"menu_item_id": "8888",
"menu_family": "",
"menu_major_group": "",
"serial_number": "5.0"
},
{
"item_name": "Credit Card",
"item_qty": 1,
"item_amount": 20,
"menu_item_type": "P",
"menu_item_id": "7777",
"menu_family": "",
"menu_major_group": "",
"serial_number": "6.0"
}
],
"employee_id": "7",
"employee_name": "Rachel Green",
"subtotal_amount": 18.50,
"receipt_amount": 18.50,
"payable": 20,
"cc_last4": "3453",
"punchh_key": "PUNCHH_KEY_GOES_HERE",
"pos_type": "micros",
"status": "void",
"channel": "pos"
}		 {}

Code Sample 3 (Direct API Integration) - Updating the Check

After the check-in is voided, Rachel removes Ross's items from the check per Monica’s request. Rachel looks up Monica’s account using her phone number to assign the check to Monica. Rachel then submits another Receipt Details API request with the same transactional details, such as transaction number and Punchh key, from Ross's order but updates the menu items. The Receipt Details call is sent with the following details:

  • Receipt date and time: 2023-01-29T09:10:18Z
  • Menu items: remove the items that Ross ordered for himself (matcha latte and chocolate chip cookie)
  • Subtotal amount: $11.50
  • Receipt amount: $11.50
  • Payable: $13
Request Body Response Body
API endpoint name: Receipt Details
POST {server-name}/receipt_details
{
"pos_version": "V03",
"transaction_no": "5148",
"receipt_datetime": "2023-01-29T09:10:18Z",
"revenue_id": "Dine In",
"revenue_code": "10",
"menu_items": [
{
"item_name": "Americano",
"item_qty": 1,
"item_amount": 3.50,
"menu_item_type": "M",
"menu_item_id": 10,
"menu_family": "800",
"menu_major_group": "152",
"serial_number": "1.0"
},
{
"item_name": "Avocado Toast",
"item_qty": 1,
"item_amount": 8,
"menu_item_type": "M",
"menu_item_id": 2,
"menu_family": "801",
"menu_major_group": "153",
"serial_number": "2.0"
},
{
"item_name": "Tax",
"item_qty": 1,
"item_amount": 1.50,
"menu_item_type": "T",
"menu_item_id": "8888",
"menu_family": "",
"menu_major_group": "",
"serial_number": "3.0"
},
{
"item_name": "Credit Card",
"item_qty": 1,
"item_amount": 13,
"menu_item_type": "P",
"menu_item_id": "7777",
"menu_family": "",
"menu_major_group": "",
"serial_number": "4.0"
}
],
"employee_id": "7",
"employee_name": "Rachel Green",
"subtotal_amount": 11.50,
"receipt_amount": 11.50,
"payable": 13,
"cc_last4": "3453",
"punchh_key": "PUNCHH_KEY_GOES_HERE",
"pos_type": "micros",
"channel": "pos"
}		 {}
Previous
Module 8b: Concepts
Next
Module 9: Concepts