Previous Topic		Next Topic
POS Module 3: User Look-up - Example Scenarios		POS Module 4: Show Account Balance After Look-up - Example Scenarios

POS API Certification Tutorial - Module 4: Show Account Balance After Look-up - Concepts

Goal

Display the proper guest account balance during look-up.

Prerequisites

You must have read the Module 1: Location Configuration and Program Meta and Module 3: User Look-up tutorials.

Use Cases and Context

Loyalty guests may want to know from the POS operator their account balance such as the total number of points or bank rewards accumulated in their account. The POS operator performs a user look-up using one of the identifiers (phone number, email address, loyalty card number, QR code, or redemption code) provided by the guest. The POS system then fetches the account balance information of the guest from the Punchh server.

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	created_at These parameters under the Balance object show the account balance of the user: net_balance - Net available balance of current account. This value always shows the available balance of the user whether it's visits, banked rewards or points. For more details, see the table in the Workflow section. points_balance - Returns points balance of the user account. This value gets reset based on the point conversion value once reached as configured in the platform. For more details, see the table in the Workflow section. total_credits - Total points earned through the Punchh loyalty program to date, which is net_balance + net_debits + pending_points. total_point_credits - Total points credited to the user account. For non-migrated Punchh users, this value is the same as the total_credits value. For users who migrated to the Punchh loyalty program, total_point_credits is the total of the previous loyalty program points (the points that the user has earned through the previous loyalty program) and the points added through the Punchh loyalty program (shown in total_credits). total_visits - A value is shown if the program type is set to visit-based. unredeemed_cards - A value is shown if the program type is set to visit-based. banked_rewards - A value is shown if the program type is set to Points Convert to Currency/Banked Reward.

Workflow

Punchh supports different program types and structures. When looking up guests, knowing the program type of the business allows developers to display account balances in the correct unit. We recommend you to use the Program Meta API to find:

Program type of the business (program_type), such as Points unlock redeemables, Points, and Visits.
Conversion type configured for the business in the Punchh platform. It could be “staged”, “currency”, “rewards”, and “no conversion” (points_conversion_type). For program_type as “points” and “points_conversion_type”: “currency”, the points are converted to currency. This program type is also known as “Points convert to currency”. For program_type as “points” and “points_conversion_type”: “rewards”, the points are converted to rewards. This program type is also known as “Points convert to rewards”. For “program_type”: “points_unlock_redeemables”, “points_conversion_type”: “staged” or “points_conversion_type”: “none”, the points are converted to redeemables/offers.
The value that an end-user earns as the result of a check-in (earning_unit).
Threshold value at which an end-user's accumulated points get converted to rewards or currency (points_conversion_threshold).
The number of visits that are required for a single card completion for a visit-based program (visits_per_card). When the available visits balance is divided by visits per card, the quotient gives the card completed for the user if the available visits balance value is greater than the number of visits required for a single card completion. For example, if 5 visits are required for a single card completion and the user has made 12 visits or check-ins, then the card completed value is 2 and the remainder 2 means 3 more visits are required for the next card completion.

Also, see the Module 1: Location Configuration and Program Meta tutorial related to the Program Meta API. The loyalty program type is configured in the Punchh platform. Contact your Punchh representative for more information about this Punchh platform configuration setting.

This table lists the balance parameters points_balance, net_balance, and banked_rewards (returned in the User Look-up and Fetch Balance API response under the balance object) and what they mean for different program types.


Response Parameters in Balance Object	Points Unlock Redeemable	Points Convert to Currency	Points Convert to Rewards	Visit-Based
points_balance	N/A (The points_balance value should not be displayed for this program type as there is no conversion of points into currency or reward.)	Shows progress toward the threshold for conversion to currency (e.g., how many points convert to a dollar). The points value gets reset when it reaches the threshold value (returned in the Program Meta API under “points_conversion_threshold”).	Shows progress toward the threshold for conversion to rewards (e.g., how many points convert to a reward). The points value gets reset when it reaches the threshold value (returned in the Program Meta API under “points_conversion_threshold”).	N/A (The points_balance value should not be displayed for this program type as there is no conversion of visits into currency or reward.)
net_balance	Current available points	N/A (Refer to banked_rewards parameter for available currency balance in the user account.)	Current available points	Shows available visits balance earned for a user. Note that after a certain number of visits (returned in the Program Meta API under visits_per_card), the visits are converted to a redeemable card. When a card is redeemed, the visits that are required to complete a card are debited from the net balance. To fetch the count for available unredeemed cards, use the “unredeemed_cards” parameter under the Balance Object returned in the User Look-up and Fetch Balance API call.
banked_rewards	N/A	Current available currency.	N/A	N/A

After a user look-up, you can configure the POS to show account balance information on the POS device depending on the program type of the business.


Features	Program Types	Response Parameters	Description
Points Balance	Points unlock redeemable	net_balance	Shows the current point balance for the user
Banked Reward Balance	Points convert to currency	banked_rewards	Shows the total banked reward balance the loyalty user has available to redeem
Points Balance	Points convert to rewards	net_balance	Shows the current point balance for the user
Visit Balance	Visit-based	net_balance	Shows the current visit balance for a user. You can display the visit balance on the loyalty guest's receipt by calculating the modulus of "net_balance" and Program Meta response parameter "visits_per_card". For example, if "net_balance" is 10 and "visits_per_card" is 3, then 10 mod 3 = 1. This means the visit balance is 1, and 2 more visits are required to complete the current card.

Best Practices

Display account balance automatically without additional user entry.
Support balances and units of the business program type.
Change the “units” of what is displayed according to program type. For example, visit-based programs should use a unit of “visits” when showing the balance, while points-based programs should show a balance of “points” and currency programs should show “dollars” or “currency”.
We recommend that you configure POS to look up the Program Type and other parameters from the Program Meta API that are discussed in the Workflow section in this tutorial before displaying points/visits, etc. The parameter values may change as the business marketing strategy evolves. For example, if the program type of business changes from "Points unlock redeemable" to "Points convert to currency", points in the guest account need to be converted to currency. See Module 1: Location Configuration and Program Meta.