Shipping

Spree comes with a complete shipping framework that allow you to configure shipping to your exact needs. Shipping is implemented through a combination of zones and calculators.

Product Dimensions

The core shipping extension in Spree adds several columns to the variant table to assist in shipping. Each product variant has a weight, height, width and depth field. There is an assumption of an implicit common unit of measurment for each of these fields.

Shipping Category

The core shipping extension also adds a shipping_category field to the Product model. Products can be assigned to zero or one shipping categories. The shipping_category field is entirely optional. Shipping calculators can be designed to take advantage of this category information or ignore it entirely.

Shipping Methods

Shipping methods are the basic build blocks of the shipping calculation. They are basically equivalent to the individual choices the user is presented with. In other words, the dropdown or radio buttons listing their shipping options (ex. UPS Ground, UPS 2nd Day, UPS Next Day.) You will need to construct one shipping method for each option you wish to present the user. You will need to create even more shipping methods then this if you wish to present different methods depending on the shipping destination (see zones.)

Zones

The first step to setting up shipping is to set up at least one zone. Spree will not allow you to choose a shipping method, nor calculate the shipping cost without at least one zone configured. If you are going to offer the same shipping methods for all locations that you deliver to, then you can simply set up a single zone that covers all of the locations that you ship to.

A side effect of setting up shipping zones is that they will affect the list of countries in the combo box that the user is presented with when filling out there shipping address. This is a convenient way of limiting that list of countries to only the countries where you are able to ship to. If you choose not to set up a shipping method for some reason (perhaps you are using your own shipping framework), then the list of countries will include every country in the standard ISO list of countries.

Calculators

Shipping calculators are the key to Spree’s shipping framewok. Each of the shipping methods relies on a calculator to determine the actual shipping costs. Calculators contain a calculate_shipping method to which you pass an Order object. The order contains an Address which is the shipping address as well as LineItems which contain references to the Variants and their quantities.

Calculators are meant to be flexible. They can do their work in a variety of ways. One approach is to simply use calculators to wrap an existing webservice. This is the approach taken by the active-shipping extension which provides UPS rate quotes. When wrapping a webservice like this you need to create one calculator for each of the rates that you want to offer (ex. UPS Ground, UPS 2nd Day, UPS Next Day.) The webservice will usually want to return all of the possible rates (at least that’s the case with UPS) so you will probably want to cache them so that each calculator does not need to lookup the same set of rates for the same order.

Remember that shipping methods are the radio button choices a customer selects from during checkout. So each method (UPS Ground) needs a corresponding calculator (Ups::Ground). Many times you will be able to get away with a single zone (say you ship to three different countries but UPS is offered in all of them.) In cases where you do not offer shipping methods in certain countries/regions, then you will need to set up the different combinations of zones and shipping methods. Ultimately, this gives you very granular control over the shipping configuration.

Custom shipping calculators can also be written to perform their own calculations without the aid of a webservice. Calculators can take advantage of zones, shipping categories and other custom information as needed. For instance, the flexirate-shipping extension takes an interesting approach and allows you to specify different rates depending on the zone, shipping category and quantity of good.

Extensions

It is our experience that most applications require very specific logic for their shipping needs. Most open source platforms fall into the trap of trying to integrate a shipping solution that attempts to meet everyone’s needs. Spree takes a different approach. Spree comes with a simple flat rate shipping option as well as the ability to turn off shipping all together (just remove the shipping extension.) It is expected that you will either develop your own shipping extension or use an existing third party extension. Spree puts an emphasis on making it easier to customize the piece that always ends up needing to be customized anyways.

Be sure to checkout the Extensions Listing for more information on all of the shipping and other Spree extensions.