RoyaltEE
If you ever wanted to pay commission/reward to authors/owners of items sold in your online store, RoyaltEE is the add-on the does just that! Define commissions rules on per-product basis and have the reward added instantly once orders are complete (using CartThrob or Store modules). Pay out using PayPal MassPay or manually.
↑General concepts
In order to get RoyaltEE working for your store's items authors/owners, you need to set to custom field or RoyaltEE type in your products channel. You can create up to 5 rules based on total amount of author's items sold (not total commission).
Author of entry in products channel is the one who gets the reward.
Once someone purchases an item with commission rule(s) set up, the reward is added to author's virtual balance. If you have DevDemon Credits module installed, it is also recorded as a credit (so the user can spend it on your site). The commissions can be requested to withdraw using integrated PayPal MassPay feature, or you can perform payouts on individual basis manually.
The module works with 2 most popular e-comerce solutions for ExpressionEngine: CartThrob and Store.
↑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 (CartThrob or Store)
Minimum amount to withdraw (requests for smaller amounts will not be accepted) - 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)
PayPal MassPay API credentials are only required if you indend to perform payouts automatically using MassPay.
↑Commission rules explained
Above is shown the example of rules setup for product entry. Let's suppose the item costs $10. Then, the author will get from each sale:
$1 if the total revenue from ALL products by this author is less than $1,000
$1,20 if the total revenue from ALL products by this author is between $1,000 and $5,000
$1,30 if the total revenue from ALL products by this author is between $5,000 and $10,000
$1,40 if the total revenue from ALL products by this author is between $10,000 and $25,000
$1,50 if the total revenue from ALL products by this author is more than $25,000
Note that 'total revenue' here refers to the amount that the store (not author) has received (taxes and shipping not counted)
↑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 RoyaltEE 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} — author member ID;
{username} — author username;
{screen_name} — author 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 author statistics for your system.
You can see the records for all commissions, including author name, link to product and order details.
You can also narrow down results by certain author or display only selected period of time.
↑Template tags
↑Balance
{exp:royaltee:balance}
{exp:royaltee:balance} USD on your author's commissions balance
Prints out user's current royalty 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:royaltee:stats}
{exp:royaltee:stats limit="20" paginate="bottom"}
{if count==1}
<p>Total hits: {total_hits}</p>
{/if}
{if total_commission_records>0}
<p>{count}. ${commission}, recorded on {record_date format="%Y-%m-%d"}</p>
{/if}
{paginate}{pagination_links}{/paginate}
{/exp:royaltee: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 commissions recorded for user (matches the number of sold items)
- total_results — total number of records on page
- count — rows counter on each page
- balance — the user's commission balance
- withdraw_minimum — withdrawal minimum set in settings
- commission_id — internal ID of commission record
- order_id — ID of order/purchase that resulted in commission
- product_id — ID of product sold
- product_title — title of product sold
- method — method representing either e-commerce solution used or withdraw
- 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:royaltee:withdraw_history}
{exp:royaltee: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:royaltee:withdraw_history}
Displays history of RoyaltEE 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 commission 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:royaltee:withdraw_request_form}
{exp:royaltee: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:royaltee: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 'royaltee_form')
- class — form class (defaults to 'royaltee_form')
- name — form name (defaults to 'royaltee_form')