POS API Certification Tutorial - Module 1: Location Configuration and Program Meta - Concepts

Goal

Fetch the business loyalty program and POS location-specific configurations from the Punchh platform onto the POS device.

Prerequisites

• You must have read Getting Started With POS API Integrations.

• You need a location API key, which is UNIQUE for every location, and the business key. A business key is the same for a whole brand. The location and business keys will need to be created and provided by Punchh.

  The location API key is displayed in the Punchh platform under Store Locations > All Store Locations. Click the location link and then go to the POS tab and find the value of the key in the Location Key field. The location and business keys used for the POS, kiosk, and table-side integrations are visible only to Punchh admin accounts.

  Note: Contact your Punchh representative for location and business keys if you do not have the keys. The location and business keys will be created and provided to you by Punchh.

• The loyalty program (see Punchh Offers and Program Types) and store locations for the business must be configured in the Punchh platform. In the Punchh platform, the store locations for the business are configured under Store Locations > All Store Locations. Contact your Punchh representative to update these Punchh platform configuration settings.

• The barcode header, barcode image, barcode text, receipt message line 1, receipt message line 2, receipt message line 3, receipt message line 4, and receipt message line 5 are printed on the check. Receipt messages (lines 1-5) should be configured for the store location of a business on the Punchh platform. On the Punchh platform, the receipt messages for the store location of a business are configured under Store Locations > Receipt Messages.

  Configuring a receipt message for a store location is optional. The receipt messages must be associated with the store location or business on the receipt message setup page (Store Locations > Receipt Messages) on the Punchh platform to print the receipt messages at a store location.

Use Cases and Context

Brands that are Punchh customers use the Punchh platform to configure their business-level data associated with the loyalty program and location-specific configurations for POS stores. The POS device at stores needs all this data from the Punchh server to provide guests loyalty services. The POS fetches the business-level and location configuration data from the Punchh server and stores them locally on the POS device. The configuration data resides on the POS device cache. The POS device updates the configuration information stored locally at regular intervals by polling the configuration data from the Punchh server.

The loyalty program configuration information lets you derive the guest loyalty data and show it on the POS device. For example, the program type configured for the business can be used internally by the POS to determine whether the points earned by the guest will be translated to rewards, currency, or a redeemable card (for a visit-based program) when the POS device fetches the guest account balance information from the Punchh server.

The POS will use the location-specific configuration information to determine if a barcode or QR code is to be printed on the check or not, the header and footer message text on the check, the time interval for polling business-level data and location-specific configuration data from the Punchh server, etc.

Applicable API Endpoints

Example Code

Location Configuration

curl --location --request GET 'https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/locations/configuration' \
--header 'Cache-Control: no-cache' \
--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'

const url = 'https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/locations/configuration';

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: 'GET',
  headers: headers
};

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/pos/locations/configuration"

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'
}

response = requests.request("GET", url, headers=headers)

print(response.text)

Program Meta

curl --location --request GET 'https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/meta' \
--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'

const url = 'https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/meta';

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: 'GET',
  headers: headers
};

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/api/pos/meta"

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("GET", url, headers=headers)

print(response.text)

Workflow

Punchh provides the Program Meta API endpoint to fetch business-level data associated with the loyalty program and the Location Configuration API endpoint to fetch location-specific configurations for POS stores. The POS should make calls to the Program Meta API and the Location Configuration API at the start-up of the POS system.

1. Call the Program Meta API and the Location Configuration API endpoints with the location API key and the business key in the HTTP authorization header. Send the location API key of the POS store for which you want to get the location settings.

Authorization: Token token=LOCATION_KEY_GOES_HERE, btoken=BUSINESS_KEY_GOES_HERE

Note: Contact your Punchh representative for location and business keys if you do not have the keys. The location and business keys will be created and provided to you by Punchh.

2. Call the Program Meta API to fetch a business loyalty program and its various configurations as configured for the business on the Punchh platform from the Punchh server. Save the Program Meta API data locally on the POS and use this information to configure the POS store settings.

3. Call the Location Configuration API to fetch the POS store settings as configured for the business on the Punchh platform from the Punchh server. The configurations provide information about the check header and trailer message text, update interval between the POS and Punchh to fetch the updated program meta and location configuration information, and whether to print barcode, header, or trailer message on the receipt, etc. Save the Location Configuration API data locally on the POS and use this information to configure the POS store.

4. Repeat calls to the Program Meta API and Location Configuration API at the interval of minutes specified in the update_interval parameter. Repeating the call on this interval ensures that updates made from the Punchh platform reflect on the printed receipts within the interval time frame.

Note: There is no specific order for calling the Program Meta and Location Configuration API endpoints. You can call them in any order.

The Program Meta information contains the loyalty settings that apply to the overall business, such as program type, earning unit for the loyalty program, the minimum time duration between two consecutive visits (for a visit-based program), etc.; whereas the Location Configuration information contains location-specific configurations for a target store. As the location configurations are related to a particular store, the configurations may differ from store to store.

The store locations for a business are configured on the Punchh platform under Store Locations > All Store Locations. The following table lists some of the important location-specific configuration information returned by the Location Configuration API endpoint:

Configure the POS To Update Program Meta and the Location Configuration API Data

You should configure the POS to call the Program Meta API and Location Configuration API endpoints at the interval configured in the update_interval parameter in the last API call to the Location Configuration API endpoint. This will keep the Punchh data in the POS cache in sync with that on the Punchh server.

The update_interval value determines the maximum time delay for configuration updates made on the Punchh platform to be available on the POS device. For example, if the update_interval parameter is set to 15 minutes in the first call to the Location Configuration API, the POS caches this information and then calls the API again in 15 minutes. If the update_interval value changes to 60 in the latest API response, the POS caches this value and makes the next call at 60 minutes.

How To Interpret Program Meta Data

The Program Meta API gives you a starting point for knowing how to show the account balance to a loyalty guest at POS using the User Look-up and Fetch Balance API. For more use cases, see the Program Meta API.

Example 1

For a visit-based loyalty program, you can use “number of visits required for a card completion” (returned in the Program Meta API under visits_per_card) and “available visits balance” (returned in the User Look-up and Fetch Balance API under net_balance) to calculate “Completed Card(s)” for a guest. For example, if 10 visits = a completed card, and the loyalty user has 7 of 10 visits, then 3 more visits are required for a completed card.

Example 2

For the "points unlock redeemable" program type, you can fetch the full list of loyalty program redeemables (returned in the Program Meta API under the Rewards object) and configure the POS to show which redeemables can be unlocked as they accumulate more points.

Example 3

For the "points convert to reward" or "points convert to currency" program type, you can use the points_conversion_threshold parameter value (returned in the Program Meta API) to calculate the threshold value at which a user's accumulated points get converted to rewards/currency as configured in the Punchh platform. Contact your Punchh representative for more information about this Punchh platform configuration setting.

Example 4

The earning_unit parameter returned in the Program Meta API determines whether the guest will earn points or visits as the result of check-in depending on what is configured in the Punchh platform. You can configure the POS to show the unit when displaying the points balance.

Example 5

Depending on the program type (returned in the Program Meta API under program_type), you can configure the POS to show rewards, currency, or a redeemable card (for a visit-based program) to guests when they inquire about their account balance information. See Punchh Offers and Program Types.

How To Read Balance Information Returned in the User Look-up API for Various Program Types

The following table correlates program types returned in the Program Meta API and the corresponding account balance parameters returned for each program type in the User Look-up and Fetch Balance API. The User Look-up and Fetch Balance API returns the parameters listed in the "Balance Parameters" and "Redeemable" columns. The Program Meta API returns the program type that is configured for the business.

Businesses can choose only one program type for their loyalty program (see Punchh Offers and Program Types). Store locations for the business must be configured in the Punchh platform. In the Punchh platform, the store locations for the business are configured under Store Locations > All Store Locations. Contact your Punchh representative to update these Punchh platform configuration settings.

Best Practices

• When the POS calls the Program Meta API or Location Configuration API, Punchh recommends using the “If-None-Match” condition and the “ETag” value in the request header to check if the program meta and location configurations are updated on the Punchh server from the time the data was last pulled on the POS device. If the ETag value sent in the Program Meta API and Location Configuration API request headers and the Punchh server are the same, it means the program meta and location configuration data on the Punchh server are not modified. You can configure the POS to update the location and program meta configuration data in the POS cache only when the ETag value in the request header and the ETag value on the Punchh server do not match.
  
  For example, assume that the first time the POS calls the Program Meta API, the Punchh server sends an ETag with a value rW/"18805506c18dee12634a54aec35565e2” in the API response. The POS stores the ETag value and next time, when the POS makes a call to the Program Meta API, the POS needs to add the “If-None-Match” condition in the request header with the ETag value that is stored on the POS: If-None-Match: “rW/"18805506c18dee12634a54aec35565e2”” to check if the program meta configuration data is modified. When the POS calls the Program Meta API with the ETag value in the request header, the Punchh server compares the current value of the ETag identifier on the Punchh server and the one that is received in the request header from the POS. If the ETag value in the request header matches the value on the Punchh server, then status code 304 (Not Modified) with the empty body is sent back and the POS can continue to use the cached copy of the configurations.
  
  

  If the ETag value in the request header does not match the value on the Punchh server, the Punchh server sends back the new configurations in the body along with status code 200. The new ETag value is included in the response. The POS needs to update its cache with the new configurations and store the new ETag value. The POS needs to use this ETag value when making the next call to the Program Meta API. Similarly, you will use the ETag value in the request header when making calls to the Location Configuration API.

• Punchh recommends printing QR codes instead of barcodes because QR codes support vastly more store locations than the EAN 13 barcode limit of 8,192 locations. Punchh recommends printing barcodes only if the store’s POS printer does not support QR codes. Barcodes or QR codes are unique IDs for transactions; internally, Punchh uses the code to track the receipt details, but it is not used to associate the transaction with a guest.

• The recommended time interval for polling the program meta and location configuration information from the Punchh server by the POS using the Location Configuration API and Program Meta API is 60 minutes. If the API calls fail, retry 5 times. If the calls still fail, then it should serve up the last cached values.

Related Topics

Getting Started With POS API Integrations

Location Configuration API

Program Meta API

Pending Points Feature Overview

User Look-up and Fetch Balance API

Implement the Punchh Barcode and QR Code Algorithm