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.

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.rb
index 99c88f0842..9690fc679e 100644
--- a/spree/core/app/models/spree/market.rb
+++ b/spree/core/app/models/spree/market.rb
@@ -15,10 +15,26 @@ module Spree
has_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: true
validates :default_locale, presence: true
diff --git a/spree/core/app/services/spree/returns/eligibility_validator.rb b/spree/core/app/services/spree/returns/eligibility_validator.rb
new file mode 100644
index 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
+end
diff --git a/spree/core/config/locales/en.yml b/spree/core/config/locales/en.yml
index 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 Authorization
return_authorization_canceled: Return authorization canceled
return_authorizations: Return Authorizations
+ return_errors:
+ outside_window: This order is outside the %{days}-day return window
return_item_inventory_unit_ineligible: Return item's inventory unit must be shipped
return_item_inventory_unit_reimbursed: Return item's inventory unit is already reimbursed
return_item_order_not_completed: Return item's order must be completed
diff --git a/spree/core/lib/spree/core/engine.rb b/spree/core/lib/spree/core/engine.rb
index 00b5215624..4529ba110d 100644
--- a/spree/core/lib/spree/core/engine.rb
+++ b/spree/core/lib/spree/core/engine.rb
@@ -474,6 +474,14 @@ module Spree
end
end
+ # 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 decorators
I18n.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.rb
new file mode 100644
index 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