@spree/docs 0.1.0

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

@@ -0,0 +1,265 @@
+---
+title: Addresses
+description: Addresses, countries, states, and zones — how geography drives checkout, taxes, and shipping
+---
+
+## 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**](/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) |
+| `label` | User-facing label like "Home" or "Office" (optional, unique per customer) |
+| `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.
+
+
+```typescript 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
+await client.customer.addresses.markAsDefault('addr_xxx', 'shipping')
+```
+
+```bash cURL
+# List addresses
+curl 'https://api.mystore.com/api/v3/store/customer/addresses' \
+  -H 'Authorization: Bearer <jwt_token>'
+
+# Create an address
+curl -X POST 'https://api.mystore.com/api/v3/store/customer/addresses' \
+  -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/customer/addresses/addr_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/customer/addresses/addr_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:
+
+
+```typescript 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 'Authorization: Bearer spree_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 'Authorization: Bearer spree_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](/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](/developer/core-concepts/markets) are available during checkout. This lets you control exactly where you sell.
+
+
+```typescript 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', { include: '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', { include: 'market' })
+// germany.market => { currency: "EUR", default_locale: "de", tax_inclusive: true }
+```
+
+```bash cURL
+# List all countries
+curl 'https://api.mystore.com/api/v3/store/countries' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+
+# Get a country with states
+curl 'https://api.mystore.com/api/v3/store/countries/US?include=states' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+
+# Get a country with its market
+curl 'https://api.mystore.com/api/v3/store/countries/DE?include=market' \
+  -H 'Authorization: Bearer spree_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 `?include=states`:
+
+
+```typescript SDK
+const usa = await client.countries.get('US', { include: 'states' })
+
+// Build a state picker from the response
+usa.states.forEach(state => {
+  console.log(state.abbr, state.name) // "AL", "Alabama"
+})
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/countries/US?include=states' \
+  -H 'Authorization: Bearer spree_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](/developer/core-concepts/taxes) and [shipping](/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](/developer/core-concepts/taxes))
+2. Which **shipping methods** are available (see [Shipments](/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](/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](/developer/core-concepts/markets) — Multi-region commerce with currency, locale, and country grouping
+- [Taxes](/developer/core-concepts/taxes) — How zones and addresses affect taxation
+- [Shipments](/developer/core-concepts/shipments) — How zones and addresses affect shipping availability
+- [Orders](/developer/core-concepts/orders) — Order billing and shipping addresses

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

@@ -0,0 +1,107 @@
+---
+title: Adjustments
+description: How taxes, promotions, and other price modifications are applied to orders
+---
+
+## Overview
+
+An Adjustment modifies the price of an [Order](/developer/core-concepts/orders), a [Line Item](/developer/core-concepts/orders#line-items), or a [Shipment](/developer/core-concepts/shipments). Adjustments can be positive (charges) or negative (credits).
+
+```mermaid
+erDiagram
+    Adjustment {
+        decimal amount
+        string label
+        boolean eligible
+        boolean mandatory
+        string state
+        boolean included
+        string source_type
+        string adjustable_type
+    }
+
+    Order ||--o{ Adjustment : "has many"
+    Order ||--o{ LineItem : "has many"
+    Order ||--o{ Shipment : "has many"
+    LineItem ||--o{ Adjustment : "has many"
+    Shipment ||--o{ Adjustment : "has many"
+    TaxRate ||--o{ Adjustment : "creates"
+    PromotionAction ||--o{ Adjustment : "creates"
+```
+
+**Key relationships:**
+- **Adjustment** modifies prices on orders, line items, or shipments
+- **Source** is where the adjustment comes from ([Tax Rate](/developer/core-concepts/taxes) or [Promotion Action](/developer/core-concepts/promotions))
+- **Adjustable** is what's being adjusted (Order, LineItem, or Shipment)
+- Positive amounts are charges, negative amounts are credits
+
+## Adjustment Types
+
+### Included vs Additional
+
+- **Included** adjustments are part of the item's displayed price (e.g., VAT in European stores)
+- **Additional** adjustments are added on top of the item's price (e.g., US sales tax)
+
+### Sources
+
+Adjustments are created by two sources:
+
+| Source | Example | Typical Amount |
+|--------|---------|----------------|
+| [Tax Rate](/developer/core-concepts/taxes) | Sales tax, VAT | Positive (charge) |
+| [Promotion Action](/developer/core-concepts/promotions) | Coupon discount, free shipping | Negative (credit) |
+
+## Adjustment Attributes
+
+| Attribute | Description | Example |
+|-----------|-------------|---------|
+| `amount` | The monetary value of the adjustment | `-10.00` |
+| `label` | Human-readable description | `10% off order` |
+| `eligible` | Whether the adjustment currently applies | `true` |
+| `mandatory` | If `true`, always applied regardless of eligibility rules | `false` |
+| `state` | `open` (auto-updated) or `closed` (locked) | `open` |
+| `included` | Whether the amount is included in the item's displayed price | `false` |
+
+## Adjustment Lifecycle
+
+- **Open** adjustments are recalculated whenever the order is updated (e.g., items added/removed, address changed)
+- **Closed** adjustments are locked and will not be automatically recalculated
+- When a promotion becomes ineligible (e.g., item removed from cart), its adjustments are automatically removed
+
+## Store API
+
+Adjustments appear in order responses when you expand line items or shipments:
+
+
+```typescript SDK
+const order = await client.orders.get('or_abc123', {
+  spreeToken: '<token>',
+})
+
+// Line item adjustments (promotions, taxes)
+order.items?.forEach(item => {
+  item.adjustment_total  // total adjustments on this item
+  item.additional_tax_total
+  item.included_tax_total
+})
+
+// Order-level totals
+order.adjustment_total    // total of all adjustments
+order.promo_total         // total promotional discounts
+order.additional_tax_total
+order.included_tax_total
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/orders/or_abc123?expand=items,shipments' \
+  -H 'Authorization: Bearer spree_pk_xxx' \
+  -H 'X-Spree-Token: <token>'
+```
+
+
+## Related Documentation
+
+- [Promotions](/developer/core-concepts/promotions) — Promotion-based adjustments
+- [Taxes](/developer/core-concepts/taxes) — Tax adjustments
+- [Shipments](/developer/core-concepts/shipments) — Shipping adjustments
+- [Orders](/developer/core-concepts/orders) — How adjustments affect order totals

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

@@ -0,0 +1,177 @@
+---
+title: Architecture
+description: How Spree's core models, APIs, and packages work together
+---
+
+## Overview
+
+Spree is a commerce engine built around interconnected models that represent the core concepts of commerce: products, orders, payments, and shipments. It adapts to your stack — use it as a headless API for any frontend, embed it into an existing application, or scale it from a single storefront to a global multi-vendor marketplace.
+
+> **INFO:** Spree supports PostgreSQL, MySQL, and SQLite. PostgreSQL is recommended for production. [Learn more about database configuration](/developer/deployment/database).
+
+## Core Commerce Flow
+
+The following diagram shows how the main models interact during a typical customer purchase:
+
+```mermaid
+flowchart TB
+    subgraph Catalog["Catalog"]
+        Product --> Variant
+        Variant --> Price
+        Variant --> StockItem
+        StockItem --> StockLocation
+    end
+
+    subgraph Shopping["Shopping"]
+        User --> Order
+        Order --> LineItem
+        LineItem --> Variant
+    end
+
+    subgraph Checkout["Checkout"]
+        Order --> Address
+        Order --> Shipment
+        Order --> Payment
+        Shipment --> ShippingMethod
+        Payment --> PaymentMethod
+    end
+
+    subgraph Fulfillment["Fulfillment"]
+        Shipment --> InventoryUnit
+        InventoryUnit --> Variant
+        StockLocation --> Shipment
+    end
+
+    subgraph Pricing["Pricing & Adjustments"]
+        Order --> Adjustment
+        LineItem --> Adjustment
+        Shipment --> Adjustment
+        TaxRate --> Adjustment
+        Promotion --> Adjustment
+    end
+```
+
+**How it works:**
+
+1. **Catalog** — [Products](/developer/core-concepts/products) have [Variants](/developer/core-concepts/products#variants) (SKUs) with prices and inventory tracked at [Stock Locations](/developer/core-concepts/inventory#stock-locations)
+
+2. **Shopping** — Customers add Variants to their cart, creating an [Order](/developer/core-concepts/orders) with Line Items
+
+3. **Checkout** — The Order collects [Addresses](/developer/core-concepts/addresses), calculates [Shipping](/developer/core-concepts/shipments) options, and processes [Payments](/developer/core-concepts/payments)
+
+4. **Fulfillment** — [Shipments](/developer/core-concepts/shipments) are created from Stock Locations, tracking individual [Inventory Units](/developer/core-concepts/inventory#inventory-units)
+
+5. **Pricing & Adjustments** — [Taxes](/developer/core-concepts/taxes) and [Promotions](/developer/core-concepts/promotions) create [Adjustments](/developer/core-concepts/adjustments) that modify order totals
+
+## Core Model Relationships
+
+This diagram shows the key database relationships between Spree's main models:
+
+```mermaid
+erDiagram
+    Store ||--o{ Order : "has many"
+    Store ||--o{ Product : "has many"
+
+    Product ||--o{ Variant : "has many"
+    Product }o--|| TaxCategory : "belongs to"
+    Product }o--|| ShippingCategory : "belongs to"
+    Product }o--o{ Taxon : "categorized by"
+
+    Variant ||--o{ Price : "has many"
+    Variant ||--o{ StockItem : "has many"
+    Variant ||--o{ LineItem : "has many"
+
+    Order ||--o{ LineItem : "has many"
+    Order ||--o{ Shipment : "has many"
+    Order ||--o{ Payment : "has many"
+    Order ||--o{ Adjustment : "has many"
+    Order }o--|| User : "belongs to"
+    Order }o--|| Address : "ship address"
+    Order }o--|| Address : "bill address"
+
+    Shipment ||--o{ InventoryUnit : "has many"
+    Shipment }o--|| StockLocation : "ships from"
+    Shipment }o--|| ShippingMethod : "via"
+
+    Payment }o--|| PaymentMethod : "via"
+
+    StockLocation ||--o{ StockItem : "has many"
+
+    TaxRate }o--|| TaxCategory : "belongs to"
+    TaxRate }o--|| Zone : "applies to"
+    TaxRate ||--o{ Adjustment : "creates"
+
+    Promotion ||--o{ Adjustment : "creates"
+```
+
+## APIs
+
+Spree exposes two REST APIs, both under API v3:
+
+| API | Purpose | Authentication |
+|-----|---------|----------------|
+| [**Store API**](/api-reference/introduction) | Customer-facing — cart, checkout, products, account | Publishable API key + JWT |
+| **Admin API** | Operational — manage products, orders, customers, settings | Secret API key |
+
+Both APIs use [prefixed IDs](/api-reference/introduction) (e.g., `prod_86Rf07xd4z`, `or_m3Rp9wXz`), flat JSON request/response structures, and full TypeScript types via the [@spree/sdk](/developer/sdk/quickstart).
+
+Events from both APIs can trigger [Webhooks](/developer/core-concepts/webhooks) to notify external systems in real time.
+
+## Multi-Store Architecture
+
+Spree supports [multiple stores](/developer/multi-store/quickstart) from a single installation. Each Store can have:
+
+- Its own domain and branding
+- Different currencies and locales
+- Separate product catalogs
+- Independent payment and shipping methods
+- Isolated orders and customers
+
+This makes Spree suitable for multi-brand retailers, international expansion, or B2B/B2C hybrid setups.
+
+## Extension Points
+
+Spree is designed to be customized without modifying core code. The main extension mechanisms are:
+
+| Mechanism | Use Case | Documentation |
+|-----------|----------|---------------|
+| **Events & Subscribers** | React to order completion, payment, shipment events | [Events Guide](/developer/core-concepts/events) |
+| **Webhooks** | Notify external systems of changes | [Webhooks Guide](/developer/core-concepts/webhooks) |
+| **Dependencies** | Swap out services (tax calculation, shipping estimation) | [Dependencies Guide](/developer/customization/dependencies) |
+| **Decorators** | Modify existing model/controller behavior (use sparingly) | [Decorators Guide](/developer/customization/decorators) |
+
+> **INFO:** For most customizations, prefer **Events** and **Dependencies** over Decorators. They're easier to maintain and won't break during upgrades.
+
+## Packages
+
+Spree is distributed as a set of packages:
+
+**Core (required):**
+
+| Package | Purpose |
+|---------|---------|
+| `spree` | Models, services, business logic, Store API, Admin API, and Webhooks |
+
+**Optional:**
+
+| Package | Purpose |
+|---------|---------|
+| `spree_admin` | Admin dashboard for managing your store |
+| `spree_emails` | Transactional email templates (order confirmation, shipping, etc.) |
+
+**TypeScript packages:**
+
+| Package | Purpose |
+|---------|---------|
+| [`@spree/sdk`](/developer/sdk/quickstart) | TypeScript SDK for Store API and Admin API |
+| [`@spree/next`](/developer/storefront/nextjs/spree-next-package) | Next.js integration — server actions, caching, cookie-based auth |
+
+> **INFO:** For headless commerce, you only need the `spree` package. Build your customer-facing frontend with any technology (Next.js, Nuxt, mobile apps) using the Store API and SDK.
+
+## Related Documentation
+
+- [Products](/developer/core-concepts/products) — Product catalog and variants
+- [Orders](/developer/core-concepts/orders) — Order lifecycle and state machine
+- [Payments](/developer/core-concepts/payments) — Payment processing
+- [Shipments](/developer/core-concepts/shipments) — Shipping and fulfillment
+- [Customization Quickstart](/developer/customization/quickstart) — How to extend Spree