Online Ordering API Certification Tutorial - Module 3a: Show Offers in Guest Account

Goal

Look up information about offers available to a user so that the offers 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 1a: Create User and Online Ordering Module 2: Sign-in tutorials.

• A guest must have offers (e.g., rewards or redeemables) in the user’s account.

Use Cases and Context

In addition to the account balance of a user (e.g., loyalty/reward points that a guest has accumulated through recurring visits to a restaurant chain), the online ordering system may also show the available offers in the user’s account. The Fetch Account Balance of User API can be used to retrieve information about eligible offers for a guest from the Punchh server so that the offers can be displayed on the website or mobile app when the guest logs in to the account. Generally, there are two types of offers associated with the various program types that Punchh supports: rewards and redeemables. Rewards are offers that are tied to an individual user’s account, whereas redeemables are offers that are configured at the business level.

Redeemables are used only with the “Points Unlock Redeemables” program type, and each redeemable in the user’s account must be correlated with a valid redeemable as defined in the Mobile Program Meta API. For example, for loyalty guests in the “Points Unlock Redeemables” program type, the website or mobile app can show the available redeemables that a guest has already unlocked as well as additional redeemables that can be unlocked as the guest accumulates more points (e.g., “You need just 45 more points to earn a free salad.”). The Fetch Account Balance of User API lists the offers that are currently available to the user, whereas the Mobile Program Meta API lists all redeemables set at the business level (including those that are currently locked due to insufficient points).

Applicable API Endpoints

Example Code

Fetch Account Balance (for General Use)

curl --location --request GET 'https://SERVER_NAME_GOES_HERE.punchh.com/api/auth/checkins/balance' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'x-pch-digest: SIGNATURE_GOES_HERE' \
--header 'Authorization: Bearer ACCESS_TOKEN_GOES_HERE' \
--header 'User-Agent: Punchh/OnlineOrder/1.0/Web/BrowserVersion/OS_Type' \
--data-raw '{
	"client": "CLIENT_GOES_HERE"
}'

import json
from http_client import send_request

def fetch_account_balance():
  path = "/api/auth/checkins/balance"
  http_verb = "GET"
  body = json.dumps({
    "client": "CLIENT_GOES_HERE"
  })
  response = send_request(path, http_verb, body)
  print(f"Response: {response}")

fetch_account_balance()

class FetchAccountBalance
  require_relative 'generate_signature.rb'
  require_relative 'http_client.rb'
  require 'json'

  # Client for the environment that you are pointing the request to
  CLIENT = "CLIENT_GOES_HERE"
  PATH = "/api/auth/checkins/balance"
  HTTP_VERB = "GET"

  def self.fetch_account_balance
    body = {client: CLIENT}.to_json
    response = HttpClient::send_request(PATH, HTTP_VERB, body)
  end
end

FetchAccountBalance.fetch_account_balance

Points Unlock Redeemables Example

Show full list of redeemables using Program Meta API:

curl --location --request GET 'https://SERVER_NAME_GOES_HERE.punchh.com/api2/mobile/meta.json' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Accept-Language: en' \
--header 'Authorization: Bearer ACCESS_TOKEN_GOES_HERE' \
--header 'x-pch-digest: SIGNATURE_GOES_HERE' \
--header 'User-Agent: Punchh/OnlineOrder/1.0/Web/BrowserVersion/OS_Type' \
--data-raw '{
	"client": "CLIENT_GOES_HERE"
}'

import hmac
import hashlib
import json
import requests

def program_meta():
  path = "/api2/mobile/meta.json"
  http_verb = "GET"
  body = json.dumps({
    "client": "CLIENT_GOES_HERE"
  })
  response = send_request(path, http_verb, body)
  print(f"Response: {response}")

program_meta()

require "json"
require "net/http"
require "openssl"
require "uri"

# Client for the environment that you are pointing the request to
CLIENT = "CLIENT_GOES_HERE"
PATH = "/api2/mobile/meta.json"
HTTP_VERB = "GET"

def self.program_meta
  body = {client: CLIENT}.to_json
  response = send_request(PATH, HTTP_VERB, body)
end

program_meta

Workflow

• The Fetch Account Balance of User API endpoint shows the available offers (redeemables and rewards) in the user account under the Redeemables and Rewards arrays in the API response; the type parameter in each Redeemable or Reward object indicates either “redeemable” or “reward”. In the online ordering system, redeemables are shown only for the loyalty guests on the “Points Unlock Redeemables” program type. Loyalty guests on the “Points Unlock Redeemables” program type can directly redeem offers only if they have sufficient points in their account needed to unlock the offers. A redeemable appears in the “Points Unlock Redeemables” 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 Redeemable. 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 rewards to guest accounts through a campaign or a deal, or directly through support gifting. Guests can also earn rewards through check-ins, which can be converted to rewards based on the earning settings of the business. 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.

• All offers have different offer IDs. In the Fetch Account Balance of User API response under a Redeemable or Reward object, the id parameter displays the ID of an offer, and the type parameter indicates whether the offer is a redeemable or a reward. Redeemables are set at the business level, so the ID of a redeemable is the same across the business. Reward IDs are unique and disappear once redeemed.

• You can use the parameters in the Fetch Account Balance of User API response under each Redeemable object (name, description, image, thumb_image, points, discount_amount, etc.) to display the reward information for the loyalty guest.

• Rewards display chronologically by creation date.

• For a loyalty guest on the “Points Unlock Redeemables” program type, you can use the Mobile Program Meta API to retrieve the full list of loyalty program redeemables and display the redeemables that are already unlocked and available to the user, along with additional redeemables that can be unlocked as the user accumulates more points. The “unlocked redeemables” can be retrieved from the Fetch Account Balance of User API. The Mobile Program Meta API will show only the redeemables that are part of the loyalty program and are available through the “Points Unlock Redeemables” program. The Mobile Program Meta API does not show the rewards received through campaigns or when guests earn rewards from check-ins.

• The redeemable_properties parameter can be used for special processing. Attributes such as "Merchandise", “Donatable”, "Food Item", “In-Store Only”, etc. can be added to a particular redeemable. For example, adding an “In-Store Only” property at the business level and then assigning it to a subset of redeeemables enables a business to filter customer rewards that show up only in the store and not in the online ordering system (the business website would need to filter out “In-Store Only”). Attributes that can be applied to redeemables are configured in the Punchh platform (contact your Punchh representative to update this configuration). To apply one or more attributes to a particular redeemable in the Punchh platform, go to Offers > All Redeemables > [select redeemable] > Validity > Attributes applicable on this redeemable and then check the relevant attribute(s).

Depending on the program type of the business, you can use the response parameters in the Fetch Account Balance of User API to show the available offers of a loyalty guest on the website or mobile app.

Best Practices

• Reward selection should be required after the look-up has been completed.

• Allow the integration to display all reward item fields for the most custom experience.

• Each Redeemable object within the Redeemables array in the response of the Fetch Account Balance of User API contains a “description” parameter. This can be ignored or included. If included, redeemable descriptions do not have a maximum character count.

• See the Module 3b: Show Account Balance tutorial for information about which response parameters in the Fetch Account Balance of User API show the user account balance for different program types.

• Use the Applicable Offers API to return rewards applicable to the current basket. Punchh rewards undergo a validation 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.

Related Topics

Fetch Account Balance of User API

Mobile Program Meta API

Applicable Offers API

Online Ordering Module 2: Sign-in

Online Ordering Module 3b: Show Account Balance