This isn't your father's UPS module! It offers many more configuration options than Merchant's standard UPS module, such as calculation of "oversize" and "dimensional" weights, declared value insurance, and Hazmat. In addition, it lets you configure products to be shipping independently
in their own box (or multiple quantity per box) and from their own zip code. Individual products can
be flagged to have free shipping, products being shipping in their own box can be specified
to have free shipping on a per-method basis (eg. free UPS ground for product x), and individual methods can be
configured to be free (eg. free UPS ground). Individual methods can be discounted (eg. UPS Ground
25% off). Individual methods can also have specific handling charges assigned to them.
The merchant can specify the maximum weight to put
into individual shipping boxes. The module uses a sophisticated algorithm to pack the boxes
to the maximum weight while maintaining the lowest number of boxes. The methods seen by the customer
in the drop down shipping selection list can be sorted either ascending or descending (or not at all).
Individual products can be configured to ship in their own packaging. The
originating zip code to ship the product from can also be configured and all of the UPS
shipping options are available to be configured for these products as well. Similarly, a category can be configured such that all products in that category will follow the configuration set for that category.
The message which is displayed to the customer in the drop-down
shipping selection list can be individually set for each method. The option to replace
the normal message or to append the message to the normal message
is configurable.
The module does NOT do real-time communication with the UPS site (at least those versions after 4.01). Instead, it stores copies of the UPS rate and zone tables on your server. Those tables are used to calculate the shipping. This results in a much quicker determination of shipping rates. To account for changes in rates, the module's admin provides a "button" to update the rate tables by downloading the latest version from the Miva website.
NOTE: the module currently uses the same rate tables as Merchant's UPS module, so it's capable of offering only domestic shipping (i.e. within the US). I'm working on figuring out a way to extend the capabilities to international shipping
If you're upgrading from a version of the module prior to 4.01, note that the "services" (eg. "residency rates", "confirmation", etc.) are handled differently in this module. Some of those settings may not carry forward in the upgrade so be sure to check your settings after upgrading to make sure that they are set to what you want them to be.
I will not attempt to detail the various UPS shipping methods
and the options available for them (there are simply too many). A very good place to
learn about the various methods can be found in the
UPS Service Guide.
How the module does what it does
As with the standard UPS module, this module generates a list of available
UPS methods, with the associated rates for reach, from which the customer selects their
desired shipping method. However, unlike the standard UPS module
this module lets you set products to be shipped independently. Here's how it goes about
generating that list. It first goes through the basket an item at a time and checks to
see if each item is to be shipped separately. If it is, it calculates the rate for
the various methods for that product (using the configuration options set for it on the individual
product configuration screen), keeping a running total of the shipping rate for
each method as it goes along. After it has gone through the entire basket, it sorts the
remaining products (ie. those that are not configured to be shipped separately) into boxes to
determine the minimum number of packages to use. The "max weight per package" setting is
used to limit how much can be shipped in each package. The weights for these individual packages
are then used to calculate for each package a shipping rate for all of the methods (using the options set
on the main configuration screen). These determined rates are then added to the
rates determined for the products shipping separately to produce a final rate for each UPS method.
Note that the method used to determine the number of boxes
to use to pack the products is not 100% accurate. Unfortunately, a method that
assured that degree of accuracy would take so long to run and require so much
computer power that no one would ever be able to check out of your store! However,
the method used, called a "first fit bin packing" algorithm is sufficiently accurate
to assure that extra shipping won't be calculated for the relatively small number of boxes
sent by the typical merchant. As the number of necessary boxes increases
the chance of mis-packing the boxes increases. In all instances the total
weight that shipping is calculated for will be the same; the total weight of the products
purchased. And if the method mispacks, it will always be in the favor of using too many
boxes.
In Merchant admin, expand your store, then click on the link to Shipping Configuration
under your store. In the right frame you will see a tab at the top for UPS Online Advanced.
Clicking on that tab takes you to
The module's main interface:
Details on each feature of the main interface are listed below that feature in blue.
Enable module?
If this option is not checked the module is "disabled" and will not offer any methods to the customer. No data will be lost and you can "re-enable" it simply by rechecking the box.
Server Address:
Reset to Default Server
This is the URL to Merchant's server which stores the rate and zone tables. You won't ever need to change this unless Merchant changes the path to the script on their server.
The UPS zone and rate tables used by the module to calculate shipping rates are stored on your server. Occasionally, UPS will change their rates. To keep your shipping rate calculations accurate, you can click on the "Update Tables" button to have the module download the latest tables from Miva's website.
UPS charges and additional surcharge to reflect the varying price of fuel. The module does not update this automatically. To make sure that you have the most up-to-date fuel surcharge, visit the url at least once a month to check to make sure that you have the correct rate configured.
Additional Charges:
Declared Value Insurance?
per $100
Packages sent via UPS are insured for a value of $100. If this
option is checked additional insurance will be added to the cost of shipping for
product price over $100. The value used for this field is the basket price of the
product (ie. the price as it appears in the basket including attributes and options).
More information can be found about Declared Value Insurance here. If UPS' current rate of .35 per $100 of insured value changes, you'll need to update this field to make sure that your shipping rates are accurate.
Hazmat Surcharge, Air?
Hazmat Surcharge, Ground?
If you know your packages contain hazard materials by the UPS definition, you can check these fields to have the hazmat surcharge added to the calculated rates. The "Air" surcharge will be added to all methods except "UPS Ground". The "Ground" surcharge will be added only to UPS Ground rates. If the UPS surcharge changes, you'll need to update this field to make sure that your shipping rates are accurate.
Additional Handling Charge
Packages with the longest side measuring over 60 inches or with the second-longest side measuring over 30 inches will be assessed this "Additional Handling" charge. If the UPS surcharge changes, you'll need to update this field to make sure that your shipping rates are accurate.
These surcharges are explained in the UPS service guide. They are downloaded when the rate and zone tables are updated so you do not need to manually maintain them.
Available Shipping Methods:
UPS Next Day Air
UPS Next Day Air Saver
UPS 2nd Day Air
UPS 2nd Day Air A.M.
UPS 3 Day Select
UPS Ground
To make a method available to the customer place a check
in the box next to the method name and click on "update". Note that even
though a method is indicated here to be "available", it might not be available
to the customer at the time of checkout. For example, some orders might have a weight or size which exceeds the limit on some methods.
Origination Zip code:
The zip code that will be used as the "originating" zip code when calculating rates.
Sort:
none
Ascending
Descending
The order to sort the methods displayed to the customer in the drop down
shipping selection list. Sorted by shipping rate.
Offer to PO boxes?
UPS does not ship to Post Office boxes. If you do NOT want UPS to offer methods to addresses which are to P.O. boxes, then enable this option. Note that the module checks for as many combinations of "P.O", "PO", "PO Box", etc as I could think of but I'm not confident that it will catch every address intended to go to a PO box.
Message for 0 weight orders?
Normally, if the total basket weight is 0, the module will not generate any methods to display in the drop down selection box shown to the customer. If no other shipping module generates a method to show, Merchant will generate the "no available shipping methods" message. However, if this option is checked, orders which have 0 weight, will have the Free/0 weight message inserted into the drop down list. This "shipping method" will have a $0.00 cost.
Message for free orders:
This is the message that will be displayed to the customer in the drop down payment selection box, if all of the products in the order have free shipping OR if the total order weight is 0 and you have checked the "Message for 0 weight orders" option above.
Handling only message:
This is the message that will be displayed to the customer in the drop down payment selection box, if the only "rate" calculated for the entire order is a handling charge (i.e. the rates themselves calculated to 0.00 but the handling charge added a "base" rate).
Extra Handling Charge:
The handling that will be added to the determined shipping rate.
Note that this is NOT the UPS Additional Handling option, which is a surcharge added for oversized packages.
How to charge handling?
once per order
per package
per item
This determines if the handling charge will be added only once for the whole order, once for every package in the order, or once for every item in the order.
Charge as percentage?
This determines if the handling charge will be calculated as a percentage of the total order or as a flat fee.
Handling charge cap
This is a cap on the total handling charged (as set in the field above). In this example,
the cap is set at $12. So if a customer purchases items which ship in 5 different boxes, instead of the handling
charge being $15 (5 x $3.00) it will be capped at $12 and that is all the handling that will be charged regardless
of how many boxes are shipped. Note that this cap applies ONLY to the handling field set above. It does not apply
to handling charged on a method basis (as set below) or on handling charged for specific products (as set on the
individual product configuration page). If set to 0, no cap will be applied.
Charge for orders w/ only free shipping?
If this option is checked, then handling will be charged even if all of the products in the basket have free shipping configured for them. If un-checked, if an order contains only free shipping items, no additional handling will be added.
Free shipping for:
UPS Next Day Air
UPS Next Day Air Saver
UPS 2nd Day Air
UPS 2nd Day Air A.M.
UPS 3 Day Select
UPS Ground
This is a listing of all of the shipping methods that have
been "checked" above as being available. To make a shipping method free
to the customer, check the box and update. Free methods will have a shipping
rate of $0.00. In this example, UPS Ground will be offered free to customers.
Free shipping if over:
UPS Next Day Air
UPS Next Day Air Saver
UPS 2nd Day Air
UPS 2nd Day Air A.M.
UPS 3 Day Select
UPS Ground
Again, this is a listing of all of the shipping methods that have
been "checked" above as being available. These settings let you make the specific methods conditionally free,
depending on the order sub total (excluding shipping, tax, and other "order charges"). In other words, you can make
a particular shipping method free if the subtotal equals or exceeds the amount entered into the field next to the method
name. In the above example, UPS Ground shipping will be free if the order subtotal is equal to or greater than $10.00
and 2nd day air will be free if the subtotal is equal to or greater than $40. Note that if the method is checked
as being free in the "free shipping" section above, then the setting for that method has no effect here.
Discount shipping for:
UPS Next Day Air
UPS Next Day Air Saver
UPS 2nd Day Air
UPS 2nd Day Air A.M.
UPS 3 Day Select
UPS Ground
Discount as a percentage?
This is a listing of all of the shipping methods that have
been "checked" above as being available. To discount a particular method (eg.
offer UPS Ground at a 25% discount) enter the value of the discount into the
field next to the shipping method. If the "Discount as a percentage?" field is
checked, the discount entered will be treated as a percentage (eg. enter
25 and the discount will be calculated as 25%). If that check box
is left unchecked, the discount would be treated as a flat rate (in the above
example the discount would then be $25!). In this example, UPS ground is configured
to be offered at a 25% discount.
Handling charge for:
UPS Next Day Air
UPS Next Day Air Saver
UPS 2nd Day Air
UPS 2nd Day Air A.M.
UPS 3 Day Select
UPS Ground
Handling as a percentage?
This is a listing of all of the shipping methods that have
been "checked" above as being available. To provide a method specific handling charge enter
the handling charge for that method. This handling charge will be charged in addition to any
handling charge set above. Note also that the "Handling per package" setting above also
applies to this method specific handling charge. If the "Handling as a percentage" box is NOT
checked then the handling charge will be charged as a flat rate. If it is checked, the handling
will be charged as a percentage of the total rate for that method. In the example above,
UPS 2nd Day Air has a handling charge set for 10% (the "Handling as a percentage" box is checked).
Drop down message:
UPS Next Day Air
UPS Next Day Air Saver
UPS 2nd Day Air
UPS 2nd Day Air A.M.
UPS 3 Day Select
UPS Ground
Append Message?
This is a listing of all of the shipping methods that have
been "checked" above as being available. Here you can set the message to be displayed
for each method in the drop down list of shipping methods at checkout.
Any text entered into the corresponding field will be displayed in the drop down list for that
method. If the "Append Message?" box is selected, the text will be appended after the normal
message displayed (eg. UPS Ground ($4.50)). If it is NOT selected, it will replace the normally
displayed message. If no text is entered here the normal UPS method will be shown. The token %cost%
can be used to represent the cost for that method's rate.
In this example, the message "Ships in 2-3 days" will be appended to the
end of the UPS Ground method in the drop down list. It would then appear such as: UPS Ground
($4.50) Ships in 2-3 days. For 2nd day air, the message "2nd day air costs %cost%" would be displayed to the customer
as "2nd day air costs $10.00" (assuming that 2nd day air costs $10 and that the "append" button is NOT checked).
Package Details:
Box weight:
This "box weight" is a weight added to each package weight before calculating shipping (so if the order will ship in multiple packages it will be added once per-package). You can add the weight of your packaging here so that the calculated rates more accurately reflect your costs.
Max # products per package:
You can limit the number of products shipped in each package. For example, if you set this to 4, and your order has 9 products in it, the module will calculate shipping as if the order were shipping in three separate packages; 2 with 4 products in them, and a third with only 1 product in it.
Max weight per package:
This is the maximum weight the module will attempt to pack into a box. The module
sorts through the products in the order and packs them into boxes in an efficient manner,
attempting to pack them into the least number of boxes. This weight is the limit to
how much it will attempt to pack into each box. The default upon installation is
the UPS maximum weight of 150 lbs. Note: If an individual product is heavier than the maximum
weight set here, then the weight of the product will be used to calculate shipping, unless
the weight is greater than 150lbs. In that case shipping will be calculated as 150 lbs.
Weight Unit
This is where you can select the shipping units that you used for your product weights.
The module will convert the weights to pounds before submitting them to the UPS web site. In this example,
the merchant has used ounces when specifying his product weights and so he has configured the UPS Advanced module
to treat the product weights as ounces so that the module can make the appropriate conversion when calculating the
shipping. [Feature sponsored by Seron Mfg. Co., http://www.seron.com]
Length
Height
Width
These are the package dimensions used by the module to determine if the package is to be subjected to "Oversize 1" or "Oversize 2" rules (for UPS Ground) or "Dimensional weight" (for rates other than UPS Ground). It is not necessary that they be entered in any specific order (i.e. it does not matter if you don't enter the longest dimension into the "length" field). The module will sort them to properly determine which is the longest dimension. If the dimensions are left at 0, the package will automatically NOT be assessed Oversize or dimensional weight.
To get to the configuration screen for the individual products,
expand your store (by clicking on the > next to your store's name in admin), then click on
the "products" link. Select the product that you want to configure in the right frame.
On that product's individual configuration screen you will see a tab for "UPS Online
Advanced". Clicking on that link takes you to the
Individual Product Configuration Screen
You'll notice that many of the configurable options here are identical to those on the
main interface. I won't repeat the description for those items here.
Extra Handling Charge:
How to charge handling?
once per order
per package
per item
This extra handling charge will be added to the shipping total
if this product is one of those being ordered. If the "charged per item" box is checked
then this charge will be assessed for each of this product in the basket. So in this
example, if a person purchases 2 of this item, they will be charged an additional handling
charge of $4.00 (2 x $2.00).
Omit option: (if product is ordered)
UPS Next Day Air
UPS Next Day Air Saver
UPS 2nd Day Air
UPS 2nd Day Air A.M.
UPS 3 Day Select
UPS Ground
You can use these options to omit that shipping method as an available method if the product is in the basket. For example, if this product contains hazardous materials which can only ship via UPS Ground, then you could check off all methods except UPS Ground. If a customer were to put this product in their basket, then only the unchecked UPS Ground would be available as a shipping method, regardless of what other products they have in their basket. If multiple products are in the basket, each with their own restrictions, then only the "commonly allowed" methods will appear as available.
Free Shipping?
If this option is checked, the shipping weight for this product
will NOT be included when determining the shipping weight for the purposes of calculating
shipping. The handling charge configured above WILL still be added to the shipping rate.
Ship in Separate Package?
Checking this option will cause the product to have shipping
calculated as if it will ship in it's own packaging. NOTE that none of the options listed below this on the page will have any affect UNLESS this option is checked.
Origination Zip Code:
When shipping is calculated for this product, this is the zip
code that will be used as the originating zip code (ie. the place from which the
package(s) will be sent).
Max Quantity Per Box:
This determines how many of this product will be shipped in
a single box. But only if the
customer has purchased multiple quantities of the product of course. For example, if a customer
purchases 12 of an item, and the max quantity is set to "3", then shipping will be
calculated to send 4 different packages with a weight of 3 x the product weight for
each one.
OR
Split into how many boxes:
In the alternative, you can configure the module to calculate shipping for this product as if it ships in separate packages such as might be the case with a large speaker system which sells as a single product but cannot ship in a single package. In the "Split into how many boxes" field you indicate how many boxes to split the shipping in to.
Split for weight (xx|yy|etc.)
In this field you indicate how the product weight is to be split between the boxes. The format is weight in box 1|weight in box 2|weight in box 3. As an example, if you want to ship your product in 3 boxes with a weight of 10, 20, and 30 pounds, you would enter 10|20|30 into this field.
Split for cost (xx.xx|yy.yy|etc.)
In this field you indicate how the product price is to be split between the boxes. This is used to calculate the "added value insurance" (if that option is configured) for each package. The format is price in box 1|price in box 2|price in box 3.
The methods checked here will be shipped free. A rate for this product will not be
calculated when determining the total shipping for that method.
Discount shipping for:
UPS Next Day Air
UPS Next Day Air Saver
UPS 2nd Day Air
UPS 2nd Day Air A.M.
UPS 3 Day Select
UPS Ground
Discount as a percentage?
When calculating shipping for this product the discount will be
applied to the determined rate. It works the same was as the configuration on the
main admin screen.
Handling charge for:
UPS Next Day Air
UPS Next Day Air Saver
UPS 2nd Day Air
UPS 2nd Day Air A.M.
UPS 3 Day Select
UPS Ground
Handling as a percentage?
When calculating shipping for this product the handling configured for each method will be
applied to the determined rate. It works the same was as the configuration on the
main admin screen.
Package Details:
Box weight:
Length
Height
Width
In addition to being able to configure the options for individual products, the module will also let you configure them for individual categories. That configuration will then be used for any product in that category. Note that if a product is in multiple categories, then the module will use the category configuration of the first category that it finds to which the product is assigned. There isn't any way for it to know which specific category the product was purchased from.
To get to the configuration screen for the individual categories,
expand your store (by clicking on the > next to your store's name in admin), then click on
the "Categories" link. Select the category that you want to configure in the right frame.
On that category's individual configuration screen you will see a tab for "UPS Online
Advanced". Clicking on that link takes you to the
Individual Category Configuration Screen
You'll notice that many of the configurable options here are identical to those on the
product and main interface. I won't repeat the description for those items here.
Override product settings?
If this option is checked, then any configuration on the individual product's UPS Online Advanced tab will be overridden by the configurations on this page. If the option is not checked, then the configuration here will be used for all products in the category UNLESS the product has a specific configuration already set for it, on it's own UPS Online Advanced tab.
Extra Handling Charge:
How to charge handling?
once per order
per package
per item
This extra handling charge will be added to the shipping total
if this product is one of those being ordered. If the "charged per item" box is checked
then this charge will be assessed for each of this product in the basket. So in this
example, if a person purchases 2 of this item, they will be charged an additional handling
charge of $4.00 (2 x $2.00).
Omit option: (if product is ordered)
UPS Next Day Air
UPS Next Day Air Saver
UPS 2nd Day Air
UPS 2nd Day Air A.M.
UPS 3 Day Select
UPS Ground
You can use these options to omit that shipping method as an available method if the shipping is in the basket. For example, if this product contains hazardous materials which can only ship via UPS Ground, then you could check off all methods except UPS Ground. If a customer were to put this product in their basket, then only the unchecked UPS Ground would be available as a shipping method, regardless of what other products they have in their basket. If multiple products are in the basket, each with their own restrictions, then only the "commonly allowed" methods will appear as available.
Free Shipping?
If this option is checked, the shipping weight for this product
will NOT be included when determining the shipping weight for the purposes of calculating
shipping. The handling charge configured above WILL still be added to the shipping rate.
Ship in Separate Package?
Checking this option will cause the product to have shipping
calculated as if it will ship in it's own packaging. NOTE that none of the options listed below this on the page will have any affect UNLESS this option is checked.
Origination Zip Code:
When shipping is calculated for this product, this is the zip
code that will be used as the originating zip code (ie. the place from which the
package(s) will be sent).
Max Quantity Per Box:
This determines how many of this product will be shipped in
a single box. But only if the
customer has purchased multiple quantities of the product of course. For example, if a customer
purchases 12 of an item, and the max quantity is set to "3", then shipping will be
calculated to send 4 different packages with a weight of 3 x the product weight for
each one.
OR
Split into how many boxes:
In the alternative, you can configure the module to calculate shipping for this product as if it ships in separate packages such as might be the case with a large speaker system which sells as a single product but cannot ship in a single package. In the "Split into how many boxes" field you indicate how many boxes to split the shipping in to.
Split for weight (xx|yy|etc.)
In this field you indicate how the product weight is to be split between the boxes. The format is weight in box 1|weight in box 2|weight in box 3. As an example, if you want to ship your product in 3 boxes with a weight of 10, 20, and 30 pounds, you would enter 10|20|30 into this field.
Split for cost (xx.xx|yy.yy|etc.)
In this field you indicate how the product price is to be split between the boxes. This is used to calculate the "added value insurance" (if that option is configured) for each package. The format is price in box 1|price in box 2|price in box 3.
The methods checked here will be shipped free. A rate for this product will not be
calculated when determining the total shipping for that method.
Discount shipping for:
UPS Next Day Air
UPS Next Day Air Saver
UPS 2nd Day Air
UPS 2nd Day Air A.M.
UPS 3 Day Select
UPS Ground
Discount as a percentage?
When calculating shipping for this product the discount will be
applied to the determined rate. It works the same was as the configuration on the
main admin screen.
Handling charge for:
UPS Next Day Air
UPS Next Day Air Saver
UPS 2nd Day Air
UPS 2nd Day Air A.M.
UPS 3 Day Select
UPS Ground
Handling as a percentage?
When calculating shipping for this product the handling configured for each method will be
applied to the determined rate. It works the same was as the configuration on the
main admin screen.
This module installs like any typical shipping module.
To install the module:
1.
If you prefer to ftp the module file (BROK_UPSA.mv or BROK_UPSA.mvc) to your server, do so now.
For convenience, place it into the Merchant2/modules/shipping directory (for versions 3.x and below) or Merchant2/4.xx/modules/shipping directory (for versions 4.xx and above; where xx is the particular version of Merchant that you have installed). 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 module file to your server, enter
the path to that file into the text field (usually modules/shipping/BROK_UPSA.mv or modules/shipping/BROK_UPSA.mvc).
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 >Shipping Configuration.
In the right frame, you will see the module listed near the top with a check box
next to the name. Check that box, and click on "update".
6.
The module is now installed into your store. You will see a new tab in the right
frame, UPS Online Advanced. Clicking on that tab takes you to the
module's administration screen. The first time that you visit the module's admin interface, you will be prompted to enter the license key. Enter they key, agree to the license, and click on "update".
