Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
---
title: Addresses
description: How Spree models addresses, countries, states, and zones, and how geographic data drives checkout, tax calculation, and shipping rates.
canonical: "https://spreecommerce.org/docs/developer/core-concepts/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**](/v5/developer/core-concepts/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
## Addresses
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.
<CodeGroup>
```typescript Store SDK
// 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 })
```
```bash cURL
# 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>'
```
</CodeGroup>
### 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](/v5/developer/sdk/store/cart-checkout) for the full flow of passing addresses during checkout:
<CodeGroup>
```typescript Store SDK
// 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',
},
})
```
```bash cURL
# 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"
}
}'
```
</CodeGroup>
## Countries
Countries are the foundation of Spree's geographic system. They connect to [Markets](/v5/developer/core-concepts/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](/v5/developer/core-concepts/markets) are available during checkout. This lets you control exactly where you sell.
<CodeGroup>
```typescript Store SDK
// 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 }
```
```typescript Admin SDK
const { data: countries } = await adminClient.countries.list()
const usa = await adminClient.countries.get('US')
```
```bash cURL
# 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'
```
</CodeGroup>
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`](/api-reference/store-api/relations):
<CodeGroup>
```typescript Store SDK
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"
})
```
```typescript Admin SDK
const usa = await adminClient.countries.get('US', { expand: ['states'] })
```
```bash cURL
curl 'https://api.mystore.com/api/v3/store/countries/US?expand=states' \
-H 'X-Spree-API-Key: pk_xxx'
```
</CodeGroup>
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](/v5/developer/core-concepts/taxes) and [shipping](/v5/developer/core-concepts/shipments) 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:
1. Which **tax rates** apply (see [Taxes](/v5/developer/core-concepts/taxes))
2. Which **shipping methods** are available (see [Shipments](/v5/developer/core-concepts/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](/v5/developer/core-concepts/markets) 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:
1. **Customer visits the store** — their country is detected (from URL, geolocation, or selection)
2. **Market resolved** — the country maps to a market, which sets the currency and locale
3. **Products displayed** — prices use the market's currency and tax zone for correct formatting
4. **Customer enters address** — the address form adapts based on `states_required` and `zipcode_required`
5. **Zones matched** — the shipping address determines which tax rates and shipping methods apply
6. **Order completed** — the address is cloned onto the order for permanent record
## Related Documentation
- [Markets](/v5/developer/core-concepts/markets) — Multi-region commerce with currency, locale, and country grouping
- [Taxes](/v5/developer/core-concepts/taxes) — How zones and addresses affect taxation
- [Shipments](/v5/developer/core-concepts/shipments) — How zones and addresses affect shipping availability
- [Orders](/v5/developer/core-concepts/orders) — Order billing and shipping addresses
- [Account SDK guide](/v5/developer/sdk/store/account) — Managing the logged-in customer's address book with `client.customer.addresses`
- [Store API authentication](/api-reference/store-api/authentication) — How to obtain and send the customer JWT (`Authorization: Bearer` header)