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 your website, specify the Website URL in the program settings when creating it.

If the website URL points to BILLmanager, no additional actions are required. The platform will automatically extract the parameter from the request and register the referral link click.

If the URL belongs to a third-party website, perform the following steps:

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&out=xjson

Where:

bill_address — IP address of the server with the platform;
func=referralprogram.registerclick — function that registers a click on the referral link;
&p=website_url — URL-encoded link used by the client. Special characters must be replaced with codes according to percent encoding. Percent encoding (or URL encoding) is a way to safely transmit special characters in URLs. 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 partner’s personal account and provided by them to potential referrals;
out=xjson — response format.

The platform registers the click and returns a unique identifier in the doc["cntid"]["$"] field of the JSON response. Store this identifier on the website side and pass it as a parameter during subsequent redirects to BILLmanager.

Example of HTML page with referral program integration and a button to redirect 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"]) {
                        // If the platform returns cntid, save it in localStorage
                        localStorage.setItem("bill_cntid", doc["cntid"]["$"])
                    }
                }
            }
            // Request to the platform, parameter p passes the current URL, which may contain the referrer parameter.
            req.open("GET", "https://billmgr_addr/?func=referralprogram.registerclick&p=" + encodeURIComponent(window.location.href) + "&out=xjson", true);
            req.send(null);
        }
        if (!localStorage.hasOwnProperty("bill_cntid")) {
            getBillCntid();
        }
    </script>

</head>
<body>
    <script type="text/javascript">
        function gotoBillManager() {
            var url = "https://billmgr_addr";
            // If the connection identifier for the referral program (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>

Explanation of HTML code