Online Ordering API Certification Tutorial - Module 5c: Voiding Redemptions (Redemptions 1.0)

Goal

Redemptions 1.0 - Void a redemption that has already been processed/committed.

Prerequisites

You must have read the Online Ordering Module 5a: Process/Create Redemption tutorial.

Use Cases and Context

A loyalty guest wants to cancel an order and return one or more processed redemptions applied on the check/cart after they have been committed. The reward is returned to the guest account after redemptions are voided successfully.

A loyalty guest submits an order but then decides to use a different reward for that submitted order. The guest can cancel the order while it is in flight, the Void Processed Redemption API can be called to return the improperly applied reward, and the user can create a new order with a different (or the same) reward.

Note: Void Processed Redemption is a real-time/synchronous call. Once the void is successful, the voided points/rewards can immediately be reused.

Applicable API Endpoints

Example Code

The following code examples demonstrate how to send a Void Processed Redemption call in order to void a processed redemption and to return the reward, points, or currency to the guest's account.

curl --location --request DELETE 'https://server-name-goes-here.punchh.com/api/auth/redemptions' \
--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",
  "redemption_id": 111111,
  "reason": "Order Canceled"
}'

import json
from http_client import send_request

def void_processed_redemption():
    path = "/api/auth/redemptions"
    http_verb = "DELETE"
    body = json.dumps({
      "client": "CLIENT_GOES_HERE",
      "redemption_id": 111111111,
      "reason": "Order Canceled"
    })
    response = send_request(path, http_verb, body)
    print(f"Response: {response}")
    
void_processed_redemption()

class VoidProcessedRedemption
  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"
  HTTP_VERB = "DELETE"
  def self.void_processed_redemption
    body = {client: CLIENT, redemption_id: 111111111, reason: "Order Canceled"}.to_json
    response = HttpClient::send_request(PATH, HTTP_VERB, body)
  end
end

VoidProcessedRedemption.void_processed_redemption

Workflow

The Void Processed Redemption API endpoint deletes a processed redemption using the redemption_id created at the time of redemption and returns the offer tied to the redemption to the loyalty guest’s account after the redemption is voided successfully. Redemptions have no time limit and can be voided at any time.

This is the general workflow for voiding redemptions:

1. After successfully processing a redemption with the Create Online Redemption API, get the redemption_id from the Create Online Redemption API response. If check-in is completed AND STILL IN PENDING STATE for the check, then you should first cancel/void the check-in. NOTE: If the business does not have the pending points feature enabled, check-ins can NOT be voided once have they have been committed. You can still void the redemption, however (see Online Ordering Module 7: Updating/Voiding Transactions).

2. Using the redemption_id, pass the required parameters in the Void Processed Redemption API. After voiding a redemption, rerun the Possible Redemptions API call for all of the remaining offers applied to the check (if any) and for the new offers that the guest wants to apply to the check. When voiding Punchh coupons and promos, send the redemption_code parameter with the API request.

Best Practices

• Void redemptions only after they are successfully processed and do not void prior. Apply redemptions as the guest goes through the order process, and then you can void the redemption at the end.

• Void redemptions when a guest removes an applied offer with a processed redemption from a check, or when a check with a processed redemption is canceled.

Related Topics

Void Processed Redemption API

Create Online Redemption API

Online Ordering Module 5a: Process/Create Redemption

Online Ordering Module 7: Updating/Voiding Transactions