Addresses

Overview

Geography is central to how Spree handles checkout, pricing, taxes, and shipping. The system works through a chain of related concepts:

Markets → Countries → Zones → Tax Rates & Shipping Methods
                  ↘ States
                  ↘ Addresses

Markets group countries into selling regions with their own currency and locale
Countries and States provide the geographic data for addresses
Zones group countries or states together to define where tax rates and shipping methods apply
Addresses tie a customer to a specific location, determining which zones — and therefore which taxes and shipping options — apply to their order

An address represents a shipping or billing location. Every order has a shipping address and a billing address, and customers can save multiple addresses in their address book.

Field	Description
`first_name`, `last_name`	Contact name
`address1`, `address2`	Street address
`city`	City
`postal_code`	Postal code (not required for all countries)
`phone`	Phone number
`company`	Company name (optional)
`country_iso`	Country (ISO alpha-2 code, e.g., `US`)
`state_abbr`	State/province abbreviation (required for some countries, e.g., `CA`)

Whether a state or zipcode is required depends on the country. For example, the US requires both, while Hong Kong requires neither. The API returns states_required and zipcode_required on each country so your frontend can adapt the form dynamically.

Customer Address Book

Customers can save multiple addresses and set a default for shipping and billing. When a customer completes checkout, the selected addresses are cloned onto the order — so editing an address later doesn’t change past orders.

// List addresses
const { data: addresses } = await client.customer.addresses.list()

// Create an address
const address = await client.customer.addresses.create({
  first_name: 'John',
  last_name: 'Doe',
  address1: '123 Main St',
  city: 'Los Angeles',
  country_iso: 'US',
  state_abbr: 'CA',
  postal_code: '90001',
  phone: '555-0100',
})

// Update an address
await client.customer.addresses.update('addr_xxx', { city: 'Brooklyn' })

// Delete an address
await client.customer.addresses.delete('addr_xxx')

// Set as default shipping or billing address — pass the boolean flags to create or update
await client.customer.addresses.update('addr_xxx', { is_default_shipping: true })
await client.customer.addresses.update('addr_xxx', { is_default_billing: true })

# List addresses
curl 'https://api.mystore.com/api/v3/store/customers/me/addresses' \
  -H 'X-Spree-API-Key: pk_xxx' \
  -H 'Authorization: Bearer <jwt_token>'

# Create an address
curl -X POST 'https://api.mystore.com/api/v3/store/customers/me/addresses' \
  -H 'X-Spree-API-Key: pk_xxx' \
  -H 'Authorization: Bearer <jwt_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "address1": "123 Main St",
    "city": "Los Angeles",
    "country_iso": "US",
    "state_abbr": "CA",
    "postal_code": "90001",
    "phone": "555-0100"
  }'

# Update an address
curl -X PATCH 'https://api.mystore.com/api/v3/store/customers/me/addresses/addr_xxx' \
  -H 'X-Spree-API-Key: pk_xxx' \
  -H 'Authorization: Bearer <jwt_token>' \
  -H 'Content-Type: application/json' \
  -d '{ "city": "Brooklyn" }'

# Delete an address
curl -X DELETE 'https://api.mystore.com/api/v3/store/customers/me/addresses/addr_xxx' \
  -H 'X-Spree-API-Key: pk_xxx' \
  -H 'Authorization: Bearer <jwt_token>'

Checkout Addresses

During checkout, you can either reference a saved address by ID or pass a new address inline. See the cart and checkout SDK guide for the full flow of passing addresses during checkout:

// Use saved addresses
await client.carts.update(cartId, {
  shipping_address_id: 'addr_xxx',
  billing_address_id: 'addr_yyy',
})

// Or pass new addresses inline
await client.carts.update(cartId, {
  shipping_address: {
    first_name: 'John',
    last_name: 'Doe',
    address1: '123 Main St',
    city: 'Los Angeles',
    country_iso: 'US',
    state_abbr: 'CA',
    postal_code: '90001',
    phone: '555-0100',
  },
})

# Use a saved address
curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx' \
  -H 'X-Spree-API-Key: pk_xxx' \
  -H 'X-Spree-Token: order_token' \
  -H 'Content-Type: application/json' \
  -d '{ "shipping_address_id": "addr_xxx", "billing_address_id": "addr_yyy" }'

# Or pass a new address inline
curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx' \
  -H 'X-Spree-API-Key: pk_xxx' \
  -H 'X-Spree-Token: order_token' \
  -H 'Content-Type: application/json' \
  -d '{
    "shipping_address": {
      "first_name": "John",
      "last_name": "Doe",
      "address1": "123 Main St",
      "city": "Los Angeles",
      "country_iso": "US",
      "state_abbr": "CA",
      "postal_code": "90001",
      "phone": "555-0100"
    }
  }'

Countries

Countries are the foundation of Spree’s geographic system. They connect to Markets, contain states, and belong to zones. Each country includes metadata that drives address form behavior:

Field	Description	Example
`iso`	ISO 3166-1 alpha-2 code	`US`
`iso3`	ISO 3166-1 alpha-3 code	`USA`
`name`	Country name	`United States`
`states_required`	Whether the address form should show a state/province picker	`true`
`zipcode_required`	Whether the address form should require a postal code	`true`

Which Countries Are Available?

Only countries assigned to a Market are available during checkout. This lets you control exactly where you sell.

// List all countries available in this store
const { data: countries } = await client.countries.list()

// Get a country with its states (for address form dropdowns)
const usa = await client.countries.get('US', { expand: ['states'] })
// usa.states => [{ name: "Alabama", abbr: "AL" }, { name: "Alaska", abbr: "AK" }, ...]

// Get a country with its market (for currency/locale resolution)
const germany = await client.countries.get('DE', { expand: ['market'] })
// germany.market => { currency: "EUR", default_locale: "de", tax_inclusive: true }

const { data: countries } = await adminClient.countries.list()

const usa = await adminClient.countries.get('US')

# List all countries
curl 'https://api.mystore.com/api/v3/store/countries' \
  -H 'X-Spree-API-Key: pk_xxx'

# Get a country with states
curl 'https://api.mystore.com/api/v3/store/countries/US?expand=states' \
  -H 'X-Spree-API-Key: pk_xxx'

# Get a country with its market
curl 'https://api.mystore.com/api/v3/store/countries/DE?expand=market' \
  -H 'X-Spree-API-Key: pk_xxx'

Use the states_required and zipcode_required fields to build adaptive address forms — show a state picker only when needed, and skip the zipcode field for countries that don’t use them.

States

States (provinces, regions) belong to a country and are used for address validation and zone matching. Countries like the US, Canada, Australia, and India have predefined states — for these countries, customers must select a state from the list rather than typing a name. States are fetched via the country endpoint using ?expand=states:

const usa = await client.countries.get('US', { expand: ['states'] })

// Build a state picker from the response
usa.states.forEach(state => {
  console.log(state.abbr, state.name) // "AL", "Alabama"
})

const usa = await adminClient.countries.get('US', { expand: ['states'] })

curl 'https://api.mystore.com/api/v3/store/countries/US?expand=states' \
  -H 'X-Spree-API-Key: pk_xxx'

For countries without predefined states, addresses accept a free-text state_name field instead of state_abbr.

Zones

Zones group countries or states together for tax and shipping rules. A zone is either country-based or state-based. Examples:

EU VAT (country zone) — Germany, France, Italy, Spain, … → applies EU VAT rates
California (state zone) — CA → applies California sales tax
Domestic Shipping (country zone) — US, CA → enables domestic shipping methods

When a customer enters their address at checkout, Spree matches it against zones to determine:

Which tax rates apply (see Taxes)
Which shipping methods are available (see Shipments)

Zones are configured in the admin dashboard — storefront developers don’t interact with them directly via the API.

Tax Zones and Markets

Each Market resolves a tax zone from its default country. This means product prices display the correct tax treatment (inclusive or exclusive) before the customer enters an address — just from knowing their market.

How It All Fits Together

Here’s how geography flows through a typical checkout:

Customer visits the store — their country is detected (from URL, geolocation, or selection)
Market resolved — the country maps to a market, which sets the currency and locale
Products displayed — prices use the market’s currency and tax zone for correct formatting
Customer enters address — the address form adapts based on states_required and zipcode_required
Zones matched — the shipping address determines which tax rates and shipping methods apply
Order completed — the address is cloned onto the order for permanent record

Markets — Multi-region commerce with currency, locale, and country grouping
Taxes — How zones and addresses affect taxation
Shipments — How zones and addresses affect shipping availability
Orders — Order billing and shipping addresses
Account SDK guide — Managing the logged-in customer’s address book with client.customer.addresses
Store API authentication — How to obtain and send the customer JWT (Authorization: Bearer header)

Getting started

Platform

Catalog

Cart & Checkout

Fulfillment

Extensibility

Addresses

Overview

Addresses

Customer Address Book

Checkout Addresses

Countries

Which Countries Are Available?

States

Zones

Tax Zones and Markets

How It All Fits Together

​Overview

​Addresses

​Customer Address Book

​Checkout Addresses

​Countries

​Which Countries Are Available?

​States

​Zones

​Tax Zones and Markets

​How It All Fits Together

​Related Documentation

Overview

Addresses

Customer Address Book

Checkout Addresses

Countries

Which Countries Are Available?

States

Zones

Tax Zones and Markets

How It All Fits Together

Related Documentation