Before you begin, from your Viral Loops account, create and configure your e-Commerce Referral campaign. You will need: 

  • The campaign ID
  • The API token 

You will find both of these in the Installation step of your campaign wizard in Viral Loops. 

Installing the Javascript snippet

Add the Javascript snippet for your campaign near the closing <body> tag in every page of your platform where you want the e-Commerce widget to appear. If unsure what this means, add it to every page of your platform. This is it:

<script>!function(){var a=window.VL=window.VL||{};return a.instances=a.instances||{},a.invoked?void(window.console&&console.error&&console.error("VL snippet loaded twice.")):(a.invoked=!0,void(a.load=function(b,c,d){var e={};e.publicToken=b,e.config=c||{};var f=document.createElement("script");f.type="text/javascript",f.id="vrlps-js",f.defer=!0,f.src="https://app.viral-loops.com/client/vl/vl.min.js";var g=document.getElementsByTagName("script")[0];return g.parentNode.insertBefore(f,g),f.onload=function(){a.setup(e),a.instances[b]=e},e.identify=e.identify||function(a,b){e.afterLoad={identify:{userData:a,cb:b}}},e.pendingEvents=[],e.track=e.track||function(a,b){e.pendingEvents.push({event:a,cb:b})},e.pendingHooks=[],e.addHook=e.addHook||function(a,b){e.pendingHooks.push({name:a,cb:b})},e.$=e.$||function(a){e.pendingHooks.push({name:"ready",cb:a})},e}))}();var campaign=VL.load("CAMPAIGN_ID",{autoLoadWidgets:!0});campaign.addHook("boot",function(){campaign.widgets.create("rewardingWidget",{container:"body",position:"bottom-left"}),campaign.widgets.create("rewardingWidgetTrigger",{container:"body",position:"bottom-left"})});</script>

Take care to replace the CAMPAIGN_ID with your own campaign ID. Furthermore, you can also set where the widget will appear by replacing the relevant parts of the snippet. Possible options: "bottom-left", "bottom-right", "top-left", "top-right".

Identifying the user on the client side 

At every login or sign-up and on every page, check if there is an active logged in user and then execute the following Javascript:

campaign.identify({
  firstname: "Michael",
  lastname: "Bolton",
  email: "michael@initech.com",
  createdAt: 1315060510 //the createdAt of the user as a timestamp(integer)
});

replacing with the relevant details for your user.
 

Identifying the user on the server side

The first time the user lands on the website you should save the referrer’s referralCode in SESSION or a cookie so you can access it later in the backend calls. The referrer's referralCode appears as a parameter in the URL, like so:

?referralCode=abc123

If you can't or don't want to run Javascript in the user's client, then on login or sign-up, do the following API call:

POST https://app.viral-loops.com/api/v2/events
Content-type: “application/json”

Example request:
{
  "apiToken": "API-TOKEN"
  "params": {
    "event": "action",
    "user": {
       "firstname": "Michael",
       "lastname": "Bolton",
       "email": "michael@initech.com",
    },
    "referrer": {
         "referralCode": "the referrer’s code you captured"
    }
  }
}

This submits the new user to Viral Loops and responds with any coupons that should be created. For example, if the new user was inviteed (and you submitted the referral code for their referrer in the API call above) then, according to the campaign settings, they might be eligible for a welcome discount from your store so you should create the relevant coupon for them. 

Example response: 

{
  "eventId": "evt_YmNkYTFmNDI4ZmU0MWY5M2Q3ODg",
  "rewards": [
    {
      "user": {
        "firstname": "abc",
        "lastname": "abc",
        "email": "email@email.gr",
        "referralCode": "SJLJFQ8ye"
      },
      "id": "reward_NjAwNGZmZDFiYmZhMWEyOWRhNTg",
      "coupon": {
        "name": "aUniqueCouponName",
        "value": 5,
        "type": "amount/percentage",
      }
    }  
  ]
}

If the previous call was successful, there will be an eventId in the response.

If there is no eventId, there will be a status like “user already rewarded” or “user has no referrer”, or “user has already made an action”. If so, the user can’t be rewarded, isn't eligible for a discount coupon.

The previous call also returns if any new rewards were created (rewards array can also be empty, so you need to handle that).

If there are new rewards, then in the response you will find information about the coupons that need to be created: name, value, type. 

GDPR consent

If you want to capture GDPR consent as well, use the following:

{

    "apiToken":"MY_TOKEN",

    "params":{

        "event":"registration",

        "user":{

            "firstname": "the user's firstname",

            "lastname": "the user's lastname",

            "email":"the user's email",

            "extraData": { "internalID": "1234" },

            "consents": {

              "2": true // 2 is the ID of the consent.

            }

        },

        "referrer":{

            "referralCode": "the referrer's referralCode (if available)"

        },

        "refSource": "the refSource (if available)"

    }

}

Consent ID

GDPR consents can be added and enabled in the Settings page of the app. The consent ID is displayed here:

Using this info you need to create the e-Commerce coupon codes needed in your platform, adding to them any restrictions you want to apply, eg. redeemable only by a specific person, for specific purchases etc. 

All the rewards also have a rewardId. It must be saved and associated with the releavant coupon so that you can use it later to mark a reward as redeemed.

After a successful payment

When a client pays, you need to do the following API call.

POST https://app.viral-loops.com/api/v2/eventsContent-type: “application/json”

Example request:

{
  "apiToken": "MySecretT0ken(from settings)"
  "params": {
    "event": "order",
    "user": {
       "referralCode": "abc123(the referralCode of the user that made the order)",
       "email": "dimitris@viral-loops.com"
    },
    "amount": 50 (the order total amount, integer or float)
  }
}

Example response: 

{
  "eventId": "evt_YmNkYTFmNDI4ZmU0MWY5M2Q3ODg",
  "rewards": [
    {
      "user": {
        "firstname": "abc",
        "lastname": "abc",
        "email": "email@email.gr",
        "referralCode": "SJLJFQ8ye"
      },
      "id": "reward_NjAwNGZmZDFiYmZhMWEyOWRhNTg",
      "coupon": {
        "name": "aUniqueCouponName",
        "value": 5,
        "type": "amount/percentage",
      }
    }  
  ]
}

This tracks the latest purchase (conversion) to Viral Loops which means that, according to the campaign settings, rewards will be created for the referrer of the new customer and / or the new customer too. 

In the request, you can either use the new customer's referral code or email to track the order.

If the previous call was successful, there will be an eventId in the response, like so:

{
  "eventId": "evt_MWTAwYjYzZEyOTkzZjlmNDQ3OTU",
  "rewards": [
    {
      "user": {
        "firstname": "",
        "lastname": "",
        "email": "dimitris@viral-loops.com",
        "referralCode": "fXe23E2"
      },
      "id": "reward_Y2M2OWQ5MjdhGY2ZGUyYMGFmMjY",
      "coupon": {
        "name": "WHWLNEF",
        "value": 20,
        "type": "percentage",
        "settings": {
          "minimumOrderTotal": 0,
          "useInShipping": 1,
          "totalUses": 1
        }
      }
    }
  ]
}


If there is no eventId there will be a status like “user already rewarded” or “user has no referrer” in which case you should not create any discount coupon codes to reward any customers. 

The response "User has no referrer" indicates that the user that just made the purchase was not referred by someone else so no-one needs to be rewarded for this conversion. 

If there was a referrer then the previous API call also returns any new pending rewards that were created from this order (rewards array can also be empty, so you need to handle that).

If there are new rewards then in the response you will find information about the coupons that need to be created: name, value, type. 

Using this info you need to create the e-Commerce coupon codes needed, adding to them any restrictions you want to apply, eg. redeemable only by a specific person, for specific purchases etc. 

As before, all the rewards also have a rewardId. It must be saved and associated with the releavant coupon so that you can use it later to mark a reward as redeemed.

On Logout

Run the following Javascript:

campaign.$(function() {
  campaign.logout({reloadWidgets: true});
});

Make sure this is placed after the campaign Javascript snippet.

Marking a coupon as redeemed

If a coupon code was used for the payment, the following API call must be run from the server to mark the reward as redeemed, if this was a coupon code that had been provided through the referral campaign (there might be other coupons present as well, not from the Viral Loops campaign).

POST https://app.viral-loops.com/api/v2/rewarded
Content-type: “application/json”

Example request:

{
  "rewardId": "reward_NjAwNGZmZDFiYmZhMWEyOWRhNTg (a rewardId you saved, for that coupon)",
  "apiToken": "MySecretT0ken(from settings)"
}

Example response:

{
  "redeemed": {
    "total": 1,
    "rewards": [
      "reward_NjAwNGZmZDFiYmZhMWEyOWRhNTg"
    ]
  }
}

Checking for pending rewards

After a successful payment the API returns the coupons you need to create for the referrer and invitee. However, if you need to see these coupons again, use the API to check for pending rewards and create them:

method	: GET
endpoint: https://app.viral-loops.com/api/v2/pending_rewards
headers: "Content-Type: application/json"

Example request:

https://app.viral-loops.com/api/v2/pending_rewards?apiToken=MySecretToken&user={"email":"zisis@viral-loops.com"}&filter={"limit":10,"skip":25}
  • Replace MySecretToken with your API Token. Find it in the Installation step of your Campaign Wizard.
  • The filter object is optional. It can be used for pagination using limit (default=25, max=25) and skip (default=0).
  • The user object is optional. If provided, only rewards for that specific user will be returned (pagination rules apply here as well). The user object needs the email or referralCode of the user.

Here's an example response to a request without filters:

{
  "pending": [
    {
     "user": {
"firstname": "Zisis",
"lastname": "",
"email": "zisis@viral-loops.com",
"referralCode": "SkuVQmS9W",
"referralCountTotal": 1,
"risk": 0
      },
      "rewards": [
        {
          "id": "reward_MzdjN4NjQxNmZkNjQ1MDYzM4NDc",
          "coupon": {
            "name": "BDVLQJ0",
            "value": 50,
            "type": "amount",
            "settings": {
              "minimumOrderTotal": 0,
              "useInShipping": 1,
              "totalUses": 1
            },
            "currencySymbol": "$",
            "currencySymbolPosition": "before"
          }
        }
      ]
    },
    ...
  ]
}

And that's all. 

Do you need more help? Let us know!

Did this answer your question?