Affiliate program integration with REST API

Partnero simplifies the process of integrating and managing affiliate programs with its easy-to-use platform. This guide will walk you through the steps of integrating an Affiliate program into your stack.

Please note that before proceeding with the integration, you should already have an affiliate program created on Partnero. If you haven't created a program yet, refer to our guide on creating an affiliate program.

The integration process can be broken down into three simple steps: tracking visitor activity, sending data about signups, and sending data about sales. These steps will help you to set up and manage your affiliate program effectively.

Tracking

To track referrals who are visiting your website or application, you need to install the Partnero Universal javascript snippet.

Partnero Universal JS snippet tracks referral visits and signups on your website and ensures that referred signups are attributed to the correct partners.

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 Partnero
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?aff=UNIQUE_PARTNER_KEY the script matches the URL with Partnero's program settings and if the URL pattern matches the cookie is set partnero_partner with value UNIQUE_PARTNER_KEY which is the main identificator of the partner (affiliate).

Sending sign-up data

The second step is sending captured sign-up data to Partnero API. This step will have to interact with your application's code base.

In this guide, we are using REST API examples that any programming language can use. To make things easier, we have official SDKs for specific programming languages that you can use as well.

Once you have completed the Tracking part, you can start working on basic integration that sends basic customer information to Partnero when a new customer signs up on your website. This part will help attribute your customers to the partner who referred them.

Let's start with sending data about all signups to Partnero's Customer create API endpoint.

The data payload should contain two data objects, partner and customer. The most important is partner data object. You have to populate partner.key data object with UNIQUE_PARTNER_KEY, which is saved in partnero_partner cookie created by our universal javascript snippet.

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

Request example

{
  "partner": {
    "key": "UNIQUE_PARTNER_KEY"
  },
  "key": "CUSTOMER_KEY",
  "email": "customer@partnero.com",
  "name": "Partnero"
}

Request parameters

Parameters	Type	Required	Details
partner	object[]	yes	Partner data.
partner.key	string	yes	Must provide the partner's key to whom you are willing to create a customer. Should be populated with UNIQUE_PARTNER_KEY.
key	string	yes	The main identification of the customer. Can be anything, but we recommend using an account ID or customer's email address. This will be required when creating transactions for the customer.
email	string	optional	Must be a unique email address.
name	string	optional	Adds a name for the customer.

TIP

Partnero will ignore the data payload that doesn't contain partner.key. Feel free to send data about all signups in order to simplify the integration process on your application. No unnecessary data will be saved on Partnero.

Sending sales data

The last part of the integration is sending data about sales. When any customer makes a purchase, it is recommended to call Transaction create.

When making this call, we recommend including the most important data about the purchase (see Request parameters). Also, feel free to send data about all purchases; Partnero will ignore requests if there is no existing customer.key.

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

Request example

{
  "customer": {
    "key": "CUSTOMER_KEY"
  },
  "key": "transaction_123",
  "amount": 99.99,
  "product_id": "prod_123",
  "product_type": "monthly",
  "action": "sale"
}

Request parameters

Parameters	Type	Required	Limitations	Details
customer	object[]	yes		Customer data.
customer.key	string	yes		Customer identification. The same value from customer creation.
key	string	optional		Payment ID. It is not required but recommended (must be unique). We recommend using a payment ID on your system. Later can be used to refund/delete transactions.
amount	string	yes		A full amount of the purchase. Partnero will calculate partner's reward based on program settings.
product_id	string	optional		Product ID. It is used to for advanced commmission calculation.
product_type	string	optional		Product type or category. It is used to for advanced commmission calculation.
action	string	yes		Can be anything, but we prefer sale. It's visible in the program.

Recommendations

We recommend these requests when there are any updates with the customer or subscription.

Delete transaction

We recommend calling Transaction delete when chargeback or refund took place.

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

Request example

{
  "key": "transaction_123"
}

Delete customer

This call deletes an existing customer.

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

Request example

{
  "key": "CUSTOMER_KEY"
}