Legacy Documentation

Documentation for versions of Zone Based Shipping prior to version 2.0

Quick Start Guide

Please view the screenshots to help put this guide into context. Dont forget to click 'Save' to save everything when you have finished and also activate Zone Based Shipping at Dashboard > eCommerce > Shipping.

1. Define your zones

List names for the zones you will be shipping to. You can re-arrange zones by dragging them up or down.

2. Map addresses to zones

Begin with rules for Countries, then where necessary insert after any country rule one or more additional rules for State/Province, Town/City or Postal Code within that country. A rule for a State/Province, Town/City or Postal Code only applies to the preceding Country.

You must start with a country rule. Then follow it with all other rules within that country. Other rules are only applied within a country rule, even if you only ship to one country.

You can re-arrange address rules by dragging them up or down. Only have a "default" match on the last row of the list; a default rule will always match and subsequent rules will be ignored.

3. Delivery Options

List the delivery options that your customers may select between. You can re-arrange options by dragging them up or down. If you only have one delivery option, it will not be shown on the Cost Rules table.

4. Select cost basis

Tick what measures you want to use from the cost basis and whether product specific modifiers are to be applied.

Selecting Enable excess cost calculation will provide an additional table under the Unmatched Cost tab. This enables rates to be set for excess on any selected cost basis. See Excess cost calculation below.

5. Enter cost rules

For each zone and delivery option within the zone, enter one or more rows with shipping cost ranges for the Cost Basis measures you have selected. The shipping cost table will automatically sort to match the zone definitions and Cost Basis measures.

By default the shipping cost is calculated by applying the rules to the entire cart. However, options can be selected to calculate cost for each item or product separately and then add them all up at the end.

The message associated with each rule, excess rules or the unknown cost message is displayed on the checkout shipping cost row. When calculating cost by Product or Item, the message associated with the first item in the cart will be used.

The rules in the table will be automatically sorted into the order in which they are applied. You can also click Sort Rules to sort them at any time. The order in which they are sorted is:

  1. Zone
  2. Cost basis from left to right
  3. Delivery option
  4. Shipping cost
  5. Delivery message

You can change the order in which cost basis rules are applied or remove cost basis rules entirely by setting a site configuration option (see below), but beware that doing so will change the meaning of existing rules.

With most shipping agents, after a certain point further costs become proportional to the size of the order. To take advantage of this, design Cost Rules up to that point, then set excess cost rates on the Unmatched Cost tab to continue.

6. Unmatched cost rules

When a cart does not match any of the Cost Rules or Excess cost rates, the Unknown Cost Message will be returned for display on the checkout shipping cost row. The same placeholders as for the Cost Rules can be used within the unknown cost message.

When Enable excess cost calculation is selected under the Cost Basis tab, the excess cost table will be enabled and shown on the Unmatched Cost tab.This table can be used to set up excess rates for zones and delivery options.

Symbols within messages

Placeholders can be used within any Cost Rule message, the Unknown Cost message or Excess Cost message to customise the shipping note shown to the customer.

Consistency

Going back and forth between the tabs, as you edit them the rules you have entered will as far as possible maintain consistency. Nevertheless, it is possible to create rules that are confused or conflicting, or sometimes it is just hard to get the rules right. Hence...

Diagnostic assistance

To help developers create complex sets of rules, the Rule Diagnostics page enables tracing of rule logic through the checkout process. The trace is output to the Log at Dashboard > Reports > Logs. Rule Diagnostics should only be enabled to help solve problems and should not be left active on production sites.

While learning to use Zone Based Shipping, regularly reading the diagnostic trace in the Log can be a great help in understanding how your rules are being interpreted and applied. Rule import & export You can use the Export and Import pages to move complete sets of rules between sites.

Finally...

Dont forget to click 'Save' to save everything when you have finished. You also need to activate Zone Based Shipping at Dashboard > eCommerce > Shipping.

Developers may find the Quick Log View add-on useful when developing rules.

Zone Based Shipping - In more Detail

Please view the screenshots to help put this guide into context.

Cost Basis

The Cost Basis table selects what measures will be available for use in the Shipping Cost Rules.

  • Weight – The total weight of all items in the order will be added up to give a total weight for the cart.

  • Dimension – The maximum single dimension across all items in the order. This will typically be of use where a shipping agent charges a premium for bulky items.

  • Sum of Dimensions – The dimensions of each product will be summed, then the maximum across all items in the order will be used. This will typically be of use where a shipping agent charges a premium for bulky items.

  • Volume – The volume of all items will be calculated from the dimensions, then added up to give a total volume for the cart.

  • Items – A count of the total number of items in the cart.

  • Products – A count of the total number of different products in the cart.

  • Value – The value of the cart.

     

You can change the order in which cost basis rules are applied or remove cost basis rules entirely by setting a site configuration option (see below), but beware that doing so will change the meaning of existing rules.

Modifiers

Product shipping modifiers can be incorporated in two ways:

  • As a multiplier applied to a product within any of the above Cost Basis selections. For example, applied to the volume of each item to allow for packaging.

  • Actually as a Cost Basis item, where Shipping Cost Rules can be based on either a maximum of the product shipping modifiers, or a sum by item of the product shipping modifiers.

Advanced Attributes

Zone Based Shipping recognises attributes to modify the shipping cost rule calculations. These attributes can be created and named through the Attributes page within Zone Based Shipping, then assigned to individual products through the usual eCommerce product edit pages.

  • "Numeric" attribute zone_shipping_measure. The attribute will now be available as a cost basis for sum and maximum.
  • "Boolean" attribute zone_shipping_never_calculate. When set, a product is not entered into the shipping calciulation.
  • "Boolean" attribute zone_shipping_always_calculate. When set, a product is always entered into the shipping calciulation, even if it doesn't require shipping.
  • "Select" attribute zone_shipping_cart_group. Splits a cart into groups of products. Can be used to group shipping calculations and enable a split shipping message.

Zone Shipping Measure

If the above Cost Basis measures are not enough, Zone Based Shipping also recognises a ‘zone_shipping_measure’ attribute.

If you want to ship ducks by the number of feathers, animals by the number of legs or cars by the number of wheels, declare a numerical product attribute with the handle ‘zone_shipping_measure’ and whatever name you like. The Cost Basis tab will then show options to use the sum of the zone_shipping_measure and the maximum zone_shipping_measure.

Zone Shipping Never Calculate

Enter whatever name you like for a product attribute with the attribute handle "zone_shipping_never_calculate" of type "boolean". When checked for a product, that product will never be included in the shipping calculation.

Zone Shipping Always Calculate

Enter whatever name you like for a product attribute with the attribute handle "zone_shipping_always_calculate" of type "boolean". When checked for a product, that product will always be included in the shipping calculation. When set, this attribute takes precedence over Zone Shipping Never Calculate above, except when all items in the cart are marked Zone Shipping Never Calculate, in which case none are calculated.

Zone Shipping Cart Group

Enter whatever name you like for a product attribute with the attribute handle "zone_shipping_cart_group" of type "select". This attribute may then be used to group cart calculations and enable the split cart message. You will need to add select options to this attribute through Dashboard > eCommerce > Products > Attributes. The value "Any" is automatically added and if assigned means there are no limitations on what other products a product can be shipped with. Products grouped "Any" will be by default be grouped with whatever other group is first encountered in the cart, though that can be modified using the site constant ZBS_MAP_ANY_GROUP.

Options for ZBS_MAP_ANY_GROUP are:

  • default - the default option, Products grouped "Any" will be grouped with whatever other group is first encountered in the cart.
  • first_in_cart - same as the default option.
  • last_in_cart -  Products grouped "Any" will be grouped with whatever other group is last encountered in the cart.
  • largest_group -  Products grouped "Any" will be grouped with whatever other group is most numerous in the cart.
  • smallest_group -  Products grouped "Any" will be grouped with whatever other group is most numerous in the cart.
  • "Group name" - Products grouped "Any" will be grouped with a specified group name in the cart.

Explain Options

For each Cost Basis measure, the ‘explain’ options allow site administrators to decide whether its application will be shown to customers during the checkout process.

Shipping Cost Rules

Shipping cost rules are applied to a customer's cart during the checkout process to determine what the actual shipping cost will be. Each address zone should have one or more corresponding rules.

A rule comprises the zone it applies to and one or more Cost Basis measures, as selected by the Cost Basis tab. The customer’s cart is sequentially matched against rules until a matching rule is found and the cost associated with that rule is then returned as the shipping cost for the cart.

The table of Shipping Cost Rules will automatically sort to follow the order in which the zones are defined and then numerically left to right by the Cost-Basis measures.

A rule matches when all Cost-Basis measures are less than or equal to the value entered for the rule. For example, if you have defined a ‘Local’ shipping zone and selected ‘weight’ as the ‘Cost-Basis’, you could then specify shipping costs for orders up to 1kg, up to 10kg, and up to 50kg. (All units are configurable – see Units).

If any cost basis measure is greater than the value for that rule, then the rule does not match.

Cost Basis measures left blank are ignored, so the match is tested on the remaining measures in the rule.

Setting a cost basis measure to ‘default’ means that the rule will always pass for that zone, irrespective of other measures in that rule. As a consequence, 'default' should only be used in the last rule for each zone.

Split cart message

Where a the zone_shipping_cart_group attribute is defined and a cart contains two or more groups other than 'Any', the shipping message defined in the field "Split cart message:" will be used in preferance to individual rule messages. If left empty, individual rule messages will be concatenated for such carts.

Unknown Cost Message

If the customer’s cart does not match any of the rules, the ‘Unknown cost message’ will be shown with a shipping cost of ‘0’. This message defaults to 'UNKNOWN SHIPPING COST'', but can be replaced with any text.

If this is not convenient for a business, it is up to the site administrator to make sure the Shipping Cost Rules are comprehensive enough that it will never happen.

For developers, this message is within an html span with the ‘zone-tbd’ so it can be further styled. Another option for developers which is outside the scope of the Zone Based Shipping package is to add some jQuery to the checkout page to detect this message/class and remove the ‘Next’ button so that orders with an unknown shipping cost cannot be processed further.

Excess cost calculation

Excess cost calculation is selected with a check box under the Cost Basis tab and shown on the Unmatched Cost tab.

This table can be used to set up excess rates for zones and delivery options. The quantity of each Cost Basis excess can be calculated exactly, or rounded up to the nearest integer value, as selected by the Cost Basis option Round up excess quantities to integer values.

Excess rates are accumulated for each enabled cost basis and are proportional to the quantities involved.

Rule Messages

The message associated with each rule or the unknown cost message is displayed on the checkout shipping cost row. When calculating cost by Product or Item, the message associated with the first item in the cart will be used.

Placeholders can be used within any message including the unknown cost message to insert information about the shipping:

  • {{zone}} or {{shipping-zone}} - the zone matched.
  • {{delivery}} - the delivery option.
  • {{cart-weight}} - the cart weight.
  • {{mod-cart-weight}} - the modified cart weight.
  • {{items}} - the number of items in the cart.
  • {{products}} - the number of products in the cart.
  • {{cost}} - the calculated shipping cost.
  • {{null}} - forces a null return, so no shipping method - see also {{error}} below.
  • {{error}} - any text after after {{error}} will be shown by eCommerce as an error message and eCommerce will not allow the shipping method. (An oversight in eCommerce prevents this from working when only one shipping method is enabled)

Further symbols are available for each Cost Basis and for excess calculation (when enabled). Enable and view the cart calculation diagnostics in the Log for a complete list of available message tokens.

'null' Return

Including {{null}} in any configurable message will result in Zone Based Shipping returning 'null' when the associated rule is matched.

For example, if you only deliver pizzas within your neighbourhood, Create a zone to match your neighbourhood. Create a default zone of 'outside area' that matches all other addresses. Include {{null}} in the message, or just make the whole message {{null}}. Zone Based Shipping will now return 'null' for any address outside your neighbourhood. eCommerce then announces 'Shipping unavailable' and refuses to complete the checkout process.

Units

The weight, dimension and volume units used for Shipping Cost Rules are selectable between a range of metric, US and Imperial units. The units that products are defined with of weight, length, width and height are translated into the units of the Shipping Cost Rules.

Currency

The currency symbol and position follows that set by the core eCommerce add-on.

Cost by Cart, Group, Item or Product

By default, the Shipping Cost Rules are applied to an entire shopping cart. However, if you ship each item or product separately, the Shipping Cost Rules can be applied to individual items or Products (Items x Quantity) to give a total cost for shipping each item separately.

You can also select 'Group' to split the cart calculation by the product attribute zone_shipping_cart_group. In this case, special rules apply to how products marked 'Any' are grouped with other products in the cart.

In this context, some Cost-Basis measures will be nonsensical.

Address to Zone Rules

Address to Zone rules are applied to a customer’s address during the checkout process to determine which shipping zone they are in.

eCommerce shipping address fields available for comparison are: country, state/province/county, town/city, zip code, and the actual text of the address.

You must start with a country rule. Then follow it with all other rules within that country. Other rules are only applied within a country rule, even if you only ship to one country.

The 'match type' when assigning a customer address to a zone is case insensitive. The corresponding match text can contain a list of matches separated by the pipe '|' symbol, semicolon ';' or ':'. It can be a good optimisation within any address rule to use this to list multiple possibilities within that rule. This can be more efficient that multiple separate rules and prevents the list from growing massively if you have, for example, many zip codes to assign to a single zone.

Address rules can use the following match types:

  • Equal to - an exact match against the field in customer's address.
  • Begins with - the field in customer's address must begin with the match text
  • Contains - the field in customer's address must contain the match text
  • Ends with - the field in customer's address must end with the match text
  • Number Range -  the field in customer's address must either match the specified number or be within the range expressed as nnn-mmm
  • Default - will always pass, regardless of the match text. No subsequent rules will be processed. Default would generally be used as the last rule to assign an 'Anywhere Else' zone

For experts who want even more, within the guts of the add-on all of these match types use php regular expressions. The final match type 'regex' allows expert developers to use the entire match text as a regular expression to check against the customer's address. The final address option 'All of Address' contains the text for everything from the first line of the customer's address through to the country.

Rule Diagnostics

During development, site administrators can enable Rule Diagnostics to trace the application of rules to the log (dashboard -> reports -> log).

  • Enable cart calculation diagnostic trace to Log: will show how the Cost Basis measures are calculated for a Cart during the checkout.

  • Enable shipping cost rule diagnostic trace to Log: will show how the Cart is matched to the Shipping Cost Rules.

  • Enable address zone rule diagnostic trace to Log: will show how the customer’s address is matched in Address to Zone Rules.

The final diagnostic, 'Copy zone database entries to Log', will output all the rules for Zone Based Shipping to the log when 'Save' is clicked and changes to the rules are saved. You can leave this diagnostic enabled on a production site as a means of making rule backups.

Developers may find the Quick Log View add-on useful when developing rules.

Installation Notes

The eCommerce add-on must be installed first. Zone Based Shipping should then install automatically as a Concrete5 add-on. The site administrator then uses the eCommerce section of the dashboard to enable Zone Based Shipping and then uses Zone Based Shipping's own dashboard pages to enter the detailed configuration.

The Import/Export dashboard pages can be used to copy rules between sites and backup rules independantly of the Concrete5 database.

There are no known conflicts with other add-ons. The jQuery used within this add-on makes no use of any jQuery plugins and works with the standard jQuery library and jQuery UI already provided and loaded by Concrete5.

Development Tips

During development it is best to leave the diagnostic 'Copy zone database entries to Log' option permanently enabled. Rules will then be backed up to the log every time they are edited.

Should you inadvertently corrupt your rules, the data saved to the log can then be used with phpMyAdmin to restore just the Zone Based Shipping rules in the Config table of the database.

For site administrators and developers with expertise at using phpMyAdmin, you can also use this process to transfer rules from a development site to a production site.

Plan your shipping zones first on paper. Think about how your shipping costs break down, what cost-basis measures you need and where the cost breaks are for each zone. In the mean time, have a play with Zone Based Shipping on a development site, create some zones and rules and familiarise yourself with how it all fits together.

Put a few test orders through the eCommerce checkout with all the diagnostic trace options enabled, then look at the log and see how your rules are processed.

You can then replace the zones and rules you have been using to learn and enter your real rules on the development site. With the rules in place, build test orders to thoroughly test that your zone shipping rules behave as you expect.

Finally, either re-enter or copy your rules to the production site and test again.

Third Party Integration

Zone Based Shipping is structured as a series of libraries and has its own single page editing interface to support integration with other eCommerce systems and extension using concrete5 events.

Cart calculation

Cart calculation can be extended by responding to the events.

zbs_cart_calc_add_product_table_def

A response extends the table used to develop the various cart calculation measures.

zbs_cart_calc_cart_complete_done

An opportunity to completely modify the cart calculation result. This doesn't get cart details, just the overall picture and could, for example, be used to apply discounts based on user or value.

zbs_cost_basis_table

An opportunity to add a new cost basis meaure by modifying the cost basis tables.

Address Matching

zbs_address_rule_get_match_types

Extend the list of available match types.

zbs_address_rule_match_new_type

Respond to a match type that was added by the 'zbs_address_rule_get_match_types' event.

zbs_address_rule_match_ok
zbs_address_rule_match_fail

Override the result of an address rule a match.

Site Configuration Settings

Zone Based Shipping responds to the following constants when defined in config/site.php.

  • ZBS_CALCULATION_PRECISION - the maximum number of decimal places used internally for calculation. Defaults to 6.
  • ZBS_UNSET_COST_BASIS - remove cost basis options (string as comma separated list). May help speed up the in-browser editing of ZBS Configuration. Beware that removing columns that are in use can break a site!
  • ZBS_VALUE_COLUMNS_ORDER - redefines the sequence of cost basis options (string as comma separated list).  Beware that changing the order or leaving out columns that are in use can chnage the way rules are evaluated and could even break a site!
  • ZBS_MAP_ANY_GROUP - mapping of the 'Any' group, as described above.

Cost basis columns available are: weight, dimension, sum_dimensions, volume, items, products, value, modifier_total, modifier_max, attribute_total,  attribute_max.

The default definition is:

 define('ZBS_VALUE_COLUMNS_ORDER','weight,dimension,sum_dimensions,volume,items,products,value,modifier_total,modifier_max,attribute_total,attribute_max'); 

Last updated: 9 months ago