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.
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. When there is none, the most expensive rule without matching entries is chosen.
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. The unit doesn't matter, as long as the products and the rules use the same unit.

4. Tax on the shipping cost

The tax on the shipping cost comes from the Store Tax module (based on the billing country and company of the cart). Without Store Tax, no tax is added to the shipping cost of this module. The Shipping TAX percentage setting of Store only applies to Store's own default shipping option, which this module removes.

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 its rule still exists. 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. When the rule has no label, the carrier stays empty (the default Shipping Label is not used here).
• 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.

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. Always select first shipping method is one setting shared by these add-ons, so the first method may come from another add-on.

Common pitfalls

No shipping method is shown

• No rule has the shipping country of the cart (or its continent). 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).

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, 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.
• The country changed after the method was chosen and no rule matches the new country: the order is placed without shipping cost.

Other

• No tax on the shipping cost: Store Tax is not installed.
• The order has no carrier: the rule has no Shipping label.
• The Store shipping or country settings are missing in the Store settings: they are on the Settings page of this module.
• The Logging page doesn't show why a rule was (not) used. Check the rules against the country and weight of the cart instead.