Skip to content

armgit / spree

Public Imported from GitHub
0

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.

10.9 KB
Raw Blame
---
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)