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

POS API Certification Tutorial - Module 6c: Voiding Redemptions - Concepts (Redemptions 1.0)

Goal

Redemptions 1.0 - Void processed redemptions.

Prerequisites

You must have read the Module 6b: Process/Create Redemption tutorial.

Use Cases and Context

At a store/restaurant, a loyalty guest asks the POS operator to delete one or more processed redemptions applied on the check/cart after the check-in. The POS operator first voids the check-in and then deletes the redemptions one at a time. The reward is returned to the guest account after redemptions are voided successfully.

Applicable API Endpoints


Endpoint Name/Path	Relevant Request Parameters	Relevant Response Parameters
Void Redemption DELETE {server-name}/api/pos/redemptions	- redemption_id - email (required if using redemption_id) - redemption_code - transaction_no	N/A
Void Multiple Redemptions DELETE {server-name}/api/pos/redemptions/multiple_destroy	- redemption_id (array of) - email (required if using redemption_id) - redemption_code (array of) - transaction_no	N/A

Example Code

Void Redemption - Redemption ID

curl --location --request DELETE 'https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/redemptions' \
--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 '{
	"phone": "1111111111",
	"redemption_id": "REDEMPTION_ID_GOES_HERE",
  "transaction_no": "111111111"
}'

let requestBody = {
  'phone': '1111111111',
  'redemption_id': 'REDEMPTION_ID_GOES_HERE',
  'transaction_no': '111111111'
};

const url = 'https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/redemptions';
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 = {
  method: 'DELETE',
  headers: headers,
  body: JSON.stringify(requestBody)
};

fetch(url, options)
  .then(response => {
    return response.text().then(responseText => {
      if (response.ok) {
        if (responseText) {
          console.log(response.status + ' - ' + responseText);
        } else {
          console.log(response.status);
        }
      } else {
        console.log(response.status + ' - ' + responseText);
      }
    });
  })
  .catch(error => {
    console.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"

payload = json.dumps({
  "phone": "1111111111",
  "redemption_id": "REDEMPTION_ID_GOES_HERE",
  "transaction_no": "111111111"
})
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("DELETE", url, headers=headers, data=payload)

if response: 
  print(response.status_code, "Successful")
else: 
  print(f"{response.status_code} {response.reason} - {response.json()['error']['message']}")

Void Redemption - Redemption Code

curl --location --request DELETE 'https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/redemptions' \
--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 '{
	"phone": "1111111111",
	"redemption_code": "REDEMPTION_CODE_GOES_HERE",
  "transaction_no": "111111111"
}'

let requestBody = {
  'phone': '1111111111',
  'redemption_code': 'REDEMPTION_CODE_GOES_HERE',
  'transaction_no': '111111111'
};

const url = 'https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/redemptions';
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 = {
  method: 'DELETE',
  headers: headers,
  body: JSON.stringify(requestBody)
};

fetch(url, options)
  .then(response => {
    return response.text().then(responseText => {
      if (response.ok) {
        if (responseText) {
          console.log(response.status + ' - ' + responseText);
        } else {
          console.log(response.status);
        }
      } else {
        console.log(response.status + ' - ' + responseText);
      }
    });
  })
  .catch(error => {
    console.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"

payload = json.dumps({
  "phone": "1111111111",
  "redemption_code": "REDEMPTION_CODE_GOES_HERE",
  "transaction_no": "111111111"
})
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("DELETE", url, headers=headers, data=payload)

if response: 
  print(response.status_code, "Successful")
else: 
  print(f"{response.status_code} {response.reason} - {response.json()['error']['message']}")

Void Multiple Redemptions - Redemption ID

curl --location --request DELETE 'https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/redemptions/multiple_destroy' \
--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 '{
	"phone": "1111111111",
	"redemption_id": ["111111","222222","333333"],
  "transaction_no": "111111111"
}'

let requestBody = {
  'phone': '1111111111',
  'redemption_id': ['111111','222222','333333'],
  'transaction_no': '111111111'
};

const url = 'https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/redemptions/multiple_destroy';
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 = {
  method: 'DELETE',
  headers: headers,
  body: JSON.stringify(requestBody)
};

fetch(url, options)
  .then(response => {
    return response.text().then(responseText => {
      if (response.ok) {
        if (responseText) {
          console.log(response.status + ' - ' + responseText);
        } else {
          console.log(response.status);
        }
      } else {
        console.log(response.status + ' - ' + responseText);
      }
    });
  })
  .catch(error => {
    console.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/multiple_destroy"

payload = json.dumps({
  "phone": "1111111111",
  "redemption_id": ["111111","222222","333333"],
  "transaction_no": "111111111"
})
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("DELETE", url, headers=headers, data=payload)

if response: 
  print(response.status_code, "Successful")
else: 
  print(f"{response.status_code} {response.reason} - {response.json()['error']['message']}")

Void Multiple Redemptions - Redemption Code

curl --location --request DELETE 'https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/redemptions/multiple_destroy' \
--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 '{
	"phone": "1111111111",
	"redemption_code": ["1111111","2222222","3333333"],
  "transaction_no": "111111111"
}'

let requestBody = {
  'phone': '1111111111',
  'redemption_code': ['1111111','2222222','3333333'],
  'transaction_no': '111111111'
};

const url = 'https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/redemptions/multiple_destroy';
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 = {
  method: 'DELETE',
  headers: headers,
  body: JSON.stringify(requestBody)
};

fetch(url, options)
  .then(response => {
    return response.text().then(responseText => {
      if (response.ok) {
        if (responseText) {
          console.log(response.status + ' - ' + responseText);
        } else {
          console.log(response.status);
        }
      } else {
        console.log(response.status + ' - ' + responseText);
      }
    });
  })
  .catch(error => {
    console.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/multiple_destroy"

payload = json.dumps({
  "phone": "1111111111",
  "redemption_code": ["1111111","2222222","3333333"],
  "transaction_no": "111111111"
})
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("DELETE", url, headers=headers, data=payload)

if response: 
  print(response.status_code, "Successful")
else: 
  print(f"{response.status_code} {response.reason} - {response.json()['error']['message']}")

Workflow

The Void 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. The Void Multiple Redemptions API allows you to delete multiple processed redemptions by passing an array of redemption IDs. Redemptions have no time limit and can be voided at any time.

This is the general workflow for voiding redemptions:

1. After successfully creating a redemption with the Create Redemption API, get the redemption_id from the Create Redemption response. If check-in is completed for the check, then you first need to cancel/void the check-in. See Module 8b: Updating/Voiding Transactions.

2. Using the redemption_id, pass the required parameters in the Void Redemption API. If you are voiding multiple redemptions, use the Void Multiple Redemptions API. After voiding one or more redemptions, the POS operator needs to rerun the Possible Redemptions API 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.
Tip: When voiding Punchh coupons and promo codes, send the redemption_code parameter along with the transaction_no. Email is not a required parameter when voiding Punchh coupons and promo codes using the redemption code. Before voiding Punchh coupons and promo codes, show a message on the POS that the reward will not be credited back to the guest account and whether the guest wants to proceed with the Yes and No options.

Voiding Redemptions for Split Checks

If the POS supports splitting checks, each check should be treated as a separate, independent check with Punchh. If existing loyalty transactions are on the check before being split, all transactions will need to be removed before splitting. Any redemption applied to the check before splitting will need to be revalidated via a Possible Redemptions API call to Punchh after the check is split. Receipt details already sent to Punchh will need to be updated after the check is split with the new check contents.

Best Practices

Void redemptions only after they are successfully processed and do not void prior.
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.