| Previous Topic | Next Topic |
|---|---|
| POS Module 3: User Look-up - Concepts | POS Module 4: Show Account Balance After Look-up - Concepts |
POS API Certification Tutorial - Module 3: User Look-up - Example Scenarios
Prerequisites
-
You must have read the scenario assumptions.
General Tasks for Performing User Look-up
1. Fetch the user identifier provided by the guest at the POS. The user identifier can be an email address, a phone number, a QR code, a redemption code, or a loyalty card number of the guest. The POS uses the identifier to look up the guest on the Punchh server.
2. Send a user look-up request to the Punchh server with the user identifier using the User Look-up and Fetch Balance API.
3. If the user is found, the POS operator assigns the transaction to the guest after receiving confirmation from the guest. If the guest does not exist in the Punchh server and if the create user at POS option is enabled (i.e., the autocreate_user_phone response parameter in the Program Meta API is set to true), the POS prompts Create a New User with Yes and No options to the POS operator.
If the operator chooses Yes, send a create new user request to the Punchh server with the user identifier provided by the guest at the POS using the Create New User API. After successful user creation, allow the POS operator to continue with the transaction. If the create user at POS option is disabled (i.e., the autocreate_user_phone response parameter in the Program Meta API is set to false), show the “user not found” message to the POS operator and allow the POS operator to continue with the transaction.
Possible Scenario
The following scenario is based on the assumptions here.
Story Line
Ross’s sister Monica is next in line, and she believes it is her first time here. However, she does not recall that she came to Central Punchh Coffee once when she was in high school and had created a rewards account then using her phone number. After observing Ross open a rewards account and hearing about the splendid benefits that come with it, Monica decides she also wants to open a rewards account. Rachel gives Monica the same prompts she gave to Ross, and when she inputs Monica’s phone number into the POS, it gives her details about Monica's existing account. To Monica’s surprise, Rachel informs her that her phone number is already associated with an account that she created five years ago when purchasing a blueberry scone and matcha latte. Unfortunately, the points she got from that purchase have expired, because it has been so long since she used her account.
Janice, who only recently started getting her coffee from Central Punchh Coffee, forgot whether she created an account during one of her previous visits. Rachel first asks for her phone number, and the user look-up gives the response “User not found, would you like to create a new loyalty user?”. Rachel enters “No” on the POS, and performs a new look-up as she wants to verify whether Janice’s account was created using her email address. She prompts Janice for her email address, which successfully returns Janice’s account. Rachel can now provide Janice with her account balance, offers and rewards, and other account information.
Ross is next in line and orders his usual morning latte. Knowing that Ross is a regular customer, Rachel assigns his order to his account. Now that Ross has the loyalty account, Rachel asks him for his phone number, and she can assign the order to his account so that Ross can earn loyalty points for this transaction which will be credited to his account.
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 Monica's account using her phone number (212-555-6578), the User Look-up and Fetch Balance API call returns the following information about Monica's account:
- First name: Monica
- Last name: Geller
- Phone number: 212-555-6578
- Banked rewards balance: 0
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": "0", "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": 0, "signup_anniversary_day": "10/17", "total_credits": 0, "total_debits": 0, "total_point_credits": 0, "total_redeemable_visits": 1, "total_visits": 1, "unredeemed_cards": 0 }, "birthday": null, "city": null, "created_at": "2022-11-07T18:40:05Z", "discount_type": null, "email": "2125556578-619@phone.punchh.com", "email_verified": false, "fb_uid": null, "first_name": "Monica", "gender": "female", "id": 1107620, "last_name": "Geller", "phone": "2125556578", "privacy_policy": false, "rewards": [], "selected_card_number": null, "selected_discount_amount": null, "selected_rewards": [], "selected_redeemables": [], "selected_redeemables_cards": [], "selected_coupons": [], "selected_tip_amount": [], "state": null, "updated_at": "2022-10-28T14:43:15Z", "user_digest": "USER_DIGEST_GOES_HERE", "zip_code": null } |