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.

Give the marketplace a seller

Damian Legawiec61e27d933a99
diff --git a/CLAUDE.md b/CLAUDE.md
index 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.md
index 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 prefi
class Spree::Vendor < Spree.base_class
has_prefix_id :ven
include Spree::SingleStoreResource
- include Spree::Metafields
+ include Spree::UserManagement # roles, role_users, users, invitations — the team
+ include Spree::HasCustomFields # Metafields is a 6.1-removed shell
include Spree::Metadata
include Spree::TranslatableResource # about/description translate like Product
acts_as_paranoid
@@ -196,8 +197,9 @@ class Spree::Vendor < Spree.base_class
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
+ # 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.rb
index 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 Spree
has_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 destroying
has_many :spree_roles, through: :role_users, class_name: 'Spree::Role', source: :role
has_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: :destroy
has_many :sent_invitations, class_name: 'Spree::Invitation', as: :inviter, dependent: :destroy
diff --git a/spree/core/app/models/spree/delivery_method.rb b/spree/core/app/models/spree/delivery_method.rb
index 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 Spree
include Spree::CalculatedAdjustments
include Spree::HasCustomFields
include Spree::Metadata
- if defined?(Spree::VendorConcern)
- include Spree::VendorConcern
- end
include Spree::MemoizedData
include Spree::TypedAssociations
diff --git a/spree/core/app/models/spree/export.rb b/spree/core/app/models/spree/export.rb
index 022d2a5b79..eb6f4f2da3 100644
--- a/spree/core/app/models/spree/export.rb
+++ b/spree/core/app/models/spree/export.rb
@@ -8,7 +8,6 @@ module Spree
include Spree::SingleStoreResource
include 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.rb
index 69880e7918..e629d321df 100644
--- a/spree/core/app/models/spree/fulfillment.rb
+++ b/spree/core/app/models/spree/fulfillment.rb
@@ -12,9 +12,6 @@ module Spree
if defined?(Spree::Security::Shipments)
include Spree::Security::Shipments
end
- if defined?(Spree::VendorConcern)
- include Spree::VendorConcern
- end
include Spree::Fulfillment::CustomEvents
publishes_lifecycle_events
diff --git a/spree/core/app/models/spree/order.rb b/spree/core/app/models/spree/order.rb
index a09a4945fb..6cf75c6596 100644
--- a/spree/core/app/models/spree/order.rb
+++ b/spree/core/app/models/spree/order.rb
@@ -50,9 +50,6 @@ module Spree
if defined?(Spree::Security::Orders)
include Spree::Security::Orders
end
- if defined?(Spree::VendorConcern)
- include Spree::VendorConcern
- end
has_secure_token :token, length: 35
diff --git a/spree/core/app/models/spree/product.rb b/spree/core/app/models/spree/product.rb
index 52b7f871d6..51cc005c91 100644
--- a/spree/core/app/models/spree/product.rb
+++ b/spree/core/app/models/spree/product.rb
@@ -33,9 +33,6 @@ module Spree
include Spree::Product::Channels
include Spree::SearchIndexable
include Spree::StorePreferences
- if defined?(Spree::VendorConcern)
- include Spree::VendorConcern
- end
publishes_lifecycle_events
@@ -130,6 +127,10 @@ module Spree
belongs_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 at
diff --git a/spree/core/app/models/spree/report.rb b/spree/core/app/models/spree/report.rb
index e39a0acd77..bda32a45c0 100644
--- a/spree/core/app/models/spree/report.rb
+++ b/spree/core/app/models/spree/report.rb
@@ -3,7 +3,6 @@ module Spree
has_prefix_id :rep
include Spree::SingleStoreResource
- include Spree::VendorConcern if defined?(Spree::VendorConcern)
publishes_lifecycle_events
diff --git a/spree/core/app/models/spree/stock_location.rb b/spree/core/app/models/spree/stock_location.rb
index 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 Spree
if defined?(Spree::Security::StockLocations)
include Spree::Security::StockLocations
end
- if defined?(Spree::VendorConcern)
- include Spree::VendorConcern
- end
acts_as_paranoid
diff --git a/spree/core/app/models/spree/vendor.rb b/spree/core/app/models/spree/vendor.rb
new file mode 100644
index 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
+end
diff --git a/spree/core/db/migrate/20260816000001_create_spree_vendors.rb b/spree/core/db/migrate/20260816000001_create_spree_vendors.rb
new file mode 100644
index 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
+end
diff --git a/spree/core/db/migrate/20260816000002_add_vendor_to_spree_products.rb b/spree/core/db/migrate/20260816000002_add_vendor_to_spree_products.rb
new file mode 100644
index 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
+end
diff --git a/spree/core/lib/spree/core/engine.rb b/spree/core/lib/spree/core/engine.rb
index e476667532..fa265445e6 100644
--- a/spree/core/lib/spree/core/engine.rb
+++ b/spree/core/lib/spree/core/engine.rb
@@ -397,7 +397,8 @@ module Spree
Spree::Collection,
Spree::Category,
Spree::Store,
- Spree::Policy
+ Spree::Policy,
+ Spree::Vendor
]
# Resources that expose tags via `acts_as_taggable_on :tags`. The
diff --git a/spree/core/lib/spree/testing_support/factories/vendor_factory.rb b/spree/core/lib/spree/testing_support/factories/vendor_factory.rb
new file mode 100644
index 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
+end
diff --git a/spree/core/spec/models/spree/vendor_spec.rb b/spree/core/spec/models/spree/vendor_spec.rb
new file mode 100644
index 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