Online Ordering API Certification Tutorial - Module 5b: Show Applicable Offers (Redemptions 1.0)

Goal

Redemptions 1.0 - Display available offers based on a user's current cart.

Prerequisites

You must have read the Online Ordering Module 3a: Show Offers in Guest Account and Online Ordering Module 5a: Process/Create Redemption tutorials.

Use Cases and Context

You can use an Applicable Offers API call to display which offers, if any, are applicable for the user given the specific set of menu items in the cart when placing an online order. The specific menu items are required in order to make this work (for details, see How To Send Menu Items to Punchh). If one or more offers are present in the loyalty guest account, the online ordering system queries the Punchh server to find which offers in the guest account can be applied to the guest’s current cart so that the user can choose which applicable offers to use for the current cart.

Applicable API Endpoints

Example Code

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

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.

The following code examples demonstrate how to send an Applicable Offers call in order to check to see which offers, if any, are available for a user to apply to the specific set of menu items in the cart.

curl --location --request GET 'https://server-name-goes-here.punchh.com/api/auth/redemptions/applicable_offers' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'x-pch-digest: SIGNATURE_GOES_HERE' \

# A guest's access_token can be retrieved from the API response to a Sign Up or Sign In API call.
# To get an access_token for use with our Online Ordering APIs, this will need to be configured on the Punchh Platform.
# Please reach out to your Punchh representative in order to get that set up.
--header 'Authorization: Bearer ACCESS_TOKEN_GOES_HERE' \
--header 'User-Agent: Punchh/OnlineOrder/1.0/Web/BrowserVersion/OS_Type' \

--data-raw '{
  "client": "CLIENT_GOES_HERE",
  "menu_items": [
    {
      "item_name": "Pizza with Pepperoni Topping",
      "item_qty": 1,
      "item_amount": 10.99,
      "menu_item_type": "M",
      "menu_item_id": "3001",
      "menu_family": "Pizza",
      "menu_major_group": "Pizza",
      "serial_number": "1.0"
    },
    {
      "item_name": "Pepperoni Topping",
      "item_qty": 1,
      "item_amount": 0.99,
      "menu_item_type": "M",
      "menu_item_id": "3002",
      "menu_family": "Pizza Topping",
      "menu_major_group": "Pizza",
      "serial_number": "1.1"
    },
    {
      "item_name": "Discount",
      "item_qty": 1,
      "item_amount": 5.00,
      "menu_item_type": "D",
      "menu_item_id": "4001",
      "menu_family": "Discount",
      "menu_major_group": "Discount",
      "serial_number": "2.0"
    }
  ],
  "subtotal_amount": 6.98,
  "receipt_amount": 6.98,
  "receipt_datetime": "2022-09-012T07:42:03-00:00",
  "store_number": "001"
}'

import json
from http_client import send_request

def applicable_offers():
    path = "/api/auth/redemptions/applicable_offers"
    http_verb = "GET"
    menu_items = [{"item_name": "Pizza with Pepperoni Topping", "item_qty": 1, "item_amount": 10.99, "menu_item_type": "M", "menu_item_id": "3001", "menu_family": "Pizza", "menu_major_group": "Pizza", "serial_number": "1.0"}, {
        "item_name": "Pepperoni Topping", "item_qty": 1, "item_amount": 0.99, "menu_item_type": "M", "menu_item_id": "3002", "menu_family": "Pizza Topping", "menu_major_group": "Pizza", "serial_number": "1.1"}, {
        "item_name": "Discount", "item_qty": 1, "item_amount": 5.00, "menu_item_type": "D", "menu_item_id": "4001", "menu_family": "Discount", "menu_major_group": "Discount", "serial_number": "2.0"}]
    receipt_amount = 0
    for item in menu_items:
        if item["menu_item_type"] == "M":
            receipt_amount += item["item_amount"]
        if item["menu_item_type"] == "D":
            receipt_amount -= item["item_amount"]
    body = json.dumps({
      "client": "CLIENT_GOES_HERE",
      "receipt_amount": receipt_amount,
      "subtotal_amount": receipt_amount,
      "store_number": "001",
      "menu_items": menu_items,
      "receipt_datetime": "2022-09-012T07:42:03-00:00"
    })
    response = send_request(path, http_verb, body)
    print(f"Response: {response}")
    
applicable_offers()

class ApplicableOffers
  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/redemptions/applicable_offers"
  HTTP_VERB = "GET"
  MENU_ITEMS = [{ item_name: "Pizza with Pepperoni Topping", item_qty: 1, item_amount: 10.99, menu_item_type: "M", menu_item_id: "3001", menu_family: "Pizza", menu_major_group: "Pizza", serial_number: "1.0" }, { item_name: "Pepperoni Topping", item_qty: 1, item_amount: 0.99, menu_item_type: "M", menu_item_id: "3002", menu_family: "Pizza", menu_major_group: "Pizza", serial_number: "1.1" }, { item_name: "Discount", item_qty: 1, item_amount: 5.00, menu_item_type: "D", menu_item_id: "4001", menu_family: "Discount", menu_major_group: "Discount", serial_number: "2.0" }]
  
  def self.fetch_applicable_offers
    receipt_amount = 0
    MENU_ITEMS.each do |item|
      if item[:menu_item_type] == "M"
        receipt_amount += item[:item_amount]
      end
      if item[:menu_item_type] == "D"
        receipt_amount -= item[:item_amount]
      end
    end
    
    body = {client: CLIENT, receipt_amount: receipt_amount, subtotal_amount: receipt_amount, receipt_datetime: "2022-09-07T07:42:03-00:00", store_number: "001", menu_items: MENU_ITEMS}.to_json
    response = HttpClient::send_request(PATH, HTTP_VERB, body)
  end
end

ApplicableOffers.fetch_applicable_offers

Here is an example API response after sending an Applicable Offers request using the example code above:

[
  {
    "menu_items":[
      {
        "item_name":"Pepperoni Topping",
        "item_qty":1,
        "item_amount":0.99,
        "menu_item_type":"M",
        "menu_item_id":"3002",
        "menu_family":"Pizza",
        "menu_major_group":"Pizza",
        "serial_number":"1.1"
      }
    ],
    "discount_amount":0.99,
    "reward":{
      "id":1111111111,
      "created_at":"2022-09-15T18:10:45Z",
      "end_date_tz":nil,
      "start_date_tz":"2022-09-15T18:10:45Z",
      "updated_at":"2022-09-15T18:10:45Z",
      "image":"IMAGE_URL_GOES_HERE",
      "status":"unredeemed",
      "points":0,
      "discount_amount":0,
      "description":"",
      "name":"Free Pepperoni Topping",
      "redeemable_properties":""
    }
  }
]

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 Fetch Account Balance of User response for the "points unlock redeemables" program type. See Module 3a: Show Offers in Guest Account

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. A business with the "points unlock redeemables" program type will not be able to use this endpoint to return applicable redeemables that cost points for redemption.

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

• Menu items must be sent to Punchh in the format prescribed in How To Send Menu Items to Punchh. 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 set of menu items available for a restaurant. A business or the Punchh marketing team uses the menu item data to create qualification criteria in the Punchh dashboard. 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, then the online ordering system needs to send the discount information to Punchh in the API request. Otherwise, Punchh will not know that a menu item has been discounted. To indicate to Punchh that a discount is applied, 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 data in the Menu Items object in the API request is not correct.

• The Applicable Offers API call will return an empty array ([]) if no applicable offers are found for the specified user's menu items.

• Each time one of the applicable offers is applied to a menu item on the check to process a redemption, you need 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, 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. 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. You can then display the returned offers to the user for them to choose which one they would like to apply.

3. Pass the reward ID as the value of the reward_id request parameter in the Possible Redemptions API call (see Online Ordering Module 5a: Process/Create Redemption).

Use the Possible Redemptions API Call 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 make a possible redemptions call using the Create Online Redemption API. 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, it determines applicable rewards for the menu items in the order.

The possible redemptions 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

• The specific menu items are required in order for the Applicable Offers API call to work (see How To Send Menu Items to Punchh). Punchh does not store the entire list of menu items for a given restaurant; the offer only uses the qualification criteria configured in the Punchh dashboard. The offer will fail if the qualification criteria are not met or if the Menu Items object is not complete. The Menu Items object must be sent exactly as specified in How To Send Menu Items to Punchh.

• Submit the Applicable Offers API call as items change on the cart/transaction to ensure that the online ordering system displays which offers apply to the transaction in real-time. If you process a redemption, you need to rerun the Applicable Offers API call to refresh the list of available offers for that specific check/transaction. In the online ordering system, you can show offers as the user adds items to the cart. In this case, you should run the applicable offers call every time items are added/removed from the check or when the user applies/removes discounts from the check. Or you can wait until the cart/order is completed.

• It is important to categorize items (menu item type) to show discounts (Punchh will not know that a menu item has been discounted). Use item type “D” to indicate a discount (see How To Send Menu Items to Punchh).

• Commit redemptions as they apply to the check using the Create Online Redemption API. If the check is modified post redemption, the loyalty discounts applied will be voided and need to be reapplied. Submit the Applicable Offers API call after modifying the order and reapply the discount.

Related Topics

Applicable Offers API

Create Online Redemption API

How To Send Menu Items to Punchh

Fetch Account Balance of User API

Online Ordering Module 3a: Show Offers in Guest Account

Online Ordering Module 5a: Process/Create Redemption