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 handles addresses, country and state data, and building address forms that adapt to the country a customer picks.
---
## Overview
An address is where something goes or who gets billed. Every cart collects a shipping and a billing address, and signed-in customers can keep an address book.
Addresses matter beyond the label on a parcel: the shipping address decides which delivery options a customer sees and how much tax they pay.
```mermaid
erDiagram
Customer ||--o{ Address : "address book"
Cart }o--|| Address : "shipping"
Cart }o--|| Address : "billing"
Order }o--|| Address : "shipping (copied)"
Order }o--|| Address : "billing (copied)"
Address {
string first_name
string last_name
string address1
string city
string postal_code
string country_code
string state_code
}
```
## Address fields
| Field | Description |
|---|---|
| `first_name`, `last_name` | Contact name |
| `address1`, `address2` | Street address |
| `city` | City |
| `postal_code` | Postal code — not used by every country |
| `phone` | Phone number |
| `company` | Company name, optional |
| `country_code` | Country, as an ISO code such as `US` |
| `state_code` | State or province code such as `CA`, where the country has them |
| `state_name` | Free text, for countries with no official list |
| `label` | What the customer filed it under — "Home", "Office" |
| `is_default_shipping`, `is_default_billing` | Whether it is the default in the address book |
| `owner` | The address book it belongs to — `{ id, type, name }`, where `type` is `customer` or [`company`](/developer/core-concepts/companies). Read-only, and `null` for an address in no book: one a guest typed in, or the copy a placed order keeps |
<Note>
Countries and states are named by their **ISO codes** — `country_code: "US"`, `state_code: "CA"` — never by an ID. A code means the same thing everywhere, so you can send one without looking anything up first.
The older names `country_iso` and `state_abbr` still work but are going away. Use `country_code` and `state_code` in new code.
</Note>
## Address forms that adapt
Address formats are not universal. The United States wants a state and a ZIP code; Hong Kong wants neither. A form that demands both everywhere will block real customers from checking out.
Every country tells you what it needs:
<CodeGroup>
```typescript Store SDK
const { data: countries } = await client.countries.list()
// One country, with its states for a picker
const usa = await client.countries.get('US', { expand: ['states'] })
usa.states_required // true → show a state picker
usa.zipcode_required // true → require a postal code
usa.states // [{ abbr: "CA", name: "California" }, ...]
```
```bash cURL
curl 'https://api.mystore.com/api/v3/store/countries' \
-H 'X-Spree-API-Key: pk_xxx'
curl 'https://api.mystore.com/api/v3/store/countries/US?expand=states' \
-H 'X-Spree-API-Key: pk_xxx'
```
</CodeGroup>
Drive the form from those two flags rather than hardcoding a list of countries. When `states_required` is `false`, let the customer type a `state_name` instead of picking a `state_code`.
Only countries you actually sell to are listed — that's decided by your [Markets](/developer/core-concepts/markets).
## The customer address book
A signed-in customer can save addresses and mark defaults, so checkout is one tap next time.
<CodeGroup>
```typescript Store SDK
const { data: addresses } = await client.customer.addresses.list()
const address = await client.customer.addresses.create({
label: 'Home',
first_name: 'John',
last_name: 'Doe',
address1: '123 Main St',
city: 'Los Angeles',
country_code: 'US',
state_code: 'CA',
postal_code: '90001',
phone: '555-0100',
is_default_shipping: true,
})
await client.customer.addresses.update(address.id, { city: 'Brooklyn' })
await client.customer.addresses.delete(address.id)
```
```bash cURL
curl -X POST 'https://api.mystore.com/api/v3/store/customers/me/addresses' \
-H 'X-Spree-API-Key: pk_xxx' \
-H 'Authorization: Bearer <customer_token>' \
-H 'Content-Type: application/json' \
-d '{
"label": "Home",
"first_name": "John",
"last_name": "Doe",
"address1": "123 Main St",
"city": "Los Angeles",
"country_code": "US",
"state_code": "CA",
"postal_code": "90001"
}'
```
</CodeGroup>
## Addresses at checkout
On a cart you can point at a saved address or send a new one inline:
<CodeGroup>
```typescript Store SDK
// Reuse something from the address book
await client.carts.update(cartId, {
shipping_address_id: 'addr_xxx',
billing_address_id: 'addr_yyy',
})
// Or send one directly — nothing needs saving first
await client.carts.update(cartId, {
email: '[email protected]',
shipping_address: {
first_name: 'John',
last_name: 'Doe',
address1: '123 Main St',
city: 'Los Angeles',
country_code: 'US',
state_code: 'CA',
postal_code: '90001',
},
})
```
```bash cURL
curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx' \
-H 'X-Spree-API-Key: pk_xxx' \
-H 'Authorization: Bearer $CUSTOMER_JWT' \
-H 'Content-Type: application/json' \
-d '{
"shipping_address_id": "addr_xxx",
"billing_address_id": "addr_yyy"
}'
```
</CodeGroup>
Setting the shipping address is what makes delivery options and tax appear, so do it before asking the customer to choose delivery. The updated cart comes back with new totals — you don't need a second request.
<Warning>
An address is **copied onto the order** when the cart completes, not linked to. Editing a saved address next year does not rewrite last year's invoice — which is exactly what you want when a customer moves house.
</Warning>
## Validating addresses
Spree checks that required fields are present and that the state and postal code make sense for the country. Anything it rejects comes back as a `422` naming the field, so you can put the message next to the input.
For real-world verification — that a street exists, that a unit number is missing — connect an address validation service. See [Providers](/developer/providers/overview).
## How geography flows through a purchase
<Steps>
<Step title="A customer arrives">
Their country resolves to a [Market](/developer/core-concepts/markets), which sets the currency and locale, and whether prices are shown with tax included.
</Step>
<Step title="They fill in an address">
The form adapts to the country using `states_required` and `zipcode_required`.
</Step>
<Step title="Delivery options appear">
The shipping address decides which [delivery methods](/developer/core-concepts/fulfillments) can reach them, and what each costs.
</Step>
<Step title="Tax is worked out">
The same address decides the [tax](/developer/core-concepts/taxes) charged.
</Step>
<Step title="The order is placed">
Both addresses are copied onto the order as a permanent record.
</Step>
</Steps>
## Related
- [Markets](/developer/core-concepts/markets) — where you sell, in which currency
- [Fulfillments](/developer/core-concepts/fulfillments) — how the address shapes delivery options
- [Taxes](/developer/core-concepts/taxes) — how the address shapes tax
- [Carts](/developer/core-concepts/carts) — the checkout flow end to end