Addresses

The Spree::Address model is used to track address information, mainly for orders. Address information can also be tied to the Spree.user_class which by default is Spree::User (More on Users).

Addresses have the following attributes:

Name	Description	Example Value
firstname	The first name for the person at this address.	John
lastname	The last name for the person at this address.	Doe
address1	The address’s first line.	123 Main St
address2	(Optional) The address’s second line.	Apt 4
city	The city where the address is.	Springfield
zipcode	The postal code.	12345
phone	The phone number.	[phone]
state_name	The name for the state.	California
alternative_phone	(Optional) The alternative phone number.	[phone]
company	(Optional) A company name.	Acme Corporation
country_id	The ID for the country.	1
state_id	(Optional) The ID for the state.	2
user_id	(Optional) The ID of the user this address is associated with.	10
label	(Optional) A label to identify the address.	Home

An address must always link to a Spree::Country object. It can optionally link to a Spree::State object, but only in the cases where the related country has no states listed. In that case, the state information is still required, and is kept within the state_name field on the address record. An easy way to get the state information for the address is to call state_text on that object.

Customers

Spree::User can have multiple addresses and can manage them on the Checkout and Account page (or via API). Each Spree::Address object has a user_id column which links to the User.

Additionally in the Spree::User there is ship_address_id and bill_address_id columns which indicates which addresses are the default ones for this User.

Checkout

When a signed in User completes the Checkout Spree clones the selected Shipping and Billing Addresses and associates them with the Order. We do so that even if User modifies those addresses in the future their current state is preserved. Cloned addresses aren’t associated to the User anymore. Originals will still be visible in their Address Books for future use.

Zones

When an order’s address is linked to a country or a state, that can ultimately affect different features of the order, including shipping availability and taxation. The way these effects work is through zones.

A zone is comprised of many different “zone members”, which can either be a set of countries or a set of states.

Every order has a “tax zone”, which indicates if a user should or shouldn’t be taxed when placing an order. For more information, please see the Taxation guide.

In addition to tax zones, orders also have shipping methods. These are provided to the user based on their address information, and once selected lock in how an order is going to be shipped to that user. For more information, please see the Shipments guide.

Countries

Countries within Spree are used as a container for states. Countries can be zone members, and also link to an address. The difference between one country and another on an address record can determine which tax rates and shipping methods are used for the order.

Country data is provided by Carmen gem which is a library for manipulating country data.

Spree::Country model includes these attributes:

Name	Description	Example Value
iso_name	The ISO 3166-1 alpha-2 code for the country.	US
iso	The ISO 3166-1 alpha-3 code for the country.	USA
iso_numeric	The ISO 3166-1 numeric code for the country.	840
name	The name of the country.	United States

States

States, or regions, provinces, or districts are used to scope address data slightly more than country. States are useful for tax purposes, as different states in a country may impose different tax rates on different products. In addition to this, different states may cause different tax rates and shipping methods to be used for an order, similar to how countries affect it also.