The Spree::Address model is used to track address information for customers. Addresses are consumed by Spree::Orders, Spree::Shipments, and Spree::Cartons.

If your store uses the solidus_auth_devise gem, customers belong to the Spree::User model. A customer may have multiple addresses. For example, it is typical for customers to have separate billing and shipping addresses.

You may want to find all of the addresses associated with a Spree::User:



Spree::Address objects have the following attributes:

  • name: The full name for the person at this address.
  • address1 and address2: The street address (with an optional second line).
  • city: The city where the address is.
  • zipcode: The postal code.
  • phone and alternative_phone: The customer's phone number(s).
  • state_name: If the customer uses a region name that doesn't correspond with a country's list of states, the address can store the user-entered state_name as a fallback.
  • alternative_phone: The alternative phone number.
  • company: A company name.
  • state_id and country_id: IDs for the Spree::State and Spree::Country objects associated with the customer's entered address. These are used to determine the customer's zone , which determines applicable taxation and shipping methods.

For more information about how countries, states, and zones work in Solidus, see the Locations documentation.

Countries and states

Countries and states can affect both taxation and shipping on orders. So, an address must always link to a Spree::Country object. Because some countries do not have associated Spree::States, a state object is not required.

If the user-entered state does not correspond with a Spree::Country's associated states, then the state_name attribute is used to record the state name.

If you use the solidus_frontend gem to provide your store's frontend, the state field is hidden if the customer's country does not have Spree::States associated with it.

Required address values

By default, Spree::Address objects require many address values, including a phone number and zip code value.

You may want to alter Solidus's address requirements for your store. For example, if you do not require customer phone numbers in order for them to check out.

In that case, you can set the address_requires_phone preference to false in an initializer.

      Spree::Config.configure do |config|
  config.address_requires_phone = false


With the exception of phone number, you need to monkey-patch the Spree::Address model in order to change its requirements. If you ship to countries that don't require postal codes, like Hong Kong or Macau, you may want to make postal codes optional instead of required.

Right now, you can monkey-patch the Spree::Address model in order to remove or change the requirements. For example, you could prepend your own custom behavior that redefines Spree::Address's require_zipcode? method:

      module ZipCodeValidation
  def require_zipcode?
    # if a country that you ship to does not require postal codes, add its iso
    # code to the following array so that Spree::Address does not require zip
    # codes for addresses in those countries.




Solidus is an open source platform supported by the community. We encourage everyone using Solidus to contribute back to the documentation and the code.

If you’re interested in contributing to the docs, get started with the contributing guidelines. If you see something that needs fixing and can’t do it yourself, please send us an email.