Implementing a Free Products Module on a Custom or Generic Platform

      Implementing a Free Products Module on a Custom or Generic Platform

        Article Summary


        Loyalty & Referrals
        Supported plans

        Premium, Enterprise

        eCommerce 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.
        Settings overview
        • Variant ID - Enter the Product ID or the Product Variant ID. This value must match the product ID in the order data sent to Yotpo.
        • Product Value in Cents - This value is added to the “Total Investment” calculation in the ROI Dashboard.
        • Name - The name of the redeemable product.
        • How many points does this coupon cost? - The number of points shoppers will need to redeem to receive the product.
        • What should we display to the user for the cost of this coupon? - The point value of the product as it is displayed to the shopper.
        • Icon - The font awesome icon that will be displayed on-site.
        • Coupon Code "Intro" - The message that will be displayed above the coupon code after the shopper decides to redeem the points.
        1. 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:

        Customer Identification

        In order to supply the relevant shopper with a free product, it is necessary to identify them at the login point.

        This identification step should be added to your platform as part of the custom or generic integration with Yotpo.

        To make sure everything is set up correctly, please view the Identifying Customers section in our Generic integration article.

        Providing Cart Data

        The cart data code is required for using the following features on a custom or generic eCommerce platform:

        The data parameter data-free-product-points should contain the updated points value of the free products that are currently in the customer’s cart.

        This allows the Module to recognize how many points the customer still has left to redeem.

        To fully implement the Free Product Module, we must make sure to add the cart data code above the module code on every page where the module is implemented.

        • Example of a cart data div:


        Implementing the module

        The Module can be set up in two ways:

        yotpo free product redemption

        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


        message = {
         guid: 'Vgac_4JUiNaTECxpLCt3zg',
         api_key: '35wqrYQDbvkOfasK17HxMQtt',
         cart_id: 123456,
         variant_id: 222,
         customer_email: '',
         point_redemption_id: 243
        digest ='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":"","point_redemption_id":243}

        Please make sure you don't have any extra spaces between the code elements.

        In this case, the token result would be:


        For security reasons, make sure not to expose the API key externally!

        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:

        Please note:
        If at any point there is an issue with adding the product to the cart and/or reducing the price to zero, the promise needs to return a false value and the redemption will not succeed.

        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:


        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.

        Please note:
        Make sure that the total value of the order does not include the free product's price, and the free product’s price should be set to $0.

        Was this article helpful?