This Javascript API helps you integrate with Refermo from the client side. Simply add Refermo's 2KB JS script then use two simple calls, and you can start tracking referrals from your app.

The REST API is available for getting data from Refermo into your app, or programatically managing your referral programme.

Add Refermo's JavaScript library

Make sure you add Refermo's JS library to your page. You can grab this code—with the correct account ID—from the API settings page in Refermo.

<script src="https://cdn.refermo.co/refermo.js" data-account="YOUR_ACCOUNT_ID" defer></script>

Important: If you're adding the script to a site that isn't on your root domain (like docs.yoursite.com), make sure you add your root domain to the script, like this:

<script src="https://cdn.refermo.co/refermo.js" data-account="YOUR_ACCOUNT_ID" data-domain="yoursite.com" defer></script>

This is so that Refermo can set and track cookies across all of your domains.

To stay compliant with EU privacy guidelines and GDPR, you need to show a cookie notice to all EU-based visitors to your site. Refermo uses a cookie to track each referral and conversion.

Refermo makes it very easy to display a cookie notice to the relevant visitors. ALl you need to do is add a simple HTML element to the marketing pages that you will send referral links to.

Simply adding

<div id="refermo-notice"><div>

will create a notice like this on your site (but with your campaign's custom reward details):

This is an important step in your integration. If you do not add this notice, EU-based visitors will never be able to convert as referrals.

Read more about the cookie notice and how to customise it

Record referrals

When a new user creates an account on your site, you should record this in Refermo, to track all referral signups.

All you need to provide is the user's unique email, username or ID from your system. Make sure you use something that won't change in the future.

You should do this for every sign up, to make sure you catch all valid referrals. It doesn't matter if you send every single sign up to Refermo; the system will only save users who signed up after visiting a referral link.

<script type="text/javascript">
  // Use the user's unique email, username or ID from your app
  var referral = await Refermo.signup("user123")
</script>

referral will contain JSON with two values, which you should store in your app's user record.

{
    "id": "65a76d04a0e11aa69cb837f7b7528662",
    "coupon_code": "D50E9F38"
}
  • id is the ID of the referral (32 chars), which you can store on your user in the app if you ever want to get or update this referral in the future over the API.
  • If your campaign offers double-sided rewards, coupon_code (typically 8 chars, max 100 chars) will be the coupon code the user can use at checkout when they sign up to a plan. This will apply a discount on their initial payment. You can apply the code automatically using Paddle's Checkout Parameters. If your campaign does not offer a reward to new users, coupon_code will be null.

Record conversions

When a user converts to a paying subscription, you need to record this in Refermo.

If you use Paddle's overlay checkout, you can add a simple callback, which will send data to Refermo after each successful checkout.

You may have something like this in your front-end:

<script src="https://cdn.paddle.com/paddle/paddle.js"></script>
<script type="text/javascript">
  Paddle.Setup({ vendor: 123456789 });
</script>

All you need to do is add a callback which calls Refermo.conversion() after Paddle's Checkout.Complete event.

Make sure you use exactly the same user identifier as in the signup() call above.

<script src="https://cdn.refermo.co/refermo.js" data-account="002a650c" defer></script>
<script src="https://cdn.paddle.com/paddle/paddle.js"></script>
<script type="text/javascript">
  // The user's unique email, username or ID from your app
  let userId = "user123"
  Paddle.Setup({
    vendor: 123456789,
    eventCallback: function(data) {
      if (data.event === 'Checkout.Complete') {
        Refermo.conversion(userId, data.eventData.checkout.id)
      }
    }
  });
</script>

If a valid referral is found in Refermo, it will be assigned the subscription and marked as converted. Your referrer will get a reward, based on your campaign settings.

Record conversions without signup()

In some instances, your sign-ups cannot be tracked easily and you can only record referrals when the user signs up to a plan (at the point of conversion).

It is possible to skip using Refermo.signup() and simply call Refermo.conversion() when users start a paid plan.

In this case, you can use the email address from the Paddle checkout as the user identifier.

<script src="https://cdn.refermo.co/refermo.js" data-account="002a650c" defer></script>
<script src="https://cdn.paddle.com/paddle/paddle.js"></script>
<script type="text/javascript">
  Paddle.Setup({
    vendor: 123456789,
    eventCallback: function(data) {
      if (data.event === 'Checkout.Complete') {
        Refermo.conversion(data.eventData.user.email, data.eventData.checkout.id)
      }
    }
  });
</script>