Welcome to Refermo! This page will show you the steps needed to integrate Refermo into your app, so that you can start recording referrals and conversions and rewarding your referrers.

Once the two systems talk to eachother, you can also query any data in Refermo over the API, so you can show referral information like total referrals and credit received to your users inside your app.

Step 1: Set up Refermo

Sign up to Refermo

Sign up with your email address and create an account in Refermo.

You will need to add your credit card details when creating a new account. You will have a free 14 day trial on the "Starter" plan, which costs $9/month + 8% fees.

Create a campaign

Now you'll need to create a campaign in Refermo. A campaign is a set of rules and rewards for your referral programme.

On the Small, Regular and Unlimited plans you can multiple campaigns to offer different sets of rewards for different groups of members in your referral programme.

Add your Paddle API credentials into Refermo

To connect Refermo to your app, you need to create a new API key in Paddle and paste it in your Refermo settings.

Go to Developer tools > Authentication and create a new API key from the form.

Then click "Reveal Auth Code" for the API key you just created and copy the code. Paste this plus the vendor ID at the top of the page into your Settings page in Refermo.

Step 2: Set up webhooks in Paddle

In order for Refermo to be able to read the transaction information from your Paddle-powered subscriptions, you need to have webhooks set up.

In Paddle, go to Developer tools > Alerts / Webhooks and make sure the the following events have "Webhook" turned on:

  • Subscription Created
  • Subscription Updated
  • Subscription Cancelled
  • Subscription Payment Success
  • Subscription Payment Refunded

Paddle only allows one webhook URL, and it's fine if you already have webhooks set up sending data to your app.

If you already have Paddle's webhooks set up in your app, just make sure that the events listed above are checked. You do not need to do anything else.

If you do not already have Paddle's webhooks set up in your app, make sure you use the Refermo webhook URL from your Settings page and paste it into the "URL for receiving webhook alerts" field in the same Alerts / Webhooks page in Paddle, and click Save.

Important
Refermo will only work if you have webhooks set up for the events listed above, plus a working webhook URL.

Step 3: Record referrals from your site

Add the JS library to your site

The easiest way to record new sign ups and referral conversions from your app is to use Refermo's JavaScript library. You can then make some quick calls to track these referral events in Refermo.

Read how to use the Refermo Javascript API

It's important to stay compliant with the EU cookie regulations, which state that you must request permission to create cookies in visitors' browsers.

Refermo makes asking for permission very simple. You just need to create an HTML element with the id refermo-notice and a cookie message will be displayed to all EU-based visitors before any referral cookies are created. For all other visitors, cookies are created immediately and the HTML element removed.

Read more about the cookie notice

Record new signups and conversions

You should tell Refermo every time a new user signs up to your app after visiting a referral link.

You can do this with the JavaScript API:

var referral = await Refermo.signup("user123")

You could then store referral["id"] on your user123 user object. This is the referral ID from Refermo and can be used to get data about a referral in the future using the API.

You should also tell Refermo when a referred user starts a paying subscription, so that your referrers start getting rewards. This is called a referral "conversion".

You can do this with the JavaScript API using a Paddle checkout ID:

Refermo.conversion("user123", data.eventData.checkout.id)

or with the API (TBC):

POST https://api.refermo.co/v1/referrals/[id]/conversion/
{
    "subscription_id": 183639
}

Show coupons to new users (double-sided rewards)

If you have double-sided rewards active, your referred users will have a Paddle coupon code they can use to get a discount when they start a new plan.

The discount code is returned in the Refermo.signup() call, or you can get it at any time from Referrals API endpoint (search by user identifier). You should store this coupon code in your app.

When the user visits your billing pages, you can then display the discount code and offer to them.

Using Paddle's checkout parameters, you can even add the discount automatically to their checkout.

Step 4: Use the API to get data in and out of Refermo

Add existing users as members in bulk

You may already have users of your app that you'd like to upload into Refermo as referrers (members).

You can use the API to run through your users and add them one by one in Refermo, and save their referral code locally.

Here's an example in Python/Django:

import requests

for user in User.objects.all():
    url = "https://api.refermo.co/v1/members/"
    
    headers = {
    	"Authorization": "Bearer YOUR_API_KEY"
    }
    
    payload = {
        "identifier": "98729473294", // unique ID in your app
        "email": "dan@danrowden.com" // email address
        "campaign: {
            "id": "YOUR_REFERMO_CAMPAIGN_ID"
        }
    }
    
    response = requests.post(url, json=payload, headers=headers)
    
    user.referral_code = response["code"]
    user.refermo_id = response["id"]
    user.save()

Simply loop your user objects and send a POST request to the members endpoint.

Here's an example response.

Then save the id and code values in your app so you can a) request or update the referrer's data at any time in the future, and b) display each user's referral code to them in your app.

Note: Referral links are always yourdomain.com/?via=CODE

Access affiliate data from your app

Now that you have the two systems talking to eachother, you can grab any data you need from Refermo into your app.

Maybe you want to get the latest status of a referral, pull in a list of your Paddle subscriptions or manage campaign rewards from your app.

All this can be done using Refermo's API.

Referrals will be generated when users a) visit referral links b) on pages which have the Refermo JavaScript API.

Referral links are in the format yourdomain.com/?via=CODE

You can append the code on any URL on your site:

  • yourdomain.com/?via=CODE
  • yourdomain/blog/?via=CODE
  • yourdomain/blog/post/?via=CODE

As long as the JavaScript file is loading on the page, you can record signups.