@spree/docs 0.1.71 → 0.1.73

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

@@ -0,0 +1,167 @@
+---
+title: Channels
+description: Per-store distribution surfaces — online storefront, POS, marketplace, wholesale — each with its own product catalog and order attribution.
+---
+
+import { Since } from '/snippets/since.mdx';
+
+
+## Overview
+
+Channels segment a single [Store](stores.md) into distinct selling surfaces. A channel represents *where* an order originates from — the online storefront, an in-person point-of-sale till, a marketplace integration (Amazon, eBay), a B2B wholesale portal, a mobile app — and *which* subset of the store's products is available there.
+
+Every store ships with one default channel named *Online Store*. You can add more from **Settings → Sales channels** in the admin dashboard.
+
+## Channel Attributes
+
+| Attribute | Description | Example |
+|-----------|-------------|---------|
+| `name` | Human-readable name, displayed in the admin and reports | `Point of Sale` |
+| `code` | URL-safe slug, stable identifier sent via the `X-Spree-Channel` header | `pos` |
+| `active` | When `false`, the channel stops accepting orders | `true` |
+| `default` | Exactly one channel per store is the default. Used as a fallback when no channel header is present and as the auto-publish target for new products | `true` |
+| `preferred_order_routing_strategy` | Optional per-channel override of the store's [Order Routing](shipments.md#order-routing) strategy | `Rules` |
+
+`code` is normalized to a URL-safe slug on save — `POS` becomes `pos`, `Point of Sale!` becomes `point-of-sale`. Leaving `code` blank derives it from `name`.
+
+## How Channels Work
+
+### Resolution at request time
+
+Every incoming Store API or storefront request resolves to a channel:
+
+1. If the `X-Spree-Channel` header is present, the value is matched against `channels.code` — or `channels.id` when the value looks like a prefixed ID (`ch_…`) — scoped to the current store.
+2. Otherwise, the store's default channel is used.
+
+The resolved channel is then available to controllers, models, and serializers throughout the request.
+
+### Selecting a channel from the Store SDK
+
+The Store SDK sends `X-Spree-Channel` on every request when configured. The value can be either the channel `code` (merchant-meaningful, recommended) or the prefixed ID (`ch_…`).
+
+
+```typescript SDK
+// Client-level default
+const client = createClient({
+  baseUrl: 'https://api.mystore.com',
+  publishableKey: 'pk_xxx',
+  channel: 'pos',
+})
+
+// Sticky setter (mirrors setLocale / setCurrency / setCountry)
+client.setChannel('wholesale')
+
+// Per-request override
+const products = await client.products.list({}, { channel: 'pos' })
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/products' \
+  -H 'X-Spree-API-Key: pk_xxx' \
+  -H 'X-Spree-Channel: pos'
+```
+
+
+The Admin API does not consume `X-Spree-Channel` — admin endpoints return data across all channels for the current store. Filter by channel on the admin side via Ransack (`q[channel_id_eq]=ch_xxx` for orders, `q[channels_id_in][]=ch_xxx` for products).
+
+### Product visibility
+
+A product is visible on a channel only when it has a publication record joining the two. Each publication carries an optional window:
+
+| Publication state | What customers see |
+|---|---|
+| No publication exists | Product is not on this channel — invisible |
+| Publication has no dates set | Live now and indefinitely |
+| `published_at` is in the future | Scheduled — not yet visible |
+| `unpublished_at` is in the past | Hidden — was visible, now sunset |
+| Within the window | Live |
+
+Product status (`draft` / `active` / `archived`) is the **outer gate**: a Draft or Archived product is hidden on every channel regardless of its publication window. The dashboard's Publishing card renders this as a "Not available" badge on every channel row when status isn't `active`.
+
+### Order attribution
+
+Every order is attributed to one channel. The channel is set from the `X-Spree-Channel` header on cart creation, from the merchant's selection on the "New order" form, or defaults to the store's primary channel.
+
+This attribution drives reporting (best-selling by channel, revenue per channel) and per-channel order routing — see [Order Routing](shipments.md#order-routing).
+
+## Publishing Products on Channels
+
+### Dashboard
+
+The product edit page has a **Publishing** card with one row per channel the product is on. Click *Manage* to attach or detach channels via checkboxes. Each row expands into a per-channel schedule editor.
+
+Bulk operations from the product list: *Add to sales channels…* and *Remove from sales channels…*.
+
+### Admin API
+
+Three endpoints cover the publishing surface:
+
+| Endpoint | Use case |
+|---|---|
+| `POST /api/v3/admin/channels/:id/add_products` | Publish one or more products on a specific channel |
+| `POST /api/v3/admin/channels/:id/remove_products` | Unpublish products from a specific channel |
+| `POST /api/v3/admin/products/bulk_add_to_channels` | Publish many products across many channels in a single request |
+
+
+```typescript SDK
+await adminClient.channels.addProducts('ch_xxx', {
+  product_ids: ['prod_aaa', 'prod_bbb'],
+  // Optional window — when omitted, existing schedules are preserved
+  published_at: '2026-07-01T00:00:00Z',
+  unpublished_at: '2026-12-31T23:59:59Z',
+})
+```
+
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/admin/channels/ch_xxx/add_products' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "product_ids": ["prod_aaa", "prod_bbb"],
+    "published_at": "2026-07-01T00:00:00Z",
+    "unpublished_at": "2026-12-31T23:59:59Z"
+  }'
+```
+
+
+`channels.addProducts` is idempotent: re-publishing an already-published product is a no-op for its window unless `published_at` / `unpublished_at` are explicitly passed. Cross-store onboarding is allowed when the caller's key has update permission on the product.
+
+For per-product updates, use `PATCH /api/v3/admin/products/:id` with a `product_publications` array:
+
+
+```typescript SDK
+await adminClient.products.update('prod_xxx', {
+  product_publications: [
+    { channel_id: 'ch_online' },
+    { channel_id: 'ch_pos', published_at: '2026-07-01T00:00:00Z' },
+  ],
+})
+```
+
+```bash cURL
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/products/prod_xxx' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "product_publications": [
+      { "channel_id": "ch_online" },
+      { "channel_id": "ch_pos", "published_at": "2026-07-01T00:00:00Z" }
+    ]
+  }'
+```
+
+
+The write contract is **full-set**: the array represents the complete desired state. Channels absent from the payload are detached.
+
+## Auto-Publish Behavior
+
+- **Dashboard** — new products are auto-published on the store's default channel. The merchant can untick channels via the Publishing card post-create.
+- **Admin API** — new products are **not** auto-published. The caller supplies `product_publications: [{ channel_id }]` on create, or calls `POST /admin/channels/:id/add_products` afterwards.
+- **Sample data** (`bin/rake spree:load_sample_data`) — all loaded products are explicitly published on the default channel.
+
+## Related Documentation
+
+- [Stores](stores.md) — Channels belong to a store
+- [Markets](markets.md) — Different from channels: markets segment geography/currency, channels segment selling surfaces
+- [Products](products.md) — Product catalog and publication
+- [Order Routing](shipments.md#order-routing) — Channels can override the store's routing strategy

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

@@ -1,8 +1,10 @@
 ---
 title: Products
-description: Products, variants, option types, images, prices, and categories
+description: How Spree models products, variants, option types, images, prices, and categories — the building blocks of every catalog and storefront.
 ---
 
+import { Since } from '/snippets/since.mdx';
+
 ## Overview
 
 A product represents something you sell. Each product has one or more **variants** — the actual purchasable items with their own SKU, price, and inventory. For example, a "T-Shirt" product might have variants for each size and color combination.
@@ -350,8 +352,153 @@ curl 'https://api.mystore.com/api/v3/store/categories/clothing/shirts/products?l
 
 > **INFO:** Category `name` and `description` fields are translatable.
 
+## Publications and Sales Channels 
+
+A product is visible on a [Channel](channels.md) only when a `ProductPublication` record joins the two. Publications carry an optional time window so a product can be scheduled to go live and come down without code or manual toggles.
+
+| Publication state | What customers see |
+|---|---|
+| No publication exists | Product is not on this channel — invisible |
+| Publication has no dates set | Live now and indefinitely |
+| `published_at` is in the future | Scheduled — not yet visible |
+| `unpublished_at` is in the past | Hidden — was visible, now sunset |
+| Within the window | Live |
+
+Product `status` (`draft` / `active` / `archived`) is the **outer gate**: a Draft or Archived product is hidden on every channel regardless of its publication window. Only `active` products consult publication state.
+
+### Reading publications
+
+Publications appear in the API under `product_publications` when expanded; the same data is available through the `channels` association as a flat list of joined channels.
+
+
+```typescript SDK
+const product = await adminClient.products.get('prod_abc', {
+  expand: ['product_publications', 'channels'],
+})
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/admin/products/prod_abc?expand=product_publications,channels' \
+  -H 'X-Spree-API-Key: sk_xxx'
+```
+
+
+```json Response
+{
+  "data": {
+    "id": "prod_abc",
+    "status": "active",
+    "channels": [
+      { "id": "ch_online", "code": "online", "name": "Online Store" }
+    ],
+    "product_publications": [
+      {
+        "id": "pp_xyz",
+        "channel_id": "ch_online",
+        "published_at": "2026-07-01T00:00:00Z",
+        "unpublished_at": null
+      }
+    ]
+  }
+}
+```
+
+### Writing publications
+
+Two write surfaces serve different shapes:
+
+- **Per-product, full-set** — `PATCH /api/v3/admin/products/{id}` with a `product_publications` array. The array represents the complete desired state; channels absent from the payload are detached.
+
+  
+
+  ```typescript SDK
+  await adminClient.products.update('prod_abc', {
+    product_publications: [
+      { channel_id: 'ch_online' },
+      { channel_id: 'ch_pos', published_at: '2026-07-01T00:00:00Z' },
+    ],
+  })
+  ```
+
+  ```bash cURL
+  curl -X PATCH 'https://api.mystore.com/api/v3/admin/products/prod_abc' \
+    -H 'X-Spree-API-Key: sk_xxx' \
+    -H 'Content-Type: application/json' \
+    -d '{
+      "product_publications": [
+        { "channel_id": "ch_online" },
+        { "channel_id": "ch_pos", "published_at": "2026-07-01T00:00:00Z" }
+      ]
+    }'
+  ```
+
+  
+
+- **Per-channel, bulk** — `POST /api/v3/admin/channels/{id}/add_products` and `POST /api/v3/admin/channels/{id}/remove_products` for publishing or unpublishing many products at once. Idempotent: re-publishing an already-published product is a no-op for its window unless `published_at` / `unpublished_at` are explicitly passed.
+
+  
+
+  ```typescript SDK
+  await adminClient.channels.addProducts('ch_online', {
+    product_ids: ['prod_abc', 'prod_def'],
+    published_at: '2026-07-01T00:00:00Z',
+  })
+
+  await adminClient.channels.removeProducts('ch_online', {
+    product_ids: ['prod_abc'],
+  })
+  ```
+
+  ```bash cURL
+  curl -X POST 'https://api.mystore.com/api/v3/admin/channels/ch_online/add_products' \
+    -H 'X-Spree-API-Key: sk_xxx' \
+    -H 'Content-Type: application/json' \
+    -d '{
+      "product_ids": ["prod_abc", "prod_def"],
+      "published_at": "2026-07-01T00:00:00Z"
+    }'
+
+  curl -X POST 'https://api.mystore.com/api/v3/admin/channels/ch_online/remove_products' \
+    -H 'X-Spree-API-Key: sk_xxx' \
+    -H 'Content-Type: application/json' \
+    -d '{ "product_ids": ["prod_abc"] }'
+  ```
+
+  
+
+The two surfaces converge on the same `spree_product_publications` table — pick whichever matches your call site.
+
+### Listing products on a specific channel
+
+Storefronts and `client.products.list()` calls return only products published on the resolved channel (live within the publication window, with the product itself `active`). To scope a Store SDK request to a non-default channel — e.g. a POS app querying for the POS catalog — set the channel `code` on the client or per-request:
+
+
+```typescript SDK
+// Client-level default
+const client = createClient({ baseUrl, publishableKey, channel: 'pos' })
+
+// Per-request override
+const posProducts = await client.products.list({}, { channel: 'pos' })
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/products' \
+  -H 'X-Spree-API-Key: pk_xxx' \
+  -H 'X-Spree-Channel: pos'
+```
+
+
+For Admin API filtering across channels (back-office reports, admin UI lists), use Ransack instead: `q[channels_id_in][]=ch_xxx`. See [Sales Channels](channels.md) for the resolution rules.
+
+### Auto-publish on the default channel
+
+When a product is created via the dashboard, it is auto-published on the store's default channel (the only channel where `default = true`). The Admin API does **not** auto-publish — supply `product_publications: [{ channel_id }]` on create or call `add_products` afterwards.
+
+See [Sales Channels](channels.md) for the full channel lifecycle, including default-channel resolution and the `X-Spree-Channel` header.
+
 ## Related Documentation
 
+- [Sales Channels](channels.md) — Channels, publications, and order attribution
 - [Pricing](pricing.md) — Price Lists, Price Rules, and market-specific pricing
 - [Inventory](inventory.md) — Stock management and backorders
 - [Media](media.md) — Image management

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

@@ -1,46 +1,11 @@
 ---
 title: Stores
-description: The central model in Spree — every resource is scoped to a store
+description: The Store is Spree's top-level tenant — products, orders, channels, markets, and stock locations all belong to exactly one store.
 ---
 
 ## Overview
 
-The Store is the central model in Spree. Every resource — products, orders, markets, payment methods, taxonomies — is scoped to a store. Most setups use a single store, but Spree supports [multi-store](../multi-store/quickstart.md) configurations where each store operates independently with its own catalog, branding, and checkout.
-
-```mermaid
-erDiagram
-    Store ||--o{ Market : "has many"
-    Store ||--o{ Order : "has many"
-    Store }o--o{ Product : "has many"
-    Store }o--o{ PaymentMethod : "has many"
-    Store }o--o{ ShippingMethod : "has many"
-    Store ||--o{ Taxonomy : "has many"
-    Store ||--o{ StockLocation : "has many"
-
-    Store {
-        string name
-        string code
-        string url
-        boolean default
-        string customer_support_email
-    }
-
-    Market {
-        string name
-        string currency
-        string default_locale
-    }
-
-    Product {
-        string name
-        string status
-    }
-
-    Order {
-        string number
-        string state
-    }
-```
+The Store is the top-level tenant in Spree. Every resource — products, orders, channels, markets, taxonomies, stock locations — belongs to exactly one store. A store owns its branding (logo, custom domain, mail-from address), its [channels](channels.md) (online, POS, wholesale, …), its [markets](markets.md) (region/currency/locale), and its catalog.
 
 ## Store Attributes
 
@@ -81,37 +46,42 @@ curl 'https://api.mystore.com/api/v3/store/store' \
 ```
 
 
-## Markets
+## Channels vs. Markets
 
-[Markets](markets.md) let you segment your store into geographic regions, each with its own currency, locale, and set of countries. For example, a single store can have:
+Two different ways to split a store, often confused:
 
-- **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
+- **[Sales Channels](channels.md)** segment **selling surfaces** — Online Store, POS, Wholesale, marketplace integrations. They control product visibility, order attribution, and per-channel routing rules.
+- **[Markets](markets.md)** segment **geography and currency** — North America (USD/en), Europe (EUR/de), UK (GBP/en). They control which currency, locale, and tax rules apply to a given customer.
 
-See the [Markets](markets.md) guide for details.
+A single Online Store channel can serve multiple markets (one storefront → many regions). Conversely, POS and Online channels can share the same market (same currency/locale, different selling surfaces).
 
 ## Store Resources
 
-Each store has its own set of resources. This means products, orders, and promotions in one store are completely separate from another.
+Each store owns its own resources. Products, orders, channels, markets, and taxonomies in one store are independent from another.
 
 | Resource | Relationship |
 |----------|-------------|
+| [**Channels**](channels.md) | A store has many channels (Online Store, POS, Wholesale, …). One is the default. |
 | [**Markets**](markets.md) | A store has many markets, each defining a geographic region with its own currency and locale |
-| [**Orders**](orders.md) | An order belongs to one store |
-| [**Products**](products.md) | A product can be available in multiple stores |
-| [**Payment Methods**](payments.md) | A payment method can be available in multiple stores |
-| [**Shipping Methods**](shipments.md) | A shipping method can be available in multiple stores |
+| [**Orders**](orders.md) | An order belongs to one store and one channel |
+| [**Products**](products.md) | A product belongs to one store. Its visibility across channels is controlled by [publications](channels.md#publishing-products-on-channels). |
 | [**Taxonomies**](products.md#taxons-and-taxonomies) | A taxonomy belongs to one store |
-| [**Promotions**](promotions.md) | A promotion can apply to multiple stores |
+| [**Payment Methods**](payments.md) | A payment method belongs to one store |
+| [**Shipping Methods**](shipments.md) | A shipping method belongs to one store |
+| [**Promotions**](promotions.md) | A promotion belongs to one store |
+
+## Running Multiple Storefronts
+
+If you need one Spree backend to serve **multiple distinct merchant brands** — different domains, different catalogs, different admin teams — there are two patterns:
 
-## Multi-Store Setup
+- **Multiple channels under one store** (recommended for most cases) — model each storefront as a Sales Channel. Products are scoped per-channel via publications, orders carry the channel that originated them, and routing/pricing can differ per channel. This is the supported pattern in core Spree 5.5+.
+- **Multiple stores in one app** — the legacy multi-store pattern, where each store is fully independent (catalog, admin, branding). In Spree 5.5+ this requires the `spree_multi_store` extension. Core Spree treats each product as belonging to a single store.
 
-To run multiple stores from a single Spree installation, see the [Multi-Store guide](../multi-store/quickstart.md). Each store gets its own domain, branding, catalog, and checkout — while sharing the same admin dashboard and infrastructure.
+For most multi-brand operations, the channel pattern is simpler and more flexible. Reach for `spree_multi_store` only when stores need genuinely independent catalogs, branding, and admin teams.
 
 ## Related Documentation
 
+- [Channels](channels.md) — Selling surfaces (Online, POS, Wholesale, …)
 - [Markets](markets.md) — Multi-region commerce within a store
 - [Products](products.md) — Product catalog
 - [Orders](orders.md) — Order management and checkout
-- [Multi-Store](../multi-store/quickstart.md) — Running multiple stores

package/dist/developer/sdk/configuration.md

@@ -1,6 +1,6 @@
 ---
 title: Configuration
-description: Localization, error handling, TypeScript types, and custom fetch
+description: Configure the Spree JavaScript SDK — localization, currency headers, error handling, TypeScript types, and a custom fetch implementation.
 ---
 
 ## Localization & Currency
@@ -27,6 +27,30 @@ const category = await client.categories.get('clothing/shirts', {
 })
 ```
 
+import { Since } from '/snippets/since.mdx';
+
+## Sales Channels 
+
+Select which [sales channel](../core-concepts/channels.md) scopes a request. The SDK sends the value as the `X-Spree-Channel` header. Pass either the channel `code` (e.g. `online`, `pos`, `wholesale`) or the prefixed ID (`ch_…`) — `code` is preferred since it's merchant-meaningful and stable across environments. When omitted, the store's default channel is used.
+
+```typescript
+// Client-level default — every request runs against the POS channel
+const client = createClient({
+  baseUrl: 'https://api.mystore.com',
+  publishableKey: 'pk_xxx',
+  channel: 'pos',
+})
+
+// Sticky setter — switch channels mid-session (e.g. after the user
+// changes storefront context)
+client.setChannel('wholesale')
+
+// Per-request override — one request only
+const products = await client.products.list({}, { channel: 'pos' })
+```
+
+The channel scopes product visibility (only products published on that channel are returned), pricing fallback (per-channel pricing rules), and order attribution (a cart created with `channel: 'pos'` gets `order.channel_id` set to the POS channel).
+
 ## Error Handling
 
 ```typescript

package/dist/developer/tutorial/testing.md

@@ -1,6 +1,6 @@
 ---
 title: Testing
-description: Learn how to write automated tests for the Brands feature
+description: Write automated tests for the Brands tutorial feature using RSpec, Factory Bot, and Capybara, plus helpers from the spree_dev_tools gem.
 ---
 
 Automated testing is a crucial part of the development process. It helps you ensure that your code works as expected and catches bugs early.
@@ -77,7 +77,7 @@ FactoryBot.define do
 
       after(:create) do |brand, evaluator|
         store = evaluator.store || create(:store)
-        create_list(:product, evaluator.products_count, brand: brand, stores: [store])
+        create_list(:product, evaluator.products_count, brand: brand)
       end
     end
   end
@@ -174,7 +174,7 @@ require 'rails_helper'
 RSpec.describe 'Spree::Product brand association' do
   let(:store) { @default_store }
   let(:brand) { create(:brand) }
-  let(:product) { create(:product, stores: [store]) }
+  let(:product) { create(:product) }
 
   describe 'brand association' do
     it 'can be assigned a brand' do
@@ -191,9 +191,9 @@ RSpec.describe 'Spree::Product brand association' do
   end
 
   describe 'brand.products' do
-    let!(:product1) { create(:product, brand: brand, stores: [store]) }
-    let!(:product2) { create(:product, brand: brand, stores: [store]) }
-    let!(:other_product) { create(:product, stores: [store]) }
+    let!(:product1) { create(:product, brand: brand) }
+    let!(:product2) { create(:product, brand: brand) }
+    let!(:other_product) { create(:product) }
 
     it 'returns products for the brand' do
       expect(brand.products).to contain_exactly(product1, product2)
@@ -327,7 +327,7 @@ RSpec.describe Spree::Api::V3::Store::ProductsController, type: :controller do
   include_context 'API v3 Store'
 
   let(:brand) { create(:brand, name: 'Nike') }
-  let!(:product) { create(:product, brand: brand, stores: [store], status: 'active') }
+  let!(:product) { create(:product, brand: brand, status: 'active') }
 
   before do
     request.headers['X-Spree-Api-Key'] = api_key.token
@@ -357,7 +357,7 @@ RSpec.describe Spree::Api::V3::Store::ProductsController, type: :controller do
 
   describe 'GET #index' do
     it 'filters products by brand_id' do
-      other_product = create(:product, stores: [store], status: 'active')
+      other_product = create(:product, status: 'active')
 
       get :index, params: { q: { brand_id_eq: brand.id } }
 

package/dist/developer/upgrades/5.4-to-5.5.md

@@ -1,6 +1,6 @@
 ---
 title: Upgrading to Spree 5.5
-description: This guide covers upgrading a Spree 5.4 application to Spree 5.5.
+description: Step-by-step guide to upgrading a Spree 5.4 application to Spree 5.5, including gem updates, migrations, and breaking changes to review.
 ---
 
 > **INFO:** Before proceeding to upgrade, please ensure you're at [Spree 5.4](5.3-to-5.4.md).
@@ -37,30 +37,41 @@ bin/rails spree:media:migrate_master_images_to_product_media BATCH_SIZE=1000
 
 > **WARNING:** Run the task locally and on production. It does not block storefront rendering — new uploads attach to the product immediately — but until the enqueued jobs finish, old assets remain pinned to variants.
 
-### Run the channels upgrade
+### Run the Channels upgrade
 
-Spree 5.5 promotes `Order#channel` from a free-text string column to a real `Spree::Channel` FK. **Run this rake task immediately after `db:migrate`** — it seeds the channel rows your existing stores need and backfills `spree_orders.channel_id` from the legacy string column:
+Spree 5.5 introduces [Sales Channels](../core-concepts/channels.md) — a per-store distribution surface (online storefront, POS, marketplace integration, wholesale portal). Products are published to a channel via the new `spree_product_publications` join table, and orders are attributed to a channel via `spree_orders.channel_id`.
+
+The migrations add a `default` boolean on `spree_channels`, a `store_id` column on `spree_products`, and create the new `spree_product_publications` table — **but they do not seed default channels, attach existing products to a store, or backfill order channels**. That work is done by an idempotent rake task you must run after `db:migrate`:
 
 ```bash
 bin/rake spree:channels:upgrade
 ```
 
-The task is idempotent — safe to re-run if it fails partway, and a no-op on stores/orders that have already been upgraded. It runs two sub-tasks in order:
+The task runs four sub-tasks in order:
 
-1. **`spree:channels:create_defaults`** — creates a default `online` channel for every store that doesn't already have one. New 5.5+ stores get this automatically via the `Store` after_create callback; this sub-task only matters for stores that already exist when you upgrade. The channel's after_create hook seeds the three default routing rules (Preferred Location → Minimize Splits → Default Location).
+1. `spree:channels:create_defaults` — creates the default "Online Store" channel for every existing store (via `Store#ensure_default_channel`).
+2. `spree:upgrade:populate_publications` — for every product that doesn't yet have a `store_id`, picks a "home" store from the legacy `spree_products_stores` join (preferring the store flagged `default: true`, otherwise the earliest row), sets `spree_products.store_id`, and creates a `spree_product_publications` row on each attached store's default channel. Runs in a transaction per product so a partial failure leaves nothing half-applied.
+3. `spree:channels:backfill_order_channel_ids` — sets `spree_orders.channel_id` from the legacy `spree_orders.channel` string column. Unknown codes auto-create a new channel under that store. NULL/blank values map to the default channel.
+4. `spree:channels:backfill_product_publication_dates` — copies the deprecated `Product.available_on` and `Product.discontinue_on` columns into each publication's `published_at` / `unpublished_at` (only where the publication's date is currently NULL).
 
-2. **`spree:channels:backfill_order_channel_ids`** — scans each store's orders, creates one `Spree::Channel` per distinct legacy `channel` value (claiming `NULL`/blank rows under the `online` default channel), and writes `channel_id`.
+The task is fully idempotent — safe to re-run if it fails partway, and a no-op on stores/products/orders that have already been upgraded.
 
-You can also run the two steps individually if you'd rather pace the upgrade:
+> **WARNING:** Until `spree:channels:upgrade` runs, every product has `store_id IS NULL` and is invisible to `Product.for_store(store)`. The admin product list, storefront catalog, and search indexer all return empty. Run the task immediately after `db:migrate`.
 
-```bash
-bin/rake spree:channels:create_defaults
-bin/rake spree:channels:backfill_order_channel_ids
-```
+#### Multi-store catalogs
+
+If you have products attached to multiple stores via the legacy `spree_products_stores` join, the `populate_publications` task picks **one** "home" store per product and creates publications on every store's default channel. The `spree_products_stores` table is **kept** as legacy compat surface — the upcoming `spree_multi_store` extension restores the full `Product has_many :stores` association on top of it.
+
+For single-store deployments this is invisible; you can move on without touching `spree_products_stores` again.
+
+#### Behavioral changes
 
-Orders modified after the upgrade auto-set `channel_id` via the model's `before_validation` callback, so the backfill is only strictly required for orders that aren't touched again post-upgrade — but running it once at upgrade time avoids surprises later.
+- Newly-created products in **the dashboard SPA** are auto-published on the store's default channel; the merchant can untick channels post-create via the Publishing card.
+- Newly-created products via the **Admin API** are NOT auto-published — the caller must supply `product_publications: [{ channel_id }]` on create or use `POST /api/v3/admin/channels/:id/add_products` afterwards.
+- `Product.available_on=` and `Product.discontinue_on=` setters emit deprecation warnings and now write to every per-channel publication's `published_at` / `unpublished_at`. Reading these attributes on a product prefers the current-channel publication's value over the legacy column.
+- `Spree::Channel#add_products(product_ids)` is idempotent and **preserves existing publication windows** when called without `published_at`/`unpublished_at` kwargs.
 
-The legacy `channel` string column is **kept** on `spree_orders` and ignored by ActiveRecord (`Spree::Order` declares it in `ignored_columns`). It will be dropped in a later Spree release once enough time has passed for everyone to have run the backfill — until then it's harmless DB ballast that lets the rake task be re-run if you need to.
+Orders modified after the upgrade auto-set `channel_id` via the model's `before_validation :ensure_channel_presence` callback, so `backfill_order_channel_ids` is only strictly required for orders that aren't touched again post-upgrade — but running it at upgrade time avoids surprises later. The legacy `channel` string column is **kept** on `spree_orders` and ignored by ActiveRecord (`Spree::Order` declares it in `ignored_columns`). It will be dropped in a later Spree release once everyone has had a chance to run the backfill.
 
 ### Schedule the Stock Reservations expiry job
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spree/docs",
-  "version": "0.1.71",
+  "version": "0.1.73",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",