This module gives a merchant the ability to track the purchase of products assigned to vendors. The module logs all purchases and sends notification emails to the vendor assigned to the products. In addition, the module is capable of tracking payouts due to vendors and provides for a convenient interface to process payouts and generate "invoices". Of course use of the payout feature is optional.
Of course there is a little more to it than that and this module provides for a great deal of flexibility:
The format of the email sent to the vendors is completely configurable with the use of tokens to specify the vendor and order information. A default template can be configured for the email and individual vendors can also have a template specifically configured for them.
Similarly, the invoice showing the payout being made to the vendor can be configured with a default template or with a template specific to the particular vendor. Like the email, the invoice template uses tokens to represent information about the vendor (name, code, payout due, total payout paid, date paid, etc.) and the products purchased.
Payouts can be calculated and tracked as a percentage or flat rate (eg. $5/product sold). The percentage can be based on the product's cost, price paid (eg. prices affected by sales), or list price. In additon, the payout calculation can be configured "globally" for the vendor (applies by default to all assigned products) and individual products can also have a specific payout method associated with them (i.e. a vendor can be provided a different payout claculation method for a specific product).
The module's admin interface provides for a simple listing of all payouts due with a link to each vendor's specific payout screen. Payout periods can be specified for each vendor and can be configured in just about time span you would want and can be set to be paid on any particular day of the week, month, year, etc.
After installation, the module adds a new tab to the Fulfillment Configuration page. Vendor Manager. The first thing you see when clicking on this tab are three "sub tabs", Vendors, Process Payouts, and Options. By default the Vendors tab is selected but we will first discuss the Options tab.
Clicking on the "Options" tab takes you to the screen at which you can configure the various options of the module.
If this option is checked, vendor data will be collected and emails sent. Otherwise, the module will be inactive but no current data or settings lost.
Mailhost
Subject
From Address
CC
The settings that will be used to send the notification email to the vendor.
Default Message
restore default
The actual HTML that will be used to generate the notification email. This is the default and will be used only if no specific template is configured for individual vendors. Tokens can be used to represent a great deal of "dynamic" data in this template. Go here to view a list of tokens that can be used in this template: Email Tokens. Go here to view a short primer on the use of tokens in general: Tokens Primer. If the "restore default" box is checked and the page updated, the field contents will be replaced with the default settings (ie. the settings that first appear when the module is installed).
Default Product data template:
restore default
The actual HTML that will be used to generate the listing of products to replace the %products% token in the email message template. This is the default and will be used only if no specific template is configured for individual vendors. Tokens can be used to represent a great deal of "dynamic" data in this template. Go here to view a list of tokens that can be used in this template: Product Tokens. Go here to view a short primer on the use of tokens in general: Tokens Primer. If the "restore default" box is checked and the page updated, the field contents will be replaced with the default settings (ie. the settings that first appear when the module is installed).
Default Attribute data template:
restore default
The actual HTML that will be used to generate the listing of attributes to replace the %attributes% token in the Products template. This is the default and will be used only if no specific template is configured for individual vendors. Tokens can be used to represent a great deal of "dynamic" data in this template. Go here to view a list of tokens that can be used in this template: Attribute Tokens. Go here to view a short primer on the use of tokens in general: Tokens Primer. If the "restore default" box is checked and the page updated, the field contents will be replaced with the default settings (ie. the settings that first appear when the module is installed).
Default Invoice template:
restore default
The actual HTML that will be used to generate the payout invoice. This is the default and will be used only if no specific template is configured for individual vendors. Tokens can be used to represent a great deal of "dynamic" data in this template. Go here to view a list of tokens that can be used in this template: Invoice Tokens. Go here to view a short primer on the use of tokens in general: Tokens Primer. If the "restore default" box is checked and the page updated, the field contents will be replaced with the default settings (ie. the settings that first appear when the module is installed).
Invoice Products template:
restore default
The actual HTML that will be used to generate the listing of products to replace the %products% token in the invoice template. This is the default and will be used only if no specific template is configured for individual vendors. Tokens can be used to represent a great deal of "dynamic" data in this template. Go here to view a list of tokens that can be used in this template: Product Tokens. Go here to view a short primer on the use of tokens in general: Tokens Primer. If the "restore default" box is checked and the page updated, the field contents will be replaced with the default settings (ie. the settings that first appear when the module is installed).
Invoice/Attribute data template:
restore default
The actual HTML that will be used to generate the listing of attributes to replace the %attributes% token in the Invoice Products template. This is the default and will be used only if no specific template is configured for individual vendors. Tokens can be used to represent a great deal of "dynamic" data in this template. Go here to view a list of tokens that can be used in this template: Attribute Tokens. Go here to view a short primer on the use of tokens in general: Tokens Primer. If the "restore default" box is checked and the page updated, the field contents will be replaced with the default settings (ie. the settings that first appear when the module is installed).
Clicking on the "Vendors" tab brings up to two new sub-tabs (or sub-sub-tabs if you will): Listing, and New Vendor. The "Listing" tab is expanded by default, but continuing with our habit of taking these somewhat out of order, We'll discuss the "New Vendor" tab first. Clicking on that tab takes you to a form where the information for a new vendor can be entered. You can enter the vendor's contact information as well as decide how the vendor is to be paid for purchases made in your store.
Modules
Vendor Manager
Vendors
|
Process Payouts
|
Options
Listing
|
New Vendor
Vendor code:
First Name:
Last Name:
Email:
Company:
Phone 1:
Phone 2:
Fax:
Address:
City:
State/province:
Zip/postal code:
Country:
Of the above Vendor information, only the Vendor Code is required. It is this which the module uses to identify the vendor. The remainder of the information is used in the generation of the notification email and template.
The follow section is where you set how the vendor's payouts are to be calculated and tracked. Note that this section is optional. If no information is entered, no trackign will occur.
Percentage payout:
Per product payout:
If a "percentage" payout is configured, then the payout will be calculated as percentage. If a "per product" payout is configured, the payout will be calculated as that amount per product sold. Note that both payout methods can be used at once.
Payout Basis:
This is the basis used to calculate the payout. If the "list price" is selected then the payout will be calculated using the product's price as set in Merchant admin. If "cost" is selected then the payout will be calculated using the product's cost as set in Merchant admin. If "price paid" is selected, the payout will be calculated on the actual price paid for the product (ie. the price listed in the customer's order).
Payout Period:
This is the time period over which to calculate the payout. The first field represents the days in the period if payout is to occur every certain number of days. In that case the second field would contain the "days" option. If any of the other options are selected in the drop down list, then the number in the first field represents the day of that time period. For example, entering 3 in the first field and "days" in the second would calculate a payout every 3 days. If a 1 is entered in the first field and "day of every week" is selected in the second then payouts will be calculated to be made the first day of every week.
Email subject
Email message
Product data template:
Attribute data template:
Invoice Product template:
Invoice Attribute data template:
Invoice template:
These fields are the same as the corresponding fields on the "options" page. If any information is entered in these fields, then it will be used in preference to defaults configured on the "options" page.
The "Listing" tab shows a listing of all vendors: the Vendors Listing page
The various checkboxes at the top dictate what data about the vendor is shown in the listing. Only those fields which are checked will appear.
Modules
Vendor Manager
Vendors
|
Process Payouts
|
Options
Listing
|
New Vendor
id
code
name
company
basis
period
last
type
paid
Search:search
Delete
Vendor ID
Code
Name
Company
Period
last paid
%
flat
basis
total paid
33
firstvendor
First Vendor
mikeWorks
1 dmonth
12/1/2001
5.00
price
50.00
edit
34
secondvendor
Second Vendor
Vendors.com
1 d2week
1/1/2002
90.00
cost
0.00
edit
1-2
reload
The vendor "code" is a link back to that vendor's specific configuration screen as is the "edit" icon in the far right column.
Clicking on one of the linked vendor codes or the "view" icon on the far right side brings up the configuration area specific to that particular vendor. You'll see that 5 new tabs are brought up: Vendor: name of vendor, Products, Due, Paid, and Orders. The first tab, Vendor:first, in this example, is a screen showing the configuration settings for this particular vendor. NOTE: these settings are identical to those on the New Vendor page, so consult that page for details.
The second tab on the vendor specific settings, is the "Products" tab. This is where you can associate products with your vendors. Whenever an assigned product is purchased an email is sent to the vendor. Note that only one email is sent to each vendor. That email will list all of the products in that order which are associated with the vendor.
Vendors
|
Process Payouts
|
Options
Vendor: firstvendor
|
Products
|
Due
|
Paid
|
Orders
All
|
Unassigned
|
Assigned
Search:
search
Assigned
Code
Name
Percentage
Flat rate
Basis
rocket
Rocket
horse
Horse
2
ship
ship
train
Train
1-8
refresh
The three links across the top will cause the page to show, respectively, all products, only those unassigned to any vendor, and only those assigned to this vendor. Unassigned products will have a checkbox so that they can be assigned (by checking the box and updating the page) to the current vendor. Products assigned to other vendors will have that vendor's id# in that column. To unassign a product simply uncheck the box and update the page. The "percentage", "flat rate", and "basis" fields correspond to those fields on the vendor's configuration screen. Those settings can be overriden for each product by providing figures specific to each product.
Note that each of the products also has a tab, Vendor Manager, on it's Product Configuration page in admin. Clicking on that tab takes you to a screen where you can select which vendor that product is assigned to as well as specific payout settings for that product and vendor.
Assigned to:
first
percent:
flat rate:
basis:
second
none
Clicking the "Due" tab takes you to a page showing all of the payouts (if any) due for that vendor.
Vendors
|
Process Payouts
|
Options
Vendor: firstvendor
|
Products
|
Due
|
Paid
|
Orders
Order #
Order Date
Code
Name
Due
Payout for 1/01/2002-1/31/2002
1179
1/27/2002
ship
ship
$6.00
1179
1/27/2002
horse
Horse
$6.00
Color
roan
$0.00
1179
9/3/2001
rocket
Rocket
$5.50
Process payout
Total:
$17.50
notes:
This screen will show a list of all pending payouts (in case you had failed to process a payout when it was due). Although all due payouts will be listed, only the oldest payout can be processed at a time. So to process all payouts, including those past due, the oldest payout must be processed, then the next oldest, etc. The "notes" field can be used to configure a note that will be included in the invoice (use the %note% token in the invoice template). Once a payout has been processed, it will be listed on the "Paid" page.
Clicking the "Paid" link brings you to a page listing all of the payouts made to that vendor. In this case you will see that only one payout has been made to this vendor.
Vendors
|
Process Payouts
|
Options
Vendor: firstvendor
|
Products
|
Due
|
Paid
|
Orders
Search:search
/
/
Delete
Payout #
Date Paid
Amount
1
1/31/2002
17.50
invoice
note:
Bob, don't forget my kickback
1-1
refresh
This page is pretty straightforward. Just a listing of all payouts that have been made to the vendor. In the far right column is a link to that payout's invoice (uses the Invoice template to generate the invoice in a new window).
Clicking on the "invoice" link on the right side of each payout brings up a new window containing the "invoice" for this payout.
Clicking on "print" from the top frame will only print the contents of the bottom frame. The bottom frame is the Invoice template with the data for that particular vendor payout.
Clicking on the "Orders" link brings up a listing of all of that vendor's products that have been sold.
This page shows the order # in which the product was purchased, the date of purchase, the payout that resulted from that sale, and the date (if any) that payout was made for that purchase.
Vendors
|
Process Payouts
|
Options
Vendor: firstvendor
|
Products
|
Due
|
Paid
|
Orders
Search:Search
/
/
Delete
Order #
Date
Code
Name
Quantity
Payout
Date paid
1302
1/28/2002
ship
Ship
1
$12.00
1/31/2002
1302
1/28/2002
train
Train
1
$12.00
1/31/2002
1-3
Refresh
Last but not least, clicking on the "Process Payouts" tab in the top row of tabs will bring you, by default, to a page listing all the payouts that are currently due. Clicking on the "all" subtab wil show a list of all due payouts AND when the the next payout is due for each vendor. The vendor's code is a link to that vendor's "Due" page.
This module installs like any typical fulfillment module.
To install the main module:
1.
If you want to ftp the module file (BROK_VENDORS.mv) to your server, do so now. For convenience,
place it into the Merchant2/modules/fulfill directory. In Merchant 4.xx stores, the file needs to go into the Merchant2/4.xx/modules/fulfill
directory. Where 4.xx corresponds with your current Merchant version (there may be several 4.xx directories, one for
each previous version of Merchant 4.x you upgraded from. Note that your Merchant scripts might NOT be installed
in a directory called Merchant2/. Although most setups use this directory. If your's
uses a different directory, make sure you put the module there
2.
Enter into admin and expand >Modules in the left frame.
3.
Click on the link to "Add Module"
4.
In the right frame, you'll see a text entry field with an "upload module" button next
to it. If you ftped the BROK_VENDORS.mv file to your server, enter the path to that
file into the text field (usually modules/fulfill/BROK_VENDORS.mv). Click on the "add" button.
If you did not ftp the file to the server, click on the 'upload' icon next to the text
entry field. This will pop up a small window. Enter the path to the file on your local
computer or click on the "browse" button to browse your hard drive to find it. After you
have the path in the text entry field click on the "upload" key. When you're back to the
right frame, click on the "Add" button. After a short delay, you should see a notification
that the module was installed and you will see it at the bottom of the list of installed
modules in the left frame.
5.
The module is now installed into your "mall", but still needs to be installed
into your store. Expand your store. Then Expand >Order Fulfillment Configuration.
In the right frame, you will see the module listed near the top with a checkbox
next to the name. Check that box, and click on "update".
6.
The module is now installed into your store. You will see the 3 new tabs in the right
frame.
A primer on tokens (or at least how this module uses them):
In short, a token is any text string that is replaced with something else (ie. some other text string) in later
processing. For example, if you were using mailmerge software to send out letters to customers, you might use a
token to represent the customer's name in the body of the letter. Then when you do the merge, the token is replaced with the customer's name.
With this module (and actually several of my other modules), you can use tokens to represent the information about the vendor, the lrders, details of the store etc.
As an example, say you wanted to display in the notification email to the vendor, the vendor's first name, last name, and the order id (over simplified obviously) in the format:
Michael Brock, An order has been placed at our store
Order #: 1402
To represent these in a generic form that will correctly display the data when the email is sent you would use the form:
%vendor_fname% %vendor_lname%, An order has been placed at our store
Order #: %orderid%
Then when the email is sent, each of the tokens will be replaced with the respective data.
Because the email sent in text format, it is difficult to format the layout of the email. One way to properly align things is to use spaces. Fortunately, almost all of the tokens that can be used with this module can be formatted to add spaces on to the right of the data that is displayed. So while the tokens:
%vendor_fname% %vendor_lname%
will be displayed with only 1 space between them, the tokens:
%vendor_fname|20%%vendor_lname%
would be displayed with 20 spaces between them, regardless of the length of the key.
Tokens which can be used in the email message and subject to the vendor.
All of the tokens below can be padded on the right side with spaces by modifying the token to be of the form: %name|xx% where xx is the number of spaces which will be added to the right of the token when it is replaced in the email. For example, to show the order id with 20 spaces added to it's right side you could
use the token: %orderid|20%.
%vendor_id%
vendor_id
%vendor_code%
code
%vendor_email%
email
%vendor_fname%
fname
%vendor_lname%
lname
%vendor_company%
company
%vendor_phone1%
phone1
%vendor_phone2%
phone2
%vendor_fax%
fax
%vendor_address%
address
%vendor_city%
city
%vendor_state%
state
%vendor_zip%
zip
%vendor_country%
country
%vendor_start%
Vendor's start date
%vendor_po_pertyp%
Vendor's period type (ie. dweek, d2week, dmonth, d2month, etc)
%vendor_po_pernum%
period length or day
%vendor_po_basis%
basis of payouts (ie. cost, list price, paid price)
%vendor_po_paid%
total amount paid out to date
%vendor_po_last%
day of last period ending
%vendor_po_lastpd%
day the last payout was processed
%todaysdate%
today's date
%orderid%
Order id
%cust_id%
Order cust_id
%ship_fname%
Order ship_fname
%ship_lname%
Order ship_lname
%ship_email%
Order ship_email
%ship_comp%
Order ship_comp
%ship_phone%
Order ship_phone
%ship_fax%
Order ship_fax
%ship_addr%
Order ship_addr
%ship_city%
Order ship_city
%ship_state%
Order ship_state
%ship_zip%
Order ship_zip
%ship_cntry%
Order ship_cntry
%bill_fname%
Order bill_fname
%bill_lname%
Order bill_lname
%bill_email%
Order bill_email
%bill_comp%
Order bill_comp
%bill_phone%
Order bill_phone
%bill_fax%
Order bill_fax
%bill_addr%
Order bill_addr
%bill_city%
Order bill_city
%bill_state%
Order bill_state
%bill_zip%
Order bill_zip
%bill_cntry%
Order bill_cntry
%storelink%
store link
%storename%
Store name
%products%
list of products/attributes
Tokens which can be used in the invoice template. Note that this template, being in html format, does not need the spacing (eg. %orderid|020%) format of the email template and that format is not available for these tokens.
%vendor_id%
vendor_id
%vendor_code%
code
%vendor_email%
email
%vendor_fname%
fname
%vendor_lname%
lname
%vendor_company%
company
%vendor_phone1%
phone1
%vendor_phone2%
phone2
%vendor_fax%
fax
%vendor_address%
address
%vendor_city%
city
%vendor_state%
state
%vendor_zip%
zip
%vendor_country%
country
%vendor_start%
Vendor's start date
%vendor_po_pertyp%
Vendor's period type (ie. dweek, d2week, dmonth, d2month, etc)
%vendor_po_pernum%
period length or day
%vendor_po_basis%
basis of payouts (ie. cost, list price, paid price)
%vendor_po_paid%
total amount paid out to date
%vendor_po_last%
day of last period ending
%vendor_po_lastpd%
day the last payout was processed
%todaysdate%
today's date
%note%
the note entered when the payout was processed
%products%
products listing
The %products% token in the email (and invoice) will be replaced with a listing of all products in that order or payout. The format of that listing is set by the "Default Product template" for the notification email, and the "Invoice product template" for the invoice template. The tokens that can be used:
%prodname%
%prodcode%
%prodweight%
%prodprice%
%prodcost%
%prodpaid%
%prodquantity%
%produpsold%
%prodtaxable%
%prodpayout%
%prodtotal%
%attributes%
The %attributes% token in the %products% template will be replaced with a listing of all attributes that were selected for that product. The format of that listing is set by the "Default Attribute template" for the notification email, and the "Invoice attribute template" for the invoice template. The tokens that can be used:
