POS API Certification Tutorial - Module 6a: Show Applicable Offers - Concepts (Redemptions 1.0)

Goal

Redemptions 1.0 - Display available offers based on current check details. 

Prerequisites

• You must have read the Module 5: Show Offers and Rewards After Look-up tutorial.

• The loyalty guest must have one or more rewards in the user’s account that can be applied to the check.

Use Cases and Context

After the user look-up, if one or more offers are present in the loyalty guest account, the POS queries the Punchh server to find which offers in the guest account can be applied to the guest’s current check. The POS shows the applicable offers on the POS terminal. The loyalty guest lets the operator know which offers are to be applied to the current check.

Primary Use Case Environment

• Quick-service restaurant or convenience store

• Quick sign-up at the counter

• Table-side

• Kiosk

Applicable API Endpoints

Example Code

We do not recommend sending the D (discount), T (tax), and P (payment) values in the item_type request parameter for Redemptions 1.0 API calls. Instead, send them in check-in API calls, such as Create Loyalty Check-in and Receipt Details.

For example, if a business offers a $2 discount on a $10 burger, send the burger as $8 ($10 - $2) in the API request. Send the discount as a line item in the Check-in API call.

If you must send D, T, and P menu item types, you must configure an exclusion qualification criterion (QC) for the offer in the Punchh platform. Create an exclusion filter using item types D, T, and P to ensure they are properly excluded. See the Qualification Criteria article on the Support Portal.

Note: To view the Punchh product documentation on the Punchh Support Portal, you must log in to a Punchh platform production environment. If you already have access to a production environment, follow the instructions here to access the Punchh Support Portal.

curl --location --request GET 'https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/redemptions/applicable_offers' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token token=LOCATION_KEY_GOES_HERE, btoken=BUSINESS_KEY_GOES_HERE' \
--header 'User-Agent: Brink/POS/1.0' \
--data-raw '{
    "email": "test@example.com",
    "menu_items": [
      {
      "item_name": "Cheese Pizza",
      "item_qty": 1,
      "item_amount": 2.86,
      "menu_item_type": "M",
      "menu_item_id": 1111,
      "menu_family": "001",
      "menu_major_group": "001",
      "serial_number": "1.0"
    },
    {
      "item_name": "BBQ Wings",
      "item_qty": 1,
      "item_amount": 7.86,
      "menu_item_type": "M",
      "menu_item_id": 2222,
      "menu_family": "002",
      "menu_major_group": "002",
      "serial_number": "2.0"
    },
    {
      "item_name": "Free Pizza",
      "item_qty": 1,
      "item_amount": 2.86,
      "menu_item_type": "D",
      "menu_item_id": 3333,
      "menu_family": "003",
      "menu_major_group": "003",
      "serial_number": "3.0"
    }
    ],
    "subtotal_amount": 7.86,
    "receipt_amount": 7.86,
    "receipt_datetime": "2022-06-15T01:01:01-07:00"
}'

let requestBody = {
  email: 'test@example.com',
  menu_items: [
    {
      item_name: 'Cheese Pizza',
      item_qty: 1,
      item_amount: 2.86,
      menu_item_type: 'M',
      menu_item_id: 1111,
      menu_family: '001',
      menu_major_group: '001',
      serial_number: '1.0'
    },
    {
      item_name: 'BBQ Wings',
      item_qty: 1,
      item_amount: 7.86,
      menu_item_type: 'M',
      menu_item_id: 2222,
      menu_family: '002',
      menu_major_group: '002',
      serial_number: '2.0'
    },
    {
      item_name: 'Free Pizza',
      item_qty: 1,
      item_amount: 2.86,
      menu_item_type: 'D',
      menu_item_id: 3333,
      menu_family: '003',
      menu_major_group: '003',
      serial_number: '3.0'
    }
  ],
  subtotal_amount: 7.86,
  receipt_amount: 7.86,
  receipt_datetime: '2022-06-15T01:01:01-07:00'
};

const url = 'https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/redemptions/applicable_offers';
let headers = {
  'Cache-Control': 'no-cache',
  'Content-Type': 'application/json',
  'Authorization': 'Token token=LOCATION_KEY_GOES_HERE, btoken=BUSINESS_KEY_GOES_HERE',
  'User-Agent': 'Brink/POS/1.0'
};

let options = {
  /* Note that in JavaScript, the request method must be POST instead of GET. Otherwise, you would receive an error since a request body is being sent. */
  method: 'POST',
  headers: headers,
  body: JSON.stringify(requestBody)
};

fetch(url, options)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

# You will need to install the Requests package before this code will work. 
# To do so, see the installation instructions here: https://requests.readthedocs.io/en/latest/user/install/#install
import requests
import json

url = "https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/redemptions/applicable_offers"

payload = json.dumps({
  "email": "test@example.com",
  "menu_items": [
    {
      "item_name": "Cheese Pizza",
      "item_qty": 1,
      "item_amount": 2.86,
      "menu_item_type": "M",
      "menu_item_id": 1111,
      "menu_family": "001",
      "menu_major_group": "001",
      "serial_number": "1.0"
    },
    {
      "item_name": "BBQ Wings",
      "item_qty": 1,
      "item_amount": 7.86,
      "menu_item_type": "M",
      "menu_item_id": 2222,
      "menu_family": "002",
      "menu_major_group": "002",
      "serial_number": "2.0"
    },
    {
      "item_name": "Free Pizza",
      "item_qty": 1,
      "item_amount": 2.86,
      "menu_item_type": "D",
      "menu_item_id": 3333,
      "menu_family": "003",
      "menu_major_group": "003",
      "serial_number": "3.0"
    }
  ],
  "subtotal_amount": 7.86,
  "receipt_amount": 7.86,
  "receipt_datetime": "2022-06-15T01:01:01-07:00"
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Token token=LOCATION_KEY_GOES_HERE, btoken=BUSINESS_KEY_GOES_HERE',
  'User-Agent': 'Brink/POS/1.0'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Workflow

The Applicable Offers API filters the rewards from the loyalty guest account and shows only the rewards that apply to the current check/cart/basket state. The Applicable Offers endpoint shows only the offers that have “type” as “reward” under the Rewards object in the User Look-up and Fetch Balance API response for the "points unlock redeemables" program type. See Module 5: Show Offers and Rewards After Look-up.

Note: The API returns only rewards and redeemables (base redeemables) that can be applied to the check for the "points convert to rewards" program type. The API returns only rewards that can be applied to the check for "points convert to currency" and "visit-based" program types.

These are some important points that you need to know before making a call to the Applicable Offers API:

• The POS needs to send the menu items to Punchh in the format prescribed in How To Send Menu Items to Punchh. The API developers are responsible for sending the menu item object exactly how Punchh specifies in that topic. There is no flexibility in the way menu items are sent in the Applicable Offers API call. Punchh does not store the entire menu items available in the restaurant’s POS system. A business or the Punchh marketing team uses the menu item data to create qualification criteria in the Punchh platform. Qualification criteria define the offers for menu items.

• As the menu item data for the menu items that qualify for offers is categorized in the qualification criteria in the same format as mentioned in How To Send Menu Items to Punchh, it is important that you send in the API call the menu item data in the same format as mentioned in Applicable Offers to show the correct applicable offers/rewards for the menu items on the check.

• If any prior discount is applied on a menu item by the POS, then the POS needs to send the discount information to Punchh in the API request. If the POS does not send the discount information, Punchh will not know that a menu item has been discounted by the POS. To indicate to Punchh that a discount is applied from the POS side, add the discount menu item and use item type D for the discounted menu item in the API request. The “serial number” in the menu item data is used to identify the discounted menu item. For example, you could assign the following serial numbers to the items: Pizza (base item) - 1.0 and 20% off on Pizza (discount) - 1.1. See the "Redemption Examples" section in How To Send Menu Items to Punchh.

• The Applicable Offers API call will fail to fetch the applicable offers for the menu items if the menu item data in the menu item object in the Applicable Offers API request is not correct.

• Each time one of the applicable offers is applied to a menu item on the check to process a redemption, you need to configure the POS/kiosk to rerun the Applicable Offers API to exclude offers that are applicable to the discounted menu item. For example, the guest may have three offers (A, B, and C) that are applicable to the same menu item on the check. Now if offer A is applied to the check, then offers B and C get disqualified because offers B and C are applicable to the same menu item. Similarly, when a menu item is added to or removed from the check, the POS should rerun the Applicable Offers API to add or remove offers accordingly. 

This is a general flow of API calls to determine the applicable offers on an order:

1. Add menu items to the guest transaction. You should include all the menu item types that can be provided at the time of the call including service charges, taxes, and payments. For more information about the structure of menu items, and for additional details about sending menu items, see How To Send Menu Items to Punchh.

2. Perform a user look-up using the User Look-up and Fetch Balance API to assign the transaction to the user.

3. Call the Applicable Offers API. If applicable offers/rewards are found that can be applied to the check, the API returns the discount amount and menu items eligible for each of these offers.

Use the Possible Redemption API for Offer Type Other Than Reward

If the loyalty guest has offers other than rewards in the account (redeemables, banked rewards, coupons, promos, etc.), you need to call the Possible Redemptions API and pass the offer type and other details in the API request to determine if an offer can be applied to the current check. When the Punchh server receives the Applicable Offers API request that includes all of the menu items on the check from the POS, it determines applicable rewards for the menu items in the order.

The Possible Redemptions API call allows you to verify (one offer at a time) if an offer (reward, redeemable, banked rewards, coupon, promo, card completion, etc.) in the guest account can be applied to the current check. The API call returns the qualified menu items and discounts for the offer sent in the API request.

Best Practices

• Submit the Applicable Offers call as items change on the cart/transaction to ensure the POS terminal displays which offers apply to the transaction in real-time. 
• Commit redemptions as they apply to the check using the Create Redemption API. If the check is modified post redemption, the POS should show a message that the loyalty discounts applied will be voided and need to be reapplied with a YES/NO option. If the POS operator chooses YES, the POS operator needs to call the Applicable Offers endpoint after modifying the order and reapply the discount.

Related Topics

Applicable Offers API

How To Send Menu Items to Punchh

User Look-up and Fetch Balance API