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
Give the marketplace a seller
Damian Legawiec61e27d933a99
diff --git a/CLAUDE.md b/CLAUDE.mdindex 58c3bd5f61..6063a9139e 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -187,7 +187,7 @@ Per-request context available in models, controllers, jobs, and services:- Include `Spree::Metadata` for JSON metadata support- ALWAYS Use string columns instead of enums- NEVER use `Struct` for domain value objects — use a plain Ruby class with `ActiveModel::Model` + `ActiveModel::Attributes` (typed attributes, validations) so it behaves like an ActiveRecord object (e.g. `Spree::PickupPointOption`)-- State machines: use `state_machines-activerecord` gem, default column `status` (legacy uses `state`, see docs/plans/6.0-normalize-state-to-status.md)+- State machines: legacy models use `state_machines-activerecord` gem, default column `status` (legacy uses `state`, see docs/plans/6.0-normalize-state-to-status.md), all new models should use `has_status` and Workflows instead- NEVER cast IDs to integer — always treat as strings (UUID support)- Uniqueness validations: ALWAYS use `scope: spree_base_uniqueness_scope`, should be also enforced by database index- If needed use paranoia gem for soft delete support (via `acts_as_paranoid`)diff --git a/docs/plans/6.0-multi-vendor-marketplace.md b/docs/plans/6.0-multi-vendor-marketplace.mdindex f24a7898de..842239249a 100644--- a/docs/plans/6.0-multi-vendor-marketplace.md+++ b/docs/plans/6.0-multi-vendor-marketplace.md@@ -180,7 +180,8 @@ The headline model. Ports the Enterprise module's `Spree::Vendor` (keeping preficlass Spree::Vendor < Spree.base_classhas_prefix_id :veninclude Spree::SingleStoreResource- include Spree::Metafields+ include Spree::UserManagement # roles, role_users, users, invitations — the team+ include Spree::HasCustomFields # Metafields is a 6.1-removed shellinclude Spree::Metadatainclude Spree::TranslatableResource # about/description translate like Productacts_as_paranoid@@ -196,8 +197,9 @@ class Spree::Vendor < Spree.base_classhas_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+ # Teams come from Spree::UserManagement above, not hand-rolled: after the+ # RBAC refactor a RoleUser has no resource of its own, so a vendor's team is+ # whoever holds a role the vendor owns (`roles` → `role_users` → `users`).# name, slug (unique per store), contact_email, billing_email# about : rich text (sanitized HTML column per 6.0-rich-text-descriptions.md)@@ -216,20 +218,25 @@ class Spree::Vendor < Spree.base_class# 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- # 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 }+ # 6.0-normalize-state-to-status.md), but NOT its state machine: approving+ # sends mail and provisions payouts, which is exactly the work+ # 6.0-service-workflows.md keeps out of save callbacks. Transitions are+ # workflows (Spree::Vendors::Invite, ::Approve, ::Suspend, …); the model+ # only declares the values.+ #+ # pending → invited → onboarding → ready_for_review → approved+ #+ # `approve` also lifts a suspension and revives a rejected vendor, so the+ # reachable set is wider than that line — which is the permissiveness the+ # legacy machine had, now expressed as workflow guards rather than a graph.+ include Spree::HasStatus+ has_status :pending, :invited, :canceled, :onboarding, :ready_for_review,+ :approved, :rejected, :suspended, default: :pending++ validates :name, presence: true+ # Scoped to the store: spree_base_uniqueness_scope is empty, so naming it+ # explicitly is what makes two marketplaces able to share a slug.+ validates :slug, presence: true, uniqueness: { scope: [*spree_base_uniqueness_scope, :store_id] }end```diff --git a/spree/core/app/models/concerns/spree/user_roles.rb b/spree/core/app/models/concerns/spree/user_roles.rbindex 3ab4c3640a..89a1667a33 100644--- a/spree/core/app/models/concerns/spree/user_roles.rb+++ b/spree/core/app/models/concerns/spree/user_roles.rb@@ -6,6 +6,7 @@ module Spreehas_many :role_users, class_name: 'Spree::RoleUser', foreign_key: :user_id, as: :user, dependent: :destroy_async # async as we need to check if the user has admin role before destroyinghas_many :spree_roles, through: :role_users, class_name: 'Spree::Role', source: :rolehas_many :stores, through: :spree_roles, source: :resource, source_type: 'Spree::Store'+ has_many :vendors, through: :spree_roles, source: :resource, source_type: 'Spree::Vendor'has_many :invitations, class_name: 'Spree::Invitation', as: :invitee, dependent: :destroyhas_many :sent_invitations, class_name: 'Spree::Invitation', as: :inviter, dependent: :destroydiff --git a/spree/core/app/models/spree/delivery_method.rb b/spree/core/app/models/spree/delivery_method.rbindex 6a7af9c33f..d2a0ede9fb 100644--- a/spree/core/app/models/spree/delivery_method.rb+++ b/spree/core/app/models/spree/delivery_method.rb@@ -7,9 +7,6 @@ module Spreeinclude Spree::CalculatedAdjustmentsinclude Spree::HasCustomFieldsinclude Spree::Metadata- if defined?(Spree::VendorConcern)- include Spree::VendorConcern- endinclude Spree::MemoizedDatainclude Spree::TypedAssociationsdiff --git a/spree/core/app/models/spree/export.rb b/spree/core/app/models/spree/export.rbindex 022d2a5b79..eb6f4f2da3 100644--- a/spree/core/app/models/spree/export.rb+++ b/spree/core/app/models/spree/export.rb@@ -8,7 +8,6 @@ module Spreeinclude Spree::SingleStoreResourceinclude Spree::NumberIdentifier- include Spree::VendorConcern if defined?(Spree::VendorConcern)has_spree_number prefix: 'EF'diff --git a/spree/core/app/models/spree/fulfillment.rb b/spree/core/app/models/spree/fulfillment.rbindex 69880e7918..e629d321df 100644--- a/spree/core/app/models/spree/fulfillment.rb+++ b/spree/core/app/models/spree/fulfillment.rb@@ -12,9 +12,6 @@ module Spreeif defined?(Spree::Security::Shipments)include Spree::Security::Shipmentsend- if defined?(Spree::VendorConcern)- include Spree::VendorConcern- endinclude Spree::Fulfillment::CustomEventspublishes_lifecycle_eventsdiff --git a/spree/core/app/models/spree/order.rb b/spree/core/app/models/spree/order.rbindex a09a4945fb..6cf75c6596 100644--- a/spree/core/app/models/spree/order.rb+++ b/spree/core/app/models/spree/order.rb@@ -50,9 +50,6 @@ module Spreeif defined?(Spree::Security::Orders)include Spree::Security::Ordersend- if defined?(Spree::VendorConcern)- include Spree::VendorConcern- endhas_secure_token :token, length: 35diff --git a/spree/core/app/models/spree/product.rb b/spree/core/app/models/spree/product.rbindex 52b7f871d6..51cc005c91 100644--- a/spree/core/app/models/spree/product.rb+++ b/spree/core/app/models/spree/product.rb@@ -33,9 +33,6 @@ module Spreeinclude Spree::Product::Channelsinclude Spree::SearchIndexableinclude Spree::StorePreferences- if defined?(Spree::VendorConcern)- include Spree::VendorConcern- endpublishes_lifecycle_events@@ -130,6 +127,10 @@ module Spreebelongs_to :tax_category, class_name: 'Spree::TaxCategory'belongs_to :product_type, class_name: 'Spree::ProductType', optional: true, counter_cache: :products_count+ # The seller this product belongs to on a marketplace. Nil is the+ # operator's own catalog — which is everything, on a store selling only+ # its own goods.+ belongs_to :vendor, class_name: 'Spree::Vendor', optional: true, inverse_of: :products# How this product ships: origins, zones and methods all hang off the# profile. Required — a product without one could not be fulfilled atdiff --git a/spree/core/app/models/spree/report.rb b/spree/core/app/models/spree/report.rbindex e39a0acd77..bda32a45c0 100644--- a/spree/core/app/models/spree/report.rb+++ b/spree/core/app/models/spree/report.rb@@ -3,7 +3,6 @@ module Spreehas_prefix_id :repinclude Spree::SingleStoreResource- include Spree::VendorConcern if defined?(Spree::VendorConcern)publishes_lifecycle_eventsdiff --git a/spree/core/app/models/spree/stock_location.rb b/spree/core/app/models/spree/stock_location.rbindex 65a10061f1..99ee503ce6 100644--- a/spree/core/app/models/spree/stock_location.rb+++ b/spree/core/app/models/spree/stock_location.rb@@ -16,9 +16,6 @@ module Spreeif defined?(Spree::Security::StockLocations)include Spree::Security::StockLocationsend- if defined?(Spree::VendorConcern)- include Spree::VendorConcern- endacts_as_paranoiddiff --git a/spree/core/app/models/spree/vendor.rb b/spree/core/app/models/spree/vendor.rbnew file mode 100644index 0000000000..ad740bff31--- /dev/null+++ b/spree/core/app/models/spree/vendor.rb@@ -0,0 +1,127 @@+# frozen_string_literal: true++module Spree+ # A selling party on a marketplace: the store is the tenant, the vendor is a+ # seller within it (docs/plans/6.0-multi-vendor-marketplace.md).+ #+ # A vendor owns roles, so its team is the people holding them — the same+ # machinery the store's own back office uses, pointed at the vendor.+ class Vendor < Spree.base_class+ has_prefix_id :ven++ acts_as_paranoid++ include Spree::SingleStoreResource+ include Spree::UserManagement+ include Spree::TranslatableResource+ include Spree::HasCustomFields+ include Spree::Metadata+ include Spree::SanitizableRichText++ publishes_lifecycle_events++ # Where a vendor is in its life on the marketplace. Transitions belong to+ # workflows (Spree::Vendors::Approve and friends) rather than a state+ # machine: approving sends mail and provisions payouts, which is exactly+ # the work that must not run inside a save callback.+ #+ # pending → invited → onboarding → ready_for_review → approved+ #+ # `approve` also lifts a suspension, and a rejected vendor can be revived,+ # so the reachable set is deliberately wider than that line suggests.+ include Spree::HasStatus+ has_status :pending, :invited, :canceled, :onboarding, :ready_for_review,+ :approved, :rejected, :suspended, default: :pending++ # Who remits consumer tax on this vendor's sales. `vendor` means they are+ # merchant of record; `platform` is the marketplace-facilitator case, and+ # only Enterprise decides a vendor belongs there — core just reads it.+ TAX_REMITTANCES = %w[vendor platform].freeze+ PAYOUT_INTERVALS = %w[daily weekly biweekly monthly manual].freeze++ TRANSLATABLE_FIELDS = %i[name about].freeze+ RICH_TEXT_TRANSLATABLE_FIELDS = %i[about].freeze+ translates(*TRANSLATABLE_FIELDS, column_fallback: Spree.mobility_column_fallback)++ self::Translation.class_eval do+ include Spree::SanitizableRichText+ sanitizes_rich_text :about+ end++ #+ # Associations+ #+ belongs_to :store, class_name: 'Spree::Store'+ # On the commission invoice (EU) and where customer returns route.+ belongs_to :billing_address, class_name: 'Spree::Address', optional: true+ belongs_to :returns_address, class_name: 'Spree::Address', optional: true++ # Products and stock survive the vendor leaving: the operator decides what+ # happens to a departed seller's catalog, so it is never cascade-deleted.+ has_many :products, class_name: 'Spree::Product', dependent: :nullify++ #+ # Attachments+ #+ has_one_attached :logo, service: Spree.public_storage_service_name+ has_one_attached :square_logo, service: Spree.public_storage_service_name+ has_one_attached :cover_photo, service: Spree.public_storage_service_name++ #+ # Validations+ #+ validates :name, presence: true+ # Scoped to the store, not global: two marketplaces on one installation+ # may each have a "sparks". Backed by the unique index on the pair.+ validates :slug, presence: true,+ uniqueness: { scope: [*spree_base_uniqueness_scope, :store_id], case_sensitive: false }+ validates :tax_remittance, inclusion: { in: TAX_REMITTANCES }+ validates :payouts_schedule_interval, inclusion: { in: PAYOUT_INTERVALS }, allow_nil: true+ validates :minimum_payout_amount, numericality: { greater_than_or_equal_to: 0 }, allow_nil: true++ has_spree_rich_text :about++ #+ # Scopes+ #+ scope :sellable, -> { approved.where(holiday_mode_until: [nil, ..Time.current]) }++ #+ # Callbacks+ #+ before_validation :normalize_slug++ # A vendor's own team is granted through its roles, not the store's.+ #+ # @return [Spree::Role]+ def default_user_role+ Spree::Role.default_admin_role(self)+ end++ # Whether the vendor is currently away. The catalog stays visible; what+ # stops is selling.+ #+ # @return [Boolean]+ def on_holiday?+ holiday_mode_until.present? && holiday_mode_until > Time.current+ end++ # Whether customers may buy from this vendor right now.+ #+ # @return [Boolean]+ def sellable?+ approved? && !on_holiday?+ end++ # @return [Boolean]+ def terms_accepted?+ terms_accepted_at.present?+ end++ private++ def normalize_slug+ self.slug = (slug.presence || name).to_s.parameterize.presence+ end+ end+enddiff --git a/spree/core/db/migrate/20260816000001_create_spree_vendors.rb b/spree/core/db/migrate/20260816000001_create_spree_vendors.rbnew file mode 100644index 0000000000..85e9eb39aa--- /dev/null+++ b/spree/core/db/migrate/20260816000001_create_spree_vendors.rb@@ -0,0 +1,43 @@+class CreateSpreeVendors < ActiveRecord::Migration[8.1]+ def change+ create_table :spree_vendors do |t|+ t.references :store, null: false+ t.string :name, null: false+ t.string :slug, null: false+ t.string :status, null: false # no DB default: set by the creating workflow+ t.string :contact_email+ t.string :billing_email+ t.text :about+ t.references :billing_address+ t.references :returns_address++ # Vendor acceptance of the store's seller terms — the timestamp is the+ # record of it, so onboarding can ask again when the terms change.+ t.datetime :terms_accepted_at+ # Set while the vendor is away: their catalog stays but stops selling.+ t.datetime :holiday_mode_until++ # Settlement configuration. Both nil mean "use the store's default", so+ # a vendor only carries a value once it deviates.+ t.string :payouts_schedule_interval+ t.decimal :minimum_payout_amount, precision: 10, scale: 2++ # Who remits consumer tax on this vendor's sales — 'vendor' (they are+ # merchant of record) or 'platform' (marketplace-facilitator rules).+ t.string :tax_remittance, null: false, default: 'vendor'++ if t.respond_to?(:jsonb)+ t.jsonb :metadata+ else+ t.json :metadata+ end++ t.timestamps+ t.datetime :deleted_at+ end++ add_index :spree_vendors, [:store_id, :slug], unique: true+ add_index :spree_vendors, [:store_id, :status]+ add_index :spree_vendors, :deleted_at+ end+enddiff --git a/spree/core/db/migrate/20260816000002_add_vendor_to_spree_products.rb b/spree/core/db/migrate/20260816000002_add_vendor_to_spree_products.rbnew file mode 100644index 0000000000..157eda1a50--- /dev/null+++ b/spree/core/db/migrate/20260816000002_add_vendor_to_spree_products.rb@@ -0,0 +1,10 @@+class AddVendorToSpreeProducts < ActiveRecord::Migration[8.1]+ # Which seller owns this product. Nil is the operator's own first-party+ # catalog, which is every product on a store that sells nothing but its own.+ #+ # Replaces the guarded Spree::VendorConcern hook the Enterprise module used+ # to fill: the marketplace is core now, so the column is too.+ def change+ add_reference :spree_products, :vendor, index: true+ end+enddiff --git a/spree/core/lib/spree/core/engine.rb b/spree/core/lib/spree/core/engine.rbindex e476667532..fa265445e6 100644--- a/spree/core/lib/spree/core/engine.rb+++ b/spree/core/lib/spree/core/engine.rb@@ -397,7 +397,8 @@ module SpreeSpree::Collection,Spree::Category,Spree::Store,- Spree::Policy+ Spree::Policy,+ Spree::Vendor]# Resources that expose tags via `acts_as_taggable_on :tags`. Thediff --git a/spree/core/lib/spree/testing_support/factories/vendor_factory.rb b/spree/core/lib/spree/testing_support/factories/vendor_factory.rbnew file mode 100644index 0000000000..1ba879f094--- /dev/null+++ b/spree/core/lib/spree/testing_support/factories/vendor_factory.rb@@ -0,0 +1,34 @@+FactoryBot.define do+ factory :vendor, class: Spree::Vendor do+ sequence(:name) { |n| "Vendor #{n}" }+ store { Spree::Store.default || create(:store) }+ status { 'pending' }++ trait :approved do+ status { 'approved' }+ terms_accepted_at { Time.current }+ end++ trait :onboarding do+ status { 'onboarding' }+ end++ trait :suspended do+ status { 'suspended' }+ end++ trait :on_holiday do+ status { 'approved' }+ holiday_mode_until { 2.weeks.from_now }+ end++ trait :with_logo do+ after(:create) do |vendor|+ vendor.logo.attach(+ io: File.new(Spree::Core::Engine.root.join('spec', 'fixtures', 'thinking-cat.jpg')),+ filename: 'thinking-cat.jpg'+ )+ end+ end+ end+enddiff --git a/spree/core/spec/models/spree/vendor_spec.rb b/spree/core/spec/models/spree/vendor_spec.rbnew file mode 100644index 0000000000..343cff654c--- /dev/null+++ b/spree/core/spec/models/spree/vendor_spec.rb@@ -0,0 +1,134 @@+require 'spec_helper'++describe Spree::Vendor do+ let(:store) { @default_store }++ describe 'statuses' do+ it 'starts pending and moves only through workflows' do+ expect(described_class.default_status).to eq('pending')+ expect(described_class.statuses).to include('approved', 'suspended', 'rejected')+ # A state machine would have generated these; the absence is the point.+ expect(described_class).not_to respond_to(:state_machines)+ end++ it 'generates a predicate and a scope per status' do+ vendor = create(:vendor, :approved)++ expect(vendor).to be_approved+ expect(vendor).not_to be_pending+ expect(described_class.approved).to include(vendor)+ end++ it 'rejects an unknown status' do+ expect(build(:vendor, status: 'flourishing')).not_to be_valid+ end+ end++ describe 'slug' do+ it 'derives from the name when absent' do+ expect(create(:vendor, name: 'Bright Sparks Ltd').slug).to eq('bright-sparks-ltd')+ end++ it 'keeps an explicit slug' do+ expect(create(:vendor, name: 'Bright Sparks', slug: 'sparks').slug).to eq('sparks')+ end++ it 'is unique within a store' do+ create(:vendor, slug: 'sparks', store: store)++ expect(build(:vendor, slug: 'sparks', store: store)).not_to be_valid+ end++ it 'may repeat on another store' do+ create(:vendor, slug: 'sparks', store: store)++ expect(build(:vendor, slug: 'sparks', store: create(:store))).to be_valid+ end+ end++ describe '#sellable?' do+ it 'is true once approved' do+ expect(create(:vendor, :approved)).to be_sellable+ end++ it 'is false while unapproved' do+ expect(create(:vendor, :onboarding)).not_to be_sellable+ end++ # The catalog stays; what stops is selling.+ it 'is false while on holiday' do+ vendor = create(:vendor, :on_holiday)++ expect(vendor).to be_on_holiday+ expect(vendor).not_to be_sellable+ expect(described_class.sellable).not_to include(vendor)+ end++ it 'resumes once the holiday has passed' do+ vendor = create(:vendor, :approved, holiday_mode_until: 1.day.ago)++ expect(vendor).not_to be_on_holiday+ expect(described_class.sellable).to include(vendor)+ end+ end++ describe 'teams' do+ let(:vendor) { create(:vendor, :approved) }+ let(:staffer) { create(:admin_user, :without_admin_role) }++ it 'owns its own roles, separate from the store' do+ role = create(:role, name: 'Packer', resource: vendor)++ expect(vendor.roles).to include(role)+ expect(store.roles).not_to include(role)+ end++ it 'adds a user through a role it owns' do+ vendor.add_user(staffer, create(:role, name: 'Packer', resource: vendor))++ expect(vendor.users).to include(staffer)+ expect(staffer.vendors).to include(vendor)+ end++ it 'refuses a role belonging to the store' do+ store_role = create(:role, name: 'Packer', resource: store)++ expect { vendor.add_user(staffer, store_role) }.to raise_error(ArgumentError)+ end++ # Membership on a vendor is not membership of the store's back office.+ it 'does not make its team store staff' do+ vendor.add_user(staffer, create(:role, name: 'Packer', resource: vendor))++ expect(staffer.stores).not_to include(store)+ expect(Spree::Ability.new(staffer, store: store).permission_keys).to be_empty+ end+ end++ describe 'products' do+ it 'keeps them when the vendor is destroyed' do+ vendor = create(:vendor, :approved)+ product = create(:product, store: store, vendor: vendor)++ vendor.destroy++ expect(product.reload.vendor_id).to be_nil+ end+ end++ describe 'settlement configuration' do+ it 'defaults to the vendor remitting its own tax' do+ expect(create(:vendor).tax_remittance).to eq('vendor')+ end++ it 'rejects an unknown remittance or interval' do+ expect(build(:vendor, tax_remittance: 'someone_else')).not_to be_valid+ expect(build(:vendor, payouts_schedule_interval: 'fortnightly')).not_to be_valid+ end++ # Nil means "use the store's default", so it stays valid.+ it 'allows both to be unset' do+ expect(build(:vendor, payouts_schedule_interval: nil, minimum_payout_amount: nil)).to be_valid+ end+ end+end