Refer-a-friend API integration

This guide walks you through integrating a refer-a-friend program using the Partnero REST API. Your existing customers share referral links with friends and earn rewards when those friends sign up or make a purchase.

Before proceeding, you should have a program created on Partnero. If you haven’t created one yet, refer to the Knowledge Base for guidance.

How it works

A customer signs up on your site and receives a unique referral link from Partnero
They share the link with friends
When a friend visits via the link, PartneroJS stores the referrer’s key in a partnero_referral cookie
When the friend signs up, your backend reads the cookie and sends it to Partnero to link them as a referred customer
When the referred customer makes a purchase, your backend records the transaction
The referring customer earns a reward

Step 1: Install PartneroJS

PartneroJS tracks referral visits by reading the referrer’s key from the URL and storing it in a first-party cookie. This cookie is what your backend reads later during sign-up.

Get your snippet

Log in to Partnero
Go to Programs and select your program
Navigate to Integration in the sidebar
Copy the PartneroJS snippet

Install the snippet

Paste the snippet into your website’s HTML just before the closing </head> tag:

<!-- PartneroJS -->
<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 PartneroJS -->

When a visitor arrives via a referral URL (e.g., yoursite.com?ref=REFERRAL_KEY), the script creates a partnero_referral cookie containing the referrer’s key.

Step 2: Track sign-ups

In a refer-a-friend program, every customer should be created in Partnero—both referrers and referred customers. The only difference is whether you include a referring_customer field.

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

How to get the referral key

The partnero_referral cookie is set by PartneroJS when a visitor arrives via a referral link. Read it on your server:

Node.js / Express
PHP / Laravel
Python / Django
Ruby on Rails

const referralKey = req.cookies['partnero_referral'];

$referralKey = $request->cookie('partnero_referral');

referral_key = request.COOKIES.get('partnero_referral')

referral_key = cookies[:partnero_referral]

Create a customer

Send a POST /v1/customers call for every sign-up. If the partnero_referral cookie exists, include it as referring_customer.key. If it doesn’t, omit the referring_customer field—the customer is still created and can share their own referral link.

With referral (referred customer)
Without referral (new referrer)

curl --location 'https://api.partnero.com/v1/customers' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "referring_customer": {
      "key": "REFERRAL_KEY_FROM_COOKIE"
    },
    "key": "customer_456",
    "email": "[email protected]",
    "name": "Bob"
  }'

curl --location 'https://api.partnero.com/v1/customers' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "key": "customer_123",
    "email": "[email protected]",
    "name": "Alice"
  }'

Request body

Parameter	Type	Required	Description
`key`	string	No	Unique customer identifier (auto-generated if not provided)
`id`	string	No	Alternative customer identifier
`email`	string	No	Customer’s email address
`name`	string	No	Customer’s first name
`surname`	string	No	Customer’s last name
`metadata.date_of_birth`	string	No	Date of birth (format: `YYYY-MM-DD`)
`referring_customer.key`	string	No*	Referrer’s key from `partnero_referral` cookie
`referring_customer.id`	string	No*	Referrer’s ID (alternative to key)

*If referring_customer is provided, at least one of referring_customer.key or referring_customer.id is required.

Response

The response includes the customer’s referral link, which you can display in your UI:

{
  "data": {
    "id": "customer_123",
    "email": "[email protected]",
    "name": "Alice",
    "surname": null,
    "status": "active",
    "approved": true,
    "referring_customer": null,
    "referrals_count": 0,
    "referral_link": "https://yoursite.com?ref=customer_123",
    "referral_links": ["https://yoursite.com?ref=customer_123"],
    "metadata": {
      "date_of_birth": null
    },
    "created_at": "2025-05-09T17:42:13.000000Z",
    "updated_at": "2025-05-09T17:42:13.000000Z"
  },
  "status": 1
}

Step 3: Track sales

When a referred customer makes a purchase, record the transaction so Partnero can calculate rewards for the referring customer.

Prefer automatic tracking? If you use Stripe, Paddle, or Chargebee, transactions are tracked automatically through Partnero’s integrations—no API call needed. Set up integrations in Program settings → Integrations.

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

curl --location 'https://api.partnero.com/v1/transactions' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "customer": {
      "key": "customer_456"
    },
    "key": "invoice_123",
    "amount": 100,
    "action": "sale"
  }'

Request body

Parameter	Type	Required	Description
`customer.key`	string	Yes	The customer identifier (the person who made the purchase)
`key`	string	Yes	Unique transaction ID (use your invoice/order ID for refund handling)
`amount`	number	Yes	Transaction amount
`action`	string	Yes	Transaction type (e.g., `sale`)

Multiple transactions

Send multiple transactions for the same customer in a single request:

curl --location 'https://api.partnero.com/v1/transactions' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "customer": {
      "key": "customer_456"
    },
    "transactions": [
      {
        "key": "invoice_123",
        "amount": 100,
        "action": "sale"
      },
      {
        "key": "invoice_456",
        "amount": 200,
        "action": "sale"
      }
    ]
  }'

Step 4: Display referral data

Show customers their referral link, stats, and rewards in your application. Fetch this data from your backend using the Partnero API.

Get customer details and referral link

curl --location 'https://api.partnero.com/v1/customers/customer_123' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Use the referral_link from the response to display a “Share your link” section in your app.

Get referral stats

curl --location 'https://api.partnero.com/v1/customers/customer_123/stats' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Returns click counts, referral counts, and social sharing links.

Get reward balance

curl --location 'https://api.partnero.com/v1/customers/customer_123/balance' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Returns the customer’s accumulated rewards.

Get referred friends

curl --location 'https://api.partnero.com/v1/customers/customer_123/referrals' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Returns a list of customers who signed up via this customer’s referral link.

Step 5: Credit rewards

If your reward configuration requires manual crediting, add credit to a referring customer’s balance:

curl --location 'https://api.partnero.com/v1/customers/customer_123/balance/credit' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 10,
    "is_currency": true,
    "amount_units": "usd"
  }'

Parameter	Type	Required	Description
`amount`	number	Yes	Credit amount
`amount_units`	string	Yes	Currency code (e.g., `usd`)
`is_currency`	boolean	Yes	Whether the amount is monetary

If rewards are configured to be applied automatically in your program settings, you don’t need to call this endpoint manually.

Complete integration example

Here’s the full flow in a Node.js/Express backend:

const express = require('express');
const cookieParser = require('cookie-parser');
const app = express();

app.use(cookieParser());
app.use(express.json());

const PARTNERO_API_KEY = process.env.PARTNERO_API_KEY;

// After user signs up
app.post('/signup', async (req, res) => {
  const { email, name, password } = req.body;
  
  // 1. Create user in your database
  const user = await createUser({ email, name, password });
  
  // 2. Create customer in Partnero (safe to call for every sign-up)
  const referralKey = req.cookies['partnero_referral'];
  
  const body = {
    key: user.id,
    email: user.email,
    name: user.name
  };
  
  // Only include referring_customer if a referral cookie exists
  if (referralKey) {
    body.referring_customer = { key: referralKey };
  }
  
  const response = await fetch('https://api.partnero.com/v1/customers', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${PARTNERO_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(body)
  });
  
  const data = await response.json();
  
  // 3. Store the referral link for the user's dashboard
  await saveReferralLink(user.id, data.data.referral_link);
  
  res.json({ success: true });
});

// After a purchase
app.post('/purchase', async (req, res) => {
  const { userId, orderId, amount } = req.body;
  
  // 1. Process the payment
  const order = await processPayment({ userId, orderId, amount });
  
  // 2. Record in Partnero
  await fetch('https://api.partnero.com/v1/transactions', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${PARTNERO_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      customer: { key: userId },
      key: orderId,
      amount: amount,
      action: 'sale'
    })
  });

  res.json({ success: true });
});

// Referral dashboard
app.get('/referrals', async (req, res) => {
  const userId = req.user.id;
  
  const [stats, balance, referrals] = await Promise.all([
    fetch(`https://api.partnero.com/v1/customers/${userId}/stats`, {
      headers: { 'Authorization': `Bearer ${PARTNERO_API_KEY}` }
    }).then(r => r.json()),
    fetch(`https://api.partnero.com/v1/customers/${userId}/balance`, {
      headers: { 'Authorization': `Bearer ${PARTNERO_API_KEY}` }
    }).then(r => r.json()),
    fetch(`https://api.partnero.com/v1/customers/${userId}/referrals`, {
      headers: { 'Authorization': `Bearer ${PARTNERO_API_KEY}` }
    }).then(r => r.json())
  ]);
  
  res.json({ stats: stats.data, balance: balance.data, referrals: referrals.data });
});

Next steps

Webhooks

Get real-time notifications when referrals convert

Customer API

Full customer endpoint documentation

Mobile apps

Integrate tracking in iOS and Android apps

Refer-a-friend forms

No-code embeddable referral forms

Getting started

Tracking integration

No-code solutions

Programs

Webhooks

Refer-a-friend API integration

How it works

Step 1: Install PartneroJS

Step 2: Track sign-ups

How to get the referral key

Create a customer

Request body

Response

Step 3: Track sales

Request body

Multiple transactions

Step 4: Display referral data

Get customer details and referral link

Get referral stats

Get reward balance

Get referred friends

Step 5: Credit rewards

Complete integration example

Next steps

Webhooks

Customer API

Mobile apps

Refer-a-friend forms

Getting started

Tracking integration

No-code solutions

Programs

Webhooks

​How it works

​Step 1: Install PartneroJS

​Step 2: Track sign-ups

​How to get the referral key

​Create a customer

​Request body

​Response

​Step 3: Track sales

​Request body

​Multiple transactions

​Step 4: Display referral data

​Get customer details and referral link

​Get referral stats

​Get reward balance

​Get referred friends

​Step 5: Credit rewards

​Complete integration example

​Next steps

Webhooks

Customer API

Mobile apps

Refer-a-friend forms

How it works

Step 1: Install PartneroJS

Step 2: Track sign-ups

How to get the referral key

Create a customer

Request body

Response

Step 3: Track sales

Request body

Multiple transactions

Step 4: Display referral data

Get customer details and referral link

Get referral stats

Get reward balance

Get referred friends

Step 5: Credit rewards

Complete integration example

Next steps