Affiliate module for Interspire Shopping Cart

Hello,
I have already implemented this module on two shops rather successfully. The concept is quite simple:

• websites that want to get rewarded through affiliation must link to your website using an identifier in the URL. If your website is http://website.com/, then your links must be of the form http://website.com/?ref=123 where 123 is the affiliate ID.
• when a visitor clicks the link, the affiliate ID will be placed in a cookie that will expire after 15 days (this can be configured)
• when the visitor purchases an item: if the affiliate ID cookie is still enabled, the affiliate will be credited of a certain amount, it can be a share of the sale or a fixed amount.
• affiliate accounts are simple customer accounts, there is no modification to make regarding accounts. When a sale is made, they receive store credit. They can either spend the store credit to purchase items on the store, or they can manually request for a withdrawal (managing withdrawals is up to you).

I will detail the implementation of this module. It's actually quite simple. You will need:

• a tiny modification of the orders SQL table if you want to log individual sales
• modifications in a few of the PHP scripts of Interspire Shopping Cart
• an additional PHP script that I have provided for download.

Finally I have to mention that I have only applied this on Interspire Shopping Cart 5.x, I've never used it on Interspire Shopping Cart 6 but I don't see any reason why this wouldn't work. You can just try it out and revert the changes if it doesn't work.

Download and install the PHP module

Download the module called affiliate.php. You need to place it in the /lib/ folder of your website. You then need to include the module into Interspire Shopping Cart. To do so, open the /init.php which is at the root of your website. At the end of the file, add this line:

require_once(dirname(__FILE__).'/lib/affiliate.php');

Modification of the SQL table

Begin by modifying the orders SQL table that will allow us to log the sales made by affiliates. The modification is very small and it will NOT affect anything in your store. It will not break anything so don't be worried about it. I've done it multiple times like I said. You need to add a single field at the end of the table: "ordaffiliate". It's an "int" field with a size of at least 10. It will be used to hold the ID of the affiliate who got the sale.

ALTER TABLE `isc_orders` ADD `ordaffiliate` INT( 11 ) NOT NULL COMMENT 'ID of the affiliate who got the sale'

Logging sales properly

Next step is: when someone places an order on the website, we need to store the affiliate ID in the "ordaffiliate" field of the order, and also credit the affiliate for the sale. Open the /includes/class/class.checkout.php file. Find this text in the source code: "$pendingOrder = array" it is not a complete line but you should only get one result.
Before the end of the array, in other words before the );  add this line:

            'ordaffiliate' => isset($_COOKIE["ref"]) ? intval($_COOKIE["ref"]) : "0",

What it does is it checks if the "ref" cookie is set; if it's set then it will save its value in the database. If it's not set it just stores 0. NOTE: if you insert this line as the last line of the array, don't forget to add a comma to the line above! Like this:

            'ordstatus' => $orderStatus,

            'ordaffiliate' => isset($_COOKIE["ref"]) ? intval($_COOKIE["ref"]) : "0"

        );

Another modification must be applied to this file: /lib/entities/entity.order.php
When you open it, you will see a massive array of strings like this:

        $schema = array(

                "orderid" => "int",

                "ordtoken" => "text",

...
Anywhere in the array, add this line:

                "ordaffiliate" => "int",

Once that is done, you can get to the next step...

Giving affiliate credit at the right time

You don't want to be giving affiliate credit when someone hasn't paid for their order yet. So we'll only give the credit when the sale is complete. Open /lib/orders.php and find this function: function UpdateOrderStatus.
Scroll down in the function until you find this:

    if (OrderIsComplete($status)) {

            $updatedOrder['orddateshipped'] = time();

        }

We are going to change this block a bit and replace it by this:

    if (OrderIsComplete($status)) {

            $updatedOrder['orddateshipped'] = time();

            // Give affiliate credit!

            require_once("affiliate.php");

            if ($order['ordaffiliate'])

                GiveAffiliateCredit($order);

        }

We call the "GiveAffiliateCredit" function only if the order is complete/shipped, and if the order has an affiliate ID defined.

At this point the module is functional. Affiliates will receive store credit for the sales they make. Now what you would like is to allow your affiliates to visualize the sales they have made! We're going to need another modification...

Integrating an "affiliate account" link on the account page

The first modification that you have to make will be in the HTML templates of your store design. Open your Admin control panel, and click the "Store design" link at the top right of the page. On the Store Design page, click the "Browse Template Files..." button. Open the "account.html" page by clicking it in the menu on the left. In the account.html page you will find a bullet list (<ul> ... </ul>) corresponding to the links from the account page. Add a new item in the bullet list (<li> tag) like this:

<li><a href='account.php?action=affiliate#affiliate' title='Manage my affiliate account'>Affiliate account</a> - Manage your affiliate account and view your sales</li>

There is another modification you need to make. After the </ul> tag, add this little bit:

%%GLOBAL_AffiliateAccount%%

Save the template and close the window. We are now going to create that affiliate page.

The Affiliate Account page

At this point if you click the link "Affiliate account" that you have inserted on the account page, it won't take you anywhere. It just takes you back to the regular account page. We need to edit the /includes/classes/class.account.php file and make the following modification:

Find the line where it says "switch ($action)" there should be only one in this file
Right below this line, add the following code:

                    case "affiliate": {

                        DisplayAffiliateAccountPage();

                        $this->MyAccountPage();

                        break;

                    }

To ensure that it works correctly, go to your account page and click the "Affiliate account" link. Here is a screenshot of the Affiliate Account section on the "My Account" page, with one affiliate sale.

Configuring the module

If you open the affiliate.php file that I've provided before, you will find interesting configuration settings at the beginning of the file.
define( "AFFILIATE_ENABLED",             true );     // enable or disable the affiliate module

define( "AFFILIATE_COOKIE_DURATION",     14);         // how many days should the affiliate cookie remain active?
 
define( "AFFILIATE_COMMISSION",         5 / 100);     // commission that affiliates make when a sale is made. Here it's 5%
 
define( "AFFILIATE_FIXED_AMOUNT",        10);        // if you want to use a fixed amount IN ADDITION TO THE COMMISSION, define the amount here.
 
define( "AFFILIATE_REASON", "AFFILIATE-CASHBACK");     // When an order is made, an entry in the "customer_credit" table is added. This is the credit "reason". If you change this after some sales were made, the sales won't be listed (see DisplayAffiliateAccountPage function below)
 
define( "AFFILIATE_SELF_AFFILIATE",     true);        // If the affiliate account is the same as the customer account (the customer is the affiliate) do we credit the affiliate account?
 
define( "AFFILIATE_INCLUDE_SHIPPING",     false);     // Include shipping costs in the commission calculation?

Feel free to change the value of each setting according to the affiliate policy you want to implement.


That's it! Your affiliate module is fully ready and functional.
Clem