Previous Topic		Next Topic
POS Module 5: Show Offers and Rewards After Look-up - Concepts		POS Module 6: Redemptions

POS API Certification Tutorial - Module 5: Show Offers and Rewards After Look-up - Example Scenarios

Prerequisites

You must have read the scenario assumptions.
Review Module 5: Show Offers and Rewards After Look-up - Concepts
Review Module 4: Show Account Balance After Look-up - Example Scenarios

General Tasks for Showing Offers and Rewards

1. Make a call to the Program Meta API to fetch a business loyalty program or fetch the program type that you stored locally on the POS.

2. Perform the guest look-up using the User Look-up and Fetch Balance API.

3. Display the rewards/offers on the POS based on the program type of the business.

Points unlock redeemable and points convert to rewards program types: Display the rewards on the POS based on the contents of the rewards object in the response of the user look-up. Parameters within the rewards object are defined here.
Points convert to currency program type: Display the currency balance of the guest on the POS based on the value in the banked_rewards parameter. You can find this parameter under the balance object in the response of the User Look-up and Fetch Balance API.
Visit-based program type: Display the unredeemed card of the guest on the POS based on the value in the unredeemed_cards parameter. You can find this parameter under the balance object in the response of the User Look-up and Fetch Balance API.

Possible Scenario

The following scenario is based on the assumptions here.

Story Line

Janice has been coming to Central Punchh Coffee almost every day for the past month. She has spent a total of $173 and would like to know her current available points and how her purchases have translated to rewards. She orders a $5 iced matcha latte, and before checking out she tells Rachel that she would like to check the value of banked rewards on her account and use them for this purchase if available. Janice provides her email address, and Rachel lets her know that her account balance is 23 points and that she has $6 in rewards.

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 Rachel looks up Janice's account using her email address (janice@example.com), the User Look-up and Fetch Balance API call returns the following information about Janice's account:

First name: Janice
Last name: Litman
Email address: janice@example.com
Banked rewards balance (shown under the balance object in the API response): $6
Points balance (shown under the balance object in the API response): 23

Not all of this information is actually displayed to Rachel on the POS screen. Note: We strongly recommend not showing the guest's personal information on the POS.


Request Body	Response Body
API endpoint name: User Look-up and Fetch Balance GET {server-name}/api/pos/users/search You need to pass one of the following query parameters: email, phone, user_as_qrcode, or card_number N/A - This request does not have a body. For examples of how to make this call using various programming languages, see Module 3: Example Code.	{ "address_line1": null, "age_verified": false, "anniversary": null, "avatar_remote_url": null, "balance": { "banked_rewards": "6", "expired_membership_level": null, "initial_visits": 0, "membership_level": null, "membership_level_id": null, "net_balance": 0, "net_debits": 0, "pending_points": 0, "points_balance": 23, "signup_anniversary_day": "08/06", "total_credits": 0, "total_debits": 0.0, "total_point_credits": 0.0, "total_redeemable_visits": 12, "total_visits": 12, "unredeemed_cards": 0 }, "birthday": null, "city": null, "created_at": "2022-11-03T08:59:18Z", "discount_type": null, "email": "janice@example.com", "email_verified": false, "fb_uid": null, "first_name": "Janice", "gender": null, "id": 19828347, "last_name": "Litman", "phone": null, "privacy_policy": false, "rewards": [], "selected_card_number": null, "selected_discount_amount": null, "selected_reward_id": null, "state": null, "updated_at": "1992-05-10T15:22:15Z", "user_digest": "USER_DIGEST_GOES_HERE", "zip_code": null }

Request Body

Response Body

API endpoint name: User Look-up and Fetch Balance
GET {server-name}/api/pos/users/search

You need to pass one of the following query parameters: email, phone, user_as_qrcode, or card_number

N/A - This request does not have a body.

For examples of how to make this call using various programming languages, see Module 3: Example Code.

{
"address_line1": null,
"age_verified": false,
"anniversary": null,
"avatar_remote_url": null,
"balance": {
"banked_rewards": "6",
"expired_membership_level": null,
"initial_visits": 0,
"membership_level": null,
"membership_level_id": null,
"net_balance": 0,
"net_debits": 0,
"pending_points": 0,
"points_balance": 23,
"signup_anniversary_day": "08/06",
"total_credits": 0,
"total_debits": 0.0,
"total_point_credits": 0.0,
"total_redeemable_visits": 12,
"total_visits": 12,
"unredeemed_cards": 0
},
"birthday": null,
"city": null,
"created_at": "2022-11-03T08:59:18Z",
"discount_type": null,
"email": "janice@example.com",
"email_verified": false,
"fb_uid": null,
"first_name": "Janice",
"gender": null,
"id": 19828347,
"last_name": "Litman",
"phone": null,
"privacy_policy": false,
"rewards": [],
"selected_card_number": null,
"selected_discount_amount": null,
"selected_reward_id": null,
"state": null,
"updated_at": "1992-05-10T15:22:15Z",
"user_digest": "USER_DIGEST_GOES_HERE",
"zip_code": null
}