Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Settle the marketplace vendor principal and API surface (#14446)
Damian Legawiecfae507176325
diff --git a/CLAUDE.md b/CLAUDE.mdindex 83f657f7ad..58c3bd5f61 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -12,7 +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-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. **Vendor principal + surface (Decision 10, 2026-08-15):** vendor staff are `Spree.admin_user_class` (no `VendorUser`; membership by `RoleUser.resource_type`, never `store_id`) on a dedicated `/api/v3/vendor` branch — own `vendor_api` JWT audience, own `Spree.vendor_authentication_strategies` + `/vendor/auth/*`, audience-stamped refresh tokens, every endpoint scope-fetched through `current_vendor` (store derived from the vendor); vendors never call the Admin API and admin controllers are never subclassed into the vendor namespace.- `6.0-cart-order-split.md` — Cart/Order model separation, dual-FK owner everywhere (`cart_id`/`order_id` exactly-one, `#owner` as method — NOT polymorphic), idempotent copy-on-completion (`Order#cart_id` unique, order-before-payment), Order state machine removed (Checkout::Requirements for steps; payment/fulfillment statuses derived-then-persisted via one recompute service). **Shipped to 6-0-dev (feature/6-0-core-rewrite Waves 1+5):** Cart owns checkout end to end, machine + `spree_orders.state` gone, `Carts::Complete` three-phase pipeline live, `Orders::UpdateStatuses` sole status writer; only Wave 7 data migration (incomplete orders → carts) remains- `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 mappingdiff --git a/docs/plans/6.0-admin-api.md b/docs/plans/6.0-admin-api.mdindex 8f56d1ec67..b16c0bebb8 100644--- a/docs/plans/6.0-admin-api.md+++ b/docs/plans/6.0-admin-api.md@@ -713,6 +713,8 @@ Per `6.0-multi-vendor-marketplace.md`. Vendor prefix is `ven_` (matches the legaAPI key scopes: `read_vendors` / `write_vendors`, `read_commissions` / `write_commissions`, `read_payouts` / `write_payouts`.+> **Operator surface only (2026-08-15).** Vendor *users* never call the Admin API. They are `Spree::AdminUser` accounts signing in through a dedicated **`/api/v3/vendor`** branch with its own `vendor_api` JWT audience and login registry, where every endpoint scope-fetches through `current_vendor`; the vendor endpoint list and serializer rules live in `6.0-multi-vendor-marketplace.md` → "Vendor API surface" (Decision 10, `decisions.md` 2026-08-15).+### Price Lists- [x] `GET /api/v3/admin/price_lists`- [x] `GET /api/v3/admin/price_lists/:id`diff --git a/docs/plans/6.0-admin-rbac.md b/docs/plans/6.0-admin-rbac.mdindex a8eff3234c..a259cb2b3b 100644--- a/docs/plans/6.0-admin-rbac.md+++ b/docs/plans/6.0-admin-rbac.md@@ -527,7 +527,14 @@ all resolved 2026-08-07 and live in Key Decisions. Genuinely deferred:vendor-side ability that reads those assignments.Surface and enforcement ship with `6.0-multi-vendor-marketplace.md`, not- here.+ here. **Settled there 2026-08-15 (Decision 10):** vendor staff are+ `Spree.admin_user_class` (no `VendorUser`), the surface is a dedicated+ `/api/v3/vendor` branch with its own `vendor_api` JWT audience, its own+ strategy registry and audience-stamped refresh tokens, and the vendor-side+ ability is `Spree::Ability` with a `resource:` option reading+ `resource: vendor` assignments. One follow-up lands on this plan's code:+ `AdminAuthentication#current_user_member_of_store?` must match+ `resource_type: 'Spree::Store'` like `staff_roles` and `RoleGrantGuard` do.- **Audit trail for role/permission changes** — rides a future admin audit-logfeature; not blocking the editor.- **CanCanCan-free admin path** — becomes possible once nothing public speaksdiff --git a/docs/plans/6.0-multi-vendor-marketplace.md b/docs/plans/6.0-multi-vendor-marketplace.mdindex 128ec23665..1968992629 100644--- a/docs/plans/6.0-multi-vendor-marketplace.md+++ b/docs/plans/6.0-multi-vendor-marketplace.md@@ -1,10 +1,10 @@# Multi-Vendor Marketplace (Open Source Core)-**Status:** Draft — design in progress, implementation not started+**Status:** Design complete (2026-08-15 — auth/API surface + the last blocking questions settled), implementation not started**Target:** Spree 6.0 (the "Marketplace" release)-**Depends on:** `6.0-cart-order-split.md` (Cart/Order split + dual-FK `LineItem` owner (`cart_id`/`order_id`, `#owner` method) — **expanded 2026-07-27; Phase 3 design can now freeze against it**), `6.0-6.1-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)+**Depends on:** `6.0-cart-order-split.md` (Cart/Order split + dual-FK `LineItem` owner (`cart_id`/`order_id`, `#owner` method) — **expanded 2026-07-27; Phase 3 design can now freeze against it**), `6.0-6.1-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), `6.0-platform-auth.md` (`Spree::AdminUser` is the vendor principal; strategy registries + JWT audiences — shipped in PR #14380), `6.0-admin-rbac.md` (permission catalog, `RoleUser` resource typing, vendor audience direction — shipped in PR #14412)**Author:** Damian + Claude-**Last updated:** 2026-07-27+**Last updated:** 2026-08-15## Summary@@ -95,7 +95,7 @@ Confirmed by the references and the legacy module (its split moves line items, aThe 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).+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` hooks (`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 `current_vendor` scope-fetching on a dedicated Vendor API branch (Decision 10 — not ability-level scoping, which the RBAC catalog cannot express).### 8. The parent is a dedicated `Spree::OrderGroup`, not `Order#parent_id` (RESOLVED 2026-06-16)@@ -144,7 +144,7 @@ Both levels are **generic in core + provider-executed**, mirroring `6.0-tax-provtransfer.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).+`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 selected per vendor by `spree_vendors.tax_remittance` (`vendor` | `platform`, default `vendor`; RESOLVED 2026-08-15): core owns both branches of the math so the ledger stays provider-independent, while *deciding* that a vendor is platform-remitted (nexus, deemed-supplier rules) is Enterprise "automatic taxes" territory (see the scope table).**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`.@@ -152,6 +152,24 @@ transfer.amount = vendor_order.total − vendor_order.commission_lines.sum(:tota**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.+### 10. Vendor users are `Spree::AdminUser`, on a dedicated `/api/v3/vendor` API branch with its own JWT audience and login registry (RESOLVED 2026-08-15)++Two questions were re-examined against the shipped auth (PR #14380) and RBAC (PR #14412) work — should vendor staff be a separate user model, and should they use the Admin API with narrower permissions or their own routes. Both settled the same way: **reuse the principal, separate the surface.**++**Principal — `Spree.admin_user_class`, no `VendorUser` model.** The platform is two-principal after #14380: `Customer` buys, `AdminUser` operates a back office — and a vendor's team operates a back office. That one class now carries the entire auth stack (`has_secure_password`, lockout, password policy, `generates_token_for :password_reset`, `UserIdentity` SSO linking, invitation acceptance, refresh-token cookie flow); a third principal would duplicate every one of those (and every future MFA/passkey improvement) as a second security surface. The RBAC rails already assume it: `RoleUser` (`user: Spree.admin_user_class`, `resource: vendor`, store binding derived from the vendor), `Invitation` (`resource: vendor`), and `Spree::Ability#staff_roles` deliberately excluding vendor-resourced assignments as belonging to "their own panel's ability". One human, one login, several hats: an `AdminUser` may hold a store role and a vendor role at once (the operator's own first-party seller; a merchant selling on two marketplaces run on two stores). A vendor member is **not** store staff — membership is by *resource type*, never by `store_id`.++**Surface — a third v3 branch, `/api/v3/vendor/…`, beside `store` and `admin`.** The plan's earlier line ("vendor users hit the same admin API with vendor-scoped abilities — no separate vendor routes") is superseded: it relied on `PermissionSets::VendorUser` with `vendor_id: user.vendor_ids` hash conditions, and #14412 removed permission sets with no bridge — the catalog is flat `read_*`/`write_*` keys with no conditions, and the RBAC plan already re-decided on 2026-08-08 that "vendor-panel endpoints scope-fetch through `current_vendor` exactly as admin endpoints scope through `current_store`". Reusing the ~300 admin endpoints would mean per-principal forks in every `scope`/`find_resource`/incidental lookup (`stock_location_id`, `reason_id`, `variant_id` on line-item writes) — each miss a cross-vendor read or write inside the same store — plus per-principal field masking in serializers. A vendor branch is ~20 controllers, each written scope-first (`current_vendor.products`, `current_vendor.orders`, …): **IDOR by construction**, the same way store isolation works on the admin branch today (controller scoping only — the ability layer has no tenancy conditions). What a vendor may not do (publish to channels, edit orders, refund, approve itself, create stock locations) is an endpoint that does not exist, not an ability rule. Do **not** subclass admin controllers into the vendor namespace — inherited `current_store.*` lookups are precisely the leak; share workflows and permitted-param lists, never controllers.++**Isolation is enforced at the token layer, not only at membership.** Three requirements, all mandatory (they answer the two concrete objections to a shared model — "staff must be SSO-only while vendors use passwords" and "what happens when a vendor token hits the Admin API"):++1. **Own JWT audience** — `JWT_AUDIENCE_VENDOR = 'vendor_api'` beside `store_api`/`admin_api`. The admin branch rejects a vendor token at `decode_jwt` (`verify_aud`) with 401 before any store resolution, membership check, or ability is built, and the vendor branch rejects admin tokens symmetrically. Fail-closed at the outermost layer; the `resource_type` filters below remain defense in depth.+2. **Own login surface** — `Spree.vendor_authentication_strategies` (default: `:email` only) + `/api/v3/vendor/auth/{login,refresh,logout,password_reset}`. Login policy is per surface, not per class: an SSO-only store keeps `Spree.admin_authentication_strategies.remove(:email)` while vendors sign in with passwords, against the same `AdminUser` table. The vendor login **refuses anyone with no vendor membership** (`role_users` on `resource: vendor`), the same "unprovisioned subject is rejected" rule the admin SSO callback applies — so a staff-only account cannot mint a token here, and a token it *could* mint carries the vendor audience anyway.+3. **Refresh tokens carry the audience** — `spree_refresh_tokens.audience` (string), written at mint and enforced on refresh, with a separate cookie name/path for the vendor panel. Today's `RefreshToken` has no audience, so without this a vendor-minted refresh token could be presented to the admin refresh endpoint and exchanged for an `admin_api` JWT.++**Accepted trade-offs:** password policy and lockout stay model-level and therefore shared between staff and vendors (desired — a vendor account locks out too; a stricter *staff-only* policy is a per-surface login concern, like MFA later). Thin controllers are duplicated across the admin and vendor branches; that duplication is the price of an auditable tenancy boundary.++**Cross-plan obligation (admin branch, ship ahead of Phase 1):** `AdminAuthentication#current_user_member_of_store?` matches `role_users.exists?(store: current_store)`, which a vendor-resourced assignment passes (its store is the vendor's store) — the Ability then yields no keys so scoped endpoints 403, but the scope-exempt ones (`/admin/tags`, `/admin/store` show, exports/imports index, translation batches) are reachable. Tighten to `resource_type: 'Spree::Store'`, mirroring `Ability#staff_roles` and `RoleGrantGuard`, with a regression spec.+## Design Details### Vendor identity & teams@@ -192,6 +210,10 @@ class Spree::Vendor < Spree.base_class# payouts_schedule_interval : string, nullable — 'daily'|'weekly'|'biweekly'|'monthly'|'manual';# nil ⇒ store default (store preference), matching today's# "Use marketplace default interval" semantics+ # minimum_payout_amount : decimal, nullable — sub-threshold balances carry to the next period;+ # nil ⇒ store preference default_minimum_payout_amount (RESOLVED 2026-08-15)+ # tax_remittance : string — 'vendor' (default) | 'platform'; selects the transfer basis (Decision 9;+ # RESOLVED 2026-08-15). Enterprise 'automatic taxes' sets it; core only reads it# Ports the legacy lifecycle (status column renamed from `state` per# 6.0-normalize-state-to-status.md). Legacy allows approve/reject/suspend from most@@ -213,7 +235,11 @@ 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.+- **Authorization** (rewritten 2026-08-15 for the shipped RBAC — Decision 10): vendor users are `Spree.admin_user_class` and sign in through the vendor login surface (own strategy registry, own `vendor_api` JWT audience). Authorization on the Vendor API branch is the same two-axis model the admin branch uses:+ - *Tenancy* is controller scoping — every vendor endpoint scope-fetches through `current_vendor` (resolved from `X-Spree-Vendor-Id` + a `role_users` membership check on `resource: vendor`; `current_store` is **derived** from `current_vendor.store`, never taken from a header). Writes are force-stamped `vendor_id`. Nothing tenancy-related lives in the ability.+ - *Capability* is the permission catalog — the same `read_*`/`write_*` vocabulary, through the same `ScopedAuthorization` key gate. Adopts the RBAC plan's settled direction: `Role#audience` (`staff` | `vendor`); a **vendor-grantable catalog subset** marked at `register_resource` (products, orders, fulfillments, stock, returns, exports/imports, analytics — never `settings`, `staff`, `api_keys`, commissions); the roles editor filters its grid by audience; assignment and invitation guards pair audience with resource type. Vendor roles are defined by the operator (role names are globally unique — vendors assign their people to tiers, they do not define roles). Two vendor-only catalog resources: `vendor_profile` (own profile, branding, addresses, onboarding tasks) and read-only `payouts` (the vendor's ledger view). `Spree::Ability` gains a `resource:` option (default the store) so the vendor branch builds its ability from `role_users` where `resource: current_vendor` — the "vendor-side ability" the RBAC plan deferred here.+ - The legacy `PermissionSets::VendorUser` baseline survives only as the **seeded default vendor role's key set** (`write_products`, `write_orders`, `write_fulfillments`, `write_stock`, `write_returns`, `write_exports`, `write_vendor_profile`, `read_payouts`). "No commission management / no channel publication / no self-approve / no stock-location create" are endpoints that do not exist on the vendor branch, not ability rules. `#13323`'s "manage permissions (via code)" = seeds or the roles API, per the RBAC plan.+ - `Spree::UserRoles` gains `has_many :vendors, through: :role_users, source: :resource, source_type: 'Spree::Vendor'` beside `stores`; the vendor branch's `/me` returns the vendor memberships so a panel can pick its context. `AdminUserMethods#can_be_deleted?` reasons about `Store.current.users` — the vendor branch needs its own "last owner of this vendor" rule.- **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).@@ -307,7 +333,7 @@ class Spree::PaymentSplit < Spree.base_classend```-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).+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 payment* — store-credit and gift-card payments are group payments too and get their own `PaymentSplit` rows, prorated by child totals with the same largest-remainder rule (RESOLVED 2026-08-15), so a mixed store-credit checkout never overstates the gateway exposure: each child's splits across all group payments sum to `child.total`. 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@@ -550,7 +576,22 @@ Mirrors what the legacy v2 storefront already exposed for Enterprise (`/api/v2/s### 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).+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`. This is the **operator's** surface only — vendor *users* never call it (Decision 10; the 2026-07-14 "collapse into ability scoping" wording is superseded).++### Vendor API surface (new 2026-08-15 — Decision 10)++A third v3 branch, `/api/v3/vendor/…`, anchored by `Spree::Api::V3::Vendor::BaseController` / `Vendor::ResourceController` (mirroring the admin pair; concerns added to one must be added to the other):++- **Auth & context:** `POST /vendor/auth/login|refresh|logout`, password reset — `Spree.vendor_authentication_strategies`, `vendor_api` JWT audience, audience-stamped refresh token + own cookie. `X-Spree-Vendor-Id` selects the vendor; membership = `role_users` on `resource: vendor`; a header naming a vendor the caller does not belong to is 403; `Spree::Current.store` is set from `current_vendor.store`. `GET /vendor/me` — user + vendor memberships + `permission_keys` for the selected vendor. Invitation acceptance stays on the existing `/admin/invitation_acceptances` (it is store-agnostic and already handles `resource: vendor`).+- **Own resources:** `GET/PATCH /vendor/profile` (name, about, branding uploads, billing/returns addresses, `payouts_schedule_interval`, ToS acceptance, holiday mode), `GET /vendor/onboarding_tasks` + `POST /vendor/onboarding/submit_for_review`, `GET /vendor/team` + team invitations (`RoleGrantGuard`-bounded to vendor-audience roles), `GET /vendor/balance`, `GET /vendor/transfers`, `GET /vendor/payouts` (read-only ledger).+- **Catalog:** products (+ nested variants, prices, media, stock items) — every lookup through `current_vendor.products`; create force-stamps `vendor_id`; approval state per the store's vendor-product preference. No channel publication, no categories/collections/tags management (read-only pickers where a product form needs them, store-scoped read).+- **Orders:** the vendor's child orders (`current_vendor.orders`), fulfillments with `Fulfillments::Fulfill`/`Cancel`/`UpdateTracking`, returns/claims on those orders. **No** refunds, order edits, approvals, payments — the vendor sees its `payment_split`, never the group's `Payment`.+- **Delivery:** the vendor's own delivery methods (`vendor_id` = self); store-wide methods read-only.+- **Exports/imports:** the vendor's own runs on the `Spree::Export`/`Import` pipeline, scoped by `vendor_id`.+- **Serializers:** `Spree::Api::V3::Vendor::*Serializer < V3::*Serializer` (the store serializer) plus an explicit list of operational fields — never a subclass of the admin serializer, so nothing leaks by inheritance. Own typelizer output and a generated `docs/api-reference/vendor.yaml` from `spree/api/spec/integration/spree/api/v3/vendor/`.+- **Tripwires:** the branch enters `Spree::StoreScopeGuard`'s coverage, and Phase 1 adds a vendor-scope guard on the same pattern (flag store-scoped-but-not-vendor-scoped scans on vendor-owned tables under `/vendor`).+- **Later, not 6.0:** vendor-bound secret API keys (Enterprise Shopify/Woo apps acting as the vendor) — safe only on this branch, because its base scope is `current_vendor`; a store-bound admin key is `can :manage, :all`.+- SDK packaging (a `@spree/vendor-sdk` vs a `vendor` namespace in the admin SDK) is decided with Phase 4; the API decision does not depend on it.## Migration Path@@ -563,11 +604,12 @@ This is **new OSS code**, not a rename of existing core — there is no in-place- 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 0 — admin-branch hardening (ships first, no Vendor model needed).** Tighten `AdminAuthentication#current_user_member_of_store?` to `resource_type: 'Spree::Store'` + regression spec; `spree_refresh_tokens.audience` written at mint and enforced on refresh (admin + store surfaces stamp their own); `Role#audience` + the vendor-grantable marker on `register_resource` (Decision 10 / RBAC plan).+ - **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`) + `UserRoles#vendors`, 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. **The Vendor API branch anchor** (`Vendor::BaseController`/`ResourceController`, `vendor_api` audience, `Spree.vendor_authentication_strategies`, `/vendor/auth/*`, `/vendor/me`, `/vendor/profile`, onboarding, team, vendor-scope guard, `Spree::Ability` `resource:` option) + the seeded default vendor role. Products/orders/fulfillments on the vendor branch follow as each domain lands (products in Phase 1, orders/fulfillments/ledger reads in Phase 3). 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-6.1-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.+ - **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) talking to the Vendor API branch (own login page + `vendor_api` tokens; `PermissionProvider` fed by `/vendor/me`). Vendor roles come from the operator's roles editor filtered to the vendor audience; the operator's Vendors detail screen assigns them. 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.@@ -583,11 +625,18 @@ Even before this lands, work touching adjacent areas should:- **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.+- **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 the *operator's* API surface — keep it in sync. Vendor users never call the Admin API (Decision 10).+- **Auth + RBAC (`6.0-platform-auth.md`, `6.0-admin-rbac.md`)**: no third principal — never add a `VendorUser`/`Spree.vendor_user_class`; vendor staff are `Spree.admin_user_class`. Never derive back-office membership from `store_id` alone — match `RoleUser.resource_type` (`Ability#staff_roles` and `RoleGrantGuard` already do; the membership check must follow). New login surfaces get their own strategy registry and JWT audience; refresh tokens must carry the audience they were minted for. Catalog resources that vendors may hold must be marked vendor-grantable at `register_resource`; `settings`/`staff`/`api_keys` never are. Vendor-branch controllers scope-fetch through `current_vendor` and never subclass admin controllers.- 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+- **Vendor principal → `Spree::AdminUser` (`Spree.admin_user_class`), no `VendorUser` model** (RESOLVED 2026-08-15). Reuse the whole shipped auth stack and the RBAC rails (`RoleUser`/`Invitation` on `resource: vendor`); membership is by resource type, never `store_id`. Isolation guaranteed at the token layer: own `vendor_api` JWT audience, own `Spree.vendor_authentication_strategies` + `/vendor/auth/*` (so staff can be SSO-only while vendors use passwords; the vendor login refuses non-members), `spree_refresh_tokens.audience`. See Decision 10 + `decisions.md` 2026-08-15.+- **Vendor API → dedicated `/api/v3/vendor` branch, `current_vendor` scope-fetching; vendors never call the Admin API** (RESOLVED 2026-08-15). Supersedes the 2026-07-14 "vendor users hit the same admin API with vendor-scoped abilities" wording — permission sets with tenancy conditions no longer exist (RBAC, PR #14412), and the RBAC plan's 2026-08-08 direction already named `current_vendor` endpoints. Own serializer branch off the store serializers, own OpenAPI spec, no subclassing of admin controllers. See Decision 10.+- **Store credit / gift cards split across child orders → group-level payments, prorated through `PaymentSplit` like any other payment** (RESOLVED 2026-08-15). A store-credit or gift-card payment is a `Payment` on the `OrderGroup` exactly like the gateway payment; every group payment gets one `PaymentSplit` row per child order, prorated by child totals with the same largest-remainder rule as order-level discounts. One attribution rule for every payment source, no priority ordering, no special-casing — and it composes with the resolved payment-source-agnostic transfer basis (the vendor's earning never depends on how the buyer paid). Confirmed against the shipped `Carts::Complete` pipeline (payments attach before the split runs).+- **Payout minimum threshold → core; rolling reserve / holdback → Enterprise** (RESOLVED 2026-08-15). `spree_vendors.minimum_payout_amount` (decimal, nullable; nil ⇒ store preference `default_minimum_payout_amount`) — the sweep skips a vendor whose `balance(currency)` is below the threshold and carries the balance to the next period. A percentage holdback with a release window is money-operations policy (chargeback buffer) and stays Enterprise, so core does not grow a third ledger row kind.+- **Marketplace-facilitator remittance → `spree_vendors.tax_remittance` (`vendor` | `platform`, default `vendor`), honored by core's transfer basis** (RESOLVED 2026-08-15). `platform` ⇒ `transfer.amount = total − tax_total − commission`; `vendor` keeps `total − commission`. Core owns the ledger math so it is provider-independent; *deciding* when a vendor is `platform`-remitted (US facilitator nexus, EU deemed-supplier scenarios) stays Enterprise "automatic taxes", which simply sets the column. Amends the Decision 9 note that this mode is "not core": the flag and the math are core, the policy is not.+- **Vendor-scoped promotions → post-6.0** (RESOLVED 2026-08-15 as deferred; shape recorded under Open Questions).- **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.@@ -606,11 +655,8 @@ Even before this lands, work touching adjacent areas should:## 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.+1. **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**. Unblocked by: a merchant asking for platform-funded campaigns once the ledger is live; the shape is a `funded_by` on Promotion + a positive `VendorTransfer` compensating row.+2. **Vendor-scoped promotions** (a vendor creates promotions limited to its own products) — **post-6.0** (resolved 2026-08-15 as deferred). Shape when it lands: `spree_promotions.vendor_id` (nullable), a `/api/v3/vendor/promotions` endpoint on the vendor branch, and a rule guard that a vendor promotion only matches line items with the same `vendor_id`. Cheap on the single-store Promotion model; unblocked by the 6.0 headline scope shipping first.## Referencesdiff --git a/docs/plans/decisions.md b/docs/plans/decisions.mdindex 21933afcc1..81a2109930 100644--- a/docs/plans/decisions.md+++ b/docs/plans/decisions.md@@ -2891,3 +2891,91 @@ serializer work must not assume fees stay hidden. A dedicated duty-providercontract (estimate/commit/void) is deliberately NOT built — it graduates onlyif the first provider gem proves the need. Plan:`6.0-duties-and-custom-fees.md`.++## 2026-08-15 — Vendor users are `Spree::AdminUser`; vendors get their own API branch, JWT audience and login surface++**Context:** The marketplace plan (2026-07-14 wording) said vendor users would+"hit the same admin API with JWT + vendor-scoped abilities — no separate+vendor routes", with abilities built from `PermissionSets::VendorUser`+carrying `vendor_id: user.vendor_ids` hash conditions. Two shipped PRs changed+the ground under that: platform-owned auth (#14380) made the platform+two-principal (`Customer` buys, `AdminUser` operates a back office, one auth+stack on that class), and first-class RBAC (#14412) removed permission sets+with no bridge — the catalog is flat `read_*`/`write_*` keys with **no+conditions**, tenancy is controller scoping, and `Spree::Ability#staff_roles`+already excludes vendor-resourced `RoleUser` rows as belonging to "their own+panel's ability" (the RBAC plan's 2026-08-08 direction: vendor-panel endpoints+scope-fetch through `current_vendor`). Two questions were re-examined: should+vendor staff be a separate model, and should they reuse the Admin API with+narrower permissions.++**Decision:** *Reuse the principal, separate the surface.*++- **Vendor staff are `Spree.admin_user_class`. No `VendorUser` model, no+ `Spree.vendor_user_class`.** A third principal would duplicate+ `has_secure_password`, lockout, password policy, password-reset tokens,+ `UserIdentity` SSO linking, invitation acceptance and the refresh-cookie+ flow — every future MFA/passkey improvement, twice. Membership is by+ `RoleUser.resource_type` (`Spree::Vendor` vs `Spree::Store`), never by+ `store_id`; one account may hold a store role and a vendor role at once.+- **A dedicated `/api/v3/vendor` branch** (third v3 branch beside `store` and+ `admin`, `Vendor::BaseController`/`ResourceController` anchors). Every+ endpoint scope-fetches through `current_vendor` (`X-Spree-Vendor-Id` ++ membership; the store is derived from the vendor, never from a header) —+ IDOR by construction, the same mechanism that isolates stores on the admin+ branch. Vendors never call the Admin API. What a vendor may not do is an+ endpoint that does not exist, not an ability rule. Own serializer branch off+ the store serializers, own OpenAPI spec; admin controllers are never+ subclassed into the vendor namespace (inherited `current_store.*` lookups+ are the leak).+- **Isolation at the token layer, not only at membership:** own+ `JWT_AUDIENCE_VENDOR = 'vendor_api'` (admin and vendor branches reject each+ other's tokens at decode, before any membership check); own+ `Spree.vendor_authentication_strategies` + `/vendor/auth/*` (login policy+ is per surface, so staff can be SSO-only while vendors use passwords — the+ vendor login refuses accounts with no vendor membership);+ `spree_refresh_tokens.audience` enforced on refresh with a separate cookie.++**Rejected:** a separate `VendorUser` model — buys only type-level separation+on top of the three token-layer measures, at the cost of a duplicated auth+stack and split identities. Reusing admin controllers with vendor+permissions — not expressible in the conditionless catalog; would require+per-principal forks in ~300 endpoints' `scope`/`find_resource`/incidental+lookups (`stock_location_id`, `reason_id`, `variant_id`), each miss a+cross-vendor read or write inside the same store.++**Consequences:** `AdminAuthentication#current_user_member_of_store?` must+match `resource_type: 'Spree::Store'` (today it matches `store_id`, which a+vendor-resourced assignment passes — scope-exempt admin endpoints such as+`/admin/tags` and `/admin/store` would be reachable by a vendor-only user+once vendors exist); ship this ahead of the Vendor model. `Role#audience` and+a vendor-grantable marker on `register_resource` come from the RBAC plan's+settled direction. Never add a login surface without its own strategy+registry and JWT audience; refresh tokens carry the audience they were minted+for. Accepted trade-off: password policy and lockout stay shared between+staff and vendors (model-level), and thin controllers are duplicated across+the two branches. Plan: `6.0-multi-vendor-marketplace.md` Decision 10;+supersedes the 2026-07-14 "collapse into ability scoping" wording there and+extends `6.0-admin-rbac.md`'s vendor-scoped-assignments direction.++## 2026-08-15 — Marketplace: facilitator-tax flag and payout floor are core; the policy around them is Enterprise++**Decision:** Three of the marketplace plan's long-open questions were settled+the same day as the vendor-principal decision. (1) Store-credit and gift-card+payments on a split checkout are group-level `Payment`s with their own+`PaymentSplit` rows, prorated by child totals like the gateway payment — one+attribution rule for every payment source. (2) `spree_vendors.minimum_payout_amount`+(nil ⇒ store preference) ships in core and the sweep carries sub-threshold+balances forward; a percentage holdback with a release window stays Enterprise.+(3) `spree_vendors.tax_remittance` (`vendor` | `platform`, default `vendor`)+ships in core and core's transfer basis honors it (`platform` ⇒+`total − tax_total − commission`); *deciding* that a vendor is+platform-remitted (US facilitator nexus, EU deemed-supplier rules) stays+Enterprise "automatic taxes", which sets the column. Vendor-scoped promotions+are deferred past 6.0 with their shape recorded.++**Why:** the ledger math must be provider- and edition-independent so+Enterprise never forks core ledger code — it configures rows, it does not+override the basis service. **Consequences:** amends the marketplace plan's+Decision 9 note that facilitator mode is "not core" (the flag and the math+are; the policy is not). Plan: `6.0-multi-vendor-marketplace.md`.