Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Documentation update
Damian Legawiec873b77a56261
diff --git a/CLAUDE.md b/CLAUDE.mdindex 2fde30587e..6a4b1a531c 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -22,7 +22,6 @@ Active plans (6.0 target, work pending):- `6.0-normalize-state-to-status.md` — Rename state → status on Payment, Shipment, InventoryUnit, ReturnAuthorization, GiftCard- `6.0-fulfillment-and-delivery.md` — Shipment→Fulfillment, ShippingMethod→DeliveryMethod, drop ShippingCategory, FulfillmentProvider strategy, pickup (merchant StockLocation) + pickup_point (third-party PickupPointProvider)- `6.0-returns-exchanges-claims.md` — First-class Return, Exchange, Claim models replacing ReturnAuthorization/Reimbursement chain-- `6.0-channels-catalogs-b2b.md` — Channel, Catalog, ProductListing (replaces StoreProduct), Company/CompanyLocation/CompanyContact for B2B (Channel shipped in 5.5)- `6.0-platform-auth.md` — Drop Devise, own auth stack, User→Customer/Staff rename (RefreshToken shipped in 5.4)- `6.0-tax-provider.md` — Per-Market TaxProvider, replaces TaxRate.adjust + Calculator, drop Zone model (TaxRate gets direct country/state FKs)- `6.0-delivery-rate-provider.md` — Per-DeliveryMethod DeliveryRateProvider, replaces Estimator + Calculator, DeliveryZone with postal code support@@ -37,7 +36,8 @@ Multi-version plans (some phases shipped, some pending):- `5.4-6.0-product-media-system.md` — Product-level media gallery. 5.5 data model (spree_variant_media, media_type, focal_point, external_video_url) shipped; admin UIs in progress; 6.0 cleanup pending.- `5.5-6.0-order-cancellation-and-approval.md` — First-class `OrderCancellation` + `OrderApproval` models. 5.5 models + migrations shipped; 6.0 drops denormalized columns.- `5.5-6.0-display-on-to-boolean.md` — Collapse `display_on` tri-state to a single `storefront_visible` boolean. 5.5 bridge (`storefront_visible` accessor + Ransacker on `Spree::DisplayOn`) shipped; 6.0 schema rename pending.-- `6.0-order-routing.md` — Two-tier extension: pluggable `Spree::OrderRouting::Strategy::Base` + STI subclasses of `Spree::OrderRoutingRule`. Phase 1 (5.5) shipped: `Channel`, `OrderRoutingRule`, strategy base + Rules + Reducer + Legacy, `preferred_stock_location_id` + `channel_id` on Order. Phase 2+ (6.0) layers ProductListing/Catalog/Company on top via `6.0-channels-catalogs-b2b.md`.+- `6.0-order-routing.md` — Two-tier extension: pluggable `Spree::OrderRouting::Strategy::Base` + STI subclasses of `Spree::OrderRoutingRule`. Phase 1 (5.5) shipped: `Channel`, `OrderRoutingRule`, strategy base + Rules + Reducer + Legacy, `preferred_stock_location_id` + `channel_id` on Order. Phase 2+ (6.0) layers Catalog/Company on top via `6.0-channels-catalogs-b2b.md`.+- `6.0-channels-catalogs-b2b.md` — Channel + ProductPublication (replaces StoreProduct) + single-owner Product (`belongs_to :store`) + Publishing card (legacy admin + SPA) + `Channel#default` boolean shipped in 5.5. Catalog, Company/CompanyLocation/CompanyContact for B2B pending in 6.0. Multi-store catalogs (historic `Product has_many :stores`) move to the `spree_multi_store` extension.Pending design work (drafts, no implementation yet):- `5.4-centralized-translations-admin.md` — Centralized Translations admin page under Products, overview grid + bulk CSV import/export@@ -108,16 +108,17 @@ Per-request context available in models, controllers, jobs, and services:### Models-- Inherit from `Spree.base_class`-- Always pass `class_name` and `dependent` on associations; use `dependent: :destroy_async` for high-fanout associations to offload deletion to a background job+- ALWAYS Inherit from `Spree.base_class`+- ALWAYS pass `class_name` and `dependent` on associations; use `dependent: :destroy_async` for high-fanout associations to offload deletion to a background job- Include `Spree::Metafields` for custom fields support (see docs/plans/5.4-6.0-custom-fields-rename.md)- Include `Spree::Metadata` for JSON metadata support-- Use string columns instead of enums+- ALWAYS Use string columns instead of enums- State machines: use `state_machines-activerecord` gem, default column `status` (legacy uses `state`, see docs/plans/6.0-normalize-state-to-status.md)-- Never cast IDs to integer — always treat as strings (UUID support)-- Uniqueness validations: always use `scope: spree_base_uniqueness_scope`, should be also enforced by database index+- NEVER cast IDs to integer — always treat as strings (UUID support)+- Uniqueness validations: ALWAYS use `scope: spree_base_uniqueness_scope`, should be also enforced by database index- If needed use paranoia gem for soft delete support (via `acts_as_paranoid`)- For configuration / options always use [Model Preferences](docs/developer/customization/model-preferences.mdx)+- NEVER hardcode table names, always use `Model.table_name` in models, queries, scopes, etc.```rubyclass Spree::Product < Spree.base_classdiff --git a/docs/developer/core-concepts/channels.mdx b/docs/developer/core-concepts/channels.mdxnew file mode 100644index 0000000000..37406c67b0--- /dev/null+++ b/docs/developer/core-concepts/channels.mdx@@ -0,0 +1,112 @@+---+title: Sales 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';++<Since version="5.5" />++## Overview++Sales channels segment a single [Store](/developer/core-concepts/stores) 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](/developer/core-concepts/shipments#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 and matches a channel `code` on the current store, that channel is used.+2. Otherwise, the store's default channel is used.++The resolved channel is then available to controllers, models, and serializers throughout the request.++### 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](/developer/core-concepts/shipments#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 client.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',+})+```++`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 client.products.update('prod_xxx', {+ 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, matching Shopify's "Online Store" behavior. 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](/developer/core-concepts/stores) — Channels belong to a store+- [Markets](/developer/core-concepts/markets) — Different from channels: markets segment geography/currency, channels segment selling surfaces+- [Products](/developer/core-concepts/products) — Product catalog and publication+- [Order Routing](/developer/core-concepts/shipments#order-routing) — Channels can override the store's routing strategydiff --git a/docs/developer/core-concepts/stores.mdx b/docs/developer/core-concepts/stores.mdxindex 533f195cbd..fe9f69b778 100644--- a/docs/developer/core-concepts/stores.mdx+++ b/docs/developer/core-concepts/stores.mdx@@ -1,46 +1,11 @@---title: Stores-description: The central model in Spree — every resource is scoped to a store+description: The top-level tenant in Spree — every resource belongs to a 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](/developer/multi-store/quickstart) 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](/developer/core-concepts/channels) (online, POS, wholesale, …), its [markets](/developer/core-concepts/markets) (region/currency/locale), and its catalog.## Store Attributes@@ -83,37 +48,42 @@ curl 'https://api.mystore.com/api/v3/store/store' \</CodeGroup>-## Markets+## Channels vs. Markets-[Markets](/developer/core-concepts/markets) 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](/developer/core-concepts/channels)** segment **selling surfaces** — Online Store, POS, Wholesale, marketplace integrations. They control product visibility, order attribution, and per-channel routing rules.+- **[Markets](/developer/core-concepts/markets)** 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](/developer/core-concepts/markets) 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**](/developer/core-concepts/channels) | A store has many channels (Online Store, POS, Wholesale, …). One is the default. || [**Markets**](/developer/core-concepts/markets) | A store has many markets, each defining a geographic region with its own currency and locale |-| [**Orders**](/developer/core-concepts/orders) | An order belongs to one store |-| [**Products**](/developer/core-concepts/products) | A product can be available in multiple stores |-| [**Payment Methods**](/developer/core-concepts/payments) | A payment method can be available in multiple stores |-| [**Shipping Methods**](/developer/core-concepts/shipments) | A shipping method can be available in multiple stores |+| [**Orders**](/developer/core-concepts/orders) | An order belongs to one store and one channel |+| [**Products**](/developer/core-concepts/products) | A product belongs to one store. Its visibility across channels is controlled by [publications](/developer/core-concepts/channels#publishing-products-on-channels). || [**Taxonomies**](/developer/core-concepts/products#taxons-and-taxonomies) | A taxonomy belongs to one store |-| [**Promotions**](/developer/core-concepts/promotions) | A promotion can apply to multiple stores |+| [**Payment Methods**](/developer/core-concepts/payments) | A payment method belongs to one store |+| [**Shipping Methods**](/developer/core-concepts/shipments) | A shipping method belongs to one store |+| [**Promotions**](/developer/core-concepts/promotions) | 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](/developer/multi-store/quickstart). 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](/developer/core-concepts/channels) — Selling surfaces (Online, POS, Wholesale, …)- [Markets](/developer/core-concepts/markets) — Multi-region commerce within a store- [Products](/developer/core-concepts/products) — Product catalog- [Orders](/developer/core-concepts/orders) — Order management and checkout-- [Multi-Store](/developer/multi-store/quickstart) — Running multiple storesdiff --git a/docs/docs.json b/docs/docs.jsonindex 626d9d11d5..5ded885ec1 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -140,6 +140,7 @@"pages": ["developer/core-concepts/architecture","developer/core-concepts/stores",+ "developer/core-concepts/channels","developer/core-concepts/markets","developer/core-concepts/customers","developer/core-concepts/staff-roles"diff --git a/docs/index.mdx b/docs/index.mdxindex f7075534d7..080aaa2e3c 100644--- a/docs/index.mdx+++ b/docs/index.mdx@@ -253,15 +253,15 @@ export const CopyCommand = ({ command }) => {<ConceptItem href="/developer/core-concepts/stores"icon={<SmallIcon><path d="m2 7 4.41-4.41A2 2 0 0 1 7.83 2h8.34a2 2 0 0 1 1.42.59L22 7" /><path d="M4 12v8a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-8" /><path d="M15 22v-4a2 2 0 0 0-2-2h-2a2 2 0 0 0-2 2v4" /><rect width="20" height="5" x="2" y="7" /></SmallIcon>}title="Stores" />+ <ConceptItem href="/developer/core-concepts/channels"+ icon={<SmallIcon><path d="M4.9 16.1C1 12.2 1 5.8 4.9 1.9" /><path d="M7.8 4.7a6.14 6.14 0 0 0-.8 7.5" /><circle cx="12" cy="9" r="2" /><path d="M16.2 4.8c2 2 2.26 5.11.8 7.47" /><path d="M19.1 1.9a9.96 9.96 0 0 1 0 14.1" /><path d="M9.5 18h5" /><path d="m8 22 4-11 4 11" /></SmallIcon>}+ title="Channels" /><ConceptItem href="/developer/core-concepts/markets"icon={<SmallIcon><circle cx="12" cy="12" r="10" /><path d="M12 2a14.5 14.5 0 0 0 0 20 14.5 14.5 0 0 0 0-20" /><path d="M2 12h20" /></SmallIcon>}title="Markets" /><ConceptItem href="/developer/core-concepts/customers"icon={<SmallIcon><path d="M16 21v-2a4 4 0 0 0-4-4H6a4 4 0 0 0-4 4v2" /><circle cx="9" cy="7" r="4" /><path d="M22 21v-2a4 4 0 0 0-3-3.87" /><path d="M16 3.13a4 4 0 0 1 0 7.75" /></SmallIcon>}title="Customers" />- <ConceptItem href="/developer/core-concepts/search-filtering"- icon={<SmallIcon><circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" /></SmallIcon>}- title="Search & Filtering" /></div></div>diff --git a/docs/plans/6.0-channels-catalogs-b2b.md b/docs/plans/6.0-channels-catalogs-b2b.mdindex 77c0d02e14..bbaaf9a683 100644--- a/docs/plans/6.0-channels-catalogs-b2b.md+++ b/docs/plans/6.0-channels-catalogs-b2b.md@@ -1,10 +1,10 @@# Channels, Catalogs & B2B Companies-**Status:** Phase 1 shipped in 5.5 (Channel + ProductPublication + channel-aware scopes + Admin API + Store API back-compat + legacy admin Channels CRUD + Meilisearch channel filter); Catalog, Company tree, and pricing integration land in 6.0+**Status:** Phase 1 shipped in 5.5 (Channel + new `spree_product_publications` table + single-store Product + channel-aware scopes + Admin API action endpoints + Store API back-compat + legacy admin Channels CRUD + Publishing card + dashboard SPA + Meilisearch channel filter); Catalog, Company tree, and pricing integration land in 6.0**Target:** Spree 5.5 (Phase 1 ✓) → 6.0 (Catalog + Company)**Depends on:** ProductType (6.0-product-types.md), PriceList system (existing)**Author:** Damian + Claude-**Last updated:** 2026-05-23+**Last updated:** 2026-06-02## Summary@@ -14,7 +14,9 @@ Add three new concepts to Spree's multi-store architecture:- **Catalog** — product assortment + optional pricing override. Controls what's available and at what price for a specific audience (B2B tier, VIP group, regional assortment).- **Company** — B2B customer hierarchy (Company → CompanyLocation → CompanyContact) for businesses with multiple buyers and offices.-`StoreProduct` is replaced by **ProductPublication** — the join between Product and Channel that says "this product is listed on this channel."+`StoreProduct` is replaced by **ProductPublication** — the join between Product and Channel that says "this product is listed on this channel." The legacy `spree_products_stores` join table stays as compat surface for the `spree_multi_store` extension; **core no longer reads or writes it.**++`Product` is now `belongs_to :store` (single owner) in core. Multi-store catalog sharing — historically every `Product` belonged to many `Store`s via `spree_products_stores` — moves to the `spree_multi_store` extension. This matches Medusa/Saleor/Vendure: the catalog has one owner, distribution to multiple selling surfaces happens through channels.## Problem@@ -93,9 +95,11 @@ Store (who you are — legal entity, config boundary)### ProductPublication (replaces StoreProduct)-- **Replaces `StoreProduct`** — the table is renamed, the join now connects Product to Channel instead of Product to Store.-- **Carries publication-specific data** — `published_at`, `unpublished_at` (scheduled publishing), `position` (sort order per channel).-- **Store-level scoping derived from Channel** — `store.products` goes through `store.channels → product_publications → products`. No direct Store → Product join needed.+- **New `spree_product_publications` table.** Joins Product to Channel, not Product to Store.+- **No `store_id` column** — the publication's store is `channel.store` (delegated). Cross-store reporting joins through `spree_channels`.+- **Carries publication-specific data** — `published_at`, `unpublished_at` (scheduled publishing).+- **`position` was dropped from the original sketch** — nothing in 5.5 reads it and `acts_as_list` added a `MAX(position)` query per insert for no gain. Clean additive migration later if per-channel ordering ever becomes a real requirement.+- **Store-level scoping is direct** — `Spree::Store has_many :products` via `store_id` on Product. The historic `store.products through: :store_products` join is gone from core.### Catalog@@ -117,19 +121,51 @@ Store (who you are — legal entity, config boundary)### Channel (shipped in 5.5)-See [`spree/core/app/models/spree/channel.rb`](../../spree/core/app/models/spree/channel.rb). Notable diffs from the original sketch:+See [`spree/core/app/models/spree/channel.rb`](../../spree/core/app/models/spree/channel.rb). Final shape:-- No `default_catalog_id` — waits for Catalog in 6.0.+- **`default` boolean column** + `scope :default` + partial unique index `(store_id) WHERE default = TRUE` on Postgres/SQLite (model-level uniqueness validation on MySQL). `before_validation :promote_first_channel_to_default` auto-promotes the first channel created on a store; `after_save :demote_other_defaults` enforces single-default invariant when an admin flips the flag.+- **No `default_catalog_id`** — waits for Catalog in 6.0.- Includes routing-rules associations + `preference :order_routing_strategy` from `6.0-order-routing.md`.-- `#add_products(product_ids, published_at:, unpublished_at:)` bulk-UPSERTs publications (mirrors `Spree::PriceList#bulk_update_prices` convention).+- `#add_products(product_ids, published_at:, unpublished_at:)` bulk-UPSERTs publications. Idempotent: re-publishing an already-published product is a no-op for its window unless dates are explicitly passed (uses `Arel.sql('updated_at = <table>."updated_at"')` for the conflict clause to satisfy PG's DO UPDATE requirement without rewriting columns).+- `#remove_products(product_ids)` mirrors `add_products` — destroys publications, touches the channel.+- Touches every product via `Product.where(id: product_ids).touch_all` + `enqueue_search_index` after the upsert, since `upsert_all` bypasses `belongs_to :product, touch: true`.++### ProductPublication (shipped in 5.5 — new table)++See [`spree/core/app/models/spree/product_publication.rb`](../../spree/core/app/models/spree/product_publication.rb). Final shape:++- **New table `spree_product_publications`** with columns `product_id`, `channel_id`, `published_at`, `unpublished_at`, `created_at`, `updated_at`. No `store_id` column — `delegate :store, :store_id, to: :channel` for in-memory access; cross-store reporting queries join through `spree_channels`.+- **Unique index on `(product_id, channel_id)`**. `(product_id, channel_id, store_id)` was abandoned along with the in-place reshape.+- **`Spree::StoreProduct` deleted.** The class is gone in 5.5. Apps on 5.4 that referenced it directly must update to `Spree::ProductPublication`.+- **Legacy `spree_products_stores` table left untouched.** Core no longer reads or writes it. The upcoming `spree_multi_store` extension uses it to restore the `Product has_many :stores` association for merchants who need shared catalogs across stores.++`prefix :pp`, validates `(product, channel)`, validates `unpublished_at_after_published_at`, has a `published` scope.++### Product (shipped in 5.5 — single store ownership)++See [`spree/core/app/models/spree/product.rb`](../../spree/core/app/models/spree/product.rb) and [`spree/core/app/models/spree/product/channels.rb`](../../spree/core/app/models/spree/product/channels.rb). Final shape:-### ProductPublication (shipped in 5.5 — reshapes StoreProduct)+- **`belongs_to :store, optional: true`** with `before_validation :assign_default_store` (uses `Spree::Current.store` → `Spree::Store.default` fallback).+- **`has_many :product_publications`** (autosave) + `has_many :channels, -> { distinct }, through: :product_publications`.+- **`accepts_nested_attributes_for :product_publications`** for Rails nested-attribute form writes (legacy admin Publishing card).+- **Custom `product_publications=`** setter for SPA's hash-array payload — full-set semantics (rows absent from the payload are destroyed). Coexists with the nested-attributes path on different keys.+- **Deprecated `available_on=` / `discontinue_on=`** setters write through to every publication's `published_at` / `unpublished_at`. Readers prefer the current-channel publication's value with a ternary fallback (`publication ? publication.send(attr) : super()`) — `||` would mask `nil` from an always-live publication.+- **`#stores` / `#stores=` / `#store_ids` / `#store_ids=` bridges** in `Spree::Product::LegacyMultiStoreSupport` (auto-included unless `SpreeMultiStore` defines), preserved as deprecation warnings for legacy callers.+- **`set_default_publication` callback removed.** New products created via the Admin API are *not* auto-published — the caller supplies `product_publications: [{ channel_id }]`. The dashboard SPA's create form does auto-publish on the store's default channel (Shopify-style); the legacy admin form has a Publishing card with the same UX.-See [`spree/core/app/models/spree/product_publication.rb`](../../spree/core/app/models/spree/product_publication.rb). Rather than renaming the table and dropping `StoreProduct`, the 5.5 implementation reshapes `spree_products_stores` in place: keeps `store_id` (denormalized but harmless) and adds `channel_id` + `published_at` + `unpublished_at`. The class moves to `Spree::ProductPublication`, but the model still points at the legacy `spree_products_stores` table via `self.table_name`; the table rename happens in 6.0. [`Spree::StoreProduct < Spree::ProductPublication`](../../spree/core/app/models/spree/store_product.rb) is an STI subclass kept for one release for backwards compatibility with apps that still reference the old class name.+### Store#default_channel via boolean column-`before_validation :assign_channel_from_store` auto-fills `channel_id` from `store.default_channel` for callers that pass only `store` + `product` (legacy StoreProduct-style construction).+```ruby+# spree/core/app/models/concerns/spree/stores/channels.rb+has_one :default_channel, -> { default }, class_name: 'Spree::Channel'++def ensure_default_channel+ return if default_channel+ channels.create!(name: 'Online Store', code: Spree::Channel::DEFAULT_CODE)+end+```-Note: `position` was dropped from the original sketch — nothing in 5.5 reads it and `acts_as_list` added a `MAX(position)` query per insert for no gain. If per-channel manual ordering becomes a real requirement later, it's a clean additive migration.+The `default` scope on Channel resolves the right row by the boolean column — no string-code lookup, no fragile rename hazard.### Catalog@@ -276,22 +312,26 @@ class Spree::Order < Spree.base_classend```-### Store gains Channels+### Store gains Channels (as-shipped in 5.5)```rubyclass Spree::Store < Spree.base_classhas_many :channels, class_name: 'Spree::Channel', dependent: :destroy+ has_one :default_channel, -> { default }, class_name: 'Spree::Channel'++ # 6.0 additionshas_many :catalogs, class_name: 'Spree::Catalog', dependent: :destroyhas_many :companies, class_name: 'Spree::Company', dependent: :destroy- # Product access now goes through channels- has_many :product_publications, through: :channels- has_many :products, through: :product_publications+ # Direct ownership in 5.5 — products belong to a single store.+ has_many :products, class_name: 'Spree::Product', dependent: :nullify+ has_many :product_publications, through: :channels, source: :publications- # Remove: has_many :store_products (replaced by channels → product_publications)+ after_create :ensure_default_channel- def default_channel- channels.find_by(code: 'online') || channels.first+ def ensure_default_channel+ return if default_channel+ channels.create!(name: 'Online Store', code: Spree::Channel::DEFAULT_CODE)endend```@@ -349,29 +389,37 @@ end### Phase 1 — shipped in 5.5-Mirrors the additive-then-swap pattern already used by `Order.channel` (see `6.0-order-routing.md`).-**Migrations** (`spree/core/db/migrate/`):-- `20260508204040_create_spree_channels.rb` — Channel table (shipped 5.5 with order routing).-- `20260522000001_add_channel_to_spree_products_stores.rb` — additive only: adds `channel_id`, `published_at`, `unpublished_at` to the existing `spree_products_stores` table.-- `20260522000002_add_unique_index_to_spree_products_stores.rb` — drops legacy `(product_id, store_id)` unique index, adds `(channel_id, product_id, store_id)` unique index.+- `20260508204040_create_spree_channels.rb` — Channel table (shipped 5.5 with order routing). Note: the in-migration `ensure_default_market` backfill that originally lived here was removed — default-channel seeding for existing stores moves to the `spree:channels:create_defaults` rake task.+- `20260601000001_create_spree_product_publications.rb` — **new** `spree_product_publications` table with `(product_id, channel_id, published_at, unpublished_at, created_at, updated_at)` + unique index on `(product_id, channel_id)`.+- `20260601000002_add_store_id_to_spree_products.rb` — adds `store_id` (nullable), `units_sold_count` (default 0), `revenue` (default 0) to `spree_products` + `(store_id, units_sold_count)` index. Existing rows have `store_id IS NULL` until the backfill rake runs.+- `20260602000001_add_default_to_spree_channels.rb` — adds `default` boolean to `spree_channels` + partial unique index on `(store_id) WHERE default = TRUE` (Postgres/SQLite; MySQL relies on the model-level uniqueness validation).++**The earlier additive-then-swap pattern (reshape `spree_products_stores` in place) was abandoned.** It carried a denormalized `store_id` column on the publication table and a `Spree::StoreProduct` STI alias for back-compat. The simpler shape — separate table, single owner on Product — is what actually shipped.-**Upgrade rake** (`spree:channels:upgrade` composes):-- `backfill_order_channel_ids` — populates `spree_orders.channel_id` from the legacy string column.-- `backfill_product_publication_dates` — copies `Product.available_on` → `ProductPublication.published_at` and `Product.discontinue_on` → `ProductPublication.unpublished_at` where the listing dates are still NULL. Per-product loop for SQLite/MySQL/Postgres portability.+**Upgrade rake** (`spree:channels:upgrade` chains):+1. `spree:channels:create_defaults` — creates the default "Online Store" channel for every existing store (via `Store#ensure_default_channel`). Idempotent.+2. `spree:upgrade:populate_publications` — for every product with `store_id IS NULL`, reads the legacy `spree_products_stores` rows (raw SELECT with parameterized binding), picks a "home" store (preferring the row whose store is `default: true`, otherwise earliest by `created_at`), sets `spree_products.store_id`, and creates a `ProductPublication` row on each attached store's default channel. Runs in a transaction per product. Idempotent.+3. `spree:channels:backfill_order_channel_ids` — populates `spree_orders.channel_id` from the legacy `spree_orders.channel` string column.+4. `spree:channels:backfill_product_publication_dates` — copies the legacy `Product.available_on` / `Product.discontinue_on` columns (read raw via `product[:column]` to bypass the channel-aware reader) into each publication's `published_at` / `unpublished_at` where currently NULL.-**Deploy order**: code → `db:migrate` (additive only) → `rake spree:channels:upgrade` → `db:migrate` (swap). The swap migration enforces this with a runtime guard.+**Deploy order**: code → `db:migrate` → `rake spree:channels:upgrade`. No swap migration — there's nothing to swap.++> **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. The upgrade guide [docs/developer/upgrades/5.4-to-5.5.mdx](../developer/upgrades/5.4-to-5.5.mdx) makes this prominent.**Model layer**:-- `Spree::ProductPublication` is the canonical class on the existing `spree_products_stores` table (table rename deferred to 6.0).-- `Spree::StoreProduct < Spree::ProductPublication` STI subclass (with `inheritance_column = nil`) preserves all existing call sites — apps on 5.4 that reference `Spree::StoreProduct` directly keep working through the 5.5 → 6.0 transition.-- `Spree::Product` gains `has_many :product_publications, :stores, :channels` via `Spree::Product::Channels` concern. Deprecated setters `available_on=`, `discontinue_on=`, `make_active_at=` write through to every listing via `autosave: true`.-- `Spree::Product.available` / `.active` / `.not_discontinued` scopes are channel-aware: when `Spree::Current.channel` is set, they join `product_publications` and filter on `published_at`/`unpublished_at`. Legacy column path is the fallback for job/console/rake contexts.-- `Spree::Current.channel` attribute + `X-Spree-Channel` header resolution in API v3 base controller. Falls back to `current_store.default_channel`.+- `Spree::ProductPublication` on the new `spree_product_publications` table — no `store_id` column, `store`/`store_id` delegated to `channel`.+- `Spree::Product belongs_to :store` (single). `for_store(store)` scope is now `where(store_id: store.id)` (was a join through publications).+- `Spree::Product::Channels` concern owns `has_many :product_publications`, `has_many :channels through:`, the deprecated `available_on=`/`discontinue_on=` cascade, and the SPA's `product_publications=` hash-array setter. **No `set_default_publication` callback** — explicit publishing only.+- `Spree::Product::LegacyMultiStoreSupport` concern owns `#stores` / `#stores=` / `#store_ids` / `#store_ids=` deprecation bridges (auto-included unless `SpreeMultiStore` is defined; the `spree_multi_store` extension supersedes them).+- `Spree::Product.available` / `.active` / `.not_discontinued` scopes are channel-aware via `Spree::Current.channel`; jobs/rake without channel context use the legacy column fallback path.+- `Spree::Channel#add_products` / `#remove_products` are the canonical bulk publishing API (used by both bulk-action controllers and the legacy/SPA Publishing cards).+- `Spree::Current.channel` + `X-Spree-Channel` header resolution in API v3 base controller. Falls back to `current_store.default_channel`.**Search provider**:-- `Spree::SearchProvider::ProductPresenter` indexes a per-product `channel_ids: [...]` array.-- `Spree::SearchProvider::Meilisearch#system_filter_conditions` adds `channel_ids = '<current channel>'` so storefronts on different channels of the same store see distinct product sets.+- `Spree::SearchProvider::ProductPresenter` indexes a per-product `channel_ids: [...]` array (computed via `product.product_publications.joins(:channel).where(spree_channels: { store_id: store.id })`).+- `Spree::SearchProvider::Meilisearch#system_filter_conditions` adds `channel_ids = '<current channel>'`.+- `Spree::SearchIndexable#store_ids_for_indexing` reads the record's own `store_id` (was hardcoded to `Spree::Store.default.id` in an earlier sketch — that broke multi-store indexing).**Admin API:**@@ -381,25 +429,41 @@ POST /api/v3/admin/channelsPATCH /api/v3/admin/channels/:idDELETE /api/v3/admin/channels/:id-GET /api/v3/admin/channels/:channel_id/product_publications-GET /api/v3/admin/channels/:channel_id/product_publications/:id-POST /api/v3/admin/channels/:channel_id/product_publications-PATCH /api/v3/admin/channels/:channel_id/product_publications/:id-DELETE /api/v3/admin/channels/:channel_id/product_publications/:id-POST /api/v3/admin/channels/:channel_id/product_publications/bulk+POST /api/v3/admin/channels/:id/add_products # body: { product_ids: [...], published_at?, unpublished_at? }+POST /api/v3/admin/channels/:id/remove_products # body: { product_ids: [...] }++POST /api/v3/admin/products/bulk_add_to_channels # body: { ids: [...], channel_ids: [...] }+POST /api/v3/admin/products/bulk_remove_from_channels # body: { ids: [...], channel_ids: [...] }```-- Admin Product API dropped `available_on`, `discontinue_on`, `make_active_at` from params + serializer (clean break — admin SDK is Developer Preview).-- Admin Product serializer gains `many :product_publications` via `expand=product_publications`.-- Bulk endpoint delegates to `Spree::Channel#add_products` (single `upsert_all`, no per-product saves).+The originally-planned nested CRUD (`GET/POST/PATCH/DELETE /admin/channels/:channel_id/product_publications/...`) was **dropped** — the SPA never used it, no industry precedent (Shopify/Saleor/Vendure/Medusa all expose action endpoints, not nested CRUD), and the `Spree::ProductPublication` model is internal join-table noise that shouldn't be a top-level API surface.++- Admin Product API dropped `available_on`, `discontinue_on`, `make_active_at` from params + serializer.+- Admin Product serializer gains `many :product_publications` via `expand=product_publications` (with `:channel` preloaded to avoid N+1).+- Bulk endpoints delegate to `Spree::Channel#add_products` / `#remove_products` (single upsert per channel, no per-product saves).+- `Spree::Channel` gains a `default: boolean` serializer field so the dashboard can identify the default channel for auto-publish on product create.**Store API:**-- `Spree::Api::V3::ProductSerializer#available_on` resolves from the current channel's listing `published_at`, falling back to the legacy `Product.available_on` column. Shape unchanged — single-channel stores see zero behavior change.+- `Spree::Api::V3::ProductSerializer#available_on` resolves from the current channel's publication `published_at`, falling back to the legacy `Product.available_on` column. Shape unchanged — single-channel stores see zero behavior change.**Legacy admin:**-- `/admin/channels` CRUD (controller + table registration + sidebar nav under Settings + permitted attributes + `ConfigurationManagement` permission grant).+- `/admin/channels` CRUD (controller + table registration + sidebar nav under Settings + permitted attributes + `ConfigurationManagement` permission grant). The settings nav labels it "Sales channels".+- Product edit page has a **Publishing card** (`spree/admin/app/views/spree/admin/products/form/_publishing.html.erb`) — channel checkboxes via Manage panel, per-publication date editor via `<details>` row. Writes through `accepts_nested_attributes_for :product_publications`. Mirrors the SPA's `<PublishingCard>`.+- `make_active_at` / `available_on` / `discontinue_on` inputs removed from the legacy admin product form's Status card — date scheduling moves to the per-publication editor on the Publishing card.++**Dashboard SPA:**++- `<PublishingCard>` at [`packages/dashboard/src/components/spree/products/publishing-card.tsx`](../../packages/dashboard/src/components/spree/products/publishing-card.tsx) — full Shopify-style publishing UI with status badges (Live / Scheduled / Hidden / Not available, gated by product status), per-channel schedule editor, Manage sheet for attach/detach.+- New-product form auto-publishes on the store's default channel (uses the Channel `default` boolean).+- Settings → "Sales channels" page (`packages/dashboard/src/routes/_authenticated/$storeId/settings/channels.tsx`).+- Bulk actions on product list: *Add to sales channels…* / *Remove from sales channels…*.+- `useChannels` hook query-keyed by `storeId` so switching stores within the staleTime window doesn't serve the previous store's channels.++**Sample data:**++- `bin/rake spree:load_sample_data` seeds three channels (Online Store [default], Point of Sale, Wholesale) via `db/sample_data/channels.rb` and explicitly publishes every loaded product on the default channel via `Loader#publish_sample_products`.### Phase 2 — 6.0: Catalog + Company tree + pricing integration@@ -511,29 +575,46 @@ DELETE /api/v3/admin/company_contacts/:id### Phase 3 — 6.0 cleanup-- Drop `Spree::Product.available_on`, `discontinue_on`, `make_active_at` columns and the deprecated setters in `Spree::Product::Channels`.-- Drop `Spree::Product.for_store`'s `store_products` join path; reroute through `product_publications`.-- Drop `Spree::StoreProduct` STI subclass and `spree/core/app/models/spree/store_product.rb`.-- Drop `store_id` column from the publications table (now denormalized — `channel.store_id` is the source of truth).-- Rename `spree_products_stores` → `spree_product_publications` and drop the `self.table_name` override in the model.+Most of the planned 6.0 cleanup already happened in 5.5 (cleaner data model from the start). Remaining items:++- Drop `Spree::Product.available_on`, `Spree::Product.discontinue_on`, `Spree::Product.make_active_at` columns and the deprecated setters in `Spree::Product::Channels`.+- Drop `Spree::Product::LegacyMultiStoreSupport` (multi-store catalogs live in the `spree_multi_store` extension from 5.5 onward).+- Drop `Spree::Product.for_store`'s legacy column-fallback branch (`Spree::Product.available` / `.not_discontinued` always use publications once `Spree::Current.channel` is unconditionally set).+- Make `spree_products.store_id` `NOT NULL` (it's nullable in 5.5 to accommodate the post-migrate / pre-backfill window).- Drop `spree_orders.channel` string column (5.5+ already ignores it via `ignored_columns`).-- Drop the channel-aware-scope legacy fallback branch (`Spree::Product.available` / `.not_discontinued` always use listings).+- Drop the channel-aware-scope legacy fallback branch in `Spree::Product.available` / `.not_discontinued` (always uses publications).++**Already done in 5.5 (don't redo in 6.0):**+- ~~Drop `Spree::StoreProduct` STI subclass~~ — deleted in 5.5.+- ~~Drop `store_id` column from the publications table~~ — new `spree_product_publications` table never had it.+- ~~Rename `spree_products_stores` → `spree_product_publications`~~ — new table created; legacy `spree_products_stores` left for `spree_multi_store`.## Constraints on Current Work-- **Don't add new features to `Spree::StoreProduct`.** It's an STI subclass of `Spree::ProductPublication` in 5.5 and gone in 6.0. Use `Spree::ProductPublication` directly in any new code.-- **6.0 cleanup will rename `spree_products_stores` → `spree_product_publications` and drop `store_id`.** Don't write new code that joins on `store_id` of the publications table — go through `channel.store` instead.+- **`Spree::StoreProduct` is gone.** Use `Spree::ProductPublication` directly. Don't reintroduce the STI alias or any reference to `spree/core/app/models/spree/store_product.rb`.+- **`Spree::ProductPublication` has no `store_id` column.** It's delegated to `channel.store`. Don't write code that calls `ProductPublication.where(store_id: …)` — use a join: `Publication.joins(:channel).where(spree_channels: { store_id: … })`.+- **`Product belongs_to :store` (single).** Don't write new code assuming `product.stores` is a real ActiveRecord association — the deprecation bridge returns `Array(store)` and won't chain. Multi-store catalogs live in `spree_multi_store`.+- **`Channel#default` is a boolean column.** Use `Spree::Channel.default.where(store: …)` or `store.default_channel`. Don't look up by `code: 'online'` — merchants can rename it.- **Channel-aware scopes assume `Spree::Current.channel` is set.** API requests set it via the X-Spree-Channel header concern; jobs / rake tasks fall back to the legacy column path. Don't add new code that reads `Spree::Current.channel` without expecting either branch.+- **`Spree::Channel#add_products` is idempotent and preserves existing publication windows** when called without `published_at` / `unpublished_at` kwargs. Don't change this — bulk-publish ergonomics depend on it.- **6.0 adds `default_catalog_id` to `spree_channels`** (additive — won't conflict with the 5.5 schema).- **PriceList stays as-is.** Catalog optionally references a PriceList — don't duplicate pricing logic.## Resolved Questions-1. **Default channel behavior.** Channel resolution via `X-Spree-Channel` request header (accepts channel `code`, e.g. `X-Spree-Channel: online`). If header is absent or doesn't match an active channel, falls back to `store.default_channel`. Shipped in 5.5 — see [`Spree::Api::V3::ChannelResolution`](../../spree/api/app/controllers/concerns/spree/api/v3/channel_resolution.rb).+1. **Default channel behavior.** Channel resolution via `X-Spree-Channel` request header (accepts channel `code`, e.g. `X-Spree-Channel: online`). If header is absent or doesn't match an active channel, falls back to `store.default_channel` (`Channel.default` scope on the `default` boolean column). Shipped in 5.5.++2. **How is the default channel identified?** Via a `default` boolean column on `Spree::Channel`, not by code. Partial unique index on Postgres/SQLite, model-level uniqueness validation on MySQL. The first channel created on a store auto-promotes; flipping the flag on a later channel auto-demotes the previous default. Looking up by `code: 'online'` would have been fragile (merchants can rename the default channel).++3. **Auto-publish on product create.** Admin API: **no** auto-publish — the caller supplies `product_publications: [{ channel_id }]`. Dashboard SPA's create form: **yes**, auto-publishes on `Channel#default == true` (Shopify-style). Sample data: explicitly publishes via `Loader#publish_sample_products`. The `set_default_publication` model callback was removed — moving the decision to the layer that knows the merchant's intent.++4. **Multi-store catalogs.** Core Spree 5.5+ models Product as `belongs_to :store` (single owner). Merchants who need shared catalogs across stores install the `spree_multi_store` extension, which restores `has_many :stores, through: :spree_products_stores` on top of the legacy join table. Matches the Medusa/Saleor/Vendure pattern (channels are the multi-brand primitive, stores are the tenant root).++5. **Cross-store onboarding via `Channel#add_products`.** Allowed: if a multi-store admin's API key has update permission on a product owned by sibling store A, calling `POST /admin/channels/:id/add_products` (where the channel belongs to store B) co-publishes the product onto store B's channel. The product's owning `store_id` doesn't change. This is the path by which the `spree_multi_store` extension's "publish across stores" UX threads through core.-2. **Catalog auto-sync.** Manual assignment only for 6.0, with bulk product assignment via Admin API (`POST /catalogs/:id/products/bulk`). Auto-sync using CollectionRule-style patterns is a future enhancement.+6. **Catalog auto-sync.** Manual assignment only for 6.0, with bulk product assignment via Admin API (`POST /catalogs/:id/products/bulk`). Auto-sync using CollectionRule-style patterns is a future enhancement.-3. **CompanyContact roles and B2B approval workflows.** Out of scope for this plan. The 6.0 deliverable is the data model: Company, CompanyLocation, CompanyContact with a simple `role` string column. Role-based permissions, approval workflows, purchase limits, and invoice management are deferred to a dedicated B2B plan post-6.0.+7. **CompanyContact roles and B2B approval workflows.** Out of scope for this plan. The 6.0 deliverable is the data model: Company, CompanyLocation, CompanyContact with a simple `role` string column. Role-based permissions, approval workflows, purchase limits, and invoice management are deferred to a dedicated B2B plan post-6.0.## Open Questions@@ -541,10 +622,17 @@ None at this time.## References-- Current Store model: `spree/core/app/models/spree/store.rb`-- Current Market model: `spree/core/app/models/spree/market.rb`-- Current CustomerGroup: `spree/core/app/models/spree/customer_group.rb`-- Current PriceList + PriceRules: `spree/core/app/models/spree/price_list.rb`, `spree/core/app/models/spree/price_rule.rb`-- Current StoreProduct: `spree/core/app/models/spree/store_product.rb`+- Channel model: `spree/core/app/models/spree/channel.rb`+- ProductPublication model: `spree/core/app/models/spree/product_publication.rb`+- Product channels concern: `spree/core/app/models/spree/product/channels.rb`+- Legacy multi-store bridge: `spree/core/app/models/spree/product/legacy_multi_store_support.rb`+- Store channels concern: `spree/core/app/models/concerns/spree/stores/channels.rb`+- Upgrade rake: `spree/core/lib/tasks/channels.rake` (`spree:channels:upgrade`)+- Population rake: `spree/core/lib/tasks/publications.rake` (`spree:upgrade:populate_publications`)+- User-facing concept doc: `docs/developer/core-concepts/channels.mdx`+- Upgrade guide: `docs/developer/upgrades/5.4-to-5.5.mdx`+- SPA Publishing card: `packages/dashboard/src/components/spree/products/publishing-card.tsx`+- Legacy admin Publishing card: `spree/admin/app/views/spree/admin/products/form/_publishing.html.erb`- Related plan: `6.0-product-types.md` (ProductType defines product schema)- Related plan: `6.0-replace-taxons-with-categories.md` (Collections for merchandising)+- Related plan: `6.0-order-routing.md` (Channel-aware order routing strategies)