Previous Topic		Next Topic
POS Module 4: Show Account Balance After Look-up - Example Scenarios		POS Module 5: Show Offers and Rewards After Look-up - Example Scenarios

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

Goal

Look up and display offers and rewards at the POS.

Prerequisites

You must have read the Module 1: Location Configuration and Program Meta, Module 3: User Look-up and Module 4: Show Account Balance After Look-up tutorials.
The guest must have rewards in their account.

Use Cases and Context

After the user look-up, in addition to the account balance of the user, the POS device may also show the available offers/redeemables in the loyalty guest account. For example, for the loyalty guests in the “Points unlock redeemables” program type, the POS can show the redeemables that a guest has unlocked and the additional redeemables that can be unlocked as the guest accumulates more points.

Primary Use Case Environment

Quick-service restaurant or convenience store
Quick sign-up at the counter
Kiosk

Applicable API Endpoints


Endpoint Name/Path	Relevant Request Parameters	Relevant Response Parameters
User Look-up and Fetch Balance GET {server-name}/api/pos/users/search	email phone user_as_qrcode card_number	These parameters under the Rewards object show the rewards of the user. These rewards do not include currency and unredeemed card values which are shown under the Balance object. - id - name - points - discount_amount - end_date_tz - type

Workflow

The User Look-up and Fetch Balance API endpoint shows the available offers (redeemables and rewards) in the user account under the Rewards object in the API response. See the “type” parameter with either “redeemable” or “reward” value under the Rewards object in the API response. At the POS, redeemables are shown only for the loyalty guests on the “Points unlock redeemable” program type. Note that loyalty guests on the “Points unlock redeemable” program type can directly redeem the redeemables only if guests have sufficient points in their account. A redeemable appears in the “Points unlock redeemable” program type when it is configured to be part of the loyalty program on the Punchh platform. To configure a redeemable to be part of the loyalty program, on the Punchh platform go to Offers > All Redeemables > New Redeemables. Go to the Validity step by clicking Next and select the Should be available as loyalty points based redemption? option.
But a business can indirectly offer redeemables to guest accounts through a campaign, deal, or directly through support gifting. When offered indirectly to a guest, a redeemable is treated as a reward in the Punchh system. Guests do not need any points to earn a reward. A user with admin access can choose a redeemable and gift the redeemable to the guest account as a reward. Punchh provides an option to configure a redeemable on the Punchh platform to make it available for support gifting. On the Punchh platform, go to Offers > All Redeemables > New Redeemable. On the New Redeemable page, enable the Make available for support gifting? option in the Info step.
Redeemables are set at the business level, so the reward ID of a redeemable is the same across the business, whereas all rewards (an instance of a redeemable) have different reward IDs. In the API response under the Rewards object, the id parameter displays the ID of a reward or a redeemable, and the type parameter displays whether the reward is a redeemable or a reward.
At the POS or Kiosk, you can use these parameters in the User Look-up and Fetch Balance API response under the Rewards object – name, description, image, points, and discount_ amount – to display the reward information for the loyalty guest. For the loyalty guests on the “Points unlock redeemables” program type, you can use the Program Meta API to fetch the full list of loyalty program redeemables and display on the POS the redeemables that are already unlocked (in grey), along with which additional redeemables can be unlocked as guests keep saving more points. The “unlocked redeemables” can be fetched from the User Look-up and Fetch Balance API endpoint. Note that the Program Meta API will show only the redeemables that are part of the loyalty program and are available through the “Points unlock redeemable” program. The Program Meta API endpoint does not show the rewards received through campaigns.
Rewards display chronologically by creation date.

Note

Use the Applicable Offers API to get rewards applicable to the current check. Punchh rewards undergo a certification process to verify that a reward is applicable towards a transaction. There is currently no way for Punchh to provide which qualifying criteria a reward is being passed through.

The “Show Account Balance After Look-up” tutorial contains information about which response parameters in the User Look-up and Fetch Balance API show the user account balance for different program types. This tutorial provides information about the parameters in the User Look-up and Fetch Balance API that show available offers in the user account balance. Depending on the program type of the business, you can use these response parameters on the POS terminal to show the available offers of a loyalty guest.


Program Types	Features	Response Parameters	Description
Points unlock redeemable	All the rewards available for the guest to redeem	These parameters are listed under the Rewards object. You can show this information for each reward. - name - description - image - points - discount_amount - type	Shows all additional reward objects possible for the loyalty user to redeem from the user look-up response.
Points convert to currency	Banked reward balance	banked_rewards	Shows the total banked reward balance the loyalty user has available to redeem.
Points convert to rewards	All the rewards available for the guest to redeem	These parameters are listed under the Rewards object. You can show this information for each reward. - name - description - image - points - discount_amount - type	Shows all additional reward objects possible for the loyalty user to redeem from the user look-up response.
Visit-based	Number of completed card(s)	unredeemed_cards	Shows the number of completed cards and allows the POS operator to redeem them.

Best Practices

Reward selection should be required after the look-up has been completed.
Allow integration to display all reward item fields for the most custom experience.
The Rewards object in the response contains a “description” parameter. This can be ignored or included. If included, note that redeemable descriptions do not have a max character count.