@spree/docs 0.1.0

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

@@ -0,0 +1,191 @@
+---
+title: Inventory
+description: Stock locations, stock items, stock movements, and inventory tracking
+---
+
+## Overview
+
+Each [Variant](/developer/core-concepts/products#variants) has a `StockItem` that tracks its inventory at a specific location. A variant can have multiple stock items if it's available at multiple stock locations.
+
+When products are sold or returned, individual `InventoryUnit` records track each unit through the fulfillment process.
+
+Adding new inventory to an out-of-stock product that has backorders will first fill the backorders, then update the available count with the remainder.
+
+### Inventory Model Diagram
+
+```mermaid
+erDiagram
+    StockLocation {
+        string name
+        string admin_name
+        boolean active
+        boolean default
+        boolean backorderable_default
+        boolean propagate_all_variants
+    }
+
+    StockItem {
+        integer count_on_hand
+        boolean backorderable
+        integer stock_location_id
+        integer variant_id
+    }
+
+    StockMovement {
+        integer quantity
+        string originator_type
+        integer originator_id
+        integer stock_item_id
+    }
+
+    StockTransfer {
+        string number
+        string reference
+        integer source_location_id
+        integer destination_location_id
+    }
+
+    InventoryUnit {
+        string state
+        integer variant_id
+        integer order_id
+        integer shipment_id
+    }
+
+    StockLocation ||--o{ StockItem : "has many"
+    StockLocation ||--o{ StockTransfer : "source"
+    StockLocation ||--o{ StockTransfer : "destination"
+    Variant ||--o{ StockItem : "has many"
+    Variant ||--o{ InventoryUnit : "has many"
+    StockItem ||--o{ StockMovement : "has many"
+    StockTransfer ||--o{ StockMovement : "has many"
+    Order ||--o{ InventoryUnit : "has many"
+    Shipment ||--o{ InventoryUnit : "has many"
+```
+
+**Key relationships:**
+- **Stock Location** → Contains Stock Items (inventory per variant) and is the source/destination for Stock Transfers
+- **Stock Item** → Tracks quantity (`count_on_hand`) for a specific Variant at a specific Stock Location
+- **Stock Movement** → Records changes to Stock Item quantities (purchases, returns, transfers)
+- **Stock Transfer** → Moves inventory between Stock Locations, creating Stock Movements at source and destination
+- **Inventory Unit** → Represents individual units in [Orders](/developer/core-concepts/orders) and [Shipments](/developer/core-concepts/shipments)
+
+## Inventory Management
+
+### Stock Locations
+
+Stock Locations are the physical locations where your inventory is stored and shipped from.
+
+Stock Locations can be created in the Admin Panel under **Settings → Stock Locations**, or via the Admin API.
+
+Stock Locations have several attributes that define their properties and behavior within the Spree system. Below is a table outlining these attributes:
+
+| Attribute         | Description                                                                 | Example Value       |
+|-------------------|-----------------------------------------------------------------------------|---------------------|
+| `name`            | The public name of the stock location. This is returned in Store API | Warehouse 1       |
+| `admin_name`       | The name used internally for the stock location. This is only returned in Admin API. | WH1 Domestic     |
+| `address1`        | The primary address line for the stock location.                           | 5th avenue     |
+| `address2`        | The secondary address line for the stock location.                         | Suite 100         |
+| `city`            | The city where the stock location is based.                                | New York        |
+| `state_id`        | The ID of the state where the stock location is based. This references the `State` model. | 1                 |
+| `country_id`      | The ID of the country where the stock location is based. This references the `Country` model. | 1                 |
+| `zipcode`         | The postal code for the stock location.                                    | 10001             |
+| `phone`           | The contact phone number for the stock location.                           | 555-1234          |
+| `active`          | A boolean indicating whether the stock location is active. Inactive stock locations will not be used in stock calculations or be available for selection during checkout. | `true`             |
+| `default`          | A boolean indicating whether the stock location is the default one used for new inventory operations. | `false`             |
+| `backorderable_default` | A boolean indicating whether new stock items in this location are backorderable by default. | `false` |
+| `propagate_all_variants` | A boolean indicating whether new stock items should be automatically created for all Store variants when a new stock location is added. | `false` |
+
+Stock Locations can be easily used for tracking warehouses and other physical locations. They can be used to track separate sections of a warehouse (e.g. aisles, shelves, etc.) or to track different warehouses.
+
+You can easily use them with your Point of Sale (POS) system to track inventory at different locations.
+
+### Stock Items
+
+Stock Items represent the inventory at a stock location for a specific variant. Stock item count on hand can be increased or decreased by creating stock movements.
+
+| Attribute         | Description                                                                 | Example Value       |
+|-------------------|-----------------------------------------------------------------------------|---------------------|
+| `stock_location_id` | References the stock location where the stock item belongs.                | `1`                 |
+| `variant_id`      | References the variant associated with the stock item.                     | `32`                |
+| `count_on_hand`   | The number of items available on hand.                                     | `150`               |
+| `backorderable`   | Indicates whether the stock item can be backordered.                       | `true`    |
+
+### Stock Transfers
+
+Stock transfers allow you to move inventory in bulk from one stock location to another stock location. This is handy when you want to integrate with a POS system or other inventory management system. Or you can just rely on Spree being the source of truth for your inventory.
+
+> **INFO:** Stock Transfers can be created in the Admin dashboard or via the Admin API.
+
+Here's the list of attributes for the Stock Transfer model:
+
+| Attribute                | Description                                                                 | Example Value       |
+|--------------------------|-----------------------------------------------------------------------------|---------------------|
+| `number`                 | The unique number identifier for the stock transfer, generated automatically. | `T123456789`        |
+| `reference`              | An optional reference field for the stock transfer.                        | Transfer for Event |
+| `source_location_id`     | The ID of the stock location where the stock is transferred from.          | `2`                 |
+| `destination_location_id`| The ID of the stock location where the stock is transferred to.            | `3`                 |
+
+Stock transfers are crucial for managing inventory across multiple locations, ensuring that stock levels are accurate and up-to-date.
+
+Each Stock Transfer will hold a list of Stock Movements.
+
+### Stock Movements
+
+Stock Movements track the movement of the inventory:
+
+* when you move inventory between stock locations (via Stock Transfer)
+* when you add inventory to a stock location
+* when you remove inventory from a stock location
+* when customers purchase products
+* when customers return products
+
+Here's the list of attributes for the Stock Movement model:
+
+| Attribute         | Description                                                                 | Example Value       |
+|-------------------|-----------------------------------------------------------------------------|---------------------|
+| `stock_item_id`   | References the stock item that the movement belongs to.                     | `45`                |
+| `quantity`        | The quantity by which the stock item's count on hand is changed. Positive values indicate stock being added, while negative values indicate stock being removed. | `-10`               |
+| `originator_type` | The type of the originator of the stock movement. This is a polymorphic association. | `Spree::Shipment`      |
+| `originator_id`   | The ID of the originator of the stock movement. This is used in conjunction with `originator_type`. | `2`                 |
+
+Stock Movements are crucial for maintaining accurate inventory levels and for historical tracking of inventory adjustments.
+
+## Inventory Units
+
+As we mentioned above, back-ordered, sold, or shipped products are stored as individual `InventoryUnit` objects so they can have relevant information attached to them.
+
+We create `InventoryUnit` objects when:
+
+* a product is sold (they are added to the Shipment)
+* a product is returned
+
+Here's a list of attributes for the Inventory Unit model:
+
+| Attribute         | Description                                                                 | Example Value       |
+|-------------------|-----------------------------------------------------------------------------|---------------------|
+| `variant_id`      | References the variant associated with the inventory unit.                 | `32`                |
+| `order_id`        | References the order associated with the inventory unit.                   | `123`               |
+| `shipment_id`          | References the shipment associated with the inventory unit.                   | `77`                |
+| `state`           | The state of the inventory unit | `on_hand`      |
+
+Inventory Units states are:
+
+* `on_hand` - the inventory unit is on hand
+* `backordered` - the inventory unit is backordered
+* `shipped` - the inventory unit is shipped
+
+> **NOTE:** As we noted before, when you add new Stock Items to a Variant (eg. via Admin Panel or Admin API), the first Inventory Units to fulfill are the backordered ones.
+
+## Disabling Inventory Tracking
+
+If you don't need to track inventory, you can disable it:
+
+- **Per variant** — set `track_inventory` to `false` on a specific variant via the Admin Panel or Admin API
+- **Globally** — disable inventory tracking for the entire store in your Spree configuration
+
+## Related Documentation
+
+- [Products](/developer/core-concepts/products) - Product and variant management
+- [Shipments](/developer/core-concepts/shipments) - How inventory relates to shipments
+- [Orders](/developer/core-concepts/orders) - How inventory is allocated to orders

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

@@ -0,0 +1,250 @@
+---
+title: Markets
+description: Multi-region commerce with Markets — bundle geography, currency, and locale into distinct selling regions within a single store.
+---
+
+## Overview
+
+Markets let you segment a single [Store](/developer/core-concepts/stores) into distinct geographic regions, each with its own currency, locale, and set of countries. For example, an international store might define:
+
+- **North America** — USD, English, ships to US and Canada
+- **Europe** — EUR, German, ships to DE, FR, AT, NL
+- **United Kingdom** — GBP, English, ships to GB
+
+```mermaid
+erDiagram
+    Store ||--o{ Market : "has many"
+    Market ||--o{ MarketCountry : "has many"
+    MarketCountry }o--|| Country : "belongs to"
+
+    Store {
+        string name
+        string url
+    }
+
+    Market {
+        string name
+        string currency
+        string default_locale
+        string supported_locales
+        boolean tax_inclusive
+        boolean default
+    }
+
+    Country {
+        string iso
+        string name
+    }
+```
+
+## Market Attributes
+
+| Attribute | Description | Example |
+|-----------|-------------|---------|
+| `name` | Human-readable name, unique per store | `North America` |
+| `currency` | ISO 4217 currency code | `USD` |
+| `default_locale` | Default language for this market | `en` |
+| `supported_locales` | All locales available in this market | `["en", "es"]` |
+| `tax_inclusive` | Whether prices include tax (affects display and checkout calculation) | `false` |
+| `default` | Whether this is the fallback market when no country match is found | `true` |
+| `countries` | List of countries in this market | `[{ iso: "US" }, { iso: "CA" }]` |
+
+## How Markets Work
+
+When a customer visits your store, their country determines which market applies. The market then sets the currency, locale, and tax behavior for that session.
+
+```
+Customer's Country → Market → Currency + Locale + Tax Zone
+```
+
+The resolution chain:
+
+1. Customer's country is detected (from URL, geolocation, `X-Spree-Country` header, or manual selection)
+2. Spree finds the market containing that country
+3. The market's currency and locale become the defaults for the session
+4. The market's tax zone determines whether prices are shown with or without tax
+
+If no market matches the customer's country, the store's **default market** is used.
+
+## Listing Markets
+
+Fetch all markets for the current store, including their countries:
+
+
+```typescript SDK
+const { data: markets } = await client.markets.list()
+// [
+//   {
+//     id: "mkt_k5nR8xLq",
+//     name: "North America",
+//     currency: "USD",
+//     default_locale: "en",
+//     supported_locales: ["en", "es"],
+//     tax_inclusive: false,
+//     default: true,
+//     countries: [
+//       { iso: "US", name: "United States", states_required: true, zipcode_required: true },
+//       { iso: "CA", name: "Canada", states_required: true, zipcode_required: true }
+//     ]
+//   },
+//   ...
+// ]
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/markets' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+```
+
+
+## Resolving a Market by Country
+
+When you know a customer's country (e.g., from geolocation or a country picker), resolve which market applies:
+
+
+```typescript SDK
+const market = await client.markets.resolve('DE')
+// { id: "mkt_gbHJdmfr", name: "Europe", currency: "EUR", tax_inclusive: true, ... }
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/markets/resolve?country=DE' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+```
+
+
+Returns the market object on success, or `404` if no market contains that country.
+
+This is useful for building a country switcher — resolve the market to show the customer what currency and language they'll get.
+
+## Countries in a Market
+
+List countries belonging to a specific market. Useful for populating address form dropdowns during checkout:
+
+
+```typescript SDK
+const { data: countries } = await client.markets.countries.list('mkt_k5nR8xLq')
+// [
+//   { iso: "CA", name: "Canada", states_required: true, zipcode_required: true },
+//   { iso: "US", name: "United States", states_required: true, zipcode_required: true }
+// ]
+
+// Get a country with its states (for address form dropdowns)
+const usa = await client.markets.countries.get('mkt_k5nR8xLq', 'US', {
+  include: 'states',
+})
+```
+
+```bash cURL
+# List countries in a market
+curl 'https://api.mystore.com/api/v3/store/markets/mkt_k5nR8xLq/countries' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+
+# Get a country with its states
+curl 'https://api.mystore.com/api/v3/store/markets/mkt_k5nR8xLq/countries/US?include=states' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+```
+
+
+You can also fetch countries flat (across all markets) or include the market on a country:
+
+
+```typescript SDK
+// All countries across all markets
+const { data: countries } = await client.countries.list()
+
+// Get a country with its market details
+const germany = await client.countries.get('DE', { include: 'market' })
+// { iso: "DE", name: "Germany", market: { currency: "EUR", default_locale: "de", tax_inclusive: true } }
+```
+
+```bash cURL
+# All countries across all markets
+curl 'https://api.mystore.com/api/v3/store/countries' \
+  -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'
+```
+
+
+## Currency and Locale
+
+Each market defines a currency and set of supported locales. When a market is resolved, its currency and locale become the defaults for the session.
+
+You can discover all available currencies and locales (aggregated from all markets) via dedicated endpoints:
+
+
+```typescript SDK
+const { data: currencies } = await client.currencies.list()
+// [{ iso_code: "USD", name: "US Dollar", symbol: "$" }, { iso_code: "EUR", name: "Euro", symbol: "€" }]
+
+const { data: locales } = await client.locales.list()
+// [{ code: "en", name: "English" }, { code: "de", name: "German" }]
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/currencies' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+
+curl 'https://api.mystore.com/api/v3/store/locales' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+```
+
+
+See [Localization](/api-reference/store-api/localization) for details on how to pass locale, currency, and country headers in API requests.
+
+## Tax Behavior
+
+The `tax_inclusive` flag on a market controls how prices are displayed and calculated:
+
+- **`tax_inclusive: true`** (common in Europe) — the price shown to the customer already includes tax
+- **`tax_inclusive: false`** (common in the US) — tax is added at checkout on top of the displayed price
+
+Each market also resolves a **tax zone** from its default country. This zone determines which tax rates apply when browsing products — before the customer enters a shipping address. Once the customer provides an address at checkout, the actual shipping address takes over for tax calculation.
+
+See [Taxes](/developer/core-concepts/taxes) for details on tax zones and rates.
+
+## Pricing Integration
+
+Markets integrate with the [Pricing](/developer/core-concepts/pricing) system, enabling market-specific pricing through **Price Lists** with a **Market Rule**. This lets you set different prices for the same product in different markets — beyond just currency conversion.
+
+For example, you could price a product at $29.99 in North America and €24.99 in Europe, rather than relying on exchange rate conversion.
+
+See [Pricing — Price Rules](/developer/core-concepts/pricing#price-rules) for details on configuring market-specific price lists.
+
+## Setting Up Markets
+
+Markets are managed in the admin dashboard under **Settings → Markets**. When you run `rails db:seed`, Spree automatically creates a default market for each store.
+
+To create markets programmatically:
+
+```ruby
+# North America market
+current_store.markets.create!(
+  name: 'North America',
+  currency: 'USD',
+  default_locale: 'en',
+  countries: [usa, canada],
+  default: true
+)
+
+# Europe market with tax-inclusive pricing
+current_store.markets.create!(
+  name: 'Europe',
+  currency: 'EUR',
+  default_locale: 'de',
+  supported_locales: 'de,en,fr',
+  tax_inclusive: true,
+  countries: [germany, france, austria, netherlands]
+)
+```
+
+## Related Documentation
+
+- [Stores](/developer/core-concepts/stores) — Multi-store setup and configuration
+- [Pricing](/developer/core-concepts/pricing) — Price Lists, Price Rules, and the Pricing Context
+- [Addresses](/developer/core-concepts/addresses) — Countries, States, and Zones
+- [Localization](/api-reference/store-api/localization) — Locale, currency, and country headers in API requests
+- [Translations](/developer/core-concepts/translations) — Resource and UI translations

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

@@ -0,0 +1,167 @@
+---
+title: Media
+sidebarTitle: "Media"
+description: Product media (images, videos), named variants, focal points, and how media is served via the Store API
+---
+
+## Overview
+
+Spree handles uploads, processing, and delivery for product media. Images are automatically converted to WebP format and preprocessed into multiple sizes for optimal performance.
+
+## Product Media
+
+Product media uses the `Spree::Asset` model, which provides:
+
+- **Multiple media per product** with ordering
+- **Media types** — `image`, `video`, `external_video`
+- **Alt text** for accessibility and SEO
+- **Focal point** coordinates for smart cropping
+- **Preprocessed named variants** for fast delivery
+
+Each media item has a `media_type` field that defaults to `image`. The `variant_ids` field indicates which product variants the media is associated with — an empty array means the media belongs to the product as a whole.
+
+> **NOTE:** `Spree::Image` is a backward-compatible subclass of `Spree::Asset` that sets `media_type` to `image`. New code should use `Spree::Asset` directly.
+
+### Named Variant Sizes
+
+When an image is uploaded, Spree automatically generates optimized versions in the background:
+
+| Name | Dimensions | Use Case |
+|------|------------|----------|
+| `mini` | 128x128 | Thumbnails, cart items |
+| `small` | 256x256 | Product listings, galleries |
+| `medium` | 400x400 | Product cards, category pages |
+| `large` | 720x720 | Product detail pages |
+| `xlarge` | 2000x2000 | Zoom, high-resolution displays |
+
+All variants are cropped to fill the exact dimensions and converted to WebP format.
+
+## Store API
+
+### Thumbnails (Always Available)
+
+Every product response includes a `thumbnail_url` field — ready to use without any expands. Similarly, each variant includes a `thumbnail` URL and a `media_count` counter.
+
+
+```typescript SDK
+// List products — thumbnail_url is always included
+const { data: products } = await client.products.list({ limit: 12 })
+
+products.forEach(product => {
+  product.thumbnail_url // "https://cdn.../tote-front.webp" — no expand needed
+})
+```
+
+```bash cURL
+# thumbnail_url is always in the response — no ?expand needed
+curl 'https://api.mystore.com/api/v3/store/products?limit=12' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+```
+
+
+> **WARNING:** Avoid using `?expand=media` on listing pages. This loads **all** media for every product in the response. Use `thumbnail_url` instead and only expand full media on product detail pages.
+
+### Full Media (On Demand)
+
+On the product detail page, expand `media` and `variants` to get the full set of media with all named variant URLs:
+
+
+```typescript SDK
+const product = await client.products.get('spree-tote', {
+  expand: ['media', 'variants'],
+})
+
+// Product media gallery
+product.media // [{ id, media_type, product_id, variant_ids, original_url, mini_url, ..., alt, position }, ...]
+
+// Each variant has its own thumbnail and media_count
+product.variants?.forEach(variant => {
+  variant.thumbnail    // "https://cdn.../tote-red.webp" — always available
+  variant.media_count  // 3 — quick check without loading media
+  variant.media        // full media array (only with ?expand=media)
+})
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=media,variants' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+```
+
+
+**Response (media object):**
+
+```json
+{
+  "id": "media_k5nR8xLq",
+  "media_type": "image",
+  "product_id": "prod_86Rf07xd4z",
+  "variant_ids": ["variant_m3Rp9wXz"],
+  "position": 1,
+  "alt": "Front view",
+  "focal_point_x": null,
+  "focal_point_y": null,
+  "external_video_url": null,
+  "original_url": "https://cdn.example.com/images/original.jpg",
+  "mini_url": "https://cdn.example.com/images/mini.webp",
+  "small_url": "https://cdn.example.com/images/small.webp",
+  "medium_url": "https://cdn.example.com/images/medium.webp",
+  "large_url": "https://cdn.example.com/images/large.webp",
+  "xlarge_url": "https://cdn.example.com/images/xlarge.webp"
+}
+```
+
+### Media Fields Summary
+
+| Field | Available on | Always Returned | Description |
+|-------|-------------|:---:|-------------|
+| `thumbnail_url` | Product | Yes | URL to the product's first media |
+| `thumbnail` | Variant | Yes | URL to the variant's first media |
+| `media_count` | Variant | Yes | Number of media items (counter cache) |
+| `media` | Product, Variant | No | Full media array (requires `?expand=media`) |
+
+### Media Object Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Prefixed ID (`media_xxx`) |
+| `media_type` | string | `image`, `video`, or `external_video` |
+| `product_id` | string \| null | Owning product prefixed ID |
+| `variant_ids` | string[] | Associated variant prefixed IDs (empty = product-level) |
+| `position` | number | Sort order |
+| `alt` | string \| null | Alt text |
+| `focal_point_x` | number \| null | Horizontal focal point (0.0–1.0) |
+| `focal_point_y` | number \| null | Vertical focal point (0.0–1.0) |
+| `external_video_url` | string \| null | External video URL (YouTube/Vimeo) |
+| `original_url` | string \| null | Full-size image URL |
+| `mini_url` ... `xlarge_url` | string \| null | Named variant URLs |
+
+## Image Processing
+
+Spree uses [libvips](https://www.libvips.org/) for image processing. Images are automatically:
+
+- Converted to **WebP format** for optimal file size
+- **Preprocessed on upload** into all named variant sizes
+- **Cached** for subsequent requests
+
+## Storage
+
+Spree supports two storage service types:
+
+| Service | Purpose | Examples |
+|---------|---------|---------|
+| Public storage | Product images, logos, taxon images | S3 public bucket, CDN |
+| Private storage | CSV exports, digital downloads | S3 private bucket |
+
+> **INFO:** For production deployments, use cloud storage (S3, GCS, Azure) instead of local disk storage. See [Asset Deployment](/developer/deployment/assets) for configuration details.
+
+## Best Practices
+
+- **Use `thumbnail_url`** on listing pages — avoid loading full media via expand
+- **Always provide alt text** for accessibility and SEO
+- **Use named variant sizes** (`mini`, `small`, `medium`, `large`, `xlarge`) for optimal performance
+- **Use a CDN** in production for faster delivery
+
+## Related Documentation
+
+- [Products](/developer/core-concepts/products) — Product catalog and media
+- [Deployment — Assets](/developer/deployment/assets) — Storage and CDN configuration