Affiliate program API integration

This guide walks you through integrating an affiliate program using the Partnero REST API. Use this approach when you want server-side tracking with full control over the data you send.

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 visitor arrives at your site via a partner’s referral link (e.g., yoursite.com?ref=PARTNER_KEY)
PartneroJS stores the partner’s key in a partnero_partner cookie
When the visitor signs up, your backend reads the cookie and sends it to Partnero along with the customer data
When the customer makes a purchase, your backend records the transaction
Partnero calculates the partner’s commission automatically

Step 1: Install PartneroJS

PartneroJS tracks referral visits by reading the partner 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, the script creates a partnero_partner cookie containing the partner’s unique key. This cookie persists for the duration configured in your program settings (default: 30 days).

Step 2: Track sign-ups

When a new user signs up, your backend reads the partnero_partner cookie from the request and sends it to Partnero to attribute the customer to the referring partner.

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

How to get the partner key

The partnero_partner cookie is set by PartneroJS and sent with every request to your domain. Read it on your server:

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

const partnerKey = req.cookies['partnero_partner'];

$partnerKey = $request->cookie('partnero_partner');

partner_key = request.COOKIES.get('partnero_partner')

partner_key = cookies[:partnero_partner]

Create the customer

Pass the partner key along with the customer data:

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

Request body

Parameter	Type	Required	Description
`partner.key`	string	Yes*	Partner’s referral key from `partnero_partner` cookie
`partner.email`	string	Yes*	Partner’s email (alternative to key)
`partner.id`	string	Yes*	Partner’s ID (alternative to key)
`key`	string	Yes	Unique customer identifier (account ID or email recommended)
`email`	string	No	Customer’s email address
`name`	string	No	Customer’s first name
`surname`	string	No	Customer’s last name
`tags`	array	No	Tag names to assign to the customer
`options.referral_url`	string	No	The URL where the referral occurred

*Provide at least one of partner.key, partner.email, or partner.id.

Partnero ignores requests with an invalid partner key. You can send customer data for every sign-up without checking the cookie first—only customers with a valid referral will be recorded.

Response

{
  "data": {
    "key": "customer_123",
    "partner": "PARTNER_KEY",
    "name": "John",
    "surname": "Doe",
    "email": "[email protected]",
    "status": "active",
    "tags": [],
    "created_at": "2025-05-09T17:42:13.000000Z",
    "updated_at": "2025-05-09T17:42:13.000000Z"
  },
  "status": 1
}

Step 3: Track sales

When a customer makes a purchase, record the transaction so Partnero can calculate the partner’s commission.

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_123"
    },
    "key": "invoice_123",
    "amount": 99.99,
    "action": "sale"
  }'

Request body

Parameter	Type	Required	Description
`customer.key`	string	Yes	The customer identifier used during sign-up
`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`)
`product_id`	string	No	Product identifier (for advanced commission rules)
`product_type`	string	No	Product type, e.g., `monthly`, `yearly` (for commission rules)

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_123"
    },
    "transactions": [
      {
        "key": "invoice_123",
        "amount": 99.99,
        "action": "sale"
      },
      {
        "key": "invoice_456",
        "amount": 199.99,
        "action": "sale"
      }
    ]
  }'

Partnero ignores transactions for customers that don’t exist in the system. You can safely send all purchase data without filtering by referred status.

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());

// 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. Send to Partnero (safe to call for every sign-up)
  await fetch('https://api.partnero.com/v1/customers', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      partner: { key: req.cookies['partnero_partner'] },
      key: user.id,
      email: user.email,
      name: user.name
    })
  });

  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 (safe to call for every purchase)
  await fetch('https://api.partnero.com/v1/transactions', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      customer: { key: userId },
      key: orderId,
      amount: amount,
      action: 'sale'
    })
  });

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

Next steps

API reference

Full REST API documentation

Webhooks

Get real-time notifications for partner events

Mobile apps

Integrate tracking in iOS and Android apps

JavaScript SDK

Client-side tracking without a backend

Getting started

Programs

Tracking integration

No-code solutions

Postbacks

Webhooks

AI & MCP

Affiliate program API integration

How it works

Step 1: Install PartneroJS

Step 2: Track sign-ups

How to get the partner key

Create the customer

Request body

Response

Step 3: Track sales

Request body

Multiple transactions

Complete integration example

Next steps

API reference

Webhooks

Mobile apps

JavaScript SDK

​How it works

​Step 1: Install PartneroJS

​Step 2: Track sign-ups

​How to get the partner key

​Create the customer

​Request body

​Response

​Step 3: Track sales

​Request body

​Multiple transactions

​Complete integration example

​Next steps

API reference

Webhooks

Mobile apps

JavaScript SDK

How it works

Step 1: Install PartneroJS

Step 2: Track sign-ups

How to get the partner key

Create the customer

Request body

Response

Step 3: Track sales

Request body

Multiple transactions

Complete integration example

Next steps