Previous Topic	Next Topic
POS Module 1: Location Configuration and Program Meta - Concepts	POS Module 2: Create User - Concepts

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

Prerequisites

You must have read the scenario assumptions.
Review Module 1: Location Configuration and Program Meta - Concepts.

General Tasks for Location Configuration and Program Meta

1. Configure each POS store to call the Program Meta API and the Location Configuration API at the start-up of the POS system using the business key and the location key generated for the specific POS store. Pass the combination of the business key and the location key in the Authorization header to make API calls.

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. Make a call to 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. Make a call to 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 a barcode, a header, or a 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.

Possible Scenario

The following scenario is based on the assumptions here.

Story Line

Phoebe owns Central Punchh Coffee and wants to integrate with the Punchh loyalty platform. The POS integrator from the business side needs to reach out to Gunther, the TAM (Technical Account Manager) at Punchh who is assigned to this business account, to get the business key and the location keys of 13 POS stores of Central Punchh Coffee. While configuring a POS device, Central Punchh Coffee’s integration team configures the POS to call the Program Meta API and the Location Configuration API using the business key and the location key generated for the specific POS store.

The POS integration team then interchanges API endpoints and API keys on a location-by-location basis for all 13 POS stores. A combination of the API key (i.e., location key) and business key needs to be passed in the Authorization header to make API calls. The business key is unique for a business. The POS integrator needs to be able to interchange API endpoints and API keys on a location-by-location basis.

After configuring the POS to use the business key and the location key in the Authorization header whenever making API calls to the Punchh server, the POS device is now ready to make its first calls to the Program Meta API to fetch the business-level data and the Location Configuration API to fetch the location-level data that is configured on the Punchh platform.

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. When the POS store fetches the location configurations, the Location Configuration API call returns the POS store configuration information that includes:

Business name: Central Punchh Coffee
Active program type (banked rewards mode): 1
Receipt header message: Header Punchh
Location name: punchh-coffee-location-1
Receipt trailer message lines 1-5: Welcome to Central Punchh Coffee, etc.
Update interval for polling location and program meta configurations from the Punchh server: 60 minutes
Location ID: 327922

When the POS store fetches the loyalty program configurations for the business, the Program Meta API call returns the loyalty program configuration information that includes:

Business program type: points
Points conversion type: currency
Points conversion threshold: 25
Earning unit: point
Autocreate user with the phone number: true

The relevant parameters are made bold in the API response sample below.


Request Body	Response Body
API endpoint name: Location Configuration GET {server-name}/api/pos/locations/configuration A combination of the API key (i.e., location key) and business key needs to be passed in the Authorization header to make API calls. N/A - This request does not have a body. For examples of how to make this call using various programming languages, see Module 1: Example Code.	{ "banked_rewards_mode": "1", "business_name": "Central Punchh Coffee", "header": "Header Punchh", "location_id": "327922", "location_name": "punchh-coffee-location-1", "log_level": "6", "points_unlock_mode": "0", "print_barcodes": "1", "send_to_datasink": "1", "short_key": "6624", "trailer_1": "Welcome to Central Punchh Coffee", "trailer_2": "Have a good day", "trailer_3": "Barcode Punchh Line #3", "trailer_4": "Barcode Punchh Line #4", "trailer_5": "THANKS Punchh", "update_interval": "60", "visits_mode": "0" }
API endpoint name: Program Meta GET {server-name}/api/pos/meta A combination of the API key (i.e., location key) and business key needs to be passed in the Authorization header to make API calls. N/A - This request does not have a body. For examples of how to make this call using various programming languages, see Module 1: Example Code.	{ "minimum_payable_price": null, "maximum_discountable_quantity": null, "program_type": "points", "points_conversion_type": "currency", "earning_unit": "point", "currency_earned": 10, "points_conversion_threshold": 25, "redemption_expiry_minutes": 0, "pending_points": true, "pending_points_duration": 15, "configurable_default_time_eod": "23:59:59", "autocreate_user_phone": true, "visits_per_card": 0, "card_redemption_value": 0, "minimum_visit_amount": 0, "minimum_visit_hours": 0, "minimum_age_to_signup": 0, "coupon_prefix": "" , "redeemables": [] }