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:

NameDescriptionExample Value
firstnameThe first name for the person at this address.John
lastnameThe last name for the person at this address.Doe
address1The address’s first line.123 Main St
address2(Optional) The address’s second line.Apt 4
cityThe city where the address is.Springfield
zipcodeThe postal code.12345
phoneThe phone number.(123) 456-7890
state_nameThe name for the state.California
alternative_phone(Optional) The alternative phone number.(098) 765-4321
company(Optional) A company name.Acme Corporation
country_idThe 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.


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.


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.


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 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:

NameDescriptionExample Value
iso_nameThe ISO 3166-1 alpha-2 code for the country.US
isoThe ISO 3166-1 alpha-3 code for the country.USA
iso_numericThe ISO 3166-1 numeric code for the country.840
nameThe name of the country.United 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.