Previous Topic		Next Topic
POS Module 7: Check-in - Example Scenarios		POS Module 8a: Receipt Details - Example Scenarios

POS API Certification Tutorial - Module 8a: Receipt Details - Concepts

Goal

Send receipt details to the Punchh system to store the full details of a transaction generated at POS.

Prerequisites

You must have read the Module 7: Check-in tutorial.

Use Cases and Context

The POS sends receipt details for every POS order, whether it is a loyalty purchase or not, to Punchh Data Sink receipt storage (database). For loyalty guests, receipt details are usually sent after the check-in is completed.

Applicable API Endpoints


Endpoint Name/Path	Relevant Request Parameters	Relevant Response Parameters
Receipt Details POST {server-name}/receipt_details	transaction_no amount receipt_datetime subtotal_amount payable status punchh_key pos_type pos_version The required parameters under the Menu Items object: - item_name - item_qty - item_amount - menu_item_type - menu_item_id - menu_family - menu_major_group - serial_number	N/A

Example Code

curl --location --request POST 'https://SERVER_NAME_GOES_HERE.punchh.com/receipt_details' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token token=LOCATION_KEY_GOES_HERE, btoken=BUSINESS_KEY_GOES_HERE' \
--header 'User-Agent: Brink/POS/1.0' \
--data-raw '{
  "pos_version": "v1",
  "sequence_no": "1111",
  "transaction_no": "111111111",
  "receipt_datetime": "2022-06-30T01:00:00-07:00",
  "menu_items": [
    {
      "item_name": "Cheese Pizza",
      "item_qty": 1,
      "item_amount": 2.86,
      "menu_item_type": "M",
      "menu_item_id": 1111,
      "menu_family": "001",
      "menu_major_group": "001",
      "serial_number": "1.0"
    },
    {
      "item_name": "BBQ Wings",
      "item_qty": 1,
      "item_amount": 7.86,
      "menu_item_type": "M",
      "menu_item_id": 2222,
      "menu_family": "002",
      "menu_major_group": "002",
      "serial_number": "2.0"
    },
    {
      "item_name": "Free Pizza",
      "item_qty": 1,
      "item_amount": 2.86,
      "menu_item_type": "D",
      "menu_item_id": 3333,
      "menu_family": "003",
      "menu_major_group": "003",
      "serial_number": "3.0"
    }
  ],
  "employee_id": "001",
  "employee_name": "EMPLOYEE_NAME_GOES_HERE",
  "subtotal_amount": 7.86,
  "receipt_amount": 7.86,
  "cc_last4": "0001",
  "punchh_key": "PUNCHH_KEY_GOES_HERE",
  "pos_type": "brink",
  "external_uid": "EXTERNAL_UID_GOES_HERE",
  "process": "true",
  "channel": "pos"
}'

let requestBody = {
  'pos_version': 'v1',
  'sequence_no': '1111',
  'transaction_no': '111111111',
  'receipt_datetime': '2022-06-30T01:00:00-07:00',
  'menu_items': [
    {
      'item_name': 'Cheese Pizza',
      'item_qty': 1,
      'item_amount': 2.86,
      'menu_item_type': 'M',
      'menu_item_id': 1111,
      'menu_family': '001',
      'menu_major_group': '001',
      'serial_number': '1.0'
    },
    {
      'item_name': 'BBQ Wings',
      'item_qty': 1,
      'item_amount': 7.86,
      'menu_item_type': 'M',
      'menu_item_id': 2222,
      'menu_family': '002',
      'menu_major_group': '002',
      'serial_number': '2.0'
    },
    {
      'item_name': 'Free Pizza',
      'item_qty': 1,
      'item_amount': 2.86,
      'menu_item_type': 'D',
      'menu_item_id': 3333,
      'menu_family': '003',
      'menu_major_group': '003',
      'serial_number': '3.0'
    }
  ],
  'employee_id': '001',
  'employee_name': 'EMPLOYEE_NAME_GOES_HERE',
  'subtotal_amount': 7.86,
  'receipt_amount': 7.86,
  'cc_last4': '0001',
  'punchh_key': 'PUNCHH_KEY_GOES_HERE',
  'pos_type': 'brink',
  'external_uid': 'EXTERNAL_UID_GOES_HERE',
  'process': 'true',
  'channel': 'pos'
};

const url = 'https://SERVER_NAME_GOES_HERE.punchh.com/receipt_details';
let headers = {
  'Cache-Control': 'no-cache',
  'Content-Type': 'application/json',
  'Authorization': 'Token token=LOCATION_KEY_GOES_HERE, btoken=BUSINESS_KEY_GOES_HERE',
  'User-Agent': 'Brink/POS/1.0'
};

let options = {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(requestBody)
};

fetch(url, options)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

# You will need to install the Requests package before this code will work. 
# To do so, see the installation instructions here: https://requests.readthedocs.io/en/latest/user/install/#install

import requests
import json

url = "https://SERVER_NAME_GOES_HERE.punchh.com/receipt_details"

payload = json.dumps({
  "pos_version": "v1",
  "sequence_no": "1111",
  "transaction_no": "111111111",
  "receipt_datetime": "2022-06-30T01:00:00-07:00",
  "menu_items": [
    {
      "item_name": "Cheese Pizza",
      "item_qty": 1,
      "item_amount": 2.86,
      "menu_item_type": "M",
      "menu_item_id": 1111,
      "menu_family": "001",
      "menu_major_group": "001",
      "serial_number": "1.0"
    },
    {
      "item_name": "BBQ Wings",
      "item_qty": 1,
      "item_amount": 7.86,
      "menu_item_type": "M",
      "menu_item_id": 2222,
      "menu_family": "002",
      "menu_major_group": "002",
      "serial_number": "2.0"
    },
    {
      "item_name": "Free Pizza",
      "item_qty": 1,
      "item_amount": 2.86,
      "menu_item_type": "D",
      "menu_item_id": 3333,
      "menu_family": "003",
      "menu_major_group": "003",
      "serial_number": "3.0"
    }
  ],
  "employee_id": "001",
  "employee_name": "EMPLOYEE_NAME_GOES_HERE",
  "subtotal_amount": 7.86,
  "receipt_amount": 7.86,
  "cc_last4": "0001",
  "punchh_key": "PUNCHH_KEY_GOES_HERE",
  "pos_type": "brink",
  "external_uid": "EXTERNAL_UID_GOES_HERE",
  "process": "true",
  "channel": "pos"
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Token token=LOCATION_KEY_GOES_HERE, btoken=BUSINESS_KEY_GOES_HERE',
  'User-Agent': 'Brink/POS/1.0'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(f"{response.status_code} {response.text}")

Workflow

The purpose of the Receipt Details call is to capture and store the full transactional details at the POS in the Punchh system. The Receipt Details API call should be made for all guests (loyalty as well as non-loyalty) at the end of the transaction when the POS operator prints the check or closes the transaction at the store after the check is paid and closed. In the case of loyalty guests, the Receipt Details call should be made after the check-in process is completed; that is, after the loyalty guest is associated with the transaction and the check is paid in full and closed.

The Receipt Details call requires you to send the transaction number, punchh key (barcodes are 12 digits long and referred to as the punchh_key; see Implement the Punchh Barcode Algorithm), amount, receipt date and time, subtotal amount, payable amount, menu items, POS type and version. The API request returns HTTP 200 OK response if the receipt details are successfully stored on the Punchh server.

The POS needs to send the menu items to Punchh in the format prescribed in How To Send Menu Items to Punchh. The API developers are responsible for sending the menu item object exactly how Punchh specifies in that topic. There is no flexibility in the way menu items are sent in the Receipt Details API call.

Generally, the Receipt Details call is made once, but you might have to do multiple Receipt Details calls if the items on the check are updated or a transaction is canceled after a Receipt Details call. This updates the details for an existing transaction. In the case of multiple Receipt Details calls, Punchh stores multiple versions of the same receipt.

You can use the Receipt Details call to update or cancel a transaction only if the pending points setting is enabled in the Punchh platform (see Pending Points Feature Overview). Contact your Punchh representative to update this Punchh platform configuration setting.

Receipt Details Call Workflow for Loyalty Guest

1. A loyalty guest goes to the store and identifies at the POS by phone, email, or other valid identifiers.

2. The loyalty guest may or may not choose to redeem an offer.

3. Finalize the transaction.

4. A Check-in call is performed.

5. A Receipt Details call is performed.

Receipt Details Call Workflow for Non-loyalty Guest

1. Finalize the transaction.

2. A Receipt Details call is performed.

Updating a Receipt (Either Loyalty or Non-loyalty Guest)

1. Send the full Receipt Details API call with the same transaction identifiers, but reflecting the latest changes. The pending points setting must be enabled for the business to update a receipt.

2. For loyalty guests, earned points are recalculated and the guest's points balance is updated automatically after the update transaction, provided that the transaction is performed within the pending points window.

Receipt Data Sink

Punchh stores the receipt data in the Receipt Data Sink. It can store the same receipt multiple times. If the POS client sends the same receipt (same punchh_key, same location_key) multiple times in the Receipt Details API call, Punchh stores all of the versions of that same receipt, provided that the time between HTTP requests is 1 second or more. However, if the same receipt is received via multiple HTTP calls in about the same time (less than 1 second), the last one received overwrites the previous version of that receipt.

Receipt Details Data Flow

The following scenarios describe the receipt details flow when the pending points setting is enabled or disabled.

Pending Points Not Enabled

If the guest is not assigned to the check and the receipt is printed with a barcode or QR code before the check is paid (table service environment), hold the Receipt Details call for the transaction until the check is paid. After the check is paid in full, call the Receipt Details API so that the guest can scan the barcode or QR code and earn points/visits.
If a loyalty guest is not assigned to the check and the check is paid in full, call the Receipt Details API for the transaction. Print the check with the barcode and trailer messages so that the guest can scan the barcode or QR code and earn points/visits. As the pending points setting is not enabled for the business, the loyalty points/visits are immediately credited to the guest account after the guest scans the barcode/QR code from the mobile app.

Pending Points Enabled

If the loyalty guest is NOT assigned to the check and the check is paid in full, call the Receipt Details API and print the receipt with the barcode and trailer messages. The guest on receiving the receipt can scan the barcode or QR code on the receipt to earn points/visits. If the pending points window is open, Punchh awards the loyalty points/visits to the guest after the expiry of the pending points window. The guest or POS can cancel or modify the order within the pending points window. If the pending points window is expired, then after scanning the barcode or QR code, the points/visits will be credited immediately to the guest account. The guest will receive the success message on the registered mobile app showing the earned points/visits. The pending points setting is configured in the Punchh platform. Contact your Punchh representative to update this configuration setting.
If the loyalty guest is assigned to the check and the pending points feature is enabled, then after the guest makes the payment for the order, the POS makes a call to the Create Check-in API and creates a check-in for the guest. The POS then makes the Receipt Details API call. If the pending points window is open, the guest or POS can add or remove items from the order or cancel the check-in/transaction, and points/visits for the transaction are awarded after the pending points window expires. And if the pending points window is not open, the guest or POS cannot add or remove items from the order or cancel the check-in/transaction.

Best Practices

Review How to Send Menu Items to Punchh to understand Punchh menu item requirements.
Send all transactions to Punchh, whether they are loyalty transactions or not.
A check-in may only be registered to one user. Attempting to process a check-in for the same transaction but for multiple users results in the following error: “This receipt has already been scanned by someone else.”
Receipts may be viewed within the Punchh platform under Diagnostic > Barcode Lookup > Barcode Search.

Troubleshooting


Common Issue	Possible Reasons	Potential Workarounds
Cannot access ISL endpoint	Network connection error Network congestion Local router/firewall issue Other	Reattempt call Save transaction in a log for later transmission. (SPOOL or CACHE)
400 Error	Poorly formed JSON object or bad data Corruption of data transmission	If error occurs, attempt to resubmit.
401 Error	Invalid location ID or business key	Check to ensure that the POS server configuration for both location ID and business key are set properly.