@spree/docs 0.1.182 → 0.1.183

package/dist/developer/core-concepts/addresses.md

@@ -1,281 +1,189 @@
 ---
 title: Addresses
-description: How Spree models addresses, countries, states, and zones, and how geographic data drives checkout, tax calculation, and shipping rates.
+description: How Spree handles addresses, country and state data, and building address forms that adapt to the country a customer picks.
 ---
 
 ## 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
+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
+    }
 ```
 
-- [**Markets**](markets.md) 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.
+## Address fields
 
 | Field | Description |
-|-------|-------------|
+|---|---|
 | `first_name`, `last_name` | Contact name |
 | `address1`, `address2` | Street address |
 | `city` | City |
-| `postal_code` | Postal code (not required for all countries) |
+| `postal_code` | Postal code — not used by every country |
 | `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`) |
+| `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 |
+
+> **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.
 
-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.
+## Address forms that adapt
 
-### Customer Address Book
+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.
 
-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.
+Every country tells you what it needs:
+
+
+```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'
+```
+
+
+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](markets.md).
+
+## The customer address book
+
+A signed-in customer can save addresses and mark defaults, so checkout is one tap next time.
 
 
 ```typescript Store SDK
-// List addresses
 const { data: addresses } = await client.customer.addresses.list()
 
-// Create an address
 const address = await client.customer.addresses.create({
+  label: 'Home',
   first_name: 'John',
   last_name: 'Doe',
   address1: '123 Main St',
   city: 'Los Angeles',
-  country_iso: 'US',
-  state_abbr: 'CA',
+  country_code: 'US',
+  state_code: 'CA',
   postal_code: '90001',
   phone: '555-0100',
+  is_default_shipping: true,
 })
 
-// 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 })
+await client.customer.addresses.update(address.id, { city: 'Brooklyn' })
+await client.customer.addresses.delete(address.id)
 ```
 
 ```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 '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_iso": "US",
-    "state_abbr": "CA",
-    "postal_code": "90001",
-    "phone": "555-0100"
+    "country_code": "US",
+    "state_code": "CA",
+    "postal_code": "90001"
   }'
-
-# 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](../sdk/store/cart-checkout.md) for the full flow of passing addresses during checkout:
+## Addresses at checkout
 
+On a cart you can point at a saved address or send a new one inline:
 
 ```typescript Store SDK
-// Use saved addresses
+// Reuse something from the address book
 await client.carts.update(cartId, {
   shipping_address_id: 'addr_xxx',
   billing_address_id: 'addr_yyy',
 })
 
-// Or pass new addresses inline
+// Or send one directly — nothing needs saving first
 await client.carts.update(cartId, {
+  email: 'john@example.com',
   shipping_address: {
     first_name: 'John',
     last_name: 'Doe',
     address1: '123 Main St',
     city: 'Los Angeles',
-    country_iso: 'US',
-    state_abbr: 'CA',
+    country_code: 'US',
+    state_code: '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"
-    }
-  }'
-```
-
-
-## Countries
-
-Countries are the foundation of Spree's geographic system. They connect to [Markets](markets.md), contain states, and belong to zones.
-
-Each country includes metadata that drives address form behavior:
+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.
 
-| 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` |
+> **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.
 
-### Which Countries Are Available?
+## Validating addresses
 
-Only countries assigned to a [Market](markets.md) are available during checkout. This lets you control exactly where you sell.
-
-
-```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" }, ...]
+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.
 
-// 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'
-```
-
-
-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.md):
-
-
-```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'
-```
+For real-world verification — that a street exists, that a unit number is missing — connect an address validation service. See [Providers](../providers/overview.md).
 
+## How geography flows through a purchase
 
-For countries without predefined states, addresses accept a free-text `state_name` field instead of `state_abbr`.
+**Step 1: A customer arrives**
 
-## Zones
+Their country resolves to a [Market](markets.md), which sets the currency and locale, and whether prices are shown with tax included.
 
-Zones group countries or states together for [tax](taxes.md) and [shipping](fulfillments.md) rules. A zone is either **country-based** or **state-based**.
+  **Step 2: They fill in an address**
 
-**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
+The form adapts to the country using `states_required` and `zipcode_required`.
 
-When a customer enters their address at checkout, Spree matches it against zones to determine:
-1. Which **tax rates** apply (see [Taxes](taxes.md))
-2. Which **shipping methods** are available (see [Shipments](fulfillments.md))
+  **Step 3: Delivery options appear**
 
-Zones are configured in the admin dashboard — storefront developers don't interact with them directly via the API.
+The shipping address decides which [delivery methods](fulfillments.md) can reach them, and what each costs.
 
-### Tax Zones and Markets
+  **Step 4: Tax is worked out**
 
-Each [Market](markets.md) 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.
+The same address decides the [tax](taxes.md) charged.
 
-## How It All Fits Together
+  **Step 5: The order is placed**
 
-Here's how geography flows through a typical checkout:
+Both addresses are copied onto the order as a permanent record.
 
-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
+## Related
 
-- [Markets](markets.md) — Multi-region commerce with currency, locale, and country grouping
-- [Taxes](taxes.md) — How zones and addresses affect taxation
-- [Shipments](fulfillments.md) — How zones and addresses affect shipping availability
-- [Orders](orders.md) — Order billing and shipping addresses
-- [Account SDK guide](../sdk/store/account.md) — Managing the logged-in customer's address book with `client.customer.addresses`
-- [Store API authentication](../../api-reference/store-api/authentication.md) — How to obtain and send the customer JWT (`Authorization: Bearer` header)
+- [Markets](markets.md) — where you sell, in which currency
+- [Fulfillments](fulfillments.md) — how the address shapes delivery options
+- [Taxes](taxes.md) — how the address shapes tax
+- [Carts](carts.md) — the checkout flow end to end