Redeem customer points

In this guide we will go through different customer redemption use-cases using direct redemption. In the previous tutorial, we learned use-cases of using customers' points balance which is retrieved by Customer's points balance API. However, for customers to make use of these points, they should be able to redeem them and apply them during checkout.

There are various scenarios when redeeming your customers points, you may want your customers to apply points redemption during checkout or you may want them to apply it at different page and apply later on in checkout page.

use-case: redeem points directly at checkout

Redemption at checkout offers a seamless and easy experience for your customer to redeem his points directly during checkout without navigating across different pages to redeem his points and copying his discount code and paste it at checkout page.

To apply points redemption on your order during checkout, we will use Order API. Order API is a tailored API to support e-commerce, a precautionary step would be to validate the customer's balance as we covered in one of customers points balance use-cases.

//Order API body request
{
  "totalPaid": "90",
  "totalDiscount": "10",
  ...
  "redeemedAmount": 10,
}

For more information about redemption integration during checkout. Visit checkout Integration example.

We will calculate the redeemedAmount, totalPrice and totalDiscount attributes after the customer redeem his point and pass it to the Order API body request, if the user completed the purchase, the order API will be called with the updated attributes we mentioned.

It is your responsibility to calculate the redeemedAmount, totalPrice and totalDiscount attribute and pass it to Order API request body.

holding points till checkout completes successfully

Holding customer's points before redemption is a use-case some businesses might need, a real life for example for this is Credit Card Authorization Hold, it is a temporary hold placed on a credit or debit card to verify that there is enough available credit. Same goes for points holding, points are hold for a temporary time till you release them after checkout is completed.

Once the checkout is completed, you can release your hold customer points and they will be deducted from his points balance.

A famous example for holding points use-case is Airline businesses, they holds passenger's points after redeeming it instead of directly deducting them from passenger's points balance as a pre-cautionary measure till checkout is completely successfully, which guarantees they are not deducted from customer's pointsBalance.

For that case and other similar cases, it’s preferable to hold the needed points for redemption before proceeding to place the order.

The process starts when your customer tries to redeem his points, you will call Hold API instead of calling Order API to hold customer points and not directly deduct them from his pointsBalance.

1. You should send with Hold API the following request body

{
   ....
   "amount":98.89,
   ....
}

Amount is the equivalent monetary value of the number of points your customer tried to redeem, so make sure you calculate the monetary value of the points before redeeming them.

Hold API will returns the following response :

{
   ....
   "holdReference":"ref_12343ds"
}

The holdReference is the reference ID that will be used when you want to release the hold on points and actually redeem them.

You should store holdReference as you will need it later to release the hold-on points and redeem them successfully.

1. If your customer successfully completed the order and redeemedAmount is successfully deducted from totalPaid, then you will need to release the hold-on points by passing holdReference Id and call the Order API with passing the following request body :

{
  ...
  "redeemedAmount": null,
  "holdReference": "ref_12343ds",
  ...
}

After calling Hold API, the points will be hold for 10 minutes and if it was not released manually by you, the points will return to the customers points balance.

Important operations to consider

A. Reverse Transaction

Sometimes, you will need to cancel a cashback transaction, or to refund the redeemed points transaction, follow the below steps:

1. While you are creating a payment reward or points redemption transaction, you will store the original transaction ID of your system on Gameball

2. You can reverse the cashback reward/points redemption transactions through Reverse Points Transactions API

B. Reverse Hold Transaction

You might need to reverse the held points during the 10 mins hold time. Follow the below steps:

1. While holding points, a hold reference ID will be created for this hold transaction

2. You can reverse the held points through Reverse Hold Transaction API

use-case: redeem points at a custom redemption page

If you want to create a page on your online website/app and uses the Redeem instead of redeeming points directly at checkout page. You can use the Redeem API to redeem points from the customer's wallet balance and create discount coupons on your system equivalent to the redeemed amount.

{
   .....
   "amount":100,
   .....
}

The Amount attribute is the monetary equivalent of your points in your system currency to be redeemed, so if .

Please note that you can use the same flow of holding points and redeeming them using Redeem API.