Previous Topic	Next Topic
Online Ordering Module 3a: Show Offers in Guest Account	Online Ordering Module 4: Update User Profile

Online Ordering API Certification Tutorial - Module 3b: Show Account Balance

Goal

Look up the account balance information of a user so that it can be displayed in the online ordering system of a business via the website or mobile app.

Prerequisites

You must have read the Online Ordering Module 2: Sign-in and Online Ordering Module 3a: Show Offers in Guest Account tutorials.

Use Cases and Context

The online ordering system can display the account balance of a user (e.g., loyalty/reward points that a guest has accumulated through recurring visits to a restaurant chain). Loyalty guests may want to view their account balance, such as the total number of points or banked rewards accumulated in their account. The Fetch Account Balance of User API can be used to retrieve the account balance information of a guest from the Punchh server so that it can be displayed on the website or mobile app when the guest logs in to the account.

Applicable API Endpoints


Endpoint Name/Path	Relevant Request Parameters	Relevant Response Parameters
Fetch Account Balance of User GET {server-name}/api/auth/checkins/balance	- client - access_token	- net_balance - Net available balance of the current account. This value shows the available balance of the user (e.g., visits, banked rewards, or points). For details, see the table in the Workflow section below. - points_balance - Returns the points balance of the user account. This value gets reset based on the point conversion value once reached as configured in the Punchh platform. For details, see the table in the Workflow section below. - 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”. Note: For information about the Rewards object and the Redeemables object, see: Module 3a: Show Offers in Guest Account

Example Code

For example code showing how to fetch the account balance of a user for general use, see the Module 3a: Show Offers in Guest Account tutorial.

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 (see the Mobile Program Meta API):

Program type of the business, such as points unlock redeemable, points, and visits.
Conversion type configured for the business in the Punchh platform. It could be “staged”, “currency”, “rewards”, or “no conversion”.
For program type = “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 = “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 redeemable” and points conversion type = “staged” or “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 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 3a: Show Offers in Guest Account tutorial related to the Mobile 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.

The following table lists the balance parameters points_balance, net_balance, and banked_rewards (returned in the Fetch Account Balance of User API response) and what they mean for different program types.


Response Parameters	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 to 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 Mobile Program Meta API with the points_conversion_threshold parameter).	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 Mobile Program Meta API with the points_conversion_threshold parameter).	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 the banked_rewards parameter for available currency balance in the user account.)	Current available points	Shows available visits balance earned for a user. After a certain number of visits (returned in the Mobile Program Meta API with the visits_per_card parameter), 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 returned in the Fetch Account Balance of User API call.
banked_rewards	N/A	Current available currency	N/A	N/A

You can configure the website or mobile app to show account balance information depending on the program type of the business.


Features	Program Types	Response Parameters	Description
Points Balance	Points Unlock Redeemable	net_balance	Shows the current points balance for the user
Banked Reward Balance	Points Convert to Currency	banked_rewards	Shows the total banked reward balance the user has available to redeem
Points Balance	Points Convert to Rewards	net_balance	Shows the current points balance for the user
Visit Balance	Visit-based	net_balance	Shows the current visit balance before the next completed 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”. The name that a business uses for units is a customizable string defined in the Punchh platform. Contact your Punchh representative for more information about this Punchh platform configuration.

Configure the website or mobile app to retrieve the program type and other parameters from the Mobile Program Meta API that are discussed in the Workflow section above 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 Mobile Program Meta API for details.