| Previous Topic | Next Topic |
|---|---|
| POS Module 6: Redemptions Overview | POS Module 6b: Process an Auto-Redemption (Redemptions 2.0) |
POS API Certification Tutorial - Module 6a: Find a User (Redemptions 2.0)
Goal
Redemptions 2.0 - Look up a guest account.
Prerequisites
In the Punchh platform, multiple redemptions must enabled for each business location:
1. Your Punchh representative enables and configures the Multiple Redemptions settings in the Punchh platform.
2. Go to Store Locations > All Store Locations and then choose the location(s).
3. Enable the Allow Location for Multiple Redemption option.
4. Click the Update button.
Note: The Redemptions 2.0 protocol is not backward compatible with the existing Redemptions 1.0 endpoints. Configurations within the Punchh platform are required, so please contact your Punchh representative for help before starting development.
Use Cases and Context
Redemptions 2.0 enables several Punchh features, such as multiple redemptions, single-scan flow, auto-redemption, proportional discounting, stacked discounting, item qualifier recycling, and enhanced flexibility to redemption processing orders. Redemptions 2.0 uses the concept of a discount basket, which is a persisted object for selecting available rewards to redeem in the next transaction.
Note: Only one active basket will be associated with the guest at a time.
Before performing operations on a guest's discount basket, you need to use the Find User API endpoint to retrieve the guest's user ID. Both lookup_field and lookup_value (e.g., phone number, email address, and single-scan code) are passed as request parameters to look up the user account. The API response includes user profile information in addition to the user ID.
Applicable API Endpoints
| Endpoint Name/Path | Relevant Request Parameters | Relevant Response Parameters |
| Find User GET {server-name}/api/pos/users/find |
lookup_field lookup_value |
user_id phone first_name last_name payment_mode |
| Get Access Code (Mobile) POST {server-name}/api2/mobile/single_scan_tokens |
client access_token payment_type |
single_scan_code expires_in |
Workflow
The primary purpose of the Find User API endpoint is to retrieve the user ID. Save the user ID returned in the API response for future reference. You will need this value for subsequent API calls, such as auto-redemption, discount look-up, adding items to the discount basket, removing items from the discount basket, batch redemption, and voiding redemptions.
Generating One Time Passcode (OTP) via Mobile App for Single Scan Flow
The Get Access Code mobile API is used with single-scan flow functionality to generate a single-scan code for a user from the mobile app for making payments. The mobile app invokes the Punchh API when the user selects a payment type, a discount that the user wants to redeem, and a tip amount on the mobile app to generate a single-scan code.
The Get Access Code mobile API returns the single-scan code containing a UUID string in the API response. The loyalty user can use the single-scan code to pay, earn, and redeem a reward/offer with a single scan at the POS store. The value of the single_scan_code parameter returned in the response of the Get Access Code API can then be passed as the otp (one-time passcode) with the lookup_field parameter in the request of the Find User API.
For more information, see Single Scan Flow.