Zones

This guide covers how to manage and configure zones within Spree. After reading it, you should be familiar with:

  • The purpose of zones and how they relate to shipping and taxation
  • How to create a new zone
  • How to edit an existing zone
  • Other possible uses for zones

1 Overview

The zone concept is used by Spree to assist in various calculations and reports. Zones serve as a mechanism for grouping geographic areas together into a single entity. Zones are used by the core system (for tax and shipping calculations) but they are also available to custom extensions that may require them.

2 Zone Basics

A Zone consists of one or more members. All of a zone’s members must be the same type. The three zone member types are country, state and zone.

Zones have a helpful include? method that can be used to determine whether or not an address falls within a particular zone. The following is an example in the Rails console:

>> z = Spree::Zone.first
=> #<Zone id: 1, name: "EU_VAT", description: "Countries that make up the EU VAT zone.", created_at: "2009-04-20 19:08:23", updated_at: "2009-04-20 19:08:23">
>> z.include?(Address.first)
=> false

Zones also have a convenient country_list method for returning the Countries contained within a zone. This is different from the countries method which only returns the zones children and does not consider the grandchildren if the children themselves are zones.)

The following is an example of this method as visible in the Rails console:

>> z = Spree::Zone.all[1]
=> #<Zone id: 284254445, name: "Zone with one shipping option", description: "Zone with one shipping option", created_at: "2009-04-20 19:08:26", updated_at: "2009-04-20 19:08:26">
>> z.country_list
=> [#<Country id: 212, iso_name: "UNITED ARAB EMIRATES", iso: "AE", name: "United Arab Emirates", iso3: "ARE", numcode: 784>, #<Country id: 213, iso_name: "UNITED KINGDOM", iso: "GB", name: "United Kingdom", iso3: "GBR", numcode: 826>]

3 Building a Zone

Lets examine the steps for building a new zone more closely.

  1. Click on the “Configuration” tab in the admin menu.
  2. Click the “Zones” link.
  3. Click the “New Zone” button
  4. Enter a name for the zone (ex. “Nordic Countries”)
  5. Enter an optional description for the zone (ex. “The five countries that comprise Northern Europe”)
  6. Chose the type of zone. In this case we’ll leave it as the default choice of “Country.”
  7. Select the first zone member for the country you wish to add (ex. Norway)
  8. Click “Add Country” to add another member (ex. Finland)
  9. Repeat this process for the remaining members (ex. Iceland, Denmark and Sweden)
  10. Click the “Create” button to save the new zone.

If you are adding state/province members they must already exist before trying to add them to the zone (Spree comes with only a limited number of states in its database.)

4 Updating an Existing Zone

Updating a zone is very similar to creating one. There are few minor differences to be aware of.

  • It is possible to change an existing zone’s type (you will need to add new members of course.)
  • Any zone member that is removed from the list will be deleted once you click “Update.”

If you are editing an existing zone and change its type (say from “Country” to “State”), you will see empty select boxes since the existing members to do not map to the new set of choices. Just set the desired state values and then remove any unused entries using the “delete icon.” Any “blank” values (resulting from a new zone type) will be discarded if you attempt to save them.

5 Zone Types

5.1 Country

A zone can consist of one or more countries. An example of a zone you might wish to create would be “Nordic Countries.” It would consist of five zone member countries: Denmark, Finland, Iceland, Norway and Sweden.

5.2 State

A zone can also consist of one or more states. If you wish to include all of the states then it makes sense to just use a country based zone instead. The states must exist in the database before attempting to add them to the zone. New states can be added by the “Configuration” tab and then clicking “States.”

5.3 Zone

A zone can also consist of other zones. The only requirement here is that zone members are all zones. It does not matter what type of zone each zone member is - only that they are all zones. Using the zone type allows you to achieve fine grained control of your zones. For instance, if you needed a “foo” zone that included the United States, France, Germany but excluded New York state you could achieve this by creating three zones.

  • Zone 1: USA (minus NY)
    • Zone Type: State
    • Members : Alabama, Alaska, Arizona …. Wyoming (all 49 states except New York)
  • Zone 2: FR + DE
    • Zone Type: Country
    • Members : France, Germany
  • Zone 3: Foo Zone
    • Zone Type: Zone
    • Members : USA (minus NY), FR + DE

6 Other Possible Uses for Zones

There are some interesting implications with zones as far as reporting goes. It is possible to chain relations using named scopes to do something like:

Customer.in_zone(zone).all
Customer.recently_logged.spend_more_than_10000_eur.in_zone(zone)

Alternatively, Spree uses the meta_search gem to pull off much of its dynamic searching functionality. The README is quite comprehensive and would give you some idea as the type of searches you could build that would leverage the power of zones.

This project is maintained by a core team of developers and is freely available for commercial use under the terms of the New BSD License.