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
Make refund reasons store-owned
Damian Legawiec71189c7a5688
diff --git a/CLAUDE.md b/CLAUDE.mdindex dd96de4252..3205958b0a 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -141,7 +141,7 @@ One-time machine setup: Homebrew `postgresql@18` running on :5432 (with a `postg- Follow Rails conventions and the Rails Security Guide- RESTful routes and action names- CanCanCan for authorization: listings use `accessible_by(current_ability, :show)`, other actions use `authorize!`-- Always use scope fetching for security (e.g. `current_store.orders` not `Spree::Order`)+- Always use scope fetching for security (e.g. `current_store.orders` not `Spree::Order`). This applies to **every** lookup in a controller, including the incidental ones — resolving a `reason_id` or `stock_location_id` from a create param through the model constant accepts an id belonging to another store. Reading it through `current_store.<association>` turns that into a 404, which is the cheapest defence against IDOR. `accessible_by(current_ability, ...)` is not a substitute: it filters by role, not by tenant.- Ransack for filtering/searching, Pagy for pagination- Use services only when necessary — prefer standard Rails models and concerns- DO NOT call `Spree::User` directly, use `Spree.user_class`; same for `Spree.admin_user_class`diff --git a/docs/plans/decisions.md b/docs/plans/decisions.mdindex 7fd1918e76..21ae217323 100644--- a/docs/plans/decisions.md+++ b/docs/plans/decisions.md@@ -1,3 +1,31 @@+## 2026-08-06: All three reason vocabularies are store-owned++`ReturnReason`, `ClaimReason` and now `RefundReason` include+`SingleStoreResource`. Name uniqueness moves from global to per-store, so+two stores can each have their own "Damaged" or "Order Canceled".++This is what makes the controller rule enforceable: every reason lookup+reads `current_store.return_reasons` rather than the model constant, so a+prefixed id from another store is a 404 instead of a silent success — the+cheapest defence against IDOR, and now uniform across the returns surface+alongside `current_store.stock_locations`.++Refund reasons carried one wrinkle the others did not. Core looks three+of them up by name (`RETURN_PROCESSING_REASON` and friends) to attach to+refunds it issues itself, and a global `find_or_create_by(name:)` under a+per-store unique index would either find another store's row or create a+storeless one. The class methods therefore take the store explicitly —+`return_processing_reason(store)` — defaulting to `Spree::Current.store`+but never relying on it from a workflow, because a background job or+console session has no current store and would bind the reason to the+wrong one. All four call sites pass the store they already hold.++Existing rows are backfilled by `spree:upgrade:backfill_reason_store_ids`,+registered before `migrate_returns` in the 5.6→6.0 manifest. The+migration only adds the column — data transformations stay in rake tasks,+matching `backfill_delivery_and_stock_store_ids`.++## 2026-08-06: Return shipping labels are carrier output, not return state — cut from 6.0`Spree::Return` briefly carried a `return_label_url` column written by adiff --git a/spree/api/spec/controllers/spree/api/v3/admin/refund_reasons_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/refund_reasons_controller_spec.rbindex b127328cf8..884b466cc8 100644--- a/spree/api/spec/controllers/spree/api/v3/admin/refund_reasons_controller_spec.rb+++ b/spree/api/spec/controllers/spree/api/v3/admin/refund_reasons_controller_spec.rb@@ -21,6 +21,26 @@ RSpec.describe Spree::Api::V3::Admin::RefundReasonsController, type: :controllerto change(Spree::RefundReason, :count).by(1)end+ # The seeded reasons are per store now, so one store's "Return processing"+ # is invisible to another rather than shared.+ describe 'store scoping' do+ let!(:other_store) { create(:store) }+ let!(:other_store_reason) { Spree::RefundReason.return_processing_reason(other_store) }++ it 'excludes another store\'s reason from the listing' do+ get :index, as: :json++ expect(json_response['data'].map { |r| r['id'] }).not_to include(other_store_reason.prefixed_id)+ end++ it 'gives each store its own seeded reason' do+ mine = Spree::RefundReason.return_processing_reason(@default_store)++ expect(mine.id).not_to eq(other_store_reason.id)+ expect(mine.name).to eq(other_store_reason.name)+ end+ end+# Core looks this one up by name to attach to every return refund.context 'with the seeded return-processing reason' dolet!(:locked) { Spree::RefundReason.return_processing_reason }diff --git a/spree/core/app/models/spree/refund_reason.rb b/spree/core/app/models/spree/refund_reason.rbindex 658ef0f563..a43c073178 100644--- a/spree/core/app/models/spree/refund_reason.rb+++ b/spree/core/app/models/spree/refund_reason.rb@@ -1,27 +1,51 @@module Spree+ # Why money went back — "Return processing", "Order Canceled". Store-owned+ # like {Spree::ReturnReason} and {Spree::ClaimReason}.class RefundReason < Spree.base_classhas_prefix_id :rrinclude Spree::NamedType+ include Spree::SingleStoreResource++ # Names are unique per store, not globally — two stores can each have+ # their own "Order Canceled" without colliding.+ validates :name, uniqueness: { case_sensitive: false, scope: :store_id }self.whitelisted_ransackable_attributes = %w[name active mutable]- RETURN_PROCESSING_REASON = 'Return processing'- ORDER_CANCELED_REASON = 'Order Canceled'- SHIPMENT_CANCELED_REASON = 'Shipment Canceled'+ RETURN_PROCESSING_REASON = 'Return processing'.freeze+ ORDER_CANCELED_REASON = 'Order Canceled'.freeze+ SHIPMENT_CANCELED_REASON = 'Shipment Canceled'.freezehas_many :refunds, dependent: :restrict_with_error- def self.return_processing_reason- find_or_create_by(name: RETURN_PROCESSING_REASON, mutable: false)- end+ class << self+ # The seeded reasons core attaches to refunds it issues itself.+ #+ # Each takes the store explicitly rather than reading+ # `Spree::Current.store`: these are called from workflows that already+ # hold the record's store, and a background job or console session has+ # no current store to fall back on — which would silently create the+ # reason against the wrong one.+ def return_processing_reason(store = Spree::Current.store)+ seeded(RETURN_PROCESSING_REASON, store)+ end- def self.order_canceled_reason- find_or_create_by(name: ORDER_CANCELED_REASON, mutable: false)- end+ def order_canceled_reason(store = Spree::Current.store)+ seeded(ORDER_CANCELED_REASON, store)+ end++ def shipment_canceled_reason(store = Spree::Current.store)+ seeded(SHIPMENT_CANCELED_REASON, store)+ end++ private- def self.shipment_canceled_reason- find_or_create_by(name: SHIPMENT_CANCELED_REASON, mutable: false)+ def seeded(name, store)+ where(store: store).find_or_create_by(name: name) do |reason|+ reason.mutable = false+ end+ endendendenddiff --git a/spree/core/app/models/spree/store.rb b/spree/core/app/models/spree/store.rbindex c0f29d6582..28b5801347 100644--- a/spree/core/app/models/spree/store.rb+++ b/spree/core/app/models/spree/store.rb@@ -84,6 +84,7 @@ module Spreehas_many :claims, class_name: 'Spree::Claim', inverse_of: :storehas_many :return_reasons, class_name: 'Spree::ReturnReason', inverse_of: :store, dependent: :destroyhas_many :claim_reasons, class_name: 'Spree::ClaimReason', inverse_of: :store, dependent: :destroy+ has_many :refund_reasons, class_name: 'Spree::RefundReason', inverse_of: :store, dependent: :destroy# :nullify (not :destroy) — clearing the collection must not cascade into# Promotion#not_used? / payment records; orphaned rows are detached, not deleted.diff --git a/spree/core/app/services/spree/seeds/returns_environment.rb b/spree/core/app/services/spree/seeds/returns_environment.rbindex 77514b36d6..fe989f5312 100644--- a/spree/core/app/services/spree/seeds/returns_environment.rb+++ b/spree/core/app/services/spree/seeds/returns_environment.rb@@ -26,13 +26,13 @@ module Spree].freezedef call- # Through the model helper, not a literal — the workflows look this- # row up by the same constant, so a hard-coded string here would- # silently create a second, unfindable reason if the name ever moves.- Spree::RefundReason.return_processing_reason-- # Reasons are store-owned, so every store gets its own vocabulary.+ # All three vocabularies are store-owned, so every store gets its own.Spree::Store.all.find_each do |store|+ # Through the model helper, not a literal — the workflows look this+ # row up by the same constant, so a hard-coded string here would+ # silently create a second, unfindable reason if the name ever moves.+ Spree::RefundReason.return_processing_reason(store)+RETURN_REASONS.each { |name| Spree::ReturnReason.where(store: store).find_or_create_by!(name: name) }CLAIM_REASONS.each { |name| Spree::ClaimReason.where(store: store).find_or_create_by!(name: name) }enddiff --git a/spree/core/app/workflows/spree/claims/resolve.rb b/spree/core/app/workflows/spree/claims/resolve.rbindex 925ba7eaa9..fd28f09cf2 100644--- a/spree/core/app/workflows/spree/claims/resolve.rb+++ b/spree/core/app/workflows/spree/claims/resolve.rb@@ -142,7 +142,7 @@ module Spree@refunds << payment.refunds.create!(amount: creditable,- reason: Spree::RefundReason.return_processing_reason,+ reason: Spree::RefundReason.return_processing_reason(claim.store),refunder: resolver,originator: claim)diff --git a/spree/core/app/workflows/spree/exchanges/fulfill.rb b/spree/core/app/workflows/spree/exchanges/fulfill.rbindex a50c1bc02e..043ed479f0 100644--- a/spree/core/app/workflows/spree/exchanges/fulfill.rb+++ b/spree/core/app/workflows/spree/exchanges/fulfill.rb@@ -121,7 +121,7 @@ module Spree@refunds << payment.refunds.create!(amount: creditable,- reason: Spree::RefundReason.return_processing_reason,+ reason: Spree::RefundReason.return_processing_reason(exchange.store),refunder: refunder,originator: exchange)diff --git a/spree/core/app/workflows/spree/payments/refund.rb b/spree/core/app/workflows/spree/payments/refund.rbindex e5d6a69219..ce34ff2b4e 100644--- a/spree/core/app/workflows/spree/payments/refund.rb+++ b/spree/core/app/workflows/spree/payments/refund.rb@@ -61,7 +61,7 @@ module Spreedef issue_refund@refund = payment.refunds.create!(amount: @amount_to_refund,- reason: reason || Spree::RefundReason.return_processing_reason,+ reason: reason || Spree::RefundReason.return_processing_reason(payment.order&.store),refunder: refunder)rescue Spree::Core::GatewayError => errordiff --git a/spree/core/app/workflows/spree/returns/refund.rb b/spree/core/app/workflows/spree/returns/refund.rbindex 3beeac5fcd..bc25d56631 100644--- a/spree/core/app/workflows/spree/returns/refund.rb+++ b/spree/core/app/workflows/spree/returns/refund.rb@@ -107,7 +107,7 @@ module Spree@refunds << payment.refunds.create!(amount: creditable,- reason: Spree::RefundReason.return_processing_reason,+ reason: Spree::RefundReason.return_processing_reason(return_record.store),refunder: refunder,originator: return_record)diff --git a/spree/core/db/migrate/20260805100001_rename_return_authorization_reasons_to_return_reasons.rb b/spree/core/db/migrate/20260805100001_rename_return_authorization_reasons_to_return_reasons.rbindex ea6f7e2ec3..685fb52596 100644--- a/spree/core/db/migrate/20260805100001_rename_return_authorization_reasons_to_return_reasons.rb+++ b/spree/core/db/migrate/20260805100001_rename_return_authorization_reasons_to_return_reasons.rb@@ -17,10 +17,23 @@ class RenameReturnAuthorizationReasonsToReturnReasons < ActiveRecord::Migration[# Store-owned like every other reason vocabulary, so two stores can each# have their own "Damaged" without colliding. The uniqueness scope moves# with it: name is unique per store, not globally.+ #+ # Refund reasons join them: all three answer "why", differ only in which+ # record they explain, and a single-store install can't tell the+ # difference.+ #+ # Existing rows are backfilled by `spree:backfill_reason_store_ids`, not+ # here — data transformations belong in a rake task. That matters more+ # than usual for refund reasons: core looks three of them up by name, so+ # until the task runs those lookups see a null store_id and would mint a+ # duplicate per store.add_reference :spree_return_reasons, :store+ add_reference :spree_refund_reasons, :storeremove_index :spree_return_reasons, :name+ remove_index :spree_refund_reasons, :nameadd_index :spree_return_reasons, [:store_id, :name], unique: true+ add_index :spree_refund_reasons, [:store_id, :name], unique: trueadd_index :spree_claim_reasons, [:store_id, :name], unique: trueendenddiff --git a/spree/core/lib/spree/testing_support/factories/refund_factory.rb b/spree/core/lib/spree/testing_support/factories/refund_factory.rbindex 7cd93a93d8..88ba082066 100644--- a/spree/core/lib/spree/testing_support/factories/refund_factory.rb+++ b/spree/core/lib/spree/testing_support/factories/refund_factory.rb@@ -15,6 +15,7 @@ FactoryBot.define doendfactory :refund_reason, class: Spree::RefundReason do+ store { Spree::Store.find_by(default: true) || association(:store) }sequence(:name) { |n| "Refund for return #{n}" }active { true }mutable { false }diff --git a/spree/core/lib/spree/upgrades/5_6_to_6_0/manifest.yml b/spree/core/lib/spree/upgrades/5_6_to_6_0/manifest.ymlindex b292ae2f5a..eae71080c9 100644--- a/spree/core/lib/spree/upgrades/5_6_to_6_0/manifest.yml+++ b/spree/core/lib/spree/upgrades/5_6_to_6_0/manifest.yml@@ -130,6 +130,17 @@ steps:migration. spree_adjustments stays intact as the rollback source.Idempotent — orders that already have typed rows are skipped.+ - id: backfill_reason_store_ids+ name: "Bind return and refund reasons to the default store"+ task: "spree:upgrade:backfill_reason_store_ids"+ notes: |+ Return and refund reasons are store-owned in Spree 6. Unassigned rows go+ to the default store; additional stores manage their own afterwards.++ Run before migrate_returns. Core looks three refund reasons up by name+ scoped to a store, so until every row carries one those lookups miss and+ mint a duplicate on the next refund. Idempotent.+- id: migrate_returnsname: "Move returns onto the new returns models"task: "spree:upgrade:migrate_returns"diff --git a/spree/core/lib/tasks/backfill_reason_store_ids.rake b/spree/core/lib/tasks/backfill_reason_store_ids.rakenew file mode 100644index 0000000000..6d26452aec--- /dev/null+++ b/spree/core/lib/tasks/backfill_reason_store_ids.rake@@ -0,0 +1,27 @@+namespace :spree do+ namespace :upgrade do+ desc <<~DESC+ Assigns the default store to return and refund reasons that predate+ their store binding (Spree 6.0). Idempotent — rows that already carry a+ store_id are skipped.++ Run this immediately after db:migrate. Core looks three refund reasons+ up by name (RefundReason::RETURN_PROCESSING_REASON and friends) scoped+ to a store, so until every row carries one those lookups miss and mint+ a duplicate on the next refund.++ Claim reasons need no backfill — the table is new in 6.0 and its rows+ are born with a store.+ DESC+ task backfill_reason_store_ids: :environment do+ store = Spree::Store.default+ abort ' No default store found — create a store first.' if store.nil?++ return_reasons = Spree::ReturnReason.where(store_id: nil).update_all(store_id: store.id)+ refund_reasons = Spree::RefundReason.where(store_id: nil).update_all(store_id: store.id)++ puts " Assigned #{return_reasons} return reason(s) and #{refund_reasons} refund reason(s) " \+ "to store #{store.name} (#{store.id})."+ end+ end+end