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
Enforce a return window by default, bypassed by staff
Damian Legawiec438ab91f3c16
diff --git a/spree/core/app/models/spree/market.rb b/spree/core/app/models/spree/market.rbindex 99c88f0842..9690fc679e 100644--- a/spree/core/app/models/spree/market.rb+++ b/spree/core/app/models/spree/market.rb@@ -15,10 +15,26 @@ module Spreehas_many :countries, through: :market_countries, class_name: 'Spree::Country'has_many :orders, class_name: 'Spree::Order', dependent: :nullify+ #+ # Preferences+ #+ # How long after an order completes a customer may open a return or+ # exchange. Per market because this is a legal question before a+ # merchandising one — the EU right of withdrawal is 14 days minimum,+ # US practice is the merchant's choice. Nil means no limit.+ #+ # Enforced by Spree::Returns::EligibilityValidator, which staff bypass;+ # a store replaces that handler to express anything more elaborate.+ # Nullable so nil survives as "no limit" — an integer preference without+ # it collapses nil to 0, which would reject every return.+ preference :return_window_days, :integer, default: 30, nullable: true+## Validations#validates :store, presence: true+ validates :preferred_return_window_days,+ numericality: { only_integer: true, greater_than: 0, allow_nil: true }validates :name, presence: true, uniqueness: { scope: spree_base_uniqueness_scope + [:store_id] }validates :currency, presence: truevalidates :default_locale, presence: truediff --git a/spree/core/app/services/spree/returns/eligibility_validator.rb b/spree/core/app/services/spree/returns/eligibility_validator.rbnew file mode 100644index 0000000000..846e38eb3d--- /dev/null+++ b/spree/core/app/services/spree/returns/eligibility_validator.rb@@ -0,0 +1,50 @@+module Spree+ module Returns+ # The default return-eligibility rule: a time window, measured from order+ # completion, configured per market.+ #+ # Registered by core on `returns.create.validate` and+ # `exchanges.create.validate`. A store that wants different rules —+ # final-sale categories, per-customer-group windows, restocking fees —+ # unregisters this and registers its own handler:+ #+ # Spree.hooks.unregister('returns.create.validate',+ # 'Spree::Returns::EligibilityValidator')+ # Spree.hooks.register('returns.create.validate', 'MyStore::ReturnPolicy')+ #+ # Core deliberately ships this one rule and no policy engine+ # (decisions.md 2026-08-03): the hook is the extension point, and a+ # richer rules model can arrive behind it without changing its contract.+ class EligibilityValidator+ # @param workflow [Spree::Returns::Create, Spree::Exchanges::Create]+ def call(workflow)+ order = workflow.order+ window = window_for(order)++ return if window.nil?+ return if order.completed_at.nil?+ return if order.completed_at > window.days.ago+ # Staff opened this, so treat the window as advisory — a supervisor+ # making an exception is ordinary retail, and Shopify behaves the+ # same way. The override is attributable through `created_by`.+ return if workflow.created_by.present?++ workflow.reject!(+ Spree.t('return_errors.outside_window', days: window)+ )+ end++ private++ # Market first, because the window is a per-region legal matter. An+ # order without a market (single-region store, or one placed before+ # markets existed) falls back to the preference default.+ def window_for(order)+ market = order.market+ return market.preferred_return_window_days if market.present?++ Spree::Market.new.preferred_return_window_days+ end+ end+ end+enddiff --git a/spree/core/config/locales/en.yml b/spree/core/config/locales/en.ymlindex 176164a2d1..5da52537fd 100644--- a/spree/core/config/locales/en.yml+++ b/spree/core/config/locales/en.yml@@ -1424,6 +1424,8 @@ en:return_authorization: Return Authorizationreturn_authorization_canceled: Return authorization canceledreturn_authorizations: Return Authorizations+ return_errors:+ outside_window: This order is outside the %{days}-day return windowreturn_item_inventory_unit_ineligible: Return item's inventory unit must be shippedreturn_item_inventory_unit_reimbursed: Return item's inventory unit is already reimbursedreturn_item_order_not_completed: Return item's order must be completeddiff --git a/spree/core/lib/spree/core/engine.rb b/spree/core/lib/spree/core/engine.rbindex 00b5215624..4529ba110d 100644--- a/spree/core/lib/spree/core/engine.rb+++ b/spree/core/lib/spree/core/engine.rb@@ -474,6 +474,14 @@ module Spreeendend+ # The one eligibility rule core ships: a per-market return window,+ # bypassed by staff. Registered after application initializers so a+ # store can unregister it in its own initializer.+ initializer 'spree.returns.register_eligibility_validator', after: :load_config_initializers do+ Spree.hooks.register('returns.create.validate', 'Spree::Returns::EligibilityValidator')+ Spree.hooks.register('exchanges.create.validate', 'Spree::Returns::EligibilityValidator')+ end+config.to_prepare do# Ensure spree locale paths are present before decoratorsI18n.load_path.unshift(*(Dir.glob(diff --git a/spree/core/spec/services/spree/returns/eligibility_validator_spec.rb b/spree/core/spec/services/spree/returns/eligibility_validator_spec.rbnew file mode 100644index 0000000000..376c6eeaa0--- /dev/null+++ b/spree/core/spec/services/spree/returns/eligibility_validator_spec.rb@@ -0,0 +1,86 @@+require 'spec_helper'++RSpec.describe Spree::Returns::EligibilityValidator do+ let(:store) { @default_store }+ let(:order) { create(:shipped_order, store: store) }++ def open_return(created_by: nil)+ Spree::Returns::Create.call(+ order: order,+ items: [{ fulfillment_item: order.fulfillment_items.first, quantity: 1 }],+ created_by: created_by+ )+ end++ # The engine registers this handler at boot; specs run against an app where+ # that has already happened, so nothing to register here.+ it 'is registered on the create workflows' do+ expect(Spree.hooks.for('returns.create.validate').map(&:class)).to include(described_class)+ expect(Spree.hooks.for('exchanges.create.validate').map(&:class)).to include(described_class)+ end++ context 'within the window' do+ it 'allows a customer return' do+ order.update_columns(completed_at: 5.days.ago)++ expect(open_return).to be_success+ end+ end++ context 'outside the window' do+ before { order.update_columns(completed_at: 60.days.ago) }++ it 'rejects a customer return' do+ result = open_return++ expect(result).to be_failure+ expect(result.error.value).to include('30-day return window')+ expect(order.reload.returns).to be_empty+ end++ # A supervisor making an exception is ordinary retail — and the override+ # is attributable, because created_by lands on the return.+ it 'lets staff open one anyway' do+ admin = create(:admin_user)++ result = open_return(created_by: admin)++ expect(result).to be_success+ expect(result.value.created_by).to eq(admin)+ end+ end++ describe 'the window comes from the market' do+ let(:market) { order.market || create(:market, store: store) }++ before { order.update_columns(market_id: market.id, completed_at: 20.days.ago) }++ it 'uses a shorter market window' do+ market.update!(preferred_return_window_days: 14)++ expect(open_return).to be_failure+ end++ it 'uses a longer market window' do+ market.update!(preferred_return_window_days: 90)++ expect(open_return).to be_success+ end++ # Nil is the escape hatch for a market with no time limit at all.+ it 'treats a nil window as unlimited' do+ market.update!(preferred_return_window_days: nil)+ order.update_columns(completed_at: 5.years.ago)++ expect(open_return).to be_success+ end+ end++ it 'ignores an order that was never completed' do+ # Returns::Create rejects it for its own reasons; the validator must not+ # blow up on a nil completed_at first.+ order.update_columns(completed_at: nil)++ expect { open_return }.not_to raise_error+ end+end