Module 6b: Process/Create Redemption (Redemptions 1.0)
Previous Topic Next Topic
POS Module 6b: Process/Create Redemption - Concepts (Redemptions 1.0) POS Module 6c: Voiding Redemptions - Concepts (Redemptions 1.0)

POS API Certification Tutorial: Module 6b: Process/Create Redemption - Example Scenarios (Redemptions 1.0)

Prerequisites

General Tasks for Performing Redemption

1. Determine the redemption type (redeemable, reward, card completion, redemption code, discount amount, and fuel rewards) by first performing a user look-up with the User Look-up and Fetch Balance API. The Module 6b: Process/Create Redemption tutorial outlines different redemption types and their requirements for redemption.

2. Add menu items to the transaction. You should include all of the menu item types that can be provided at the time of the call, such as service charges, taxes, and payments. For additional details on the Punchh menu item format and sending menu items to Punchh, see How To Send Menu Items to Punchh.

3. When redeeming a reward, perform the Possible Redemptions API call first. Note: Send different parameters in the request based on the type of redemption.

4. Once the Possible Redemptions call indicates that you can redeem the reward/offer, it is a good practice to immediately perform the Create Redemption API call. 

5. Repeat steps 3 and 4 until you redeem all of the rewards/offers as needed. To avoid any mismatch between the redemption amount applied at the POS and allowed by Punchh, every Possible Redemptions API call must be immediately followed by a Create Redemption API call. If you apply more than one discount, you will need to specify the previous discounts in separate menu items with the menu item type as “D” on subsequent redemption calls. Examples of how to specify a discount as a separate menu item are found in How To Send Menu Items to Punchh.

Note

If the check is modified post redemption, the POS should show a message that the loyalty discounts applied will be voided and must be reapplied with a YES or NO option. If the POS operator chooses YES, the POS operator needs to reapply the discount using the Possible Redemptions/Create Redemption API endpoints after modifying the order.

Processing Different Redemption Types

Following are the steps to process different redemption types in the Possible Redemptions and Create Redemption API requests:

Redeemable

Applicable program type: points unlock redeemable

1. Look up the Program Meta information response stored locally on the POS system and search for the redeemables array in the response, OR look up the Program Meta information using the Program Meta API. The API response returns the redeemables array, which contains the redeemable_id parameter. 

2. Pass the value of redeemable_id (ID of the redeemable from the response of Program Meta) with discount_type: redeemable to the Possible Redemptions and Create Redemption API requests based on the user’s redeemable selection.

Reward

Applicable program type: points convert to rewards

1. The POS operator needs to select the reward that will be redeemed. 

2. Perform a user look-up using the User Look-up and Fetch Balance API. The API response returns the rewards array, which contains the id parameter. The value of the id parameter is the reward ID.

3. Pass the value of id (ID of the reward from the response of User Look-up and Fetch Balance) with discount_type: reward to the Possible Redemptions and Create Redemption API requests based on the user’s reward selection. 

Card Completion

Applicable program type: visit-based

1. Perform a user look-up using the User Look-up and Fetch Balance API. The API response returns the balance object, which contains the unredeemed_cards parameter.

2.  If the value of the unredeemed_cards parameter is greater than 0, use this redemption type and pass discount_type: card_completion to the Possible Redemptions and Create Redemption API requests. 

Discount Amount

Applicable program type: banked currency

1. Perform a user look-up using the User Look-up and Fetch Balance API. The API response returns the balance object, which contains the banked_rewards parameter. 

2. If the value of the banked_rewards parameter is greater than 0, pass a dollar amount in the redeemed_points parameter to the Possible Redemptions and Create Redemption API requests based on the amount the guest wishes to redeem. The dollar amount to be redeemed should not exceed the value of the banked_rewards parameter. Use discount_type: discount_amount with the Possible Redemptions and Create Redemption API requests. 

Redemption Code

Applicable program type: redemption code

1. The guest provides the redemption code to redeem an offer using a redemption code, Punchh coupon code, or promo code, which is entered on the POS either manually or by scanning the QR code. 

2. Pass this code in the redemption_code parameter alongside discount_type: redemption_code with the Possible Redemptions and Create Redemption API requests.

Fuel Rewards Discount

Applicable program type: fuel rewards

1. Perform a user look-up using the User Look-up and Fetch Balance API. Using the fuel rewards discount redemption type requires a user to be identified first. 

2. Use discount_type: fuel_reward with the Possible Redemptions and Create Redemption API requests to redeem the reward. 

Possible Scenario

The following scenario is based on the assumptions here.

Story Line

When Rachel lets Janice know that she has some applicable rewards, Janice wants to use them for her order. Rachel makes a Possible Redemptions API call to make sure that the $6 reward can be used for the large matcha latte that Janice wants to purchase. The call is successful, so Rachel proceeds and the POS makes a Create Redemption API call and is able to complete Janice’s order. Janice exits the shop happily with her free drink in hand.

Code Sample (Direct API Integration)

The following code sample contains the API request and response for the transactions between the POS and Punchh based on this story line. After the successful look-up of Janice's account using her email address (janice@example.com), the POS calls the Possible Redemptions API first with redeemed points and discount type to check if the redemption can be applied to the order. After receiving a successful response from the Punchh server, the POS calls the Create Redemption API to process the redemption. The request and response parameters are the same for both Possible Redemptions and Create Redemption. The POS calls the Possible Redemptions and Create Redemption APIs with these parameters:

  • Discount type: discount amount
  • Redeemed points: $6
  • Menu items
  • Subtotal amount: $6
  • Receipt amount: $6
  • Receipt date and time: 2023-01-05T13:05:01+05:30
  • Transaction number: 5678
  • Punchh key: PUNCHH_KEY_GOES_HERE
  • Email: janice@example.com

The Possible Redemptions and Create Redemption APIs return the following information about the redemption:

  • Category: redeemable
  • Redeemed points: $6
  • Redemption ID: 209348
  • Status: Redeemed on January 5, 2023, 13:05 by Janice Litman at Central Punchh Coffee. It can be honored.
Request Body Response Body
API endpoint name: Possible Redemptions
POST {server-name}/api/pos/redemptions/possible

{
"discount_type": "discount_amount",
"redeemed_points": "6 ",
"cc_last4": 4380,
"employee_id": 7,
"employee_name": "Rachel Green",
"menu_items": [
{
"item_name": "Matcha Latte, Large",
"item_qty": 1,
"item_amount": 6,
"menu_item_type": "M",
"menu_item_id": 12,
"menu_family": "800",
"menu_major_group": "152",
"serial_number": "1.0"
},
{
"item_name": "Tax",
"item_qty": 1,
"item_amount": 0.2,
"menu_item_type": "T",
"menu_item_id": 8888,
"menu_family": "",
"menu_major_group": "",
"serial_number": "2.0"
},
{
"item_name": "Credit Card",
"item_qty": 1,
"item_amount": 6.2,
"menu_item_type": "P",
"menu_item_id": 7777,
"menu_family": "",
"menu_major_group": "",
"serial_number": "3.0"
}
],

"subtotal_amount": 6,
"receipt_amount": 6,
"receipt_datetime": "2023-01-05T13:05:01+05:30",
"transaction_no": 5678,
"external_uid": "12312318778",
"punchh_key": "PUNCHH_KEY_GOES_HERE",
"email": "janice@example.com",
"channel": "pos"
}		 {
"category": "redeemable",
"qualified_menu_items": [
{
"item_amount": 6,
"item_name": "Matcha Latte",
"item_qty": 1,
"menu_family": "800",
"menu_item_id": "12",
"menu_item_type": "M",
"menu_major_group": "152",
"serial_number": "1.0"
}
],
"redemption_amount": 6,
"redemption_code": 834507,
"redemption_id": 209348,
"status": "Redeemed on January 5, 2023, 13:05 by Janice Litman at Central Punchh Coffee. It can be honored."
}
API endpoint name: Create Redemption
POST {server-name}/api/pos/redemptions

{
"discount_type": "discount_amount",
"redeemed_points": "6 ",
"cc_last4": 4380,
"employee_id": 7,
"employee_name": "Rachel Green",
"menu_items": [
{
"item_name": "Matcha Latte, Large",
"item_qty": 1,
"item_amount": 6,
"menu_item_type": "M",
"menu_item_id": 12,
"menu_family": "800",
"menu_major_group": "152",
"serial_number": "1.0"
},
{
"item_name": "Tax",
"item_qty": 1,
"item_amount": 0.2,
"menu_item_type": "T",
"menu_item_id": 8888,
"menu_family": "",
"menu_major_group": "",
"serial_number": "2.0"
},
{
"item_name": "Credit Card",
"item_qty": 1,
"item_amount": 6.2,
"menu_item_type": "P",
"menu_item_id": 7777,
"menu_family": "",
"menu_major_group": "",
"serial_number": "3.0"
}
],

"subtotal_amount": 6,
"receipt_amount": 6,
"receipt_datetime": "2023-01-05T13:05:01+05:30",
"transaction_no": 5678,
"external_uid": "12312318778",
"punchh_key": "PUNCHH_KEY_GOES_HERE",
"email": "janice@example.com",
"channel": "pos"
}		 {
"category": "redeemable",
"qualified_menu_items": [
{
"item_amount": 6,
"item_name": "Matcha Latte",
"item_qty": 1,
"menu_family": "800",
"menu_item_id": "12",
"menu_item_type": "M",
"menu_major_group": "152",
"serial_number": "1.0"
}
],
"redemption_amount": 6,
"redemption_code": 834507,
"redemption_id": 209348,
"status": "Redeemed on January 5, 2023, 13:05 by Janice Litman at Central Punchh Coffee. It can be honored."
}

Related Topics

Possible Redemptions API

Create Redemption API

Applicable Offers API

How To Send Menu Items to Punchh

User Look-up and Fetch Balance API

Previous
Module 6b: Concepts
Next
Module 6c: Concepts