Partnero Developers

Refer-a-Friend referral program integration with REST API

This guide will walk you through the process of creating and integrating a "Refer-a-Friend" referral program within your application using Partnero.

By following the steps outlined in this guide, you will be able to set up a referral program that allows existing customers to refer friends to your application and earn rewards for successful referrals.

Here is an example of how this type of referral program can work using Partnero:

  1. A customer signs up for an account on your application and is given a unique referral code.
  2. The customer shares this referral code with their friends and family via personal referral link.
  3. When a friend signs up for an account on your application using the referral code, they are considered a referred customer.
  4. Partnero tracks the referral and attributes the signup to the referring customer.
  5. Once the referred customer makes a purchase, the referring customer earns a reward, such as a discount or credit on their account. Please note that these rules can be set up on Partnero, so you can decide when and how to reward customers.
  6. Partnero will notify you of the transaction via webhook and you can apply the rewards to the referring customer's account.

This type of referral program can be a powerful way to drive growth for your business by encouraging existing customers to promote your application to their network. Partnero makes it easy to set up and manage a referral program like this, so you can focus on growing your business.

Tracking

To accurately track referrals visiting your website or application, it is essential to install the Partnero Universal javascript snippet.

This snippet is responsible for tracking referral visits and signups on your website, and it ensures that referred signups are correctly attributed to the correct partners.

Once the referral visits your website, Partnero will add a cookie with the referral code, which can then be used to create the user account.

To integrate Partnero on your website, get the snippet from your existing program. To find the snippet, please follow these steps:

  1. Log in to Partneroopen in new window
  2. Go to Programs
  3. Choose your Program if there is more than one
  4. On the left sidebar, go to Integration under Program
  5. Copy the Partnero Universal snippet

Once you have your unique Partnero Universal javascript snippet copied, paste it into your website’s HTML just before the closing of the </head> tag.

Example of Partnero Universal

<!-- Partnero Universal -->
<script>
    (function(p,t,n,e,r,o){ p['__partnerObject']=r;function f(){
    var c={ a:arguments,q:[]};var r=this.push(c);return "number"!=typeof r?r:f.bind(c.q);}
    f.q=f.q||[];p[r]=p[r]||f.bind(f.q);p[r].q=p[r].q||f.q;o=t.createElement(n);
    var _=t.getElementsByTagName(n)[0];o.async=1;o.src=e+'?v'+(~~(new Date().getTime()/1e6));
    _.parentNode.insertBefore(o,_);})(window, document, 'script', 'https://app.partnero.com/js/universal.js', 'po');
    po('settings', 'assets_host', 'https://assets.partnero.com');
    po('program', 'PUBLIC_PROGRAM_ID', 'load');
</script>
<!-- End Partnero Universal -->

When Partnero Universal javascript snippet is added to the website and someone is visiting it with a referral URL, for example, partnero.com?ref=UNIQUE_REFERRAL_KEY the script matches the URL with Partnero's program settings and if the URL pattern matches the cookie is set partnero_referral with value UNIQUE_REFERRAL_KEY which is the main identificator of the partner (referring customer).

Creating customers

In Refer-A-Friend program each customer of your application can be both referring customer and referred customer.

Every time your application gets a new signup you need to create a customer profile at Partnero.

Creating a referring customer

Create a new customer using your sign-up data. A referring customer refers to a regular customer who signs up without being referred by anyone else.

POST https://api.partnero.com/v1/customers

Request example

{
  "id": "referring_id",
  "key": "referring_key",
  "name": "Customer",
  "email": "customer@partnero.com"
}

Request parameters

ParametersTypeRequiredDetails
idstringoptionalMain identification of the customer.
Can be anything, but we recommend using an account ID of your application. Must be unique. If not provided will be generated randomly.
keystringoptionalMain customer referral key that goes to referral url. Must be unique. If not provided will be generated randomly.
emailstringoptionalIf provided must be a unique email address.
namestringoptionalAdds a name for the customer.

Creating a referred customer

This type of customer is created when you can find partnero_referral cookie, and the customer is recognized as referred customer.

POST https://api.partnero.com/v1/customers

Request example

{
  "id": "referred_id",
  "key": "referred_key",
  "name": "Referred customer",
  "email": "referred-customer@partnero.com",
  "referring_customer": {
    "id": "referring_id",
    "key": "referring_key"
  }
}

Request parameters

ParametersTypeRequiredDetails
idstringoptionalMain identification of the customer.
Can be anything, but we recommend using an account ID of your application. Must be unique. If not provided will be generated randomly.
keystringoptionalMain customer referral key that goes to referral url. Must be unique. If not provided will be generated randomly.
emailstringoptionalIf provided must be a unique email address.
namestringoptionalAdds a name for the customer.
referring_customerobject[]no
referring_customer.idstringyes if referring_customer.key is not providedIf provided REFERRING_CUSTOMER will be searched using REFERRING_CUSTOMER_ID.
referring_customer.keystringyes if referring_customer.id is not providedIf provided REFERRING_CUSTOMER will be searched using REFERRING_CUSTOMER_KEY.

Please note: if referring_customer is not provided, customer will be created without referring customer.

"referring_customer.id" takes priority over "referring_customer.key", so if both are provided, the referring customer will be searched using "referring_customer.id".

Displaying customer data on your application

Since you can manage all programs settings on Partnero you need to show the most important information on your application. In this case it would be unique referral link which can be shared by your customer.

In order to do that you need to get partner information:

Fetch a customer

Get the details about specific partner. You need to provide either an email address or a unique key of the partner.

GET https://api.partnero.com/v1/customers/(:id)

Request parameters

ParametersTypeRequiredDetails
idstringyes *Must provide unique customer identifier.

Response example

{
  "data": {
    "email": "customer@partnero.com",
    "created_at": "2023-05-19T09:04:33.000000Z",
    "updated_at": "2023-05-19T09:04:33.000000Z",
    "name": "Customer",
    "key": "referring_customer",
    "status": "active",
    "referring_customer": null,
    "referrals_count": 1
  },
  "status": 1
}

Get customer's balance

GET https://api.partnero.com/v1/customers/(:id)/balance

Request parameters

ParametersTypeRequiredDetails
idstringyes *Must provide unique customer identifier.

Response example

{
  "data": {
    "customer": {
      "email": "gediminas@partnero.com",
      "created_at": "2023-05-19T09:04:33.000000Z",
      "updated_at": "2023-05-19T09:04:33.000000Z",
      "name": "Customer",
      "key": "referring_customer",
      "status": "active",
      "referring_customer": null,
      "referrals_count": 1
    },
    "balance": []
  },
  "status": 1
}

Displaying customer referrals

GET https://api.partnero.com/v1/customers/(:id)/referrals

Request parameters

ParametersTypeRequiredDetails
idstringyes *Must provide unique customer identifier.

Response example

{
  "data": [
    {
      "email": "referred-customer-3@partnero.com",
      "created_at": "2023-05-19T09:04:51.000000Z",
      "updated_at": "2023-05-19T09:04:51.000000Z",
      "key": "referred_customer_3",
      "name": "Referred customer",
      "status": "active"
    },
    {
      "email": "referred-customer-4@partnero.com",
      "created_at": "2023-05-19T09:15:05.000000Z",
      "updated_at": "2023-05-19T09:15:05.000000Z",
      "key": "referred_customer_4",
      "name": "Referred customer",
      "status": "active"
    }
  ],
  "status": 1
}

Creating transactions

We recommend to send each transaction (about sales) to Partnero. When any customer makes a purchase, it is recommended to create a transaction.

Creating a transaction for referral

POST https://api.partnero.com/v1/transactions

{
  "key": "invoice_1",
  "amount": 100,
  "action": "sale",
  "customer": {
    "id": "referred_id",
    "key": "referred_key"
  }
}

Crediting a customer

POST https://api.partnero.com/v1/customers/parent/balance/credit

{
  "amount": 10,
  "is_currency": true,
  // what you can credit depends on what kinda rewards you have
  "amount_units": "usd"
  // what you can credit depends on what kinda rewards you have
}