How does the referral program work?

Referral program is a type of cooperation between the client and provider, in which the client receives a referral link or a promotional code. Such a client is considered a partner or referrer, and new clients who have registered under that link (promotional code) are referrals. The partner receives a percentage of the expenses of his referrals.

Only a new client, who has not yet purchased any services, can be added using a promotional code.

Referral program results:

partner makes a profit from the attracted clients;
provider gets new clients and advertising by the partner.

For information on how to create a referral program, see the article Referral program. General information.

The information in this article is relevant for BILLmanager version 6.135 and above. For information on how the referral program works in earlier versions, see the article How does the affiliate program work? (for version 6.134 and lower)

Integration with your website

To integrate the referral program with a website, when creating a referral program, specify the Website URL in the settings:

if the website URL is the BILLmanager address, no additional actions are required. The platform will automatically extract the parameter value from the request and register the referral link click;
if the URL is a third-party website, from the website side, send a request to the platform in the following format:

https://bill_address?func=referralprogram.registerclick&p=https%3A%2F%2Fsite.com%2F%3Ffrom%3D2&r=https%3A%2F%2Freferrer.com%2Fpage&out=xjson

Where:

- bill_address — domain name of the server with the platform;
- func=referralprogram.registerclick — function that registers a click on a referral link;
- &p=website_address — URL-encoded link that the client clicked. Special characters must be replaced with codes according to percent encoding. Percent encoding (or URL encoding) is a method to safely transmit special characters in links (URL). For example, for the URL https://site.com/?from=2 specify &p=https%3A%2F%2Fsite.com%2F%3Ffrom%3D2. This address is displayed in the referrer's client area and provided by them to potential referrals;
  
  The value of the p parameter must exactly match the link specified in the referral program settings — field Website URL, otherwise the click will not be registered. For example, if the program is configured for the domain root https://example.ru/ , and the parameter transmits an address with a path .../catalog/.
  For universal configuration, it is recommended to normalize the address: leave only the protocol and domain, removing the path and parameters.
- &r=referrer_url — the URL-encoded link to the page from which the client navigated to the current page (the `HTTP_REFERER` value). This parameter is passed to track the referral source. To obtain the value, use the `document.referrer` property in JavaScript. If the referrer is missing, this parameter can be omitted.
- out=xjson — response format.

The platform registers the click and returns a unique identifier in the field doc["cntid"]["$"] of the JSON response. The received identifier is saved on the website side and transmitted as a parameter during subsequent redirection to BILLmanager.

Example with normalization

Example HTML page with referral program integration and a button to navigate to BILLmanager:

<html>
<head>
    <script type="text/javascript">
        function getBillCntid() {
            var req = new XMLHttpRequest();
            req.responseType = 'json';
            req.onload = function() {
                if (req.status == 200) {
                    var json = req.response;
                    var doc = json.doc;
                    if (doc["cntid"]) {
                        // Save cntid to localStorage
                        localStorage.setItem("bill_cntid", doc["cntid"]["$"]);
                    }
                }
            }
            
            // Forming address for parameter p
            var referralParam;
            
            // Link normalization: leave only protocol and domain
            // This guarantees matching with referral program settings,
            // even if the user navigated to a page with a path (e.g., /catalog/)
            if (typeof URL === "function") {
                var urlObj = new URL(window.location.href);
                urlObj.pathname = "/";   // reset path to root
                urlObj.search = "";      // optionally: remove query parameters
                referralParam = encodeURIComponent(urlObj.toString());
            } else {
                // Fallback for old browsers: use as is
                referralParam = encodeURIComponent(window.location.href);
            }
            
            // Replace bill.example.com with your platform address
            var billUrl = "https://bill.example.com/billmgr  ";
            
            // Sending request
            req.open("GET", billUrl +
            "?func=referralprogram.registerclick&p=" + encodeURIComponent(window.location.href) + "&r=" +  encodeURIComponent(document.referrer)  + "&out=xjson", true);
req.send(null);
        }
        if (!localStorage.hasOwnProperty("bill_cntid")) {
            getBillCntid();
        }
    </script>
</head>
<body>
    <script type="text/javascript">
        function gotoBillManager() {
            // Replace bill.example.com with your platform address
            var url = "https://bill.example.com/billmgr  ";
            // If the referral program connection identifier (bill_cntid) is found in localStorage, add it as a parameter:
            if (localStorage.getItem("bill_cntid") !== null) {
                url += "?cntid=" + localStorage.getItem('bill_cntid');
            }
            window.location.href = url;
        }
    </script>
    <input type="button" onclick="gotoBillManager();" value="Go to BILLmanager">
</body>
</html>

Explanations for the HTML code