How does it work

The Store Shipping module has no template tags of its own. It works inside the cart and checkout of Reinos Store, so you use the regular Store tags in your templates: the shipping_methods tag, the checkout tag and the cart tag.

You create shipping rules (countries or continents, a price, an optional weight threshold or matching entries). The module picks the rule that fits the cart and offers it as a shipping method at checkout.

What changes in Reinos Store

When the module is installed, Reinos Store changes as follows:

• The default shipping option of Store is removed. The fixed Default shipping cost of Store is no longer offered. The shipping methods now come from the rules of this module (and from other shipping add-ons, see below).
• Store's shipping and country settings move to this module. The Shipping settings (Shipping Label, Free shipping above, disable_shipping param, Always select first shipping method) and the Country settings (Default country, Allowed countries) are no longer shown in the Store settings. You manage them on the Settings page of this module.
• Manage Shipping Status is turned on. Orders get a shipping status (Not shipped / Shipped) that you can change in the order detail of Store, and the order overview gets a shipping status column.
• The global variable {reinos_store_shipping_module_installed} is true, so you can check for the module in your templates.

Uninstalling

Uninstalling the module removes its rules, settings and logs. After that, Store shows its own shipping and country settings again and offers its default shipping option again. A cart that still had a rule of this module selected loses that selection, so the customer has to choose a shipping method again. Existing orders keep their shipping method and carrier. Manage Shipping Status stays on; turn it off in the Store settings if you don't need it.

From cart to order

1. The shipping country of the cart

The shipping cost depends on the shipping country of the cart:

• A new cart starts with the Default country.
• The default_shipping_country param of the checkout tag sets the country when the cart has none yet.
• The country is updated when the customer changes it, either with the {reinos_store_update_checkout_details_ajax_url} call (see the Store example template) or when the checkout form is posted. When shipping same as billing is used, the billing country is used as shipping country.

2. The shipping_methods tag

The shipping_methods tag lists the shipping methods. This module adds one option: the rule that matches the cart (see How the rule is chosen). When no rule matches, it adds nothing.

Variable	Value
{shipping_methods:name}	shipping_module__ followed by the rule ID, e.g. shipping_module__3
{shipping_methods:title}	The Shipping label of the rule, or the default Shipping Label when the rule has none
{shipping_methods:price}	The shipping cost excluding tax
{shipping_methods:price_plus_tax}	The shipping cost including tax

Post the chosen method as shipping_method in the checkout form:

{exp:reinos_store:shipping_methods}
    <input {if shipping_methods:selected}checked{/if} id="{shipping_methods:name}" type="radio" name="shipping_method" value="{shipping_methods:name}" />
    <label for="{shipping_methods:name}">{shipping_methods:title} ({shipping_methods:price_plus_tax:formatted})</label>
{/exp:reinos_store:shipping_methods}

Good to know:

• When the selected method is no longer in the list (e.g. the country changed and another rule matches), the selection is cleared.
• When Always select first shipping method is on and nothing is selected, the first method in the list is selected.
• When the cart has free shipping, every method is shown with a price of 0 (see Free shipping).

3. How the rule is chosen

1. The shipping country of the cart is used, or the Default country when it is empty.
2. A rule matches when the country is one of its countries, or lies on one of its continents. A rule for the country wins over a rule for its continent: each step below first looks at the rules of the country, and only uses the continent rules when none of them matches (see step 4 for one exception; e.g. Europe 9.95 and the Netherlands 4.95: a Dutch cart gets 4.95). With weight thresholds, give the country its own tiers. Items with disable_shipping="yes" don't count for the weight, the matching entries and the quantity below.
3. The cart has a weight (weight × quantity of all items is more than 0): only rules without matching entries are used. The rule with the highest weight threshold that the cart weight reaches is chosen. When no rule reaches it, there is no shipping option.
4. The cart has no weight: weight thresholds are ignored. The most expensive rule whose matching entries contain a product in the cart is chosen (first the rules of the country, then the continent rules). When there is none, the most expensive rule without matching entries is chosen (again first the country, then the continent). "Most expensive" compares the shipping cost of the rules for this cart: the price plus the price per additional item for every item after the first one (e.g. with 5 items a rule of 5.00 + 2.00 per additional item (13.00) wins over a rule of 10.00). With the same cost, the rule with the highest price wins. So a continent rule with matching entries for a product in the cart wins over a country rule without matching entries.
5. The price is the price of the rule, plus the price per additional item for every item after the first one (the quantity of all items in the cart is counted).

The weight of a product comes from the weight param of the add_to_cart tag. Store converts it to its Weight unit setting (kilogram by default) when the product is added to the cart, also for a product with its own weight_unit. The weight thresholds of the rules are in that unit too; the CP shows it next to the threshold.

4. Tax on the shipping cost

The tax on the shipping cost comes from the Store Tax module when it is installed (based on the billing country and company of the cart, also when its rate is 0%, e.g. reverse charge). Without Store Tax, the Shipping TAX percentage setting of Store is used. When Calculate tax is off in Store, the shipping cost has no tax. The shipping options and the cart use the same rate.

5. Checkout validation

When the checkout form is posted, the chosen shipping_method is saved in the cart. The checkout only continues when a method of this module (or another shipping add-on) is selected and, for this module, its rule is the rule that matches the cart now (country, weight and entries, see How the rule is chosen). When the cart changed after the method was chosen (e.g. another country), the customer has to choose the shipping method again. Otherwise the checkout stops with the shipping_method_missing error ({global_error:shipping_method_missing} in the checkout tag).

The shipping cost is calculated again at this point, with the rule that matches the shipping country of the cart.

6. The order

The order gets:

• The shipping method, e.g. shipping_module__3 ({order:shipping_method}).
• The carrier: the Shipping label of the rule, or the default Shipping Label when the rule has no label.
• The shipping status Not shipped. Set it to Shipped in the order detail of Store ({order:shipping_status} in the order tag).
• The shipping cost (and its tax) in the totals, or 0 when the order has free shipping.

Free shipping and disable_shipping

Free shipping is handled by Store and works on top of the rules. The shipping cost of the cart and the price of all shipping methods become 0 when:

• the subtotal of the cart (excluding tax) is higher than Free shipping above (when it is more than 0),
• a free shipping rule of Store Price Rule applies,
• items have disable_shipping="yes", depending on the disable_shipping param setting.

Use {cart:has_free_shipping} to show a message in the cart. The customer still has to select a shipping method at checkout.

Orders made in the CP (Create order)

Available from v2.0.0, with Store 4.0.0

Create order in the CP of Store has no cart, so the module chooses the rule for the order form instead: the country of the shipping address (the billing address when the shipping address is the same, the Default country when it is empty) and the lines of the order. The rule is chosen the same way as in the checkout (see How the rule is chosen) and offered as one shipping method, with the Shipping label of the rule (or the default Shipping Label when the rule has none) as title and carrier.

The differences with the checkout:

• Every line counts for the weight and the quantity, also a Custom line: the form has no disable_shipping. Only lines with an entry count for the matching entries.
• The price of the method is the price of the rule plus the price per additional item, or 0 when the subtotal of the order (excluding tax) is higher than Free shipping above. A Price Rule free shipping rule and disable_shipping don't apply; change the shipping price in the form when the order ships for free.
• When the products or the address change and another rule matches, the form chooses the new rule and tells you.

Combining with other add-ons

• Store Pickup: the pickup locations are shown as extra methods next to the rule of this module. Pickup orders get the Not Picked Up / Picked Up status instead of Shipped.
• Store MyParcel: its rules are shown as extra methods. The shipping status of MyParcel orders is managed by MyParcel.
• Store Price Rule: free shipping rules make the shipping cost 0, next to Free shipping above.
• Store Tax: calculates the tax on the shipping cost (see Tax on the shipping cost).

All methods appear together in one list, in this order: the methods of MyParcel, then the pickup locations of Pickup, then the rule of this module. Always select first shipping method is one setting shared by these add-ons, so with MyParcel or Pickup installed the first method comes from that add-on.

Common pitfalls

No shipping method is shown

• No rule has the shipping country of the cart (or its continent), or the country of the cart is not a country code known by Store. Check the country of the cart and the Default country; when both are empty, no rule can match.
• The cart has a weight, but no rule without matching entries has a weight threshold the cart reaches (e.g. the lowest threshold is 1 while the cart weighs 0.5). Add a rule with threshold 0 as the base rule.
• The cart has a weight and the only rule for the country has matching entries: rules with matching entries are skipped when the cart has a weight.
• The shipping_methods tag is not in the template, or it is placed outside the checkout form.

"No shipping method selected" (shipping_method_missing)

• The form doesn't post shipping_method (e.g. the input has another name), or the customer didn't choose one. Turn on Always select first shipping method to preselect the option.
• The selected rule was deleted, or replaced by an import (imported rules get new IDs).
• The cart changed after the method was chosen (another country, weight or products), so another rule matches now. The customer has to choose the shipping method again.

Wrong shipping cost

• A product with a weight is in the cart: matching entries are ignored and the weight rules are used.
• The cart has no weight: weight thresholds are ignored and the most expensive rule for the country is used, also when it is meant for heavy parcels.
• The country was changed in the form but not saved in the cart: the cost is based on the country stored in the cart. Update the cart with the {reinos_store_update_checkout_details_ajax_url} call when the country changes.
• The price per additional item counts the quantity of all items (except items with disable_shipping="yes"), not the number of different products.

Shipping cost is 0

• Free shipping applies: Free shipping above, a Price Rule free shipping rule or disable_shipping="yes" items.

Other

• No tax on the shipping cost: Store Tax gives 0% for the billing country or company, Store Tax is not installed and the Shipping TAX percentage of Store is 0, or Calculate tax is off in Store.
• The Store shipping or country settings are missing in the Store settings: they are on the Settings page of this module.
• Why no rule was used: set Logging to Everything and check the Logging page, it shows the country, the cart weight and the entries for which no rule was found.