Referal program. General information

You can launch a referral program using BILLmanager. Within the program, the provider pays monetary rewards to their partners for each referred client (referral).

A partner can refer clients in two ways:

• via a referral link — a unique link is automatically generated for each partner. If a client used such a link, they are considered to have been attracted by the partner. Typically, the provider's partners place these special links on their own websites;
• via a promo code — each partner has a unique promo code. Referrals need to enter the promo code when ordering services. If clients used such a link, they are considered to have been attracted by the partner.

Creating a referral program

To add a new program, go to Marketing → Referral programs → click Add:

1. Select the Provider running the referral program. 
2. Enter the Name of the referral program.

3. Specify the Promo code template for generating the partner's promo code. Use the macro @ID@ in the field — the partner’s unique identifier (id). A promo code created without using this macro is considered invalid.

   The promo code will work only on the client's first order. If the client already has several ordered services on their account, the promo code will not work.
4. Set the Start date. Partners will start receiving rewards for expenses created by clients after this date.
5. Set the End date. The referral program will be active until the specified date inclusive. 
6. Assign automatically — when a client connects to the provider, this referral program will automatically become active for them. By default, only one referral program can be active per provider.
7. Enter the Website URL of the provider. To form the referral link, the site domain must be supplemented with the ?from= parameter. For example, http://example.com/?from=. BILLmanager uses this parameter to identify the partner who referred the client. Each partner has a unique link; to generate it, their identifier (id) is appended to the end of the URL.
8. Select the Client group eligible to participate in the referral program. 
9. Select a customer group under Restrict for members of group. Members of this group will not receive rewards under the referral program.
10. Click:
    • Save and go to rules to configure referral program rules;
    • Ok to configure rules later.

Configuring referral program rules

By default, the referral program does not apply to all service types. To create specific reward rules for certain product types and referral expenses, go to Marketing → Referral programs → select the program → click Rules → click Add:

1. Select the Accrual type:
   • Calculated (default);
   • Fixed.
2. Enter the Reward amount. You can enter values with precision up to two decimal places. If you selected Calculated, enter the percentage of the referral’s expenses that will be awarded to the partner at the end of the month. The value cannot exceed 100%. If you selected fixed, enter the amount the partner will receive.
3. Set the Maximum amount for reward. If this field is left empty, the value from the Reward amount field will be used.
   
   Examples

   Example 1: Base reward without limit.

   The provider sets the Reward amount to 10%, and leaves the Maximum amount for reward field empty. The referral spends 5000 USD within a month. The calculated partner reward:

   10% × 5000 = 500 USD.

   Example 2: Reward with a cap.

   The provider sets the Reward amount to 10% and enters 300 USD in the Maximum amount for reward field. The referral spends 5000 USD within a month.
   Calculated reward:

   10% × 5000 = 500 USD,

   but this exceeds the maximum amount of 300 USD, so the partner receives 300 USD. 

   Example 3: Reward below the maximum amount.

   The provider sets the Reward amount to 10% and enters 1000 USD in the Maximum amount for reward field. The referral spends 5000 USD within a month.
   Calculated reward:

   10% × 5000 = 500 USD.

   Since the calculated reward is less than the maximum amount, the partner receives the full amount — 500 USD. 
4. Award rewards — choose when the referral’s purchases start being counted in the referral program. Options:
   • After referral's purchase — the reward will be credited on the 1st day of the month following the month in which the referral made the purchase. For example, if the purchase was made on May 5, the reward will be credited on June 1;

   • After a period has passed. When selecting this option, specify when the reward will be paid. If the service is deleted earlier, no reward will be issued. Available settings:

     • Reward after — specify after how many months the reward will be credited;
       Example

       For example, the Reward after field is set to 3 months. The referral orders a service on January 15, 2025, for three months, until April 15, 2025. If the service is still active on May 15, 2025, the reward will be credited on June 1, 2025, based on expenses for the entire activation period. Note:

       • if the service is deleted during the selected period, no reward will be issued to the referrer;
       • if the referral program is active at the time of purchase but ends before the reward should be credited, the reward will still be issued. However, only expenses incurred before the program ends are taken into account.
     • Expenses created — select which expenses to include:
       • created Upon purchase — only expenses created at the time of purchase are considered for reward calculation;
         Example

         For example, the service was activated on March 5. Later, before the reward is credited, its cost is recalculated and split into three months: March, April, and May. This results in separate expenses with different dates. Only the expense dated March 5 will be counted toward the reward.
       • Over the entire time — all expenses created from the service activation date until the reward crediting date are included in the calculation.
5. Set the Reward period, months. If left blank, rewards will be credited indefinitely as long as the referral program conditions are met.
   If the referral program is configured with Award rewards → After a period has passed, the reward period will be counted from that deferred period.
   Example

   Example 1. Only the Reward period of 2 months is configured for the referral program.

   For a service paid on January 15, payments will be made on:

   • February 1 — for expenses from January 15 to January 31;
   • March 1 — for expenses from February 1 to February 28 or 29;
   • April 1 — for expenses from March 1 to March 15.

   Example 2. The referral program is configured with After a period has passed set to 3 months and Reward period set to 2 months.

   For a service purchased on January 15, payments will be made on:

   • February 1 — no payment;
   • March 1 — no payment;
   • April 1 — no payment;
   • May 1 — for expenses from January 15 to April 30;
   • June 1 — for expenses from May 1 to May 31;
   • July 1 — for expenses from June 1 to June 15.
6. Define the Reward payout schedule — the frequency of reward payouts. By default, payments are made monthly. You can set a range from 1 to 12 months.
   
   Example

   For example, the Reward payout schedule is set to 2 months. The referrer purchases a service on January 17, 2025, and continues to renew it regularly. Rewards will be paid every two months: March 1, 2025; May 1, 2025; July 1, 2025, etc. If the referrer purchases a second service on February 13, 2025, payments for it will also occur every two months: April 1, 2025; June 1, 2025; August 1, 2025, etc.
7. Set the Priority for applying rules within the referral program. Higher priority means the rule is processed earlier. If priorities are equal, the most beneficial rule for the referrer is selected. Only one reward rule applies per service.
8. Click:
   • Save and go to conditions to configure conditions for the rule. See Setting conditions for a rule;
   • OK to configure conditions later.

Setting conditions for a rule

To create conditions for an existing rule, go to Marketing → Referral programs → select the program → click Rules → select the rule → click Conditions → click Add:

1. Select a Condition:
   • No conditions — rewards are issued to the referrer without restrictions, for any purchase;
   • Referral’s sales volume — r ewards are issued based on the referral’s turnover over the selected period. Specify:
     • Product/Service — select services and their add-ons for which rewards will be issued. For example, virtual hosting;
     • Order period — select periods during which orders should trigger rewards. For example, day, month, or year. If no period is selected, it is equivalent to selecting all periods;
     • Comparison  — logical operator for the condition. If satisfied, the participant receives a reward. For example, if "greater than (>)" is selected and "Amount" is set to 100 USD, all referrals who spent more than 100 USD will get a reward;
     • Amount  — specify the amount against which the referral’s sales volume is compared. For example, more than 100 USD. The referral’s expenses during the order period matching the reward schedule are considered:
       • if the order period is set to 1 month, only the previous month is considered;
       • if the order period is set to 2 months, the previous 2 months are considered, etc.;

   • By number of services purchased by the referral — rewards are issued when the referral makes a first-time purchase of specified service types in the required quantity. Specify:

     • Product/Service — select services and their add-ons for which rewards will be issued. For example, virtual hosting;
     • Order period — select periods during which orders should trigger rewards. For example, day, month, or year;
     • Comparison — logical operator for the condition. If satisfied, the participant receives a reward;
     • Number of services — specify the number of services purchased by the referral throughout the program duration that will be counted. For example, if "Greater than or equal to (>=) 3" is set and the referral bought two services, no reward will be issued;

   • By the number of referrals brought — r ewards are issued if the referrer brings a specified number of referrals. Specify:

     • Comparison — logical operator for the condition. If satisfied, the participant receives a reward;
     • Number of referrals — the number of referrals needed to meet the rule. This condition can be used to create referrer tiers. As the referrer brings the required number of clients, they move up through the tiers. Conditions should be configured for different groups.
       Example

       For example:

       • for level 1 with a 3% reward, up to 10 clients need to be referred;
       • for level 2 with a 5% reward, 10 to 50 clients need to be referred;
       • for level 3 with a 20% reward, more than 100 clients need to be referred.

       The referrer brings 8 clients, reaches level 1, and receives a 3% reward on their referrals’ purchases.

       The referrer brings 45 clients, moves to level 2, and receives a 5% reward. Referrals that previously gave 3% now give 5%.

       The referrer brings 110 clients, moves to level 3, and receives a 20% reward. Referrals that previously gave 5% now give 20%.

If there is only one condition and no others, expenses from any referral purchase are considered for reward calculation.

1. • Total sales volume of all referrals — rewards are issued based on the total turnover of all referrals over a selected period. Specify:

     • Product/Service — select services and their add-ons for which rewards will be issued. For example, virtual hosting;
     • Order period — select periods during which orders should trigger rewards. For example, day, month, or year;
     • Comparison — logical operator for the condition. If satisfied, the participant receives a reward;
     • Amount  — specify the amount against which the referrals' sales volume is compared. For example, more than 1000 USD. The referral’s expenses during the order period matching the reward schedule are considered:
       • if the order period is set to 1 month, only the previous month is considered;
       • if the order period is set to 2 months, the previous 2 months are considered, etc.

     Conditions can be used individually or in combinations allowing joint or separate application.
     

     Example

     For example, the condition based on total turnover of all referrals can be used alone or combined with other conditions:

     • with the condition on number of referrals brought — referrals must be brought in the specified quantity OR their combined turnover must fall within the specified range;
     • with the condition on number of services — each referral must purchase a specified number of services by type AND their combined turnover must fall within the specified range;
     • with the condition on individual referral sales volume — each referral must make purchases totaling the specified amount AND their combined turnover must be within the specified range.

     
     

2. Select an existing condition group or create a new one. Condition group — the group to which the condition will be added. Within a single group, conditions are combined with the logical operator "OR". Groups are combined with each other using the logical operator "AND". All added conditions form a single complex logical expression. 
3. Click Ok.

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:

1. 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

   • getBillCntid() — function that sends a request to the platform to register a click on the referral link;
   • encodeURIComponent(window.location.href) — function that encodes the current page URL, including the from=ID parameter indicating the referrer;
   • localStorage.setItem("bill_cntid", ...) — function that saves the received unique click identifier across sessions;
   • gotoBillManager() — function that constructs the URL for redirecting to the platform, adding the cntid parameter if it was saved;
   • cntid — parameter that allows the platform to associate future registration or purchase with a specific referral link click.

Assigning a client manually

To associate a referral with the client, navigate to Clients → Clients → select a client → Accounts → select an account → Edit → Referred by client:

To unlink a client, select the value "not set" in the Referred by client field.

Rewarding partners

Rewards to partners for participating in the referral program are credited on the 1st of each month. The reward is credited to the referrer regardless of whether the referral’s expense has been paid at the time of crediting. The reward amount is calculated based on the referral’s expenses according to the configured rules. See Configuring referral program rules. The billing platform automatically creates a payment of the required amount for the partner.

The provider can manually trigger reward crediting for the referral program:

/usr/local/mgr5/sbin/billmaintain --command affiliatemonthly --date 2016-04-01

Payouts for the referral program are created for the current month. Therefore, if the parameter --date 2016-04-01 is specified, payments will be created for April (the fourth month).

Withdrawal of funds

To make a withdrawal from the personal account:

1. Enter Clients → Clients → select a client → click Accounts.
2. Select an account → click Refund.
3. Fill in the form:
   1. Payment method — the payment method by which the refund will be made. A negative payment will be created with the specified payment method. 
   2. Refund rules — Select the rule that determines the amount of the withdrawal fee. 
   3. Payment — select the payment from which you want to perform a refund. All credited and unspent advances are available for selection. 
   4. Amount — enter the amount of the refund.
4. Click Finish.

Refund rules

To add a rule, enter Settings → Refund rules → click Add:

1. Name — specify the name for the refund rule. 
2. Fee amount — specify a fixed commission amount. Specified in the provider's currency. If the field is not filled in, no fixed commission will be charged.
3. % from refund — specify the percentage rate of the commission charged. If the field is not filled in, no percentage rate will be charged.
4. Calculate amount of refund — select the rule for calculating the total commission amount. Enabled if the fields Commission amount and % of refund amount are filled in.
   • % + amount — calculated according to the formula: (refund amount / % of refund amount) + Commission amount.
     For example, a provider has processed a refund to a client using the so called "10 + 10" rule. The amount of refund is 200 USD. The commission amount will be 30 USD ((200 / 10) + 10), including: refund amount 20 USD - 10% of 200 and 10 USD - fixed commission. 
   • amount + % — calculated according to the formula: Commission amount + ( (refund amount - Commission amount) / % of refund amount).
     For example, a provider has processed a refund to a client using the so called "10 + 10" rule. The amount of refund is 200 USD. The commission amount will be 29 USD (10 + (200 - 10) / 10%), including: 10 USD - fixed commission and 19 USD - 10% of 190. Commission amount - 10 USD, % of refund amount - 10%.
5. Expense name — specify the name for the commission withdrawal expense.