Implementing a Free Products Module on a Custom or Generic Platform

The Free Product Module allows your customers to exchange their loyalty points for awesome products.

To add the module to your generic or custom eCommerce platform, follow these steps:

1. Creating Free Product coupons in your Loyalty & Referrals admin
2. Setting up the Free Products On-site Module
3. Adding free products to the shopper’s cart
4. Sending Yotpo the free product coupon with the order data

Let’s look at each step individually and see how to set it up.

Step 1: Creating Free Product coupons in your Loyalty & Referrals admin

1. In Yotpo Loyalty & Referrals admin, go to Set Up Program > Rewards.
2. Click on Create a New Coupon.
3. Select the Free Product coupon type from the dropdown menu.
4. Configure the coupon settings as needed.

5. Click the Save Coupon button

Step 2: Setting up the Free Products On-site Module

Before implementing the module on your site, we need to make sure that the Loyalty program is set up correctly and that the following data is sent to Yotpo:

Implementing the module

The Module can be set up in two ways:

• Create a rewards page using the Rewards Page Builder and add the free products section to the rewards page (recommended).

• Create a standalone Free Products module instance.

Simply click the option you wish to implement and follow the implementation guide.

Step 3: Adding free products to the shopper’s cart

The next step is for the customer to redeem points for a free product and have that product added to their cart with a $0 price tag.

This step consists of two parts: 

A. Verification of the redemption process between the shop and Yotpo to ensure this is not a fraudulent action.

B. Adding the product to the shopper’s cart and reducing its price to zero.

For these steps to happen smoothly and securely, you first need to implement the onProductRedemption function:

Implementing onProductRedemption function

The onProductRedemption function must be added to your storefront so that Yotpo will call on it once a redemption occurs. This function allows both Yotpo and your store to verify the exchange.

Since product addition and price reduction happen on the store’s side, Yotpo needs to receive a response that signals whether this process was successful or not.

For this reason, the onProductRedemption function should return a Boolean value from a promise - instead of immediately returning the final value, the asynchronous method returns a promise to supply the value at some point in the future, when the process fails/completes.

There are two possible values the promise can eventually return:

• false - The process may fail due to unsuccessful verification or if the product was not added to the shopper’s cart correctly. In this case, the promise must return a false value and fail the process. This means that no redemption will occur and the shopper will see an error message:

• true - If the verification process was successful and the item was added to the shopper’s cart and its price reduced to zero, the promise object will return a true value and the redemption will be completed.

The function should be implemented with the following signature:

async function onProductRedemption(data)

The parameter data will have the following data structure automatically from the module:

data = {
"id": "243",
"rewardText": "624Y387G",
"token": "11IYUp3FcymYJKYCvl32wQmbBCA",
"variantId": "222",
"costInPoints": "100"
}

Function Details:

• id - This value is used as the point_redemption_id value as part of the token construction.
• rewardText - The coupon code generated by the Loyalty & Referrals admin. This field will be sent out as the coupon code to Yotpo as part of the order so we know that we can deduct the points.
• token - Used to authenticate the redemption
• variantId - The product ID. This should match the Variant ID field you entered when creating the Free Product coupon.
• costInPoints - The number of points redeemed by the customer in exchange for the free product. This value will match the points value in the coupon settings of your Loyalty admin.

A. Verification

Constructing the token

The token authentication step is essential in establishing that this discount information is shared across two specific sources: your site and Yotpo. No foreign or irrelevant party is able to access the information as they will not be able to confirm the token authentication.

The token must be constructed as the SHA256 hash and The Secret Key input of the HMAC should be the account’s API Key.

The hash must consist of the following parameters:

• GUID - This value can be found in your Loyalty & Referrals admin under Settings
• API key - This value can be found in your Loyalty & Referrals admin under Settings.
• Cart ID - This is the cart-id date that is populated in the cart data code.
• Variant ID - This is the variant ID that Yotpo Loyalty & Referrals sends with the redemption call. It must match the Variant ID you inserted in the Free Product coupon settings
• Customer email - This is the email that is populated in the customer identification div
• Point redemption ID - This is the ID that Loyalty & Referrals sends with the redemption call

Example

message = {
 guid: 'Vgac_4JUiNaTECxpLCt3zg',
 api_key: '35wqrYQDbvkOfasK17HxMQtt',
 cart_id: 123456,
 variant_id: 222,
 customer_email: 'example@gmail.com',
 point_redemption_id: 243
}
digest = OpenSSL::Digest.new('sha256')
OpenSSL::HMAC.hexdigest(digest, '35wqrYQDbvkOfasK17HxMQtt', message.to_json)

In this example, converting to JSON will result in this string:{"guid":"Vgac_4JUiNaTECxpLCt3zg","api_key":"35wqrYQDbvkOfasK17HxMQtt","cart_id":"123456","variant_id":"222","customer_email":"example@gmail.com","point_redemption_id":243}

In this case, the token result would be:

5b63ffaea1ef674f75907e4e50cd7ef22e96a51eeb1b4f158d5f99c332ea5d76

The constructed token must then be compared to the token sent from Yotpo. The redemption process should only continue if the tokens match.

B. Adding the product to the cart

You will need to implement a process that adds the product to the shopper’s cart and changes the price of the product to zero.

Once this process is completed successfully, the Promise’s value should be updated to true and the module will show the product as added:

The cart data-div must also be updated so that we will know how many points the shoppers have at their disposal to make additional redemptions. This also applies to when a shopper decided to remove a free product and now has more redeemable points at their disposal.

The cart div must reflect the shopper's current point balance within the cart.

Example of a cart data div:

<div 
id="yotpo-loyalty-cart-data" 
data-free-product-points="100" 
data-cart-currency=”USD”
data-applied-coupon-points="100" 
data-cart-id="12345" 
data-has-paid-product="false" 
data-has-free-product="true">
</div>

Step 4: Sending Yotpo the Free Product coupon and order data

Once the shopper completes the checkout process and the order is sent to Yotpo Loyalty & Referrals, the order API call needs to include the free product coupon code - this information allows Yotpo to deduct the correct number of points from the relevant shopper’s account.

These API Calls are set up on your platform as part of the Yotpo Loyalty & Referrals integration process. If you want to verify the setup and learn more, you can view the Order Data section in our integration guide and check out the Create Order endpoint in our API documentation.