Affiliate Plus
Affiliate+ is a system that makes managing referrals in ExpressionEngine easy. Highly customizable commission rules, stats, balance/withdraw system and DevDemon Credits integration. Integrates with CartThrob, Store and SimpleCommerce e-commerce modules. Simply saying, it's a referrals system that works well
↑General concepts
With Affiliate+, anyone can be an affiliate. That means that anyone can generate an affiliate link (though not every link will result in commission, taking advantage of flexible commission rules explained below).
The referral commission is calculated separately for each item in the order (so you can set up the rules to include/exclude certain items).
The referral commission for each rule is summed up.
The link between affiliate and referral is established when affiliate link is clicked. The cookies need to be enabled in referral's browser.
The referral record will not be made if user was registered before
The module works with following e-comerce solutions: CartThrob, Store, Simple Commerce (PayPal cart is not supported)
↑Settings
Before proceeding, you need to save your settings. You will not be permitted to access rest of module's control panel before you do so.
The main settings are:
E-commerce solution used on your site (currently CartThrob, Store and SimpleCommerce are supported)
Minimum amount to withdraw (requests for smaller amounts will not be accepcted) - provide only number, without currency code
Integrate with DevDemon Credits module (if set, every commission will also be recorded and credit and can then be used using Credits gateway)
Mark rule as "terminator" (all other rules of lower priority will not be processed)
Discounts treatment (because comission is calculated per-product, dicount need to de divided between items in the order, and it can be done proportinally to number of products in the order or to their price)
PayPal MassPay API credentials are only required if you indend to perform payouts automatically using MassPay.
↑Commission rules explained
The advantage of Affiliate+ is its approach of using multiple commission rules. Different commission can be used depending on who generated the link, what has been purchased; certain limits can be applied etc.
The 2 main types of commission rules are: fixed amount (credits, dollars) and percent from purchase.
The rules are getting applied to each product in the order in sequence defined by their priority. The total commission for the product is calculates as the sum of commissions that can be applied. If some rule is marked as "terminator", the rules of lower priority are not applied and commission not added (other rules of same priority might be applied or not).
The total commission for the purchase is calculated as the sum of commissions of each product. The rules used for each product can be different.
You can restrict each rule to be applied only to:
— certain product groups (channels)
— certain products
— products with custom entry field set to "yes" or "1"
— purchases by refferals of certain affiliates
— purchases by refferals of certain affiliate groups (member groups)
— purchases by refferals of certain affiliate categories (member categories)
— purchases by refferals of affiliates with custom profile field set to "yes" or "1"
— purchases done using selected payment gateways
Besides, you can make each rule be applicable only if following conditionals are met:
— same product has been purchased by affiliate
— the total amount of purchases by referral is greater than some amount
— the total number of purchases by referral is more than some number
— the refferal record was made not too ling ago (time defined in seconds)
Example 1:
There are 2 rules: "All customers" (medium priority) giving affiliate 1% from every purchase, "Premium affiliates" rule (higher priority, marked as terminator) giving 2% from purchases for affiliates in "Premium members" group.
The referred customer A, being not logged in, is byuing Product A for $100. The affiliate will get 1% = $1
The referred customer B, referred by Premium affiliate, is byuing same Product A with a discount for $90. The affiliate will get 2% = $1.80
Example 2:
There are 3 rules: "Default rule" (medium priority) giving affiliate 1% from every purchase, "Premium products" rule (medium priority) giving 3% from purchase for selected products and "Special offer" (high priority), marked as terminator, giving $3 for products marked with "special offer" custom field.
The referred customer A is byuing Product A for $100, which is not in list of selected product, neither marked as special offer. The affiliate will get 1% = $1
The referred customer B is byuing Product B for $100, which IS in list of selected product, but not marked as special offer. The affiliate will get 1%+3% = $4
The referred customer C is byuing Product C for $100, which IS in list of selected product, and has "special offer" custom field set to "yes". The affiliate will get $3
Example 3:
The affiliate is getting 5% from first $100 spent by referral, and 1% for all next purchases.
This can be achieved by creating 2 rules: "1%" giving 1% for all purchases and "5% for first $100" giving 4% and limited to $100 on total amount of purchases. Note that 2nd rules gives 4%, not 5%, because the commissions are summed up.
Another approach would be to make 2nd rule give 5%, set higher priority to it and make it a terminator. But in some cases such setup will behave differently: if the amount of first purchase is greater than $100, in 1st case the affiliate will get commission for all amount (5% from $100 and 1% from the rest of amount), but in 2nd case he will get commission for only $100 (5%).
Example 4:
The site is letting users "fill the balance/buy credits" and then spend their balance to pay for premium features. The balance is filled by purchasing items in Credit Packs channel. The affiliate is getting 1 cent for every dollar filled to balance
The rules needs to be restricted to items in Credits Packs product group.
Example 5:
The site from example 4 is also letting users buy premium features directly using PayPal (not necessarely balance). The affiliate should get 0.5% for these purchases as well.
We need to add a rule that will be restricted to purchases in "premium features" product group and using PayPal gateway (so that purchases or premium features using balance/creadits system are not rewarded).
↑Balance and payouts
↑Credits integration
If you have DevDemon Credits installed, you can perform integration of the modules with simply marking the checkbox in settings.
If you do so, every commission or payout record of Affiliate+ will be recorded as Credits action.
The system will assume that 1 dollar (or the currency unit that you use for your store) is equal to 1 credit.
With integration checkbox marked, the users will be able to spend their earned commission on your site instead of requesting payout (or in addition to that). Besides, they will not be able to request withdraw of amount greater than their Credits balance.
↑Processing withdraws
Once the total amount of commissions earned by member has reached the withdraw minimum you've set in settings (or anytime, if you left it empty) the user can request a payout/withdraw of funds.
This is done with help of withdraw_request_form tag.
Once the request has been submitted, the site admin receives notification to his email. The notification template can be edited in module's Control Panel, in Notification templates section.
The variables available in email notification template are:
{site_name} — site name;
{site_url} — site URL;
{amount} — amount requested;
{member_id} — affiliate member ID;
{username} — affiliate username;
{screen_name} — affiliate screen name;
{cp_link} — link to payouts section of module's control panel.
The current and past withdaw requests can be found in Payouts section of module control panel.
On that page, the admin can cancel the request or mark it as processed. When marking as processed, it is possible to record the method used for payout (PayPal, Bank transfer etc.), add corresponding Transaction ID and comment.
It is also possible to process all pending automatically using PayPal MassPay. The number of pending requests should be greater than 2. If you have more than 250 requests pending, be aware that only 250 requests will be submitted to MassPay at a time. You will see a link to process requests with MassPay as s0on as there will be 3 or more pending requests.
↑Stats
The Stats tab in module's Control Panel display affiliate statistics for your system.
You can see the records for all commissions, including affiliate name, link to order details and customer profile.
You can also narrow down results by certain affiliate or display only selected period of time.
↑Template tags
↑Affiliate link
{exp:affiliate_plus:link}
<a href="{exp:affiliate_plus:link return="/profile/{username}"}">Click here</a>
Prints out affiliate link for logged in user.
Parameters:
- return — a page to redirect visitor after registrering affiliate hit. Can be a full URL or URI segments.
Use return="SAME_PAGE" to redirect to the page used to generate link.
↑Balance
{exp:affiliate_plus:balance}
{exp:affiliate_plus:balance} USD on your affiliate balance
Prints out user's current affiliate balance: total amount earned minus amount withdrawn. If you have DevDemon Credits module installed the balance can't be greater than credits balance.
↑Stats
{exp:affiliate_plus:stats}
{exp:affiliate_plus:stats limit="20" paginate="bottom"}
<p>{count}. ${commission}, recorded on {record_date format="%Y-%m-%d"}</p>
{paginate}{pagination_links}{/paginate}
{/exp:affiliate_plus:stats}
Displays detailed stats on commissions earned by logged in user.
Tag parameters (all optional):
- limit — number of records per page, if you want to use pagination
- paginate — place to display pagination links. Can be 'top', 'bottom' or 'both'. Defaults to 'bottom'
Conditional variables:
- {if no_results}{/if} — displayed if there are no commissions recorded
Variables:
- total_commission_records — total number of affiliate commissions recorded for user
- total_results — total number of records on page
- count — rows counter on each page
- balance — the user's affiliate balance
- withdraw_minimum — withdrawal minimum set in settings
- referral_member_id — member ID of reffered customer who made order resulting in commission
- referral_username — username of reffered customer who made order resulting in commission
- referral_screen_name — screen name of reffered customer who made order resulting in commission
- commission_id — internal ID of commission record
- order_id — ID of order/purchase that resulted in commission
- method — method representing either e-commerce solution used or withdraw
- hit_id — corrsponding hit record ID
- credits — amount added
- commission — same as {credits}
- credits_pending — amount scheduled for withdraw
- record_date format="%Y-%m-%d" — the commission date. Standard EE date formatting rules apply.
- {paginate}{pagination_links}{/paginate} — pagination links (if you have limit parameter set and there's more than one page)
↑Withdraw history
{exp:affiliate_plus:withdraw_history}
{exp:affiliate_plus:withdraw_history limit="20" paginate="bottom"}
<p>{count}. ${if amount}{amount}{if:else}{amount_pending}{/if}, requested on {request_date format="%Y-%m-%d"} and {status}{if status=='Processed'} on {payment_date format="%Y-%m-%d"}{/if}</p>
{paginate}{pagination_links}{/paginate}
{/exp:affiliate_plus:withdraw_history}
Displays history of Affiliate+ payouts to logged in user.
Tag parameters (all optional):
- limit — number of records per page, if you want to use pagination
- paginate — place to display pagination links. Can be 'top', 'bottom' or 'both'. Defaults to 'bottom'
Conditional variables:
- {if no_results}{/if} — displayed if there are no commissions recorded
Variables:
- total_withdraw_records — total number of withdraw records
- total_results — total number of records on page
- count — message counter on each page
- balance — the user's current affiliate balance
- withdraw_minimum — withdrawal minimum set in settings
- payout_id — internal ID of payout record
- status — Processed, Pending or Cancelled
- method — withdraw method used (PayPal, Bank etc.)
- amount — amount paid
- amount_pending — requested amount, if withdraw is pending or cancelled
- transaction_id — system (e.g. PayPal) transaction ID
- comment — comment added to transaction by admin
- request_date format="%Y-%m-%d" — date when withdraw was requested. Standard EE date formatting rules apply.
- payment_date format="%Y-%m-%d" — date when payment was made. Standard EE date formatting rules apply.
- {paginate}{pagination_links}{/paginate} — pagination links (if you have limit parameter set and there's more than one page)
↑Request withdraw
{exp:affiliate_plus:withdraw_request_form}
{exp:affiliate_plus:withdraw_request_form return="SAME_PAGE"}
<p>Enter amount you widh to withdraw (${amount_min} or more). The total amount available is ${amount}</p>
<input type="text" name="amount" value="{amount}" />
<input type="submit" value="Request payout" />
{/exp:affiliate_plus:withdraw_request_form}
Form fields:
- amount — the amount to withdraw. Mandatory
Variables:
- amount — the total amount available on user's balance
- amount_min — minimum payout amount as set in module's settings
Parameters:
- return — a page to return after submitting request. Can be a full URL or URI segments.
Use return="SAME_PAGE" to return user to the page used to display form. - skip_success_message="yes" — force redirect to return page without showing success message.
- id — form ID (defaults to 'affiliate_plus_form')
- class — form class (defaults to 'affiliate_plus_form')
- name — form name (defaults to 'affiliate_plus_form')
↑Referrer
Get information about who referred certain user.
{exp:affiliate_plus:referrer}
{exp:affiliate_plus:referrer username="{segment_3}"}
<p>Referred by <a href="{path={affiliate_username}}">{affiliate_screen_name}</a></p>
{if no_results}No referral record{/if}
{/exp:affiliate_plus:referrer}
Variables:
- affiliate_member_id — member ID of affiliate who referred this user
- affiliate_username — username of affiliate who referred this user
- affiliate_screen_name — screen name of affiliate who referred this user
Parameters:
- member_id — member ID of referred member
- username — username of referred member
If both username and member_id are omited, will display info related to logged in user.