Skip to content

armgit / spree

Public Imported from GitHub
0

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.

Added Spree 6 multi vendor plan (#14303)

Damian Legawiecc9cae77bb790
diff --git a/.claude/settings.local.json b/.claude/settings.local.json
index 961422fb25..49a8f344d6 100644
--- a/.claude/settings.local.json
+++ b/.claude/settings.local.json
@@ -23,7 +23,8 @@
"mcp__scout-apm__get_app_trace",
"mcp__scout-apm__get_app_insights",
"mcp__scout-apm__get_app_error_groups",
- "mcp__scout-apm__get_app_anomaly_events"
+ "mcp__scout-apm__get_app_anomaly_events",
+ "mcp__claude_ai_Spree_Commerce_Docs_MCP__query_docs_filesystem_spree_commerce_documentation"
],
"deny": [
"Bash(sudo *)",
diff --git a/CLAUDE.md b/CLAUDE.md
index 0ef9200499..f27cbef8c1 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -12,6 +12,7 @@ When proposing significant architectural changes:
Use `/project:create-plan` and `/project:update-plan` for plan management.
Active plans (6.0 target, work pending):
+- `6.0-multi-vendor-marketplace.md` — Open-source the marketplace core (Vendor, OrderGroup-based order splitting, commission engine with EU commission taxation, `VendorTransfer`/`VendorPayout` ledger + pluggable `PayoutProvider`) per spree/spree#13323. 6.0 headline feature; rebuilds the legacy Enterprise multi-vendor module as native models on the Cart/Order split. Basic Stripe Connect payouts (Express onboarding + on-fulfillment transfers) ship OSS in the monorepo, alongside the Stripe core gateway pulled in from the standalone `spree_stripe` repo (payment-sessions classes only, likely `spree/core` — decisions.md 2026-07-15); Enterprise keeps refund clawbacks/netting, reconciliation, KYC ops, DAC7 payout reports, facilitator taxes + Shopify/WooCommerce vendor apps.
- `6.0-cart-order-split.md` — Cart/Order model separation, polymorphic LineItem
- `6.0-admin-api.md` — Admin REST API conventions, auth, endpoint list (~300 endpoints)
- `6.0-admin-spa.md` — React admin architecture, extension points, table registry, i18n + server-error mapping
@@ -26,7 +27,7 @@ Active plans (6.0 target, work pending):
- `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
- `6.0-rich-text-descriptions.md` — Drop ActionText storage, store HTML in text columns, sanitize on write, serve `description` + `description_html` in API (description_html serializer field shipped in 5.4)
-- `6.0-inventory-operations.md` — StockTransfer lifecycle (draft → ready_to_ship → in_transit → received with partial receive), new `Spree::PurchaseOrder` + `Spree::Vendor` replacing today's "external receive" hack, variant + stock-location stock history panels. Consumes the typed-movement primitives from `6.0-typed-stock-movements.md`.
+- `6.0-inventory-operations.md` — StockTransfer lifecycle (draft → ready_to_ship → in_transit → received with partial receive), new `Spree::PurchaseOrder` + `Spree::Supplier` (renamed from Vendor — `Spree::Vendor` is the marketplace seller, see decisions.md 2026-07-14) replacing today's "external receive" hack, variant + stock-location stock history panels. Consumes the typed-movement primitives from `6.0-typed-stock-movements.md`.
- `6.0-replace-taxons-with-categories.md` — Split Taxon into Category (hierarchy) + Collection (flat/rule-based). `Spree::Category < Spree::Taxon` alias + Category API surface shipped in 5.5; table rename + Collection pending.
Multi-version plans (some phases shipped, some pending):
@@ -37,7 +38,7 @@ Multi-version plans (some phases shipped, some 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 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. Channel-level gated storefront access (`storefront_access` enum + channel-owned `guest_checkout`, both with store fallback, enforced in the v3 Store API) targeted for 5.6. 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.
+- `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. Channel-level gated storefront access (`storefront_access` enum + channel-owned `guest_checkout`, both with store fallback, enforced in the v3 Store API) targeted for 5.6. Catalog, Company/CompanyLocation/CompanyContact for B2B **deferred to 6.1** (the B2B release — see `docs/plans/decisions.md` 2026-06-16; filename keeps `6.0-` prefix for stable cross-refs). Multi-store catalogs (historic `Product has_many :stores`) move to the `spree_multi_store` extension.
- `5.6-6.0-single-store-promotions-payment-methods.md` — Migrate `Spree::Promotion` + `Spree::PaymentMethod` from multi-store (`has_many :stores` via `spree_promotions_stores` / `spree_payment_methods_stores` join tables) to single-owner `belongs_to :store`, mirroring the 5.5 single-owner Product migration. 5.6 (implemented): `store_id` FK + required-store presence via `Spree::SingleStoreResource`, backfill rake task (loud per-record deprecation on shared records), shared `LegacyMultiStoreSupport` deprecation bridge, deletes the `ResourceController` `store_ids=` seam, deprecates `StoreScopedResource`; multi-store sharing moves to the `spree_multi_store` extension (join tables left intact). 6.0 cleanup: enforce `null: false`, drop join tables + bridges. Paired with `6.0-channels-catalogs-b2b.md`.
- `5.6-project-layout-and-dashboard.md` — React Dashboard Developer Preview packaging + `backend/` → `api/` project layout. Implemented: `<Dashboard />` shell export from `@spree/dashboard` (source-only, relative imports only), monorepo-canonical `packages/dashboard-starter` thin host (embedded standalone into the `@spree/cli` tarball at build time via `scripts/sync-dashboard-starter.mjs` — Vendure-style, no template repo; create-spree-app delegates to the project-local `spree add dashboard`), `spree add dashboard` + create-spree-app dashboard phase (opt-in via `--react-dashboard` while WIP — not prompted; env carries only `VITE_API_PROXY_TARGET` — never secret keys, and never `VITE_SPREE_API_URL`, which would flip the SDK to absolute cross-origin URLs and break dev on CORS), npm release job for `@spree/dashboard{,-ui,-core}` (0.x → `next` tag). Pending: layout rename + `detectApiDir` dual-layout CLI, `spree upgrade layout`; optional public template repo at 6.0 GA.
- `5.6-dashboard-typed-plugin-routes.md` — Plugin file routes compiled into the host's TanStack route tree: `spree.dashboard.routes` marker + virtual-route-config composition in `@spree/dashboard/vite`, `createDashboardRouter` + `<Dashboard router>` ownership inversion, typed cast-free links, cross-package collision pre-flight with package-named errors. Runtime route registry stays for dynamic/in-app cases (catch-all is lowest priority). Implemented; published-tarball spike passed.
@@ -68,7 +69,7 @@ Shipped plans:
|---|---|
| `spree/core` | Ruby gem — models, services, business logic (`spree_core`) |
| `spree/api` | Ruby gem — Store & Admin REST APIs (`spree_api`) |
-| `spree/emails` | Ruby gem — transactional emails (optional). Deprecated in 6.0 — Next.js storefront handles consumer emails via webhooks. |
+| `spree/emails` | Ruby gem — transactional emails (optional). Rebuilt + modernized in 5.6. The default email stack for installations without a storefront app (e.g. mobile apps); headless storefronts may instead own consumer emails via webhooks. |
| `spree/dashboard` | Ruby gem (`spree_dashboard`, optional) — hosts a built React Dashboard at `/dashboard` from `Spree::Dashboard.dist_path` / `SPREE_DASHBOARD_DIST_PATH` (single-node topology). Successor slot to `spree_admin` at 6.0. |
| `packages/dashboard` | `@spree/dashboard` — React SPA admin dashboard (Spree 6.0, replaces `spree/admin`). The deployable app shell, routes, schemas, resource hooks, locales. |
| `packages/dashboard-ui` | `@spree/dashboard-ui` — design system. Shadcn primitives + headless composed components + tokens. Source-only; consumer compiles via Vite/Tailwind. **Components are headless: data comes via props, no provider/hook imports.** |
diff --git a/docs/plans/6.0-admin-api.md b/docs/plans/6.0-admin-api.md
index dd41c4b08c..7b7ef61e4b 100644
--- a/docs/plans/6.0-admin-api.md
+++ b/docs/plans/6.0-admin-api.md
@@ -31,7 +31,7 @@ A new REST API namespace (`/api/v3/admin/*`) that exposes every admin resource a
### Controller hierarchy
-```
+```text
Spree::Api::V3::BaseController # shared concerns: pagination, Ransack, caching
└── Spree::Api::V3::Admin::BaseController
└── Spree::Api::V3::Admin::ResourceController # default CRUD
@@ -149,11 +149,11 @@ Per-record conditions (CanCanCan blocks/hashes) are not serialized — only `has
3. **Orders + Items + Fulfillments + Payments + Adjustments + Refunds** ✅
4. **Customers + Addresses + Credit Cards + Store Credits + Customer Groups + Gift Cards** ✅
5. **Promotions + Rules + Actions + Coupon Codes** ✅
-6. **Stock (Locations, Items, Reservations, Transfers) + Price Lists + Prices** ✅ (Transfers lifecycle + Vendors + Purchase Orders pending — see `6.0-inventory-operations.md`)
+6. **Stock (Locations, Items, Reservations, Transfers) + Price Lists + Prices** ✅ (Transfers lifecycle + Suppliers + Purchase Orders pending — see `6.0-inventory-operations.md`)
7. **Categories** ✅ (read) — Collections + write/reposition pending
8. **Store settings ✅, Channels ✅, Markets ✅, Tax Categories ✅, Admin users ✅, Roles ✅ (read), Invitations ✅, API keys ✅, Webhooks ✅, Allowed Origins ✅, Exports ✅, Dashboard ✅**; Policies pending
9. **Custom Fields + Custom Field Definitions** ✅ — Translations (polymorphic) pending
-10. **Returns/Exchanges/Claims, Product Types, Collections, Catalogs/Companies (B2B), Delivery Methods/Zones, Tax Rates/Markets-as-tax, Payment Methods ✅** — remaining 6.0 model work
+10. **Returns/Exchanges/Claims, Product Types, Collections, Marketplace (Vendors/Commission/Payouts), Delivery Methods/Zones, Tax Rates/Markets-as-tax, Payment Methods ✅** — remaining 6.0 model work; Catalogs/Companies (B2B) deferred to **6.1** per `decisions.md` 2026-06-16
11. **Reports, Imports, Integrations, Price History, Stock Movements** — pending
### PR process for each endpoint
@@ -666,12 +666,14 @@ Customer assignment is handled via the standard `PATCH /api/v3/admin/orders/:id`
> **6.0:** Transfer lifecycle (draft → ready_to_ship → in_transit → received) + partial receive are pending. See `6.0-inventory-operations.md`.
-### Vendors (new in 6.0)
-- [ ] `GET /api/v3/admin/vendors`
-- [ ] `GET /api/v3/admin/vendors/:id`
-- [ ] `POST /api/v3/admin/vendors`
-- [ ] `PATCH /api/v3/admin/vendors/:id`
-- [ ] `DELETE /api/v3/admin/vendors/:id`
+### Suppliers (new in 6.0)
+- [ ] `GET /api/v3/admin/suppliers`
+- [ ] `GET /api/v3/admin/suppliers/:id`
+- [ ] `POST /api/v3/admin/suppliers`
+- [ ] `PATCH /api/v3/admin/suppliers/:id`
+- [ ] `DELETE /api/v3/admin/suppliers/:id`
+
+> **6.0:** `Spree::Supplier` is the procurement source for purchase orders (see `6.0-inventory-operations.md`). Not to be confused with marketplace **Vendors** below — `Spree::Vendor` is the marketplace seller (`6.0-multi-vendor-marketplace.md`, `decisions.md` 2026-07-14).
### Purchase Orders (new in 6.0)
- [ ] `GET /api/v3/admin/purchase_orders`
@@ -683,7 +685,31 @@ Customer assignment is handled via the standard `PATCH /api/v3/admin/orders/:id`
- [ ] `POST /api/v3/admin/purchase_orders/:id/receive` — body `{ items: [{ id, quantity_received }] }`
- [ ] `POST /api/v3/admin/purchase_orders/:id/cancel`
-> **6.0:** `Spree::PurchaseOrder` + `Spree::Vendor` replace today's "external receive" hack. See `6.0-inventory-operations.md`.
+> **6.0:** `Spree::PurchaseOrder` + `Spree::Supplier` replace today's "external receive" hack. See `6.0-inventory-operations.md`.
+
+### Marketplace (new in 6.0)
+
+Per `6.0-multi-vendor-marketplace.md`. Vendor prefix is `ven_` (matches the legacy Enterprise gem).
+
+- [ ] `GET /api/v3/admin/vendors`
+- [ ] `GET /api/v3/admin/vendors/:id`
+- [ ] `POST /api/v3/admin/vendors`
+- [ ] `PATCH /api/v3/admin/vendors/:id`
+- [ ] `DELETE /api/v3/admin/vendors/:id`
+- [ ] `POST /api/v3/admin/vendors/:id/invite` — (re)send the vendor invitation (`Spree::Invitation`, `resource: vendor`)
+- [ ] `POST /api/v3/admin/vendors/:id/approve` / `POST /api/v3/admin/vendors/:id/reject` / `POST /api/v3/admin/vendors/:id/suspend` — lifecycle transitions (approve also un-suspends)
+- [ ] `GET /api/v3/admin/commission_rates`
+- [ ] `GET /api/v3/admin/commission_rates/:id`
+- [ ] `POST /api/v3/admin/commission_rates`
+- [ ] `PATCH /api/v3/admin/commission_rates/:id` — saves rate fields + nested `rules: []` in one round-trip (PriceList-style)
+- [ ] `DELETE /api/v3/admin/commission_rates/:id`
+- [ ] `GET /api/v3/admin/commission_lines` — read-only snapshot ledger (filter by vendor/order)
+- [ ] `GET /api/v3/admin/vendor_transfers` — read-only earnings ledger (filter by vendor/payout/status)
+- [ ] `GET /api/v3/admin/vendor_payouts` / `GET /:id`
+- [ ] `POST /api/v3/admin/vendor_payouts/:id/complete` — manual settlement (system provider)
+- [ ] `GET /api/v3/admin/order_groups` / `GET /:id` — the multi-order transaction container
+
+API key scopes: `read_vendors` / `write_vendors`, `read_commissions` / `write_commissions`, `read_payouts` / `write_payouts`.
### Price Lists
- [x] `GET /api/v3/admin/price_lists`
diff --git a/docs/plans/6.0-channels-catalogs-b2b.md b/docs/plans/6.0-channels-catalogs-b2b.md
index 4cf4ea8d46..6c1f4771f4 100644
--- a/docs/plans/6.0-channels-catalogs-b2b.md
+++ b/docs/plans/6.0-channels-catalogs-b2b.md
@@ -1,7 +1,9 @@
# Channels, Catalogs & B2B Companies
-**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); gated storefront access targeted for 5.6; Catalog, Company tree, and pricing integration land in 6.0
-**Target:** Spree 5.5 (Phase 1 ✓) → 5.6 (Gated Access) → 6.0 (Catalog + Company)
+**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); gated storefront access targeted for 5.6; Catalog, Company tree, and pricing integration **deferred to 6.1** (the B2B release — see `decisions.md` 2026-06-16)
+**Target:** Spree 5.5 (Phase 1 ✓) → 5.6 (Gated Access) → 6.1 (Catalog + Company)
+
+> **Filename note:** this plan keeps its `6.0-` filename for stable cross-references (it's linked from CLAUDE.md and ~10 sibling plans), but the Phase 2 deliverable (Catalog + Company) now targets **6.1**. Don't infer the target from the filename — the header and per-phase headings are authoritative. Phase 1 (5.5) and the 5.6 Gated Access phase are unaffected.
**Depends on:** ProductType (6.0-product-types.md), PriceList system (existing)
**Author:** Damian + Claude
**Last updated:** 2026-07-01
@@ -555,7 +557,7 @@ No schema migration (preferences only — see the **Gated Storefront Access** de
- v3 Store API enforcement: `hide_prices` serializer flag + `money_attributes` price-nulling for `prices_hidden`; `before_action` 401 guard on `Store::BaseController` + `Store::ResourceController` for `login_required` (public endpoints opt out via `allow_guest_storefront_access!`); guest-checkout guard in the `Spree::Carts::Complete` service (so controller, payment-session, and webhook completion paths are all covered), with the controller also returning a `401` early.
- Non-breaking, no backfill — channels default to store fallback, preserving today's behaviour.
-### Phase 2 — 6.0: Catalog + Company tree + pricing integration
+### Phase 2 — 6.1: Catalog + Company tree + pricing integration
```ruby
class CreateCatalogsCompanies < ActiveRecord::Migration[7.2]
@@ -637,7 +639,7 @@ class CreateCatalogsCompanies < ActiveRecord::Migration[7.2]
end
```
-### Phase 2 — 6.0 Admin API additions
+### Phase 2 — 6.1 Admin API additions
```
# Catalogs
@@ -708,7 +710,7 @@ Most of the planned 6.0 cleanup already happened in 5.5 (cleaner data model from
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.
-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.
+7. **CompanyContact roles and B2B approval workflows.** Out of scope for this plan. The 6.1 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 after 6.1.
8. **Gated storefront access model.** A single tiered `storefront_access` enum on Channel (`public` / `prices_hidden` / `login_required`), `nil` → store fallback — rather than independent booleans (which permit redundant/contradictory combinations) or a prices-only boolean (which can't express a full login wall). Enforced in the v3 Store API: `prices_hidden` nulls price fields for guests, `login_required` `401`s catalog reads for guests. This is the explicit "deny anonymous" gate the visibility resolver lacked. Targeted for **5.6** — it builds only on the 5.5 channel infrastructure and needs no schema change, so it ships ahead of the 6.0 Catalog/Company work.
diff --git a/docs/plans/6.0-inventory-operations.md b/docs/plans/6.0-inventory-operations.md
index 6841abbfe6..2e99a1025e 100644
--- a/docs/plans/6.0-inventory-operations.md
+++ b/docs/plans/6.0-inventory-operations.md
@@ -4,14 +4,16 @@
**Target:** Spree 6.0
**Depends on:** Typed Stock Movements (6.0-typed-stock-movements.md), Fulfillment & Delivery (6.0-fulfillment-and-delivery.md), Stock Reservations (6.0-stock-reservations.md)
**Author:** Damian + Claude
-**Last updated:** 2026-05-16
+**Last updated:** 2026-07-14
+
+> **Naming note (2026-07-14):** the procurement-source model this plan introduces is **`Spree::Supplier`** (`spree_suppliers`, prefix `sup_`, `/api/v3/admin/suppliers`). An earlier draft called it `Spree::Vendor`, which collided with the marketplace seller model of `6.0-multi-vendor-marketplace.md` — `Spree::Vendor` is reserved for marketplace sellers (see `decisions.md` 2026-07-14). "Supplier" also matches Shopify's purchase-order vocabulary.
## Summary
Lift inventory operations from "atomic decrement + log" to a first-class workflow on par with Shopify. Three coordinated changes:
1. **`Spree::StockTransfer` gains a lifecycle.** Today a transfer is one-shot — source decrements and destination increments in the same transaction. After this plan: `draft → ready_to_ship → in_transit → received` (with `cancelled` as a terminal escape hatch), plus line items, partial receive support, and a discrepancy column. Source units leave on `mark_in_transit`, destination units land on `receive` — not at the same instant.
-2. **New `Spree::PurchaseOrder` model** for vendor receives. Today's "external receive" hack (a `StockTransfer` with `source_location_id: nil`) is replaced by a proper `PurchaseOrder` with `vendor`, `expected_at`, `line_items[]` with `unit_cost`, and the same receive flow as transfers.
+2. **New `Spree::PurchaseOrder` model** for supplier receives. Today's "external receive" hack (a `StockTransfer` with `source_location_id: nil`) is replaced by a proper `PurchaseOrder` with `supplier`, `expected_at`, `line_items[]` with `unit_cost`, and the same receive flow as transfers.
3. **Variant + Location stock history.** Surfaces the audit feed introduced by `6.0-typed-stock-movements.md` as inline timelines in the admin SPA — answering "why is on-hand 47?" in the place users always ask: on a SKU or a warehouse.
This plan is the **UX surface** for inventory ops. The data primitives (typed `StockMovement`, `kind`, concrete FKs to Order/Fulfillment/StockTransfer/ReturnAuthorization/PurchaseOrder) come from `6.0-typed-stock-movements.md` and the Fulfillment rename. Those two plans must land first.
@@ -35,9 +37,9 @@ This means:
### 2. "External receive" is a hack
-Today, receiving stock from a vendor is implemented as `StockTransfer.transfer(nil, destination, variants)` — passing a `nil` source. There is no vendor identity, no PO number, no unit cost, no expected-arrival date, no audit of who placed the order. The legacy admin's "Receive" screen is a `StockTransfer` form with the source dropdown hidden.
+Today, receiving stock from a supplier is implemented as `StockTransfer.transfer(nil, destination, variants)` — passing a `nil` source. There is no supplier identity, no PO number, no unit cost, no expected-arrival date, no audit of who placed the order. The legacy admin's "Receive" screen is a `StockTransfer` form with the source dropdown hidden.
-Vendors and merchant warehouses are different things. A PO has unit cost (drives COGS / margin reporting), an expected date (drives replenishment scheduling), and a vendor (drives accounts payable). A transfer has none of those — it's internal logistics. Folding them together costs us margin reporting and replenishment UX forever.
+Suppliers and merchant warehouses are different things. A PO has unit cost (drives COGS / margin reporting), an expected date (drives replenishment scheduling), and a supplier (drives accounts payable). A transfer has none of those — it's internal logistics. Folding them together costs us margin reporting and replenishment UX forever.
### 3. Movement history has no UI surface
@@ -48,7 +50,7 @@ Once `6.0-typed-stock-movements.md` lands, every change to `count_on_hand` carri
| What | How it works (5.5) |
|---|---|
| `Spree::StockTransfer` | One-shot atomic transfer. Columns: `source_location_id` (nullable for receives), `destination_location_id`, `number`, `reference`, `type` (STI column, unused), `created_at`. No status, no expected/received-at, no line items. |
-| External receive | `StockTransfer.transfer(nil, destination, variants)` — no vendor, no cost. |
+| External receive | `StockTransfer.transfer(nil, destination, variants)` — no supplier, no cost. |
| Movement audit | `Spree::StockMovement` with polymorphic `originator`. Only `StockTransfer`, `ReturnAuthorization`, and `nil` show up in practice. Shipment fulfillment does **not** write movements (lives on `InventoryUnit` instead). |
| Admin SPA | `Products → Transfers` (single page) with create-transfer sheet. No history view, no PO concept. |
@@ -65,9 +67,9 @@ Once `6.0-typed-stock-movements.md` lands, every change to `count_on_hand` carri
### Purchase Orders
-- **New model `Spree::PurchaseOrder`**, not an STI subclass of `StockTransfer`. The two share a UX rhythm (line items → receive flow) but their domains are distinct (vendor vs warehouse, unit cost vs no cost, AP vs internal logistics). STI would force one table to carry both vocabularies. Better to have parallel models with a shared `Receivable` concern that owns the line-items + receive-flow + status machine.
-- **`Spree::Vendor` is the supplier identity.** Minimal: `name`, `contact_name`, `email`, `phone`, `address`, `notes`, `metadata`. Stores manage their own vendor list — vendors are not shared across stores in 6.0.
-- **Status machine**: `draft | ordered | partially_received | received | cancelled`. No `in_transit` — a PO doesn't track in-flight stock from the vendor; the merchant only knows about it when units land. (Future enhancement: optional `shipped` state if the vendor provides tracking, but not in 6.0.)
+- **New model `Spree::PurchaseOrder`**, not an STI subclass of `StockTransfer`. The two share a UX rhythm (line items → receive flow) but their domains are distinct (supplier vs warehouse, unit cost vs no cost, AP vs internal logistics). STI would force one table to carry both vocabularies. Better to have parallel models with a shared `Receivable` concern that owns the line-items + receive-flow + status machine.
+- **`Spree::Supplier` is the supplier identity.** Minimal: `name`, `contact_name`, `email`, `phone`, `address`, `notes`, `metadata`. Stores manage their own supplier list — suppliers are not shared across stores in 6.0.
+- **Status machine**: `draft | ordered | partially_received | received | cancelled`. No `in_transit` — a PO doesn't track in-flight stock from the supplier; the merchant only knows about it when units land. (Future enhancement: optional `shipped` state if the supplier provides tracking, but not in 6.0.)
- **`PurchaseOrderItem` has `unit_cost` (Money) and `quantity_ordered` / `quantity_received`.** Currency comes from the PO's `currency` column (defaults to the store's). Receiving units writes typed `received` stock movements with `purchase_order_id`.
- **PO does not affect `count_on_hand` until receive.** Ordered units are visible to the merchant as "on order" (computed: `SUM(quantity_ordered - quantity_received)` per variant), but never count toward availability.
@@ -185,7 +187,7 @@ class Spree::PurchaseOrder < Spree.base_class
publishes_lifecycle_events
- belongs_to :vendor, class_name: 'Spree::Vendor'
+ belongs_to :supplier, class_name: 'Spree::Supplier'
belongs_to :destination_location, class_name: 'Spree::StockLocation'
belongs_to :store, class_name: 'Spree::Store'
@@ -199,7 +201,11 @@ class Spree::PurchaseOrder < Spree.base_class
attribute :expected_at, :date
attribute :notes, :text
- validates :vendor, :destination_location, :currency, presence: true
+ # Currency defaults from the store before validation — creation paths never
+ # need to pass it explicitly, but may override for foreign-currency POs.
+ before_validation { self.currency ||= store&.default_currency }
+
+ validates :supplier, :destination_location, :currency, presence: true
validate :has_items, on: :submit
state_machine :status, initial: :draft do
@@ -259,11 +265,11 @@ class Spree::PurchaseOrderItem < Spree.base_class
end
```
-### Vendor (new)
+### Supplier (new)
```ruby
-class Spree::Vendor < Spree.base_class
- has_prefix_id :vnd
+class Spree::Supplier < Spree.base_class
+ has_prefix_id :sup
include Spree::SingleStoreResource
include Spree::Metafields
include Spree::Metadata
@@ -302,7 +308,7 @@ The `kind` stays `received` (already defined). PO is just a new cause flavor —
New endpoints; all CRUD-shaped, all under `/api/v3/admin/`:
-```
+```text
GET /stock_transfers
POST /stock_transfers
GET /stock_transfers/:id
@@ -314,7 +320,11 @@ POST /stock_transfers/:id/mark_in_transit
POST /stock_transfers/:id/receive # body: { items: [{ id, quantity_received, discrepancy_reason }] }
POST /stock_transfers/:id/cancel # body: { on_in_transit: 'restock' | 'write_off' } when needed
-GET /vendors / POST / PATCH / DELETE (standard CRUD)
+GET /suppliers
+POST /suppliers
+GET /suppliers/:id
+PATCH /suppliers/:id
+DELETE /suppliers/:id
GET /purchase_orders
POST /purchase_orders
@@ -367,7 +377,7 @@ State-transition endpoints are explicit POSTs (not PATCHes that mutate `status`)
"id": "po_xxx",
"number": "PO-00042",
"status": "partially_received",
- "vendor_id": "vnd_xxx",
+ "supplier_id": "sup_xxx",
"destination_location_id": "sl_bbb",
"currency": "USD",
"expected_at": "2026-06-01",
@@ -427,7 +437,7 @@ class AddInventoryOperations < ActiveRecord::Migration[7.2]
unique: true,
name: 'idx_stock_transfer_items_unique'
- create_table :spree_vendors do |t|
+ create_table :spree_suppliers do |t|
t.string :name, null: false
t.string :contact_name
t.string :email
@@ -445,12 +455,12 @@ class AddInventoryOperations < ActiveRecord::Migration[7.2]
t.datetime :deleted_at
t.timestamps
end
- add_index :spree_vendors, [:store_id, :name], unique: true
+ add_index :spree_suppliers, [:store_id, :name], unique: true
create_table :spree_purchase_orders do |t|
t.string :number, null: false
t.string :status, null: false, default: 'draft'
- t.references :vendor, null: false
+ t.references :supplier, null: false
t.references :store, null: false
t.references :destination_location, null: false
t.string :currency, null: false
@@ -495,7 +505,7 @@ end
For each existing `StockTransfer` with `source_location_id IS NULL`:
-1. Find-or-create a `Spree::Vendor` named `"Migrated receives"` for the relevant store.
+1. Find-or-create a `Spree::Supplier` named `"Migrated receives"` for the relevant store.
2. Create a `Spree::PurchaseOrder` with `status: 'received'`, `received_at: transfer.created_at`, `currency` from store default, `ordered_at: nil`.
3. Migrate the transfer's `stock_movements` into the PO via `purchase_order_id` (set, leave `stock_transfer_id` for historical lineage if desired, or null it). The migration leaves `count_on_hand` untouched — the movements already affected stock at the time.
4. Create `PurchaseOrderItem` rows from the underlying movements with `unit_cost_cents: 0` (historical cost is unknown).
@@ -505,22 +515,22 @@ All other existing transfers (with a real source location) become `status: 'rece
### Phase 3: Model & service code
-- New models: `Vendor`, `PurchaseOrder`, `PurchaseOrderItem`, `StockTransferItem`.
-- `StockTransfer` gains state machine + line items + `transfer`/`receive` methods removed (the old atomic API).
+- New models: `Supplier`, `PurchaseOrder`, `PurchaseOrderItem`, `StockTransferItem`.
+- `StockTransfer` gains a state machine + line items; the old atomic `transfer`/`receive` class methods are removed.
- New services under `Spree::Inventory::`:
- `Spree::Inventory::SubmitTransfer` (draft → ready_to_ship → in_transit, writes `shipped` movements)
- `Spree::Inventory::ReceiveTransfer` (params: `{ items: [{ id, quantity_received, discrepancy_reason }] }`, writes `received` movements for deltas)
- `Spree::Inventory::CancelTransfer`
- Parallel `Spree::Inventory::SubmitPurchaseOrder` / `Spree::Inventory::ReceivePurchaseOrder` / `Spree::Inventory::CancelPurchaseOrder`
- Each service returns a `ServiceModule::Result` (success/error) — same pattern as existing checkout services.
-- CanCanCan: `Vendor` and `PurchaseOrder` map to a new permission set `Spree::PermissionSets::PurchaseOrderManagement` and `Spree::PermissionSets::PurchaseOrderDisplay`. Stock transfers stay under the existing `StockManagement` / `StockDisplay` sets.
+- CanCanCan: `Supplier` and `PurchaseOrder` map to a new permission set `Spree::PermissionSets::PurchaseOrderManagement` and `Spree::PermissionSets::PurchaseOrderDisplay`. Stock transfers stay under the existing `StockManagement` / `StockDisplay` sets.
### Phase 4: Admin API + serializers
-- Register dependencies (`admin_vendor_serializer`, `admin_purchase_order_serializer`, `admin_purchase_order_item_serializer`, `admin_stock_transfer_item_serializer`).
-- Register API scopes: `read_inventory` / `write_inventory` for POs and vendors. Transfers stay under `read_stock` / `write_stock` (existing).
+- Register dependencies (`admin_supplier_serializer`, `admin_purchase_order_serializer`, `admin_purchase_order_item_serializer`, `admin_stock_transfer_item_serializer`).
+- Register API scopes: `read_inventory` / `write_inventory` for POs and suppliers. Transfers stay under `read_stock` / `write_stock` (existing).
- Controllers under `Spree::Api::V3::Admin::`:
- - `VendorsController` (standard CRUD)
+ - `SuppliersController` (standard CRUD)
- `PurchaseOrdersController` (standard CRUD + transition actions)
- `StockTransfersController` rewritten — no more `create` doing source/dest decrement; create persists a draft. Transitions are explicit actions.
- New integration specs in `spree/api/spec/integration/spree/api/v3/admin/`.
@@ -530,8 +540,8 @@ All other existing transfers (with a real source location) become `status: 'rece
- Run typelizer + rswag + admin-client generators.
- `useTransfers`, `useTransfer`, `useTransition<Transfer>` hooks (consolidate the action endpoints behind a single hook with `action: 'mark_ready' | 'receive' | 'cancel'`).
- Same shape for purchase orders.
-- `useVendors`.
-- Admin SPA routes: `_authenticated/$storeId/products/transfers.{index,$id}.tsx`, `_authenticated/$storeId/products/purchase-orders.{index,$id}.tsx`, `_authenticated/$storeId/settings/vendors.tsx`.
+- `useSuppliers`.
+- Admin SPA routes: `_authenticated/$storeId/products/transfers.{index,$id}.tsx`, `_authenticated/$storeId/products/purchase-orders.{index,$id}.tsx`, `_authenticated/$storeId/settings/suppliers.tsx`.
- Variant detail page gets a `<StockMovementsHistory variantId>` panel; stock-location detail page gets a `<StockMovementsHistory stockLocationId>` panel. Both read `/admin/stock_movements` with the relevant `q[...]` filter and render the timeline with `RelativeTime`.
### Phase 6: Cleanup
@@ -542,14 +552,14 @@ All other existing transfers (with a real source location) become `status: 'rece
## Constraints on Current Work
- **Don't extend the old `StockTransfer.transfer` API.** It is going away. New code should write to `StockTransferItem` and use the state machine.
-- **Don't add receive flows to `StockTransfer` without `source_location_id`.** Vendor receives move to `PurchaseOrder`. If a 5.5 feature needs to record a vendor receive, scope it minimally and flag it for migration.
+- **Don't add receive flows to `StockTransfer` without `source_location_id`.** Supplier receives move to `PurchaseOrder`. If a 5.5 feature needs to record a supplier receive, scope it minimally and flag it for migration.
- **Don't create a separate "Stock Movements" admin SPA page.** Movement history is always inline on variant + stock location.
- **Don't fold cost data onto `StockTransfer`.** Transfers don't have a unit cost — they move existing inventory between owned locations. Cost lives on `PurchaseOrderItem.unit_cost`.
## Open Questions
1. **Historical "external receive" transfers — keep or hard-delete after migration?** Soft-keeping preserves audit history at the cost of a confusing dual-source-of-truth (movements visible from both the migrated PO and the legacy transfer). Hard-deleting cleans the model but loses the original `T-xxx` number for historical reporting. Lean toward soft-delete with a release-note + a rake task to purge after one release.
-2. **Vendors shared across stores?** Today the plan scopes them per-store. Some merchants run multiple storefronts off one supplier base. Could promote to a `Spree::Vendor` with a M2M to stores in a follow-up. Defer.
+2. **Suppliers shared across stores?** Today the plan scopes them per-store. Some merchants run multiple storefronts off one supplier base. Could promote to a `Spree::Supplier` with a M2M to stores in a follow-up. Defer.
3. **Average / weighted-average cost on Variant?** A PO's `unit_cost` enables margin reporting. The natural extension is `Variant.average_cost` (rolling avg of received unit costs) for COGS. Likely worth a separate plan — call it out, don't scope it here.
4. **Pickup transfers (ship-to-store).** `6.0-fulfillment-and-delivery.md` mentions `pickup_stock_policy: 'any'` as enabling ship-to-store. The natural implementation is auto-creating a `StockTransfer` when a pickup order's items aren't local at the chosen pickup location. Mechanism is straightforward; UX (does the customer see "ready in 3 days" instead of "ready in 2 hours"?) needs a separate decision. Defer.
diff --git a/docs/plans/6.0-multi-vendor-marketplace.md b/docs/plans/6.0-multi-vendor-marketplace.md
new file mode 100644
index 0000000000..4144843adc
--- /dev/null
+++ b/docs/plans/6.0-multi-vendor-marketplace.md
@@ -0,0 +1,620 @@
+# Multi-Vendor Marketplace (Open Source Core)
+
+**Status:** Draft — design in progress, implementation not started
+**Target:** Spree 6.0 (the "Marketplace" release)
+**Depends on:** `6.0-cart-order-split.md` (Cart/Order split + polymorphic `LineItem#owner` — **currently a stub; must be fleshed out before Phase 3 design freezes**), `6.0-split-adjustments.md` (TaxLine/Discount/Fee replace polymorphic Adjustment), `6.0-order-routing.md` (per-seller stock location), `6.0-fulfillment-and-delivery.md` (Fulfillment/DeliveryMethod vocabulary, per-vendor delivery selection), `6.0-admin-spa.md` (vendor panel composition), `6.0-admin-api.md` (Marketplace endpoints)
+**Author:** Damian + Claude
+**Last updated:** 2026-07-14
+
+## Summary
+
+Open-source the core of Spree's multi-vendor marketplace into Spree 6.0, per [spree/spree#13323](https://github.com/spree/spree/issues/13323). Today multi-vendor lives in the paid Enterprise module as a **decorator-heavy monkey-patch** of core (dozens of prepended core classes, a parent order mutated into a line-item-less "splitted" state). 6.0 brings the **Vendor identity, per-seller order splitting, the commission engine, and the payout ledger** into core as first-class models — built natively on the 6.0 Cart/Order split rather than retrofitted onto the legacy `Order`-only model.
+
+What stays paid (Enterprise — boundary amended 2026-07-15, see `decisions.md`): refund **clawbacks** (automatic Stripe transfer reversals + negative-balance netting), ledger⇄provider **reconciliation**, KYC/account-health operations, payout reports (incl. DAC7), marketplace-facilitator taxes, Shopify/WooCommerce sales-channel apps, the category mapper. **Basic Stripe Connect execution — Express onboarding + on-fulfillment transfers — ships open-source in the monorepo**, alongside the Stripe core gateway being pulled in from the standalone `spree_stripe` repo (the payment-sessions-API classes only; the legacy v2-API/storefront code stays behind — likely home: `spree/core`). **Core runs the happy path end-to-end (onboard, sell, get paid); Enterprise operates the unhappy paths and compliance at scale.**
+
+This plan covers the four subsystems: **(A) vendor identity & teams**, **(B) order splitting**, **(C) the commission engine**, and **(D) the payout/fund-transfer ledger**. It is informed by a source-level port review of the current Enterprise multi-vendor module (private source — internals deliberately not cited here), the Enterprise behavior documented in the public user docs, and a survey of modern open-source marketplace implementations — see References (competitor names and the detailed comparison are likewise kept out of this public file).
+
+## Key Decisions (do not deviate without discussion)
+
+### Scope split (OSS 6.0 vs Enterprise) — per #13323, amended 2026-07-15 (basic Stripe execution → OSS; see `decisions.md`)
+
+| OSS core (this plan) | Enterprise (stays paid) |
+|---|---|
+| `Spree::Vendor` identity + invitation **and self-serve application** onboarding state machine + vendor teams (reusing `Role`/`RoleUser`/`Invitation`) | KYC/account-health **operations** (requirements monitoring, restricted-account workflows) |
+| Vendor admin dashboard (composed from `@spree/dashboard-*`) + operator marketplace screens | Refund **clawbacks** — automatic Stripe transfer reversals + negative-balance netting |
+| **Basic Stripe Connect payouts** (Express onboarding link + on-fulfillment transfers — ships with the monorepo Stripe gateway) | Ledger⇄Stripe **reconciliation** |
+| Commission engine (vendor- + product- + taxon-level rules, **commission taxation**) | Payout reports (incl. EU **DAC7** seller-income reporting) |
+| Order splitting + payment split | Shopify white-label Sales Channel app |
+| **Fund ledger** — `VendorTransfer` (on-fulfillment earnings) + `VendorPayout` (scheduled settlement) + balance, lifecycle, reversals | WooCommerce integration |
+| Vendor CSV import/export (rides the `Spree::Import`/`Spree::Export` pipeline) | Category mapper (external category → Spree taxon) |
+| Vendors API endpoints (Admin + Store) + lifecycle webhooks/events + onboarding task registry (core tasks) | Enterprise onboarding **tasks** registered into the core checklist (Stripe KYC, Shopify/Woo store connection) |
+| Merchandising + permissions (via code) | "Automatic taxes" (marketplace-facilitator remittance) |
+
+The boundary is **operational depth**: you can run a marketplace for free end-to-end — vendors onboard to Stripe Express through a hosted link and get paid automatically on fulfillment — and core records what each vendor is owed (the payout ledger). The moment you need the money *operations* — automatic refund clawbacks, negative-balance netting, ledger⇄Stripe reconciliation, KYC workflows, regulatory reporting, tax remittance — that's Enterprise (Decision 9).
+
+**The OSS payout story is execution-capable, not just record-keeping (amended 2026-07-15):** the monorepo's Stripe gateway ships a basic `PayoutProvider::StripeConnect` — Express onboarding + on-fulfillment transfers — so the free tier demos money movement end-to-end, at parity with the surveyed OSS competition. `PayoutProvider` stays a public interface, so community providers (PayPal Payouts, Wise, SEPA batch files) are first-class. Enterprise differentiates on the operations *around* the money, not on whether money moves.
+
+### `Spree::Vendor` name ownership (RESOLVED 2026-07-14)
+
+`Spree::Vendor` (prefix `ven_`, table `spree_vendors`) is **the marketplace seller — this plan's model**. The purchase-order procurement source that `6.0-inventory-operations.md` had also named `Spree::Vendor` is renamed **`Spree::Supplier`** (`sup_`, `spree_suppliers`, `/api/v3/admin/suppliers`). Rationale in `decisions.md` 2026-07-14: the marketplace name is locked publicly (#13323, the user docs' Vendors area, the legacy Enterprise module's `ven_` prefix and production data), and the two are different lifecycles — a supplier is an address-book entry the merchant buys stock from; a vendor is an onboarded selling party with users, commission, and payouts.
+
+### 1. Split happens at cart completion, into N child Orders under one parent — never seller-tagged flat line items
+
+The legacy module and current industry implementations agree on the shape, and it maps cleanly onto `6.0-cart-order-split.md`:
+
+- One mixed **`Spree::Cart`** through the entire shopping + checkout flow (a customer adds items from many vendors to one cart — no per-vendor cart fragmentation).
+- At `cart.complete!` (the `Spree::Carts::Complete` service from the cart/order-split plan), partition cart line items **by the denormalized `line_item.vendor_id` snapshot** (set from `product.vendor` at add-to-cart; revalidated at completion — see Order splitting) and, **when the cart spans more than one partition** (first-party items, `vendor_id: nil`, count as their own partition), fan out into **N child `Spree::Order`s, one per partition**, all owned by **one `Spree::OrderGroup`** that holds customer/payment/address context. Single-partition carts complete as a bare order — no group (see the Trigger & gate bullet).
+- The parent↔child relationship is an explicit FK via a dedicated `Spree::OrderGroup`, **not** the legacy `state == 'splitted'` string hack and **not** a join-table indirection. See Design Details and Decision 8.
+
+This is the single most important integration point with the rest of 6.0: **the split is a consumer of the Cart/Order split, implemented inside the completion service**, not a state-machine `after_transition` callback bolted onto a monolithic `Order` (which is how the legacy module did it). The 6.0 cart/order plan removes the order-level state machine entirely, so the legacy trigger cannot survive — splitting must be invoked explicitly from `Carts::Complete`.
+
+### 2. Commission is a frozen snapshot line attached to the order line item, computed once at placement
+
+Mirror the core insight from both the legacy module and the industry references: commission is **denormalized and frozen at sale time**, never recomputed on read. This matches Spree's existing EU Omnibus "frozen at sale" precedent (`5.4-6.0-eu-legal-compliance.md` PriceHistory).
+
+- New model **`Spree::CommissionLine`** (NOT a revival of the legacy commission table, NOT a polymorphic `Adjustment`). One row per commissioned line item — plus one per fulfillment when the rate commissions delivery revenue (`include_shipping`, Decision 4) — storing a **snapshot** of `rate`, `amount`, and the resolved rule's identity.
+- Written by a service during/after `cart.complete!`, once. A later rate change does not touch existing lines.
+- **Commission is NOT a `Spree::Fee`.** `6.0-split-adjustments.md`'s `Fee` is a *buyer-facing* charge — it rolls into `order.fee_total` and the order total the customer pays. Commission is a *platform ↔ vendor* settlement line the customer never sees; it must never touch order totals. `CommissionLine` is therefore its own off-order ledger table that merely follows the same typed-line design (concrete FKs, no polymorphic source, no state machine) as the split-adjustments family. The only real split-adjustments dependency is that tax lines / discounts / fees are line-item-attached, so they re-home cleanly to the child order during the split. (A *buyer-facing* marketplace service fee — StockX-style — would be a `Spree::Fee` with a `kind`; possible later, out of scope here.)
+
+### 3. Commission taxation is a first-class field — this is the OSS differentiator
+
+This is the one place where the **legacy Enterprise module is ahead of the surveyed industry implementations** and the reason #13323 calls out "commission taxation which is essential for European marketplaces." The common industry pattern uses an `include_tax` toggle that only decides whether the *seller's item tax* inflates the commission base; it charges **no tax on the marketplace fee itself**. The legacy module already charges VAT *on the commission* at a configurable per-vendor rate (`fee_total = fee_amount + fee_amount × tax_rate`, half-up rounding). The marketplace's commission is itself a **taxable B2B service** the platform renders to the seller. 6.0 must model:
+- `amount` — the commission (the fee the platform charges the seller),
+- `tax_amount` — VAT/tax **on that commission**, at a configurable commission tax rate,
+- `total` — `amount + tax_amount`.
+
+**EU base (RESOLVED 2026-06-25):** commission is computed on the seller's **net (ex-VAT)** item price, and `tax_amount` is applied **on top of the commission** — the marketplace fee is a separate taxable supply from the consumer's item sale, so the two VATs never mix. The `include_tax`-style base toggle stays available for non-EU/edge merchants who want a gross base, but the EU default is net-base + fee-VAT. The **tax-on-the-fee** field is mandatory and is the headline EU feature. The commission tax *rate* is resolved through `6.0-tax-provider.md` (per-Market TaxProvider) rather than a bare `platform_fee_tax_rate` column on the vendor (RESOLVED — see Resolved Decisions).
+
+### 4. Commission rate resolution: layered rules, first-match-wins by priority — generalize the legacy flat rate
+
+The legacy module resolves a **single flat percentage** with a two-level fallback: the product's platform-fee override if set, else the vendor's default rate. That is "very simplified" — percentage only; no categories, no caps, no currency scoping. The industry pattern generalizes this into a proper `CommissionRate` + `CommissionRule` engine (priority-ordered, first-match-wins, dimension-grouped targeting rules, `percentage | fixed`, `min_amount` floor, currency gate, no-rules = global default).
+
+**6.0 adopts the rule-engine shape but keeps the legacy fallback as the default ladder.** New models `Spree::CommissionRate` (priority, kind, value, currency, commission tax handling) + `Spree::CommissionRule` (polymorphic `subject` → Product / Taxon / Vendor / global). Resolution walks enabled rates by `priority DESC`, first match wins. Seed two implicit rules so existing single-rate merchants keep working: a product-scoped rate and a vendor-scoped rate, mirroring `product.platform_fee || vendor.platform_fee`.
+
+**Rule matching is dimension-grouped: AND across dimensions, OR within a dimension.** A rate's rules are grouped by subject type (Product / Taxon / Vendor); the rate matches a line item when *every* dimension group present has at least one matching rule. `{taxon: Electronics, taxon: Cameras, vendor: X}` reads "(Electronics OR Cameras) AND vendor X" — which expresses plain lists *and* the **vendor × category pairing** today's Enterprise sells (user docs: "per vendor, per category-vendor pairing, or per individual product") with no `match_policy` knob at all. The leading surveyed OSS engine uses the same semantics, so the model is proven; where we differ deliberately is precedence — explicit operator `priority` instead of implicit most-specific-wins, which is more predictable (already RESOLVED below).
+
+**`include_shipping` on the rate** (default `false`): when the resolved rate has it, the same calculation also runs against the vendor order's delivery amounts, persisting a fulfillment-scoped `CommissionLine`. The surveyed OSS competitor commissions shipping via a global-rate-only flag, and Amazon-style referral fees include it; the legacy module was items-only (its order-level "reverse fee" only prorates *item* commission on whole-order refunds — shipping is excluded from its base). Ours is per-rate — strictly more flexible than a global-only flag, and off by default so legacy behavior is preserved.
+
+**Precedence (RESOLVED 2026-06-25): integer-priority, not a fixed ladder.** `priority` is operator-assignable and walked `DESC`, first match wins. Core **seeds default priorities** so the product-scoped rate beats the vendor-scoped rate out of the box — simple merchants never touch priorities, advanced merchants reorder freely. No hardcoded product > taxon > vendor > global ladder.
+
+### 5. One payment, recorded as a per-seller split — adopt the explicit split-payment record
+
+The customer makes **one payment** (one gateway charge against the order group). Do **not** create N gateway charges. The split is bookkeeping:
+
+Two patterns exist in the wild: (a) link one payment collection to all child orders and split captures *proportionally* into per-order transaction rows computed on read; or (b) an explicit **split-payment record** per child order (`authorized_amount`, `captured_amount`, `refunded_amount`).
+
+**6.0 adopts the explicit per-seller payment record** (pattern b) rather than proportion-on-read, because a marketplace needs a durable per-seller audit trail for partial captures, partial refunds, and payouts. This is also what the legacy module effectively did by creating real `Spree::Payment` rows on each vendor sub-order — but 6.0 does **not** clone `Payment` rows: the gateway object stays singular.
+
+Concretely: `Spree::Payment` gains a nullable `order_group_id` — a grouped checkout's payment attaches to the **group** (its `order_id` is nil); a plain ungrouped order keeps `payment.order` as today. The per-seller bookkeeping is a new **`Spree::PaymentSplit`** row per child order (`payment_id`, `order_id`, `authorized_amount` / `captured_amount` / `refunded_amount`, `currency`) — sketched in Design Details. A partial refund on one vendor's order updates that child's split, never the siblings'.
+
+### 6. Per-seller totals are computed independently, not prorated
+
+Confirmed by the references and the legacy module (its split moves line items, adjustments, inventory units, and shipments wholesale to the child order, then recomputes). Taxes/discounts/shipping travel with whichever line item or shipment they were attached to, into exactly one vendor's order; each child order recomputes its own totals. **No cart-level total proration** (the one exception is the single payment capture, Decision 5, and store-credit allocation, which the references and the legacy module prorate per item).
+
+### 7. Native models, not decorators
+
+The legacy module is a large decorator layer prepending ~35 core classes. 6.0 brings this into core as **real models, associations, and services** — `Spree::Vendor`, `Spree::OrderGroup`, `Spree::PaymentSplit`, `Spree::CommissionLine`, `Spree::CommissionRate`, `Spree::CommissionRule`, `Spree::VendorTransfer`, `Spree::VendorPayout`, and a `Spree::Carts::SplitByVendor` (or folded into `Carts::Complete`) service. No `prepend`. Follow `CLAUDE.md` model conventions (`Spree.base_class`, prefixed IDs, `class_name`/`dependent` on every association, string status columns, paranoia where needed).
+
+Deliberately **not** new models: vendor team membership and invitations reuse the existing polymorphic rails — `Spree::RoleUser` (`resource: vendor`) and `Spree::Invitation` (`resource: vendor`; its `resource` docstring already names Vendor as an intended type). The legacy admin's `current_vendor` seams (`spree/admin` `base_controller.rb:155`, `resource_controller.rb:249`) exist only for the Enterprise module's legacy-admin panel and die with the legacy admin; the 6.0 equivalent is ability-level scoping (see Vendor identity & teams).
+
+### 8. The parent is a dedicated `Spree::OrderGroup`, not `Order#parent_id` (RESOLVED 2026-06-16)
+
+The container is a **separate `Spree::OrderGroup` model**, not the legacy "an Order that is secretly a parent" (`Order#parent_id` + `state == 'splitted'`).
+
+**Crucially, `OrderGroup` is a domain-neutral primitive, not a marketplace concept.** It means "N orders placed together as one customer transaction" — multi-vendor is merely its *first* consumer. The same primitive is reused, without a second container model, for: split-by-fulfillment-location (one checkout → per-warehouse orders), split-by-availability (in-stock + pre-order/backorder in one cart), and B2B split-by-company-location (`6.0-channels-catalogs-b2b.md` → 6.1). Naming it `OrderGroup` (not `VendorOrderSet`) keeps it reusable across all of these. The vendor relationship lives on the **child `Order`** (`order.vendor`), never on the group — the group stays vendor-agnostic.
+
+Why a dedicated model beats `parent_id`:
+- No ambiguity / no empty parent orders. A parent `Order` with `parent_id: nil` and zero line items (the legacy shape) breaks every "an order has line items" assumption and forces a family of union-association and "is this really a parent?" workarounds. `OrderGroup` simply *has many* orders.
+- Clean composition with the Cart/Order split: `Cart` (one, mixed) → on completion → one `OrderGroup` owning N child `Order`s. The group is the natural home for the single payment, the customer, and the shared addresses; children own their own line items, shipments, totals.
+- Future-proof: when split-by-location or B2B needs the same fan-out, they reuse `OrderGroup` rather than overloading `Order` again.
+
+**This requires an Enterprise-side data backfill** (not core — existing OSS stores have no vendors). The Enterprise module must ship a one-time migration that, for every legacy `splitted` parent order, creates an `OrderGroup`, attaches its `parent_id`-children as the group's orders, and migrates the legacy commission rows into `spree_commission_lines`. The backfill lives in Enterprise because only Enterprise customers have legacy marketplace data; core ships clean. Tracked as a hard dependency for the Enterprise 6.0 upgrade. See Migration Path.
+
+### 9. Two-level fund ledger — `VendorTransfer` (on-fulfillment) + `VendorPayout` (on-interval), generic in core + a pluggable provider that executes it (RESOLVED 2026-06-25)
+
+**Transfer and payout are two distinct events** — the legacy module conflated them, and an earlier draft of this plan repeated the mistake. They must be separate models:
+
+- **`Spree::VendorTransfer`** — the **per-order** fund movement, triggered **on-fulfillment**. When a vendor's order is fully fulfilled (shipped; digital fulfills instantly after payment), the vendor *earns* `sale − commission`; that credits their balance. One transfer per fulfilled vendor order. This is what the legacy Stripe transfer ledger actually modeled (it fires when the vendor sub-order's shipments are all shipped).
+- **`Spree::VendorPayout`** — the **scheduled settlement**, triggered **on-interval** (daily/weekly/biweekly/monthly). It sweeps the vendor's accumulated unpaid transfers, batches them into one bank settlement, and debits the balance. One payout per interval per vendor (per currency).
+
+The legacy module only models the transfer and **outsources payouts to Stripe** (it just configures Stripe's native connected-account payout schedule — there is no `Payout` record; its "payouts" screens are *reports* aggregating transfers, not a ledger). That's fine for Stripe-only Enterprise but **wrong for OSS core**: a `system`-provider marketplace has no Stripe to schedule settlements, so it needs its own payout records.
+
+```text
+Spree::VendorTransfer (one per fulfilled vendor order, on-fulfillment) → credits vendor balance
+ ↓ accumulate (sale − commission)
+Spree::VendorPayout (one per interval per vendor, scheduled) → debits balance, settles to bank
+ ↑ has_many transfers (each VendorTransfer.payout_id) (batches N transfers; amount = Σ them)
+
+vendor.balance = Σ(completed transfers) − Σ(completed payouts) # derived bridge between the two levels
+```
+
+**Payout ⇄ Transfer link (RESOLVED): transfers `belong_to` a payout.** Each `VendorTransfer` carries a nullable `payout_id`. The scheduled job sweeps all unpaid completed transfers for a vendor, creates one `VendorPayout`, and stamps them with its id; `payout.amount = SUM(its transfers)`. Every payout itemizes *exactly* which order-transfers it settled — auditable, and robust to mid-period reversals (a refund after a transfer was already paid out becomes the **next** period's negative transfer rather than corrupting a closed payout). This is the seller-balance ledger the surveyed industry references *documented but never implemented* — Spree ships it properly.
+
+Both levels are **generic in core + provider-executed**, mirroring `6.0-tax-provider.md` / `6.0-delivery-rate-provider.md`:
+
+- **Core ships both ledger models** + a **`Spree::PayoutProvider::Base`** strategy with a **`system`** default: it records transfers (on-fulfillment) and payouts (on-interval) but moves no money — the OSS operator sees the per-vendor balance and the itemized payout records, and settles offline (marking the payout complete). This is what #13323 means by core knowing "what's owed."
+- **The monorepo ships the basic `Spree::PayoutProvider::StripeConnect`** (boundary amendment 2026-07-15), alongside the Stripe core gateway being pulled in from the standalone `spree_stripe` repo — only the payment-sessions-API gateway classes come over (likely into `spree/core`); the legacy v2-API/storefront code stays behind. The provider: Express-account creation + hosted onboarding link surfaced in the vendor dashboard + `account.updated` webhook → payout-account status on the vendor. `transfer!` executes an on-fulfillment `Stripe::Transfer` tied to the charge via `source_transaction` (gated on the account being payouts-enabled); `pay!` maps `payouts_schedule_interval` onto Stripe's native connected-account payout schedule and records `VendorPayout` rows from payout webhooks.
+- **Enterprise extends that provider with the money operations**: `reverse!` executing prorated Stripe transfer reversals on refund (ports the legacy reversal logic), negative-balance netting against future transfers, KYC/account-health workflows beyond the hosted flow, and ledger⇄Stripe reconciliation + payout reports. The paid tier operates the unhappy paths.
+
+**OSS funds flow — two modes.** (a) **`system`** (no gateway objects): the customer's single charge settles in full to the operator's own gateway account as a plain payment; the split is pure bookkeeping (`PaymentSplit` + this ledger); disbursement happens outside the gateway — on the payout schedule the operator pays each vendor by bank (SEPA/ACH/wire), guided by the itemized `VendorPayout`, and marks it complete, or automates it (`vendor_payout.due` webhook → banking API → `POST /vendor_payouts/:id/complete`). The platform is merchant of record for the full transaction and carries vendor payables on its own books. (b) **`stripe_connect` basic** (the monorepo Stripe gateway): vendors onboard as Express accounts through Stripe's hosted link; on fulfillment the provider executes a real transfer — money moves automatically. What OSS mode (b) does **not** do is pull money back: a refund always writes the ledger reversal (the books stay correct in every tier), but the Stripe transfer reversal, netting against future transfers, and reconciliation are Enterprise — the first production refund is where the upgrade conversation starts. Note the hard coupling that shapes this seam: a `Stripe::Transfer` requires a connected account, so basic Connect onboarding necessarily ships together with OSS transfer execution; what Enterprise keeps is not onboarding itself but the KYC *operations* around it.
+
+**Transfer amount basis** (ports the legacy allowed-transfer-amount rule, generalized per the resolved store-credit decision): the vendor's sale value minus commission, **payment-source-agnostic** (store credit / gift card is the platform's funding concern, not the vendor's):
+
+```text
+transfer.amount = vendor_order.total − vendor_order.commission_lines.sum(:total)
+```
+
+`vendor_order.total` is the child order's grand total — items + its delivery + its taxes − its discounts. The deduction is `CommissionLine#total`, i.e. commission **including the VAT on the commission** (the platform invoices the vendor commission + VAT; the vendor reclaims that VAT as input tax). The vendor is **merchant of record** for their child order in v1: consumer tax and shipping revenue are theirs. A *marketplace-facilitator / deemed-supplier* mode — where the platform withholds consumer tax and the basis becomes `total − tax_total − commission` — is deliberately **not** core; it's Enterprise "automatic taxes" territory (see the scope table and Open Questions).
+
+**Reversals** (ports the legacy reversal chain): a refund on a shipped order writes a negative `VendorTransfer` linked to the original via `reversed_from`, so the vendor's net earned is always `Σ(vendor_transfers)`. If the original was already settled in a closed payout, the reversal lands as a negative transfer in the next payout period. Ties into `6.0-returns-exchanges-claims.md`. The reversible-amount rule — original minus already-reversed, floored at zero — carries over as a model method on `VendorTransfer`.
+
+**Triggers (RESOLVED):** `vendor_transfer.due` fires **on-fulfillment** (all the vendor order's fulfillments fulfilled); `vendor_payout.due` fires **on the vendor's `payouts_schedule_interval`** (daily/weekly/biweekly/monthly/manual, `nil` ⇒ store default — the "Use marketplace default interval" semantics in today's Enterprise settings, carried over). Core honors `manual` natively (operator triggers settlement by hand); Enterprise implements the scheduled intervals.
+
+**Naming & scope (RESOLVED 2026-06-25):** the models keep the `Vendor` prefix and `belongs_to :vendor` — they are deliberately *not* generalized to bare `Transfer`/`Payout`. Rationale: (1) "transfer" and "payout" are heavily overloaded payment terms (gateway ACH/wire transfers, Stripe payout objects) — the `Vendor` prefix is what keeps these ledger records unambiguous and avoids re-introducing the very namespace confusion that made the legacy gateway-namespaced transfer model unclear; (2) the reusability that a dealership / B2B revenue-share scenario would want comes from an **abstract payee** (`belongs_to :payee, polymorphic`), *not* from a generic model name — and we have no second consumer yet, so per YAGNI we bind to `Vendor` now. If a concrete non-vendor payee requirement lands later, the migration path is to make `payee` polymorphic (Vendor + e.g. CompanyLocation) — a localized schema change — rather than a rename. This mirrors `OrderGroup`'s vendor-agnostic structure, but the inverse conclusion is correct here: the container is generic because the vendor lives on its children, whereas these ledger rows are *intrinsically* a payment to one specific payee.
+
+## Design Details
+
+### Vendor identity & teams
+
+The headline model. Ports the Enterprise module's `Spree::Vendor` (keeping prefix `ven_` for Enterprise data continuity) and adopts the lifecycle already shipped in the Enterprise admin (user docs: Invited → Onboarding → Ready for Review → Approved / Rejected / Suspended). **The external-store subsystem is not ported — none of it, ever**: the external store/product/order/category resource family, the per-platform Shopify/WooCommerce connections and sync workers, the category mapper, and the vendor-side hooks that reach into them (external-store shipping-method pulls, external-store-derived settings) all remain Enterprise. Core's `Vendor` carries no external-store associations, columns, or callbacks — the Enterprise module layers its connection models onto core's Vendor from the outside:
+
+```ruby
+class Spree::Vendor < Spree.base_class
+ has_prefix_id :ven
+ include Spree::SingleStoreResource
+ include Spree::Metafields
+ include Spree::Metadata
+ include Spree::TranslatableResource # about/description translate like Product
+ acts_as_paranoid
+ publishes_lifecycle_events
+
+ belongs_to :store, class_name: 'Spree::Store'
+ belongs_to :billing_address, class_name: 'Spree::Address', optional: true # on the commission invoice (EU)
+ belongs_to :returns_address, class_name: 'Spree::Address', optional: true # where customer returns route
+
+ has_many :products, class_name: 'Spree::Product', dependent: :nullify
+ has_many :stock_locations, class_name: 'Spree::StockLocation', dependent: :nullify
+ has_many :orders, class_name: 'Spree::Order' # child (vendor) orders
+ has_many :commission_lines, class_name: 'Spree::CommissionLine'
+ has_many :vendor_transfers, class_name: 'Spree::VendorTransfer'
+ has_many :vendor_payouts, class_name: 'Spree::VendorPayout'
+ has_many :role_users, class_name: 'Spree::RoleUser', as: :resource, dependent: :destroy
+ has_many :invitations, class_name: 'Spree::Invitation', as: :resource, dependent: :destroy
+
+ # name, slug (unique per store), contact_email, billing_email
+ # about : rich text (sanitized HTML column per 6.0-rich-text-descriptions.md)
+ # NO denormalized sales_total/commission_total counters (legacy has them) — lifetime
+ # revenue & commission derive from commission_lines / vendor_transfers (we have a ledger now)
+ # NO encrypted name/contact columns (legacy encrypts for its multi-tenant SaaS; core stays plain)
+ # logo / square_logo / cover_photo : ActiveStorage attachments (storefront-facing branding)
+ # terms_accepted_at : datetime — vendor ToS acceptance (store-configured rich-text ToS)
+ # holiday_mode_until : datetime, nullable — paused storefront presence ("holiday mode")
+ # payouts_schedule_interval : string, nullable — 'daily'|'weekly'|'biweekly'|'monthly'|'manual';
+ # nil ⇒ store default (store preference), matching today's
+ # "Use marketplace default interval" semantics
+
+ # Ports the legacy lifecycle (status column renamed from `state` per
+ # 6.0-normalize-state-to-status.md). Legacy allows approve/reject/suspend from most
+ # states; keep that permissiveness where operationally sane.
+ state_machine :status, initial: :pending do
+ event(:invite) { transition [:pending, :canceled] => :invited } # send — or re-send after cancel/expiry
+ event(:cancel_invite) { transition invited: :canceled } # withdrawn/expired invitation
+ event(:start_onboarding) { transition [:pending, :invited] => :onboarding } # invite accepted / application admitted
+ event(:submit_for_review) { transition onboarding: :ready_for_review }
+ event(:approve) { transition [:onboarding, :ready_for_review, :suspended, :rejected] => :approved }
+ event(:reject) { transition [:onboarding, :ready_for_review] => :rejected }
+ event(:suspend) { transition %i[onboarding ready_for_review approved rejected] => :suspended }
+ # suspension hides the vendor's catalog (legacy archives products); approve un-suspends
+ end
+
+ validates :name, :slug, presence: true, uniqueness: { scope: spree_base_uniqueness_scope }
+end
+```
+
+- **Two entry paths, one lifecycle.** (a) *Invitation*: operator creates a `pending` vendor and invites → `Spree::Invitation` (`resource: vendor`, vendor-role) → acceptance creates the `RoleUser` and fires `start_onboarding`. (b) *Self-serve application* — a public "become a seller" flow: a Store API endpoint creates a `pending` vendor + application; the operator admits into onboarding or rejects. Same state machine, no second flow.
+- **Teams** = `Spree::RoleUser` rows with `resource: vendor` and `user: Spree.admin_user_class`. Vendor admins invite teammates through the same `Invitation` rail the store admin uses. No new membership model.
+- **Authorization**: vendor users authenticate like any admin user (JWT); their ability is built from vendor-scoped permission sets whose conditions are tenancy hashes (`vendor_id: user.vendor_ids` on Product/Order/StockLocation/etc.). Record-state rules stay on models per the RBAC convention. `#13323`'s "manage permissions (via code)" = operators customize these permission sets. Port the legacy `PermissionSets::VendorUser` baseline: vendor-scoped CRUD on products/variants/prices/orders/fulfillments/stock/delivery methods/returns/exports, with writes force-stamped `vendor_id`; **no** commission management, no channel publication, no tag management, no stock-location create, no self-approve/suspend.
+- **Onboarding checklist — the registry is core, Enterprise contributes tasks.** Core ships a lightweight task registry (task key + completion check + required flag) and the core tasks: accept ToS, complete profile/branding, billing + returns addresses, at least one delivery method, at least one product. `submit_for_review` requires all required tasks complete (ports the legacy `onboarding_completed?` guard — without a checklist the guard has nothing to check, and vendors can't see what's missing). Extensions **register additional tasks** into the same registry: the monorepo Stripe gateway adds "connect your Stripe account" (Express onboarding); Enterprise adds KYC verification follow-through and Shopify/Woo store connection — the paid value is in *those tasks*, not in the tracker. The vendor dashboard and the operator's onboarding-progress view (the n/m column in today's Enterprise) both render from the registry.
+- **Storefront visibility**: only `approved` vendors (and their products) are exposed; `holiday_mode_until` in the future hides the vendor's products from sale (purchasability gate, not catalog deletion).
+
+**Columns added to existing tables** (the complete list — everything else in this plan is new tables):
+
+| Table | Column | Why |
+|---|---|---|
+| `spree_products` | `vendor_id` (nullable) | product ownership / split partition key |
+| `spree_stock_locations` | `vendor_id` (nullable) | vendor-owned stock, feeds order routing |
+| `spree_orders` | `vendor_id` (nullable), `order_group_id` (nullable) | child-order identity |
+| `spree_line_items` | `vendor_id` (nullable, denormalized) | split partition + vendor scoping without 3-join hops |
+| `spree_payments` | `order_group_id` (nullable) | the single shared payment (Decision 5) |
+| `spree_delivery_methods` | `vendor_id` (nullable) | optional vendor-scoped delivery options (see Order splitting) |
+
+Legacy vendor scoping deliberately **not** carried over: `spree_payments.vendor_id` and `spree_shipments.vendor_id` (both derivable — `PaymentSplit`/fulfillment reach the vendor through the child order), and `vendor_id` on reports + webhook subscribers (vendor-scoped reports and vendor-owned webhook subscriptions are post-6.0 dashboard/API work, not v1 schema).
+
+### Order splitting
+
+```text
+Spree::Cart (one, mixed)
+ └─ line_items (polymorphic owner = Cart) ← 6.0-cart-order-split.md
+
+ cart.complete! → Spree::Carts::Complete → splits by vendor
+ │
+ ▼
+Spree::OrderGroup (the transaction container — customer, single payment, shared addresses)
+ ├─ Spree::Order (vendor A) belongs_to :order_group, belongs_to :vendor
+ │ ├─ line_items (owner = this order) — vendor A's items
+ │ ├─ fulfillments — vendor A's fulfillment (Shipment pre-rename)
+ │ ├─ commission_lines — frozen at split
+ │ ├─ vendor_transfer — vendor A's earning, on-fulfillment (level-1 ledger)
+ │ └─ payment_split — vendor A's share of the single payment
+ ├─ Spree::Order (vendor B) …
+ └─ …
+```
+
+The `OrderGroup` owns the customer + single payment + shared addresses; each child `Order` owns its own line items, fulfillments, and totals. The group carries no vendor reference — `vendor` lives on the child order (Decision 8). Vocabulary follows `6.0-fulfillment-and-delivery.md` throughout: Fulfillment (né Shipment), DeliveryMethod (né ShippingMethod), and the ledger trigger is **on-fulfillment** — which also covers digital/instant fulfillment types (a digital vendor order fulfills, and therefore earns, immediately after payment).
+
+- **Trigger & gate:** explicit call inside `Spree::Carts::Complete`, after payment authorization. The gate is **more than one fulfillment partition** — line items partition by the `vendor_id` snapshot, with `nil` (the operator's own first-party items) forming its own partition, and the split + `OrderGroup` happen **only when ≥ 2 partitions exist**. A mixed cart of vendor A + first-party items splits into two child orders (one with `vendor_id: nil`). A single-partition cart — all first-party, or all one vendor — completes as a **bare order exactly as today**: no group, no `PaymentSplit`; when that partition is a vendor's, the order still carries `vendor_id` and commission + ledger apply unchanged (Phase 2's compute-only mode is exactly this). Not a state-machine callback — and not the legacy shape either: the legacy module splits **~30 seconds after checkout** in a background job, leaving a window where the parent order exists un-split. 6.0 splits synchronously inside completion, so the checkout response already returns the finished `OrderGroup` and no `splitted`-pending state ever exists.
+- **Partition key:** `line_item.vendor_id`, denormalized from `variant.product.vendor` when the item is added (matching legacy behavior). Denormalization is load-bearing, not an optimization: the split, vendor ability scoping, and vendor order lists all key on it. Because product ownership *can* change while an item sits in a cart, `Carts::Complete` revalidates each line's `vendor_id` against the product's current vendor before partitioning and refreshes stale lines (re-running package/delivery validation) — the same cart-revalidation class as price or availability drift.
+- **Per-vendor delivery selection happens at checkout, before the split.** Today's Enterprise checkout already groups packages by vendor and lets the customer pick a delivery method per vendor package (user docs: multi-vendor-checkout); 6.0 keeps that UX. The cart's packages come from `6.0-order-routing.md` (`for_allocation` — vendor items allocate from that vendor's stock location), delivery options per package come from `6.0-delivery-rate-provider.md` filtered to the package's vendor: a `DeliveryMethod` with `vendor_id` is offered only on that vendor's packages; `vendor_id: nil` methods are marketplace-wide. The chosen method + rate travel with the package into that vendor's child order at split. **This is a hard requirement on the cart/order-split checkout design** (see Constraints).
+- **Move semantics:** line items, their tax lines / discounts / fees (`6.0-split-adjustments.md`), fulfillment items, and fulfillments are assigned to the correct child `Order` (created from the cart partition). Stock location per child comes from the routing strategy, not a bare `detect`.
+- **Group status:** derived, not a column. The `OrderGroup` is "fully fulfilled" when all its orders are, "partially canceled" when some are, etc. — computed across `order_group.orders`, replacing the legacy `all_shipments`/`splitted?`/`cancel_parent_order` workarounds (which existed only because the legacy parent was itself an `Order`).
+
+### OrderGroup model
+
+```ruby
+# Transaction container — N orders placed together as one customer checkout.
+# Domain-neutral (Decision 8): multi-vendor is its first consumer, but it's
+# reused for split-by-location, split-by-availability, B2B split-by-company-location.
+class Spree::OrderGroup < Spree.base_class
+ include Spree::Metadata
+ has_prefix_id :ogrp
+ publishes_lifecycle_events
+
+ belongs_to :store, class_name: 'Spree::Store'
+ belongs_to :customer, class_name: Spree.customer_class.to_s, optional: true # guest groups allowed
+
+ has_many :orders, class_name: 'Spree::Order', dependent: :restrict_with_error # never cascade-delete completed orders
+ has_many :payments, class_name: 'Spree::Payment' # the single shared payment(s)
+ has_many :payment_splits, class_name: 'Spree::PaymentSplit', through: :payments
+ belongs_to :ship_address, class_name: 'Spree::Address', optional: true
+ belongs_to :bill_address, class_name: 'Spree::Address', optional: true
+
+ # number (human-facing, e.g. the cart-derived order number), currency
+ # email — guest checkouts have no customer; the group carries the contact email
+
+ # Status is DERIVED across orders, never a column:
+ def fulfillment_status; ...; end # all fulfilled / partial / pending
+ def payment_status; ...; end # paid / partial / void, aggregated from the shared payment
+end
+```
+
+The child `Order` gains `belongs_to :order_group` (optional — a plain single-vendor / single-fulfillment order has no group) and `belongs_to :vendor` (optional — non-marketplace orders have no vendor). No `parent_id`, no `splitted` status.
+
+### Split payment record (Decision 5)
+
+```ruby
+# Per-child-order bookkeeping of the ONE gateway payment. No cloned Payment rows.
+class Spree::PaymentSplit < Spree.base_class
+ has_prefix_id :paysp
+
+ belongs_to :payment, class_name: 'Spree::Payment' # the group's single gateway payment
+ belongs_to :order, class_name: 'Spree::Order' # the child (vendor) order
+
+ # authorized_amount / captured_amount / refunded_amount : decimal
+ # currency : string
+
+ extend Spree::DisplayMoney
+ money_methods :authorized_amount, :captured_amount, :refunded_amount
+end
+```
+
+Created at split, one per child order, with a **unique index on `(payment_id, order_id)`**. `authorized_amount` is the child's share of *that gateway payment* — `child.total` minus the child's allocated store-credit/gift-card coverage (allocation per Open Question 1), so a mixed store-credit checkout never overstates the gateway exposure. Captures on partial fulfillment and refunds on a child order update that child's split only. `Spree::Refund` against a grouped payment always carries the child-order context so the split, the commission reversal, and the transfer reversal reconcile against the same order (see Reversals).
+
+### Commission models
+
+```ruby
+# Snapshot line — one per commissioned line item, frozen at placement
+class Spree::CommissionLine < Spree.base_class
+ include Spree::Metadata
+ has_prefix_id :comln
+
+ belongs_to :order, class_name: 'Spree::Order'
+ belongs_to :line_item, class_name: 'Spree::LineItem', optional: true # the commissioned item…
+ belongs_to :fulfillment, class_name: 'Spree::Fulfillment', optional: true # …or the commissioned delivery (include_shipping)
+ belongs_to :vendor, class_name: 'Spree::Vendor'
+ belongs_to :commission_rate, class_name: 'Spree::CommissionRate', optional: true # nullable: rule may be deleted later
+
+ # exactly one of line_item / fulfillment is set (same pattern as TaxLine's adjustable),
+ # enforced by a model validation AND a DB CHECK constraint (num_nonnulls-style XOR)
+ validate :exactly_one_of_line_item_or_fulfillment
+
+ # snapshot fields (frozen — never recomputed)
+ # rate : decimal — the % or flat value applied, as resolved at sale time
+ # kind : string — 'percentage' | 'fixed'
+ # amount : decimal — commission charged to the vendor (the platform's fee)
+ # tax_amount : decimal — VAT/tax ON the commission (EU) — Decision 3
+ # total : decimal — amount + tax_amount
+ # currency : string
+
+ extend Spree::DisplayMoney
+ money_methods :amount, :tax_amount, :total
+end
+
+# Rate definition (mutable config) — rule-engine resolution, legacy-style defaults
+class Spree::CommissionRate < Spree.base_class
+ has_prefix_id :comrt
+ include Spree::SingleStoreResource
+ acts_as_paranoid
+
+ belongs_to :store, class_name: 'Spree::Store'
+ has_many :commission_rules, class_name: 'Spree::CommissionRule', dependent: :destroy
+
+ # name, code (unique per store), enabled (bool), priority (int)
+ # kind : string — 'percentage' | 'fixed'
+ # value : decimal — percent (e.g. 10.0) or flat amount
+ # currency : string — REQUIRED when kind == 'fixed', ignored when 'percentage' (RESOLVED)
+ # include_tax : bool — compute commission base on item gross vs net (EU default: net — Decision 3)
+ # include_shipping : bool — also commission the vendor order's delivery amounts (Decision 4)
+ # min_amount : decimal — nullable floor
+ # max_amount : decimal — nullable cap (NEW — neither reference has this; EU/fairness)
+ # commission tax: resolved via 6.0-tax-provider, not a flat column (Decision 3)
+
+ validates :code, uniqueness: { scope: spree_base_uniqueness_scope }
+ validates :currency, presence: true, if: -> { kind == 'fixed' } # flat fee needs a currency; percentage doesn't
+end
+
+# Targeting rule — grouped by subject_type: AND across dimensions, OR within one (Decision 4)
+class Spree::CommissionRule < Spree.base_class
+ belongs_to :commission_rate, class_name: 'Spree::CommissionRate'
+ belongs_to :subject, polymorphic: true, optional: true # Spree::Product | Spree::Taxon | Spree::Vendor; nil ⇒ global
+end
+```
+
+**Resolution** (`Spree::Commissions::ResolveRate` service): load enabled `CommissionRate`s for the store ordered by `priority DESC` — the currency gate applies **only to `fixed` rates** (a fixed rate must match the order currency; `percentage` rates are currency-agnostic and always pass) — and return the first whose rules match the line item: rules grouped by `subject_type`, every present group needs ≥1 match (Decision 4). A rate with no rules is the global default. Seed default rates so `product.platform_fee || vendor.platform_fee` behavior is preserved without configuration — including the legacy store-preference default (30%) as the seeded global rate. This also untangles the three legacy meanings of `platform_fee` (store preference / vendor column / product override) into one model.
+
+**Calculation** (`Spree::Commissions::CalculateLine` service) — ports the legacy per-item fee calculation, generalized:
+
+```text
+item_net = discounted item amount, ex-VAT # price − discounts, tax excluded (EU default base)
+item_gross = discounted item amount, incl. VAT # price − discounts, tax included
+base = include_tax ? item_gross_per_unit : item_net_per_unit
+per_unit = kind == 'percentage' ? (base * rate / 100) : rate
+amount = per_unit * quantity
+amount = clamp(amount, min_amount, max_amount) # NEW: max cap
+tax_amount = amount * commission_tax_rate / 100 # Decision 3 — the EU piece
+total = amount + tax_amount
+```
+
+The base is **payment-source-agnostic**: store credit / gift cards are how the customer *paid*, not a price component — they never reduce the commission base (consistent with the resolved transfer-basis decision; the legacy implementation subtracted a store-credit share from the base, and that behavior is deliberately dropped). "Net" here means *net of VAT*; discounts are always subtracted first in both bases (the vendor's commission is charged on what the customer actually paid for the item — promotions are vendor-funded in v1, see Open Questions).
+
+**Commission tax rate source (the contract `CalculateLine` consumes):** precedence is (1) an explicit `commission_tax_rate` override on the `CommissionRate`, else (2) the store's `TaxProvider` asked for the platform-service rate against the **vendor's billing address** (commission is a B2B supply to the vendor — not the consumer's ship address), else (3) a store-preference default, else 0. Missing/erroring provider lookups fall through to (3) — commission lines are written inside the split transaction and must never block checkout on a tax-service outage.
+
+**Rounding:** every persisted money field rounds **half-up to the currency's minor unit** (2 dp for most currencies, using the currency exponent — matching legacy behavior): `per_unit` after the percentage step, `amount` after quantity × clamp, `tax_amount` after the tax step; `total` is the sum of the two rounded parts, so `Σ CommissionLine` amounts always reconcile with balances and payouts to the cent.
+
+Persist one `CommissionLine` per line item on the child order, inside the split transaction. When the resolved rate has `include_shipping`, run the same calculation against the vendor order's delivery amount and persist a fulfillment-scoped `CommissionLine` alongside.
+
+### Fund ledger — two levels (Decision 9)
+
+```ruby
+# Level 1 — PER-ORDER, on-fulfillment. Credits the vendor's balance with what they earned.
+# CORE; provider-agnostic. The `system` provider records only; StripeConnect executes.
+class Spree::VendorTransfer < Spree.base_class
+ has_prefix_id :vtr
+ include Spree::RansackableAttributes
+
+ belongs_to :vendor, class_name: 'Spree::Vendor'
+ belongs_to :order, class_name: 'Spree::Order' # the child (vendor) order
+ belongs_to :payout, class_name: 'Spree::VendorPayout', optional: true # nil until settled (Decision 9 link)
+ belongs_to :reversed_from, class_name: 'Spree::VendorTransfer', optional: true
+ has_many :reversals, class_name: 'Spree::VendorTransfer', foreign_key: :reversed_from_id
+
+ # amount : decimal — vendor_order.total − commission_lines.sum(:total) (payment-source-agnostic)
+ # currency : string
+ # kind : string — 'earning' | 'refund_reversal'
+ # provider : string — 'system' | 'stripe_connect'
+ # reference: string — provider txn id (Stripe transfer id); nil for manual
+
+ state_machine :status, initial: :pending do
+ event(:process) { transition pending: :processing }
+ event(:complete) { transition [:pending, :processing] => :completed } # earned/confirmed
+ event(:fail) { transition [:pending, :processing] => :failed }
+ end
+
+ scope :completed, -> { where(status: 'completed') }
+ scope :unsettled, -> { completed.where(payout_id: nil) } # awaiting the next payout sweep
+
+ extend Spree::DisplayMoney
+ money_methods :amount
+
+ # original minus already-reversed, floored at zero (ports the legacy rule)
+ def reversible_amount; ...; end
+end
+```
+
+```ruby
+# Level 2 — PER-INTERVAL, scheduled. Batches the vendor's unsettled transfers into one
+# bank settlement and debits the balance. CORE; the `system` provider records the
+# settlement, StripeConnect performs it.
+class Spree::VendorPayout < Spree.base_class
+ has_prefix_id :vpo
+ include Spree::RansackableAttributes
+
+ belongs_to :vendor, class_name: 'Spree::Vendor'
+ has_many :transfers, class_name: 'Spree::VendorTransfer' # the transfers this payout settles
+
+ # amount : decimal — SUM(transfers.amount); set when the payout is assembled
+ # currency : string
+ # period_start / period_end : datetime — the interval this payout covers
+ # provider : string — 'system' | 'stripe_connect'
+ # reference: string — provider payout id; nil for manual
+
+ state_machine :status, initial: :pending do
+ event(:process) { transition pending: :processing }
+ event(:complete) { transition [:pending, :processing] => :completed } # manual mark-paid OR provider webhook
+ event(:fail) { transition [:pending, :processing] => :failed }
+ end
+
+ scope :owed, -> { where(status: %w[pending processing]) }
+ scope :completed, -> { where(status: 'completed') }
+
+ extend Spree::DisplayMoney
+ money_methods :amount
+end
+```
+
+`Spree::Vendor` exposes the derived bridge:
+
+```ruby
+# vendor.rb — per currency; every ledger row carries `currency`, so a multi-currency
+# store accrues separate balances and the payout sweep runs per (vendor, currency).
+def balance(currency) # what we still owe the vendor in that currency
+ vendor_transfers.completed.where(currency: currency).sum(:amount) -
+ vendor_payouts.completed.where(currency: currency).sum(:amount)
+end
+```
+
+```ruby
+# Pluggable execution strategy — CORE base + system no-op; basic StripeConnect ships
+# with the monorepo Stripe gateway (2026-07-15 amendment); Enterprise extends it.
+# Mirrors 6.0-tax-provider.md / 6.0-delivery-rate-provider.md. Two verbs, one per level.
+class Spree::PayoutProvider::Base
+ def transfer!(vendor_transfer); raise NotImplementedError; end # on-fulfillment (level 1)
+ def pay!(vendor_payout); raise NotImplementedError; end # on-interval (level 2)
+ def reverse!(vendor_transfer); raise NotImplementedError; end # refund → reverse transfer
+end
+
+# CORE default — records both ledgers, moves no money (manual/offline settlement).
+class Spree::PayoutProvider::System < Spree::PayoutProvider::Base
+ def transfer!(vendor_transfer) = vendor_transfer.complete! # earned → credits balance
+ def pay!(vendor_payout) = vendor_payout # no-op; admin marks complete manually
+ def reverse!(vendor_transfer) = vendor_transfer
+end
+
+# OSS — ships with the monorepo Stripe gateway (pulled in from the standalone
+# spree_stripe repo; payment-sessions classes only, likely spree/core): BASIC Stripe Connect.
+# Spree::PayoutProvider::StripeConnect — Express-account onboarding link + account
+# status webhook; transfer! → Stripe::Transfer with source_transaction on fulfillment
+# (ports the legacy transfer creation); pay! → Stripe's native connected-account
+# payout schedule (ports the legacy schedule mapping) + VendorPayout rows from payout
+# webhooks; reverse! → ledger-only (records the reversal, moves no money back).
+#
+# ENTERPRISE — extends the OSS provider with the money OPERATIONS (not in this repo):
+# reverse! → prorated Stripe transfer reversals (ports the legacy reversal logic) +
+# negative-balance netting against future transfers; KYC/account-health workflows;
+# ledger⇄Stripe reconciliation + payout reports. Credentials live on its
+# Spree::Integration record, same convention as external tax providers.
+```
+
+**Settlement sweep (level 2):** the scheduled job runs **per `(vendor, currency)` pair** on the vendor's `payouts_schedule_interval`: it collects that pair's unsettled transfers, creates one `VendorPayout` with `amount = Σ`, stamps each transfer's `payout_id`, and invokes `provider.pay!`. `system` leaves it `pending` for manual completion; `stripe_connect` settles and a webhook completes it.
+
+**Claim & idempotency contract:** creating the payout and stamping its transfers' `payout_id` happen in **one transaction — that stamp is the claim**; a re-run sweep only ever sees `payout_id IS NULL` transfers, so a batch can never be swept twice. `provider.pay!` must be idempotent, keyed on the payout's prefixed ID (Stripe idempotency key), so a crashed/retried invocation cannot double-pay. Failure paths: `pay!` raising → `payout.fail!` with its transfers **still stamped** — retry means re-invoking `pay!` on the *same* payout (never re-sweeping into a new one); a payout stuck in `processing` past a timeout is surfaced in the operator payouts queue for manual resolution (webhook lost vs. provider-side failure), never auto-recreated.
+
+**The same contract applies to level 1.** One `earning` transfer per vendor order — enforced by a partial unique index on `(order_id) WHERE kind = 'earning'` — so a re-fired fulfillment event finds the existing row instead of double-crediting. `provider.transfer!` is idempotent keyed on the transfer's prefixed ID, and the provider `reference` (Stripe transfer id) is unique when present: if `transfer!` succeeded externally but the record never reached `completed` (crash between API call and commit), the retry's idempotency key returns the same external transfer and the recovery path re-syncs `reference` + status rather than creating a second money movement. Ambiguous/timed-out attempts park the record in `processing` for the operator queue, same as payouts.
+
+**OSS settlement statements come free.** The ledger is exportable through the standard `Spree::Export` pipeline — a per-vendor CSV of transfers/payouts (sales − commission − commission VAT = net, plus reversals) is just an export of these tables, replacing the legacy `Spree::Reports::VendorsPayout` report. What stays Enterprise under "payout reports" is provider *reconciliation* (ledger ⇄ Stripe) and regulatory reporting (DAC7) — not the raw statement.
+
+### Reversals (refunds)
+
+The legacy module writes **reverse commission rows** when items are refunded (per returned item, plus an order-scoped prorated row for whole-order refunds) **and** reverse transfers. 6.0 keeps both, symmetric — but reversals are always **per line** (a whole-order refund reverses each line's commission exactly; the legacy order-level proration and its rounding fuzz are not carried over):
+- A refund writes a negative/`reversed` `CommissionLine` (net commission = `sum(commission_lines)`).
+- A refund writes a `refund_reversal` `VendorTransfer` linked via `reversed_from` (net earned = `sum(vendor_transfers)`). If the original transfer was already settled in a completed payout, the reversal lands in the next payout period (Decision 9).
+
+**The hook point is `Spree::Refund`.** `6.0-returns-exchanges-claims.md` funnels Return, Exchange, and Claim money movement through `Spree::Refund` — so a single subscriber on the refund event covers all three flows: it updates the child order's `PaymentSplit.refunded_amount`, writes the reverse `CommissionLine`s for the refunded items, and writes the reversal `VendorTransfer`.
+
+### Product ownership & approval
+
+- Products carry `vendor_id` (nullable — the operator's own first-party products have none). Vendor users only see/manage their own (ability tenancy condition).
+- **Approval reuses the product status workflow — no new approval model.** Vendor-created products default to `draft`; a store preference `vendor_products_require_approval` (default `true`) controls whether vendors may activate their own products or an operator must. This covers the seller product-approval workflow competing marketplaces ship, with zero new machinery, and `#13323`'s "merchandise Vendor's products" stays intact — the operator retains full edit rights over vendor products (naming, taxons, publication to channels).
+- Vendor bulk product CSV import/export rides the existing `Spree::Import` / `Spree::Export` pipeline (see `5.6-admin-spa-csv-import.md`) with the vendor context stamped on created records — no marketplace-specific importer.
+- **SKU uniqueness relaxes to per-vendor scope.** Two vendors legitimately sell the same manufacturer SKU (the legacy module disables SKU validation outright); 6.0 scopes the uniqueness check by `vendor_id` instead of dropping it.
+- "Shop by vendor" curated pages come from a vendor-subject `CollectionRule` kind (`6.0-replace-taxons-with-categories.md`), replacing the legacy `Spree::TaxonRules::Vendor`.
+
+### Vendor notifications
+
+Vendor notifications are **event-driven, with OSS mailers included** — split along the existing mailer boundary:
+
+- **Back-office emails to vendors and admins live in core**, next to the existing back-office mailers (`Spree::ExportMailer`, `Spree::ImportMailer`, `Spree::InvitationMailer`, `Spree::ReportMailer`): a `Spree::VendorMailer` ports the legacy set — vendor approved/rejected/suspended (to the vendor's team), onboarding started/submitted-for-review (to store admins), new vendor order, payout completed — wired as subscribers to the lifecycle events below. Vendor *invitations* need nothing new: they already ride core's `InvitationMailer` via the `Invitation` rail. Core-resident means vendor email works in every installation, regardless of gems.
+- **Consumer-facing emails** (e.g. the per-vendor shipment tracking emails customers receive) belong to `spree/emails` (rebuilt + modernized in 5.6, optional) — or to the storefront's own email stack via webhooks, for headless setups that own transactional email.
+
+Either way the events are the seam — subscribers/webhooks feed n8n/Slack/custom stacks, including OSS payout automation: `vendor_payout.due` → webhook → operator's banking flow → `POST /vendor_payouts/:id/complete`.
+
+Events (via `publishes_lifecycle_events` + explicit publishes): `vendor.created/updated/approved/rejected/suspended`, `order_group.completed`, per-child `order.placed` (existing), `commission_line.created`, `vendor_transfer.completed/reversed`, `vendor_payout.due/completed/failed`.
+
+### Store API surface
+
+Mirrors what the legacy v2 storefront already exposed for Enterprise (`/api/v2/storefront/vendors`), rebuilt on v3:
+
+- `GET /api/v3/store/vendors` + `GET /api/v3/store/vendors/:slug` — public profile: `name`, `slug`, `about`, `logo`, `square_logo`, `cover_photo`. Only `approved`, non-holiday vendors. No timestamps, no contact email, no financials (store-serializer rules).
+- Product serializers gain a `vendor { id, name, slug }` object (nil for first-party products); product listing accepts `q[vendor_id_eq]` — that plus the vendor profile endpoint is a complete vendor storefront page. Vendor becomes a search facet through the existing SearchProvider filter registry.
+- `POST /api/v3/store/vendor_applications` — the self-serve "become a seller" application (name, contact email, message) creating a pending vendor + owner invitation for operator review. Rate-limited, no auth required.
+- Checkout completion of a cart that split returns the **order group**: `{ order_group: { id, number, orders: [...] } }`; carts that don't split (a single partition — all one vendor, or all first-party) keep returning the bare order. Customer account history lists groups with nested per-vendor orders + per-order fulfillment tracking (today's "separate tracking per vendor" UX).
+
+### Admin API surface
+
+Endpoint list lives in `6.0-admin-api.md` → "Marketplace (new in 6.0)": vendors CRUD + `invite`/`approve`/`reject`/`suspend` (approve also un-suspends, matching the legacy machine), commission rates CRUD (nested `rules: []`, PriceList-style), read-only `commission_lines` + `vendor_transfers`, `vendor_payouts` + `POST :id/complete` (manual settlement), read-only `order_groups`. API key scopes: `read_vendors`/`write_vendors`, `read_commissions`/`write_commissions`, `read_payouts`/`write_payouts`. Vendor *users* hit the same admin API with JWT + vendor-scoped abilities — there are no separate "vendor API" routes to maintain (the legacy module's separate vendor endpoints collapse into ability scoping).
+
+## Migration Path
+
+This is **new OSS code**, not a rename of existing core — there is no in-place data migration for existing Spree stores (they have no vendors). The "migration" is twofold:
+
+1. **From the Enterprise module to core**, for existing marketplace customers. A one-time backfill rake task (shipped in Enterprise — only Enterprise has legacy data) must:
+ - For each legacy `splitted` parent order, create a `Spree::OrderGroup` and attach its `parent_id` children as the group's orders.
+ - Migrate the legacy per-item commission rows → `spree_commission_lines`. **Sign convention flips**: the legacy module stores order-level fee totals negative (load-bearing in its payout math); `CommissionLine` amounts are positive, reversals are their own negative/`reversed` rows.
+ - Decrypt the legacy encrypted vendor contact columns (ActiveRecord encryption — a multi-tenant SaaS choice) into core's plain columns.
+ - Migrate the legacy Stripe transfer ledger → `spree_vendor_transfers` (the per-order, on-fulfillment level) with `provider: 'stripe_connect'` and the Stripe transfer id in `reference`. The legacy module has no payout *records* (it delegated scheduling to Stripe), so there is nothing to backfill into `spree_vendor_payouts` — historical Stripe payouts can optionally be reconstructed from Stripe's API, or simply start fresh from the cutover.
+ The Enterprise module then becomes a thin layer on top of core's new models, deleting its splitting + commission + transfer decorators. The basic `Spree::PayoutProvider::StripeConnect` ships in the monorepo with the pulled-in Stripe gateway (2026-07-15 amendment); Enterprise extends it (clawbacks, netting, KYC ops, reconciliation) and keeps Shopify/WooCommerce.
+2. **Build order** (each phase shippable):
+ - **Phase 1 — Vendor identity.** `Spree::Vendor` model (see Vendor identity & teams: lifecycle, branding, ToS acceptance, holiday mode), onboarding task registry + core tasks, vendor teams via `RoleUser`/`Invitation` (`resource: vendor`), self-serve application endpoint, core `Spree::VendorMailer` lifecycle emails (see Vendor notifications), product ownership (`products.vendor_id` + approval preference), Admin API Marketplace/vendors endpoints + Store API vendor profiles, vendor CSV import/export on the `Spree::Import` pipeline. No splitting yet.
+ - **Phase 2 — Commission engine.** `CommissionRate` + `CommissionRule` + `CommissionLine`, resolution + calculation services (dimension-grouped matching, min/max clamps, `include_shipping`), commission-tax field, admin UI for rates. Compute-only (attach to single-vendor orders, no split).
+ - **Phase 3 — Order splitting + fund ledger.** `OrderGroup`, `Carts::SplitByVendor` inside `Carts::Complete`, per-vendor delivery selection at checkout, `PaymentSplit`, derived group status, reversals, the two-level `VendorTransfer` (on-fulfillment) + `VendorPayout` (scheduled sweep) + `PayoutProvider::System` + `vendor.balance(currency)`. **Gated on `6.0-cart-order-split.md` and `6.0-split-adjustments.md` landing first** — and cart-order-split is today a one-page stub: it must be expanded (checkout/delivery-selection/payment flow on Cart) before this phase's design can freeze. Flagging early: the 6.0 headline feature sits downstream of the two biggest unstarted refactors.
+ - **Phase 3b — OSS Stripe provider** (after Phase 3, alongside the Stripe gateway pull-in: the payment-sessions-API gateway classes come into the monorepo from the standalone `spree_stripe` repo, likely into `spree/core`, leaving the legacy v2-API/storefront code behind): Express onboarding link in the vendor dashboard, `account.updated` status webhook, `transfer!` on fulfillment with `source_transaction`, payout-schedule mapping + payout webhooks. Ledger-only `reverse!`.
+ - **Phase 4 — Dashboards.** (a) Operator marketplace screens in `@spree/dashboard`: Vendors list/detail (lifecycle actions, branding, commission + payout settings, ledger-derived lifetime revenue/commission), Commission Rates settings page, Payouts review queue (owed balances, itemized payouts, mark-paid), OrderGroup rendering on order screens, and a "needs attention" queue on the dashboard home (vendors `ready_for_review` + pending vendor products — a lightweight unified review inbox). (b) Vendor panel: compose `@spree/dashboard-ui` + `@spree/dashboard-core` into a vendor-scoped panel (per `6.0-admin-spa.md` — the package split exists precisely for this). Permissions via code. Surfaces the vendor's products, orders + fulfillment actions, and the balance + transfer/payout ledger (earned/settled) read-only for OSS.
+
+ **Phases 1–2 have no dependency on the Cart/Order split** — they can be built (even shipped behind a preview flag in a 5.x release) while the split refactor lands, de-risking the 6.0 timeline.
+
+## Constraints on Current Work
+
+Even before this lands, work touching adjacent areas should:
+
+- **Cart/Order split (`6.0-cart-order-split.md`)**: keep `cart.complete!`/`Spree::Carts::Complete` as the single completion entry point — the vendor split hooks in there. Do not reintroduce an order-level `after_transition` extension surface; multi-vendor must not depend on one. When fleshing out the checkout flow on Cart, design delivery selection **per package** (packages come from order routing) — the multi-vendor checkout needs one delivery choice per vendor package before completion, and payments must be attachable to an `OrderGroup`, not only to an `Order`.
+- **Split adjustments (`6.0-split-adjustments.md`)**: keep `TaxLine`/`Discount`/`Fee` strictly line-item- or fulfillment-attached (already the resolved design — order-level discounts distribute to line items) so every adjustment re-homes unambiguously to one child order during the split. Do **not** add a commission/marketplace `Fee` kind — commission is `Spree::CommissionLine`, off-order (Decision 2); `Fee` stays buyer-facing.
+- **Inventory operations (`6.0-inventory-operations.md`)**: the procurement model is `Spree::Supplier` — never reuse `Spree::Vendor` (reserved for marketplace sellers) for purchase-order sources. See `decisions.md` 2026-07-14.
+- **External-store sync stays Enterprise**: do **not** add external store/resource models, associations, or callbacks to core (no `external_store` on Vendor, no external product/order/category tables, no platform sync hooks). The Shopify/WooCommerce connection layer is an Enterprise concern that decorates core's Vendor from outside; core only needs to stay decorable (events + the onboarding task registry are the seams it plugs into).
+- **Fulfillment & delivery (`6.0-fulfillment-and-delivery.md`)**: the ledger trigger is defined against Fulfillment ("all fulfillments fulfilled"), and `DeliveryMethod` gets an optional `vendor_id` — keep the fulfillment-status surface queryable per order (child orders fulfill independently) and don't assume one order per checkout in fulfillment UIs.
+- **Order routing (`6.0-order-routing.md`)**: the per-child stock-location decision must come from the routing strategy, so a vendor's items allocate from that vendor's stock location. Keep `for_allocation` vendor-aware-friendly (it already takes `order:`).
+- **Tax provider (`6.0-tax-provider.md`)** and **Delivery rate provider (`6.0-delivery-rate-provider.md`)**: the `PayoutProvider` follows the same pluggable-strategy shape — keep the provider-registration convention consistent so all three (tax, delivery rate, payout) register and resolve the same way.
+- **Admin API (`6.0-admin-api.md`)**: the `Vendor` prefix is `ven_` (matches legacy `has_prefix_id :ven`). The "Marketplace (new in 6.0)" endpoint group there is this plan's API surface — keep it in sync.
+- Do **not** revive the legacy commission model's shape (label-based rows + denormalized fee totals on the order), do **not** model commission as a polymorphic `Adjustment`, and do **not** write commission as a `Spree::Fee` (fees are buyer-facing and roll into order totals — Decision 2) — 6.0 uses the off-order `Spree::CommissionLine` ledger. Do **not** put the fund ledger in a payment-gateway namespace (the legacy gateway-namespaced-transfer mistake) nor collapse transfer and payout into one model — `Spree::VendorTransfer` (on-fulfillment) and `Spree::VendorPayout` (scheduled) are both core and provider-agnostic.
+
+## Resolved Decisions
+
+- **Basic Stripe Connect execution → OSS (boundary amendment)** (RESOLVED 2026-07-15). Express onboarding + on-fulfillment transfers ship in the monorepo alongside the pulled-in Stripe gateway, for demo/adoption parity with the surveyed competitor — "money moves automatically" is the demo that sells, and transfers are inseparable from basic onboarding (a `Stripe::Transfer` needs a connected account). Enterprise repositions on money **operations**: automatic refund clawbacks (prorated transfer reversals + negative-balance netting), KYC/account-health workflows, ledger⇄Stripe reconciliation, payout reports incl. DAC7, facilitator taxes. Ledger reversal rows stay OSS in every mode — only the pullback execution is paid. Supersedes #13323's "execution stays Enterprise" framing (amendment by the issue author; update the issue). See `decisions.md` 2026-07-15.
+- **`Spree::Vendor` name ownership → marketplace seller; inventory-operations' procurement model renamed `Spree::Supplier`** (RESOLVED 2026-07-14). See the Key Decisions entry and `decisions.md` 2026-07-14.
+- **Commission is not a `Spree::Fee`** (RESOLVED 2026-07-14). `Fee` is buyer-facing and rolls into order totals; `CommissionLine` is an off-order platform↔vendor ledger. See Decision 2.
+- **Commission rule matching → dimension-grouped (AND across subject types, OR within one)** (RESOLVED 2026-07-14). Expresses plain lists and the vendor × taxon pairings today's Enterprise sells, with no `match_policy` knob; same semantics as the leading surveyed OSS engine, but precedence stays explicit operator `priority` rather than implicit specificity. See Decision 4.
+- **Commission on delivery revenue → `include_shipping` on the rate** (RESOLVED 2026-07-14). Per-rate flag, default off (legacy was items-only); a fulfillment-scoped `CommissionLine` (nullable `fulfillment_id`, exactly-one-of with `line_item_id`). Matches the surveyed OSS competitor (global-only there) and Amazon referral-fee behavior. See Decision 4.
+- **Split payment record → `Spree::PaymentSplit` + `payments.order_group_id`** (RESOLVED 2026-07-14). One gateway payment on the group, one split row per child order; no cloned `Payment` rows. See Decision 5 + Design Details.
+- **Vendor teams → reuse `Role`/`RoleUser`/`Invitation` with `resource: vendor`** (RESOLVED 2026-07-14). The polymorphic rails already exist in core (Invitation's docstring names Vendor); no `VendorUser` model. See Vendor identity & teams.
+- **Parent representation → dedicated `Spree::OrderGroup`** (RESOLVED 2026-06-16). See Decision 8 + Design Details. Diverges from the legacy `parent_id`/`splitted` shape; requires the Enterprise backfill.
+- **Commission tax rate source → per-`CommissionRate` field, resolved through the `TaxProvider`** (RESOLVED 2026-06-16). Not a per-vendor `platform_fee_tax_rate` column (legacy) and not a bare per-market lookup. The rate carries its own commission-tax configuration with a sensible store default; the actual rate is resolved via `6.0-tax-provider.md` so it stays jurisdiction-correct. See Decision 3.
+- **Fund ledger → two levels: `Spree::VendorTransfer` (per-order, on-fulfillment) + `Spree::VendorPayout` (per-interval settlement), both generic in core + pluggable `PayoutProvider` (system no-op in core; basic StripeConnect with the monorepo Stripe gateway per the 2026-07-15 amendment, extended by Enterprise with the money operations)** (RESOLVED 2026-06-25). See Decision 9. Transfer credits the vendor balance on fulfillment; payout sweeps unsettled transfers into a scheduled bank settlement (transfers `belong_to` their payout — auditable). `vendor.balance(currency) = Σ completed transfers − Σ completed payouts` per currency. Splits the legacy gateway-namespaced transfer ledger (which conflated the two and outsourced settlement to Stripe) into core ledger + provider execution along the OSS/Enterprise seam.
+- **Commission VAT base → net item price, VAT added on top of the fee** (RESOLVED 2026-06-25). For EU, commission is computed on the seller's **net (ex-VAT)** item price; the commission `tax_amount` (Decision 3) is then applied **on top of the commission** as a separate B2B service supply — the marketplace fee is a distinct taxable event from the consumer's item sale, so the two VATs never mix. The `include_tax` toggle stays available for non-EU/edge merchants who genuinely want a gross base, but the EU default is net-base + fee-VAT. This makes the marketplace's commission invoice to the seller stand on its own (correct for EU invoicing + remittance).
+- **Store-credit/gift-card payout → payment-source-agnostic** (RESOLVED 2026-06-25). The `VendorTransfer` amount (which rolls up into the payout) is `(vendor's sale value) − (commission owed)`, **independent of how the customer paid**. Store credit / gift cards are the platform's funding concern, not the vendor's — the vendor is owed their full cut of the sale regardless. This **drops the legacy store-credit dual-basis** from the amount calculation; that branch existed only to reconcile the old store-credit funding model and does not belong in the payout basis. (The platform still tracks its own store-credit liability separately — that's orthogonal to what the vendor receives.)
+- **Commission precedence → integer priority + seeded defaults** (RESOLVED 2026-06-25). `CommissionRate.priority` is operator-assignable, walked `DESC`, first match wins (Decision 4). Core **seeds default priorities** so a product-scoped rate beats a vendor-scoped rate out of the box — simple merchants never touch the knob; advanced merchants reorder freely. No hardcoded semantic ladder.
+- **Commission rate currency → required for fixed, ignored for percentage** (RESOLVED 2026-06-25). A `kind: 'fixed'` rate **must** carry a `currency` (a flat "2" is meaningless without one); a `kind: 'percentage'` rate ignores currency (10% applies in any currency). Enforced by a model validation: `validates :currency, presence: true, if: -> { kind == 'fixed' }`. See the `CommissionRate` model.
+- **Payout vs transfer trigger → transfer on-fulfillment, payout on-interval** (RESOLVED 2026-06-25). These are the two distinct events of Decision 9: a `VendorTransfer` becomes due **on-fulfillment** (the vendor earned it); a `VendorPayout` settles on the vendor's **scheduled interval** (`payouts_schedule_interval`). The earlier "on-ship vs on-deliver vs scheduled" framing was a category error — it conflated the two. Core's `system` provider honors `manual` settlement natively; Enterprise implements daily/weekly/biweekly/monthly.
+
+## Open Questions
+
+1. **Store credit / gift card split across vendors.** The references and the legacy module prorate store credit across child orders. Confirm this survives the 6.0 store-credit model and the `Carts::Complete` flow. (Distinct from the resolved transfer-basis decision — this is about *which child order* a store-credit payment is attributed to during the split, not about the transfer amount, which is now payment-source-agnostic.)
+2. **Payout holdback / minimum threshold.** Real marketplaces hold a rolling reserve (refund/chargeback buffer) and skip sub-threshold payouts (`minimum_payout_amount`, "carry balances under €50 to the next period"). Both are easy columns on Vendor + guards in the sweep job — decide whether v1 core ships them or they start as Enterprise policy.
+3. **Marketplace-facilitator tax remittance.** US marketplace-facilitator laws (and EU deemed-supplier rules for some scenarios) make the *platform* remit consumer tax, which changes the transfer basis to `total − tax_total − commission`. Currently parked as Enterprise "automatic taxes" — confirm core doesn't need at least a `tax_remittance: vendor|platform` flag on Vendor so the ledger math is provider-independent.
+4. **Vendor-funded vs platform-funded promotions.** v1: discounts reduce the vendor's sale value (vendor-funded). Platform-funded promos ("we run a 10% site-wide sale and make vendors whole") need a funding flag on Promotion and a compensating ledger line — post-6.0.
+5. **Vendor-scoped promotions.** Can a vendor create promotions limited to their own products (the surveyed OSS competitor supports seller promotions)? Requires `promotions.vendor_id` + ability scoping + a guard that vendor promos only match their line items. Lean post-6.0; cheap to add on the single-store Promotion model.
+
+## References
+
+- [spree/spree#13323](https://github.com/spree/spree/issues/13323) — "Open source Spree Multi Vendor for Spree 6" (the OSS/Enterprise scope split; amended 2026-07-15 — basic Stripe Connect execution moved to OSS, see `decisions.md`; the issue text needs a matching update).
+- Current Enterprise multi-vendor module (private source, actively maintained against Spree 5.4+): source-read for this port — the Vendor lifecycle, per-item commission + commission-VAT formula, parent/child split flow, Stripe transfer ledger + reversal chain, vendor-user permission baseline, and the settlement-statement report. **Internals (file paths, class/table names) are deliberately not cited in this public file** — the Enterprise repository holds the detailed port map. Public behavior cross-checked against the user docs (next bullet).
+- Surveyed modern open-source marketplace implementations (primary-source survey 2026-07-14; names and the detailed comparison deliberately kept out of this public file): source of the commission rule-engine shape (dimension-grouped matching, `percentage | fixed`, `include_tax`/`include_shipping`), the `OrderGroup` container pattern, and the payout-provider abstraction. **Framework-specific machinery NOT to copy:** big-number jsonb sidecar columns, remote-link join-table indirection (use Rails FKs + `has_many`), and external workflow/step engines (use Spree services + `publish_event`). The leading implementation's payout pipeline creates per-order payouts after capture and keeps no balance ledger and no reversal chain — Spree's two-level ledger is designed from scratch.
+- Current Enterprise behavior (user docs, spreecommerce.org/docs): `user/vendors/vendor-management` (lifecycle: Invited → Onboarding → Ready for Review → Approved/Rejected/Suspended; branding; onboarding checklist), `user/vendors/commission-rates` (product > vendor > marketplace-default ladder, category-vendor pairing), `user/vendors/vendor-payouts` (schedule intervals incl. bi-weekly + "use marketplace default"), `user/vendors/multi-vendor-checkout` (per-vendor delivery selection, suborder split, per-vendor tracking), `user/settings/marketplace` (default rate copied at invite, vendor ToS), `api-reference/storefront/vendors` (public vendor profile fields).
+- Related plans: `6.0-cart-order-split.md`, `6.0-split-adjustments.md`, `6.0-order-routing.md`, `6.0-tax-provider.md`, `6.0-delivery-rate-provider.md`, `6.0-fulfillment-and-delivery.md`, `6.0-returns-exchanges-claims.md`, `6.0-inventory-operations.md` (Supplier disambiguation), `5.4-6.0-eu-legal-compliance.md`, `5.6-admin-spa-csv-import.md`, `6.0-admin-spa.md`, `6.0-admin-api.md`, `6.0-channels-catalogs-b2b.md` (B2B — deferred to 6.1, see `decisions.md`).
diff --git a/docs/plans/decisions.md b/docs/plans/decisions.md
index 63f55bd72e..6189ff756a 100644
--- a/docs/plans/decisions.md
+++ b/docs/plans/decisions.md
@@ -1,3 +1,71 @@
+## 2026-07-15: Basic Stripe Connect payouts move to OSS; Enterprise repositions on money operations
+
+spree/spree#13323 originally kept "Stripe Connect onboarding, KYC, automatic
+payouts" in Enterprise. Amended by the issue author: the **basic** Stripe Connect
+path ships **open-source in the monorepo**, registering
+`Spree::PayoutProvider::StripeConnect` — Express-account onboarding (hosted link +
+`account.updated` status webhook) and on-fulfillment `Stripe::Transfer` execution
+(`source_transaction`-tied), plus mapping the vendor payout schedule onto Stripe's
+native schedule. It lands alongside the Stripe core gateway being pulled into the
+monorepo from the standalone `spree_stripe` repo — only the payment-sessions-API
+gateway classes come over (likely into `spree/core`); the legacy v2-API/storefront
+code in that repo stays behind.
+
+Rationale: the closest OSS competitor ships baseline Stripe transfers free —
+"money moves automatically" is the demo that sells — and transfers are inseparable
+from basic onboarding (a `Stripe::Transfer` requires a connected account), so a
+transfers-only OSS cut was never buildable.
+
+Enterprise keeps the money **operations**: automatic refund clawbacks (prorated
+transfer reversals + negative-balance netting), KYC/account-health workflows beyond
+hosted onboarding, ledger⇄Stripe reconciliation, payout reports incl. DAC7,
+marketplace-facilitator taxes, and the Shopify/WooCommerce vendor apps. Ledger
+correctness (reversal rows) stays OSS in every mode — only pullback execution is
+paid. "Core runs the happy path; Enterprise operates the unhappy paths and
+compliance at scale." #13323 to be updated accordingly.
+Plan: `6.0-multi-vendor-marketplace.md`.
+
+## 2026-07-14: `Spree::Vendor` = marketplace seller; procurement source renamed `Spree::Supplier`
+
+Two 6.0 plans introduced a `Spree::Vendor`: the marketplace seller
+(`6.0-multi-vendor-marketplace.md`, prefix `ven_`) and the purchase-order
+procurement source (`6.0-inventory-operations.md`, prefix `vnd_`). Same class
+name, same `spree_vendors` table, different domains — a hard collision.
+
+Resolution: **the marketplace owns the `Vendor` name.** It is locked publicly
+(spree/spree#13323, the user docs' "Vendors" area, the legacy Enterprise gem's
+`ven_` prefix and its production data). The inventory-operations model is renamed
+**`Spree::Supplier`** (`spree_suppliers`, prefix `sup_`, `/api/v3/admin/suppliers`) —
+matching Shopify's purchase-order vocabulary and standard ERP terminology. They
+are different lifecycles: a supplier is an address-book entry the merchant buys
+stock from; a vendor is an onboarded selling party with users, commission, and
+payouts.
+
+Hybrid marketplaces (operator buys wholesale from a marketplace seller and
+resells first-party) can later bridge the two with an optional
+`Spree::Supplier#vendor_id` link — not scoped for 6.0.
+
+## 2026-06-16: Split 6.0 into Marketplace, defer B2B to 6.1
+
+6.0 is themed as the **Marketplace release**, headlined by open-sourcing the
+multi-vendor marketplace (per spree/spree#13323) alongside React dashboard GA and
+the architecture/rename wave. B2B (Catalog + Company/CompanyLocation/CompanyContact
+from `6.0-channels-catalogs-b2b.md` Phase 2) moves to **6.1**, marketed as the B2B
+release. Rationale: a crowded 6.0 dilutes the launch; one sharp headline per release
+earns more buzz, and the B2B Phase 2 work is plan-only (not started), so deferring
+it frees capacity for the multi-vendor open-sourcing rather than parking finished code.
+
+Multi-vendor OSS/Enterprise boundary per #13323 as of this date (**superseded in
+part by 2026-07-15 above** — basic Stripe Connect execution later moved to OSS):
+core ships Vendor identity, order splitting, the commission engine (with EU
+commission taxation), the payout ledger (`Spree::VendorPayout` — records what's
+owed, provider-agnostic), vendor dashboard, CSV import/export, and Vendors API;
+Enterprise keeps Stripe Connect/KYC and the *execution* of payouts (a
+`PayoutProvider::StripeConnect` strategy), payout reports, Shopify/WooCommerce
+sales-channel apps, and the category mapper. New plan:
+`6.0-multi-vendor-marketplace.md`. The legacy Enterprise multi-vendor module is
+rebuilt as native core models on top of the 6.0 Cart/Order split.
+
## 2026-03-17: Rename StockItem → StockLevel
`Spree::StockItem` → `Spree::StockLevel`, `spree_stock_items` → `spree_stock_levels`.
Prefix ID: `si_` → `sl_`.