7.1. Shipping Cost Database

The shipping cost database (located in ProductDir/shipping.asc) is a tab-separated ASCII file with eight fields: code, text description, criteria (quantity or weight, for example), minimum number, maximum number, and cost, query, and options. None of the fields are case-sensitive.

To define the shipping database in a catalog configuration file, set the Variable MV_SHIPPING to what would be its contents.

To set the file to be something other than shipping.asc in the products directory, set the Special directive:

   Special  shipping.asc  /home/user/somewhere/shipping_defs

There are two styles of setting which can be mixed in the same file. The first is line-based and expects six or more TAB-separated fields. They would look like:

default No shipping weight  0   99999999    0

upsg    UPS Ground  weight  0   0   e Nothing to ship!
upsg    UPS Ground  weight  0   150 u Ground [default zip 98366] 3.00
upsg    UPS Ground  weight  150 999999  e @@TOTAL@@ lbs too heavy for UPS

The second is a freeform method with a mode: Description text introducing the mode line. The special encoding is called out by indented parameters. The below is identical to the above:

   upsg: UPS Ground
       criteria    weight
       min         0
       max         0
       cost        e Nothing to ship!

       min         0
       max         150
       cost        u
       table       2ndDayAir
       geo         zip
       default_geo 98366
       adder       3

       min         150
       max         999999
       cost        e @@TOTAL@@ lbs too heavy for UPS

The second format has several advantages. Multiple lines can be spanned with the <<HERE document format, like so:

   upsg: UPS Ground
       criteria    <<EOF
   [perl]
       return 'weight' if $Values->{country} eq 'US';
       return 'weight' if ! $Values->{country};
       # Return blank, don't want UPS
       return '';
   [/perl]
   EOF

The definable fields are, in order, for the tab-separated format:

MODE

The unique identifier for that shipping method. It may be repeated as many times as needed.

DESCRIPTION

Text to describe the method (can be accessed on a page with the [shipping-description] element).

CRITERIA

Whether shipping is based on weight, quantity, price, etc. Valid Interchange tags can be placed in the field to do a dynamic lookup. If a number is returned, that is used as the accumulated criteria. That is, the total of weight, quantity, or price as applied to all items in the shopping cart.
See Criteria Determination below.

MINIMUM

The low bound of quantity/weight/criteria this entry applies to.

MAXIMUM

The high bound of quantity/weight/criteria this entry applies to. The first found entry is used in case of ties.

COST

The method of developing cost. It can be a number which will be used directly as the shipping cost, or a function, determined by a single character at the beginning of the field:

           f       Formula (ITL tags OK, evaluated as Perl)
           x       Multiplied by a number
           [uA-Z]  UPS-style lookup
           m       Interchange chained cost lookup (all items summed together)
           i       Interchange chained cost lookup (items summed individually)

NEXT

The next field supplies an alternative shipping mode to substitute if the cost of the current one is zero.

ZONE

The UPS zone that is being defined.

QUERY

Interchange tags which will return a SQL query to select lines matching this specification. The current mode is replaced with this selection. If there is a query parameter of ?, it will be replaced with the mode name.

QUAL

The geographic qualification (if any) for this mode.

PERL

Perl code that is read and determines the criterion, not the cost. Use the cost option with "f" as the prelim to supply Perl code to determine cost.

TOTAL

Set to the accumulated criterion before passing to Perl.

OPT

Used to maintain UPS and freeform options. Normally these are set by separate lines in the shipping definition.