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
Seed the marketplace fallback at the bottom of the list
Damian Legawiec57c8b5fde8d6
diff --git a/docs/plans/6.0-multi-vendor-marketplace.md b/docs/plans/6.0-multi-vendor-marketplace.mdindex 7ccf7ee06c..077f994af7 100644--- a/docs/plans/6.0-multi-vendor-marketplace.md+++ b/docs/plans/6.0-multi-vendor-marketplace.md@@ -23,7 +23,7 @@ This plan covers the four subsystems: **(A) vendor identity & teams**, **(B) ord| `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) |+| Commission engine (vendor- + product- + category-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) |@@ -80,7 +80,7 @@ The legacy module resolves a **single flat percentage** with a two-level fallbac**6.0 adopts the rule-engine shape but keeps the legacy fallback as the default ladder.** New models `Spree::CommissionRate` (position, kind, value, currency, commission tax handling) + `Spree::CommissionRule` (polymorphic `subject` → Product / Category / Vendor / global). Resolution walks enabled rates in list order, first match wins. Seed a marketplace-wide rate at the bottom of the list so narrower rates an operator adds resolve ahead of it.-**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 — an explicit operator-ordered list instead of implicit most-specific-wins, which is more predictable (already RESOLVED below).+**Rule matching: every rule must hold, and a rule naming several records means any of them.** A rate carries typed rules (Product / Category / Vendor / value band / …); the rate matches a line item when every one of them says yes, and a rule holding several ids is satisfied by any of them. A category rule naming Electronics and Cameras beside a vendor rule naming 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 — an explicit operator-ordered list instead of implicit most-specific-wins, which is more predictable (already RESOLVED below).**Rule shape evidence (survey 2026-08-17).** Read against the enterprise platform's own published API contract, our `(subject_type, subject_id)` rule is the weakest of the three models surveyed. There, a rule carries a typed configuration block — seller ids, channel codes, brands, condition codes — plus a validity `period` and an applicability ceiling, and its rate is a list of tiered thresholds rather than one number. Every dimension we currently cannot express without a migration (price band, channel, validity window, product attribute) is a field there. The other OSS engine shares our shape and is equally stuck: five hardcoded dimensions behind a `switch` with no extension point, and it removed its own minimum-amount cap rather than generalising it. The conclusion is that a commission rule needs **its own configuration**, not merely a pointer to a record — which is what the STI rule pattern already used by `Spree::PriceRule` and `Spree::DeliveryMethodRule` provides (see Resolved Decisions).@@ -705,7 +705,7 @@ Even before this lands, work touching adjacent areas should:- **`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 rules → typed classes, not a polymorphic subject** (RESOLVED 2026-08-17, shipped; supersedes the original shape). A rule was `(subject_type, subject_id)`, which could only ever name a record: a price band, a channel, a promotional window were each a migration plus an edit to the matcher, and a third party could add nothing. It is now STI over `Spree.commission_rules`, matching `Spree::PriceRule` and `Spree::DeliveryMethodRule` — a rule carries its own configuration, declares it through `preference_schema`, and a new kind is a subclass and a registration. Matching semantics are unchanged: every rule must hold, and a rule naming several records means any of them, so the OR moved inside a rule and there is still no `match_policy`. Reference lists follow the house cardinality rule — vendors and categories as `normalize_id_preference` arrays, products in a join table — which also deleted the hand-rolled store check in the controller, since the preference writer scope-checks as it writes. The admin surface follows the delivery-method rules editor: `GET /commission_rates/rule_types` for discovery, one row per condition, a picker where the kind names records and its preference schema otherwise.-- **Commission rule matching → every rule must hold (AND), a rule naming several records means any of them (OR)** (RESOLVED 2026-07-14, restated 2026-08-17 for the typed shape). 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 the operator's own ordering rather than implicit specificity. See Decision 4.+- **Commission rule matching → every rule must hold (AND), a rule naming several records means any of them (OR)** (RESOLVED 2026-07-14, restated 2026-08-17 for the typed shape). Expresses plain lists and the vendor × category pairings today's Enterprise sells, with no `match_policy` knob; same semantics as the leading surveyed OSS engine, but precedence stays the operator's own ordering 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.diff --git a/spree/core/app/services/spree/seeds/commission_rates.rb b/spree/core/app/services/spree/seeds/commission_rates.rbindex d6936aea4d..4cb899c6ac 100644--- a/spree/core/app/services/spree/seeds/commission_rates.rb+++ b/spree/core/app/services/spree/seeds/commission_rates.rb@@ -29,13 +29,20 @@ module SpreeSpree::Store.find_each do |store|next if store.commission_rates.with_deleted.exists?(code: DEFAULT_CODE)- store.commission_rates.create!(+ rate = store.commission_rates.create!(name: I18n.t('spree.seed.commission_rates.marketplace_default'),code: DEFAULT_CODE,kind: 'percentage',value: 0,enabled: false)++ # New rates are born at the top, which is right for one an operator+ # adds and wrong for this one: it matches every sale, so anywhere but+ # the bottom leaves the rates below it unreachable. A store seeded+ # after it already has rates would otherwise have them all shadowed+ # the moment this was enabled.+ rate.move_to_bottomendendenddiff --git a/spree/core/spec/services/spree/seeds/commission_rates_spec.rb b/spree/core/spec/services/spree/seeds/commission_rates_spec.rbindex 618ea879f9..a7f8c1a280 100644--- a/spree/core/spec/services/spree/seeds/commission_rates_spec.rb+++ b/spree/core/spec/services/spree/seeds/commission_rates_spec.rb@@ -33,6 +33,18 @@ RSpec.describe Spree::Seeds::CommissionRates doexpect(store.commission_rates.ordered.to_a).to eq([added, seeded])end+ # The catch-all matches every sale, so anywhere but the bottom leaves the+ # rates below it unreachable — including on a store that already had some+ # when this ran.+ it 'lands below rates the store already had' do+ existing = create(:commission_rate, store: store)++ described_class.call++ seeded = store.commission_rates.find_by(code: described_class::DEFAULT_CODE)+ expect(store.commission_rates.ordered.to_a).to eq([existing, seeded])+ end+it 'seeds every store' doother_store = create(:store)