Previous Topic	Next Topic
POS Module 6d: Manage Items in the Discount Basket (Redemptions 2.0)	POS Module 6f: Void the Discount Basket (Redemptions 2.0)

POS API Certification Tutorial - Module 6e: Process/Create a Batch Redemption (Redemptions 2.0)

Goal

Redemptions 2.0 - Process a batch redemption with the appropriate discount type(s).

Prerequisites

You must have read the Module 6d: Manage Items in the Discount Basket tutorial.

Use Cases and Context

Redemption is applying a discount to an order. While ordering, a user can use offers (e.g., rewards, subscription discounts, etc.) that are available in the user's account, redeemables (business-level discounts that a user can exchange for points), or coupons and promo codes. These offers are configured by businesses. The loyalty user generates a redemption by selecting the offer to use.

For Redemptions 2.0, the Batch Redemption Process API is used for determining possible redemptions and for processing multiple redemptions based on the items in the discount basket:

Possible Redemptions: A Possible Redemptions call is used to verify that redemptions can be applied to an order. To make the Possible Redemptions call, the query parameter must be included in the request of the Batch Redemption Process API.
Process Redemption: To actually process redemptions on an order, when making the API call do NOT include the query parameter in the request of the Batch Redemption Process API.

Applicable API Endpoints


Endpoint Name/Path	Relevant Request Parameters	Relevant Response Parameters
Batch Redemption Process POST {server-name}/api/pos/batch_redemptions	- user_id - query (Include this parameter in the request only when making a Possible Redemptions call.) - subtotal_amount - receipt_datetime - receipt_amount - transaction_no The parameters under the line_items object: - item_name - item_qty - amount - item_type - item_id - item_family - item_group - serial_number external_uid (used for discount basket locking)	redemption_ref redemption_id qualified discount_type discount_id discount_value discount_amount discount_basket_item_id discount_details object success object failures object These parameters under the qualified_items object show the menu items to which the offer(s) can be applied: - item_name - item_qty - amount - item_type - item_id - item_family - item_group - serial_number

Workflow

The Batch Redemption Process API endpoint enables you to 1) apply an offer on the order as a Possible Redemptions call and determine whether the offer can be applied to a menu item in the check, and 2) process multiple redemptions based on the items in the guest’s active discount basket. Both the Possible Redemptions call and the Process Redemption call are nearly the same in terms of the request and response parameters. The difference between the two calls is that the Possible Redemptions call only verifies if items in the guest’s discount basket (sent in the API request) can be applied to the line items (menu items sent in the API request) on a current check and returns in the API response the qualified menu item(s) for the offer.

To make a Possible Redemptions call, the query parameter must be included in the request with a value of “true”. If the Possible Redemptions call shows that the offer is valid, you can then make the Process Redemption call (i.e., by removing the query parameter from the request) and submit the offer to process the actual redemption. If the Process Redemption call is successful, the offer is marked as used in the user’s account. The success object in the API response shows a list of discounts that are successfully redeemed, and the failures object in the API response shows a list of discounts that are not successfully redeemed.

Note: Before removing the query parameter from the Batch Redemption Process API request to make the Process Redemption call, use the Remove Item From Discount Basket API to clear the "failures" from the discount basket.

A unique ID associated with the discount basket is stored in the redemption_ref parameter in the API response. Save this in your system for future reference. You will need the redemption_ref if you want to void the discount basket.

Note: The discount limit can be set to 1 if you do not want to allow multiple redemptions for a single transaction. Otherwise, the system allows a maximum of 10 redemptions for a single transaction. That limit can be configured by Punchh to allow 1-10 redemptions in a single transaction.

Best Practices

We do not recommend sending the D (discount), T (tax), and P (payment) values in the item_type request parameter for Redemptions 2.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.