spree_core 5.6.1 → 6.0.0.beta2

data/app/models/spree/promotion_handler/promotion_duplicator.rb

@@ -31,7 +31,7 @@ module Spree
           new_rule.save!
 
           new_rule.users = rule.users if rule.try(:users)
-          new_rule.taxons = rule.taxons if rule.try(:taxons)
+          new_rule.categories = rule.categories if rule.try(:categories)
           new_rule.products = rule.products if rule.try(:products)
         end
       end

data/app/models/spree/promotion_rule.rb

@@ -3,23 +3,16 @@ module Spree
   class PromotionRule < Spree.base_class
     has_prefix_id :prorule
 
+    registers_subclasses_via { Spree.promotions.rules }
+
     belongs_to :promotion, class_name: 'Spree::Promotion', inverse_of: :promotion_rules, touch: true
 
     delegate :stores, to: :promotion
 
     scope :of_type, ->(t) { where(type: t) }
 
-    validates :promotion, presence: true
     validates :type, uniqueness: { scope: [:promotion_id, *spree_base_uniqueness_scope] }
 
-    # Per-subclass permitted attributes beyond `type` and `preferences`.
-    # Override in STI subclasses that accept association IDs (e.g.
-    # Rules::Product needs `product_ids`). The Admin API merges these
-    # into its `params.permit(...)` allowlist.
-    def self.additional_permitted_attributes
-      []
-    end
-
     def self.for(promotable)
       all.select { |rule| rule.applicable?(promotable) }
     end

data/app/models/spree/promotion_rule_category.rb

@@ -0,0 +1,22 @@
+module Spree
+  # Join model between a Spree::Promotion::Rules::Category rule and a
+  # Spree::Category. Renamed from Spree::PromotionRuleTaxon in 6.0 (alias kept for
+  # one release).
+  class PromotionRuleCategory < Spree.base_class
+    belongs_to :promotion_rule, class_name: 'Spree::PromotionRule'
+    belongs_to :category, class_name: 'Spree::Category'
+
+    validates :promotion_rule_id, uniqueness: { scope: :category_id }, allow_nil: true
+
+    # @deprecated Use #category / #category=; removed in 6.1.
+    def taxon
+      Spree::Deprecation.warn('Spree::PromotionRuleCategory#taxon is deprecated and will be removed in Spree 6.1. Use #category instead.')
+      category
+    end
+
+    def taxon=(value)
+      Spree::Deprecation.warn('Spree::PromotionRuleCategory#taxon= is deprecated and will be removed in Spree 6.1. Use #category= instead.')
+      self.category = value
+    end
+  end
+end

data/app/models/spree/promotion_rule_taxon.rb

@@ -1,9 +1,10 @@
+# frozen_string_literal: true
+
 module Spree
-  class PromotionRuleTaxon < Spree.base_class
-    belongs_to :promotion_rule, class_name: 'Spree::PromotionRule'
-    belongs_to :taxon, class_name: 'Spree::Taxon'
+  # Deprecation alias for Spree::PromotionRuleCategory, renamed from
+  # Spree::PromotionRuleTaxon in 6.0. A true constant alias (AR-safe); the warning
+  # fires when this file loads. Removed in 6.1.
+  PromotionRuleTaxon = PromotionRuleCategory
 
-    validates :promotion_rule, :taxon, presence: true
-    validates :promotion_rule_id, uniqueness: { scope: :taxon_id }, allow_nil: true
-  end
+  Spree::Deprecation.warn('Spree::PromotionRuleTaxon is deprecated and will be removed in Spree 6.1. Use Spree::PromotionRuleCategory instead.')
 end

data/app/models/spree/promotion_rule_user.rb

@@ -1,9 +1,9 @@
 module Spree
   class PromotionRuleUser < Spree.base_class
     belongs_to :promotion_rule, class_name: 'Spree::PromotionRule'
-    belongs_to :user, class_name: "::#{Spree.user_class}"
+    belongs_to :customer, class_name: "::#{Spree.customer_class}"
+    include Spree::DeprecatedCustomerAlias
 
-    validates :user, :promotion_rule, presence: true
     validates :user_id, uniqueness: { scope: :promotion_rule_id }, allow_nil: true
   end
 end

data/app/models/spree/prototype.rb

@@ -1,15 +1,5 @@
 module Spree
-  class Prototype < Spree.base_class
-    has_prefix_id :proto
-
-    include Spree::Metadata
-
-    has_many :option_type_prototypes, class_name: 'Spree::OptionTypePrototype'
-    has_many :option_types, through: :option_type_prototypes, class_name: 'Spree::OptionType'
-
-    has_many :prototype_taxons, class_name: 'Spree::PrototypeTaxon'
-    has_many :taxons, through: :prototype_taxons, class_name: 'Spree::Taxon'
-
-    validates :name, presence: true
-  end
+  # Constant alias for the legacy Spree::Prototype class, renamed to
+  # Spree::ProductType in 6.0. Remove in 6.1.
+  Prototype = ProductType
 end

data/app/models/spree/purchase_order.rb

@@ -0,0 +1,95 @@
+module Spree
+  # Goods bought from a supplier and expected at one of the merchant's own
+  # warehouses (docs/plans/6.0-inventory-operations.md).
+  #
+  # Replaces the 5.x "external receive" — a {Spree::StockTransfer} with no
+  # source location — with a record that has the things a purchase actually
+  # has: a supplier, a unit cost, an expected date and a number to quote back.
+  #
+  # Ordered units never count toward availability. Nothing here touches
+  # `count_on_hand` until {Spree::PurchaseOrders::Receive} runs, because the
+  # merchant only has the goods once they land.
+  #
+  # Every status change is a workflow — `Spree::PurchaseOrders::Receive`, never
+  # `purchase_order.receive!` — so receiving can take the quantities the
+  # warehouse counted rather than assuming the order arrived intact.
+  class PurchaseOrder < Spree.base_class
+    has_prefix_id :po
+
+    # Before `has_spree_number` — see the note on Spree::StockTransfer.
+    include Spree::SingleStoreResource
+    has_spree_number prefix: 'PO'
+    include Spree::NumberIdentifier
+    include Spree::HasStatus
+    include Spree::Receivable
+    include Spree::HasCustomFields
+    include Spree::Metadata
+
+    publishes_lifecycle_events
+
+    has_status :draft, :ordered, :partially_received, :received, :over_received, :canceled,
+               default: :draft
+
+    belongs_to :supplier, class_name: 'Spree::Supplier', inverse_of: :purchase_orders,
+                          counter_cache: true
+    belongs_to :destination_location, class_name: 'Spree::StockLocation'
+    belongs_to :created_by, class_name: Spree.admin_user_class.to_s, optional: true
+
+    has_many :items, class_name: 'Spree::PurchaseOrderItem',
+                     inverse_of: :purchase_order, dependent: :destroy
+    # No `dependent:` — the ledger outlives the record that caused it, the same
+    # reason Spree::Fulfillment gives for its own movements.
+    has_many :stock_movements, class_name: 'Spree::StockMovement', inverse_of: :purchase_order
+
+    accepts_nested_attributes_for :items, allow_destroy: true
+
+    before_validation :ensure_currency
+
+    validates :currency, presence: true
+    validates :items, presence: true, unless: -> { draft? || canceled? }
+
+    # Overdue and past-cancel-by read the calendar date in the server's zone;
+    # a supplier's promise is a day, and a few hours either side of midnight
+    # is not what a merchant is filtering for.
+    scope :overdue, -> { open.where(arel_table[:expected_at].lt(Date.current)) }
+    scope :past_cancel_by, -> { open.where(arel_table[:cancel_by].lt(Date.current)) }
+
+    self.whitelisted_ransackable_attributes = %w[number status currency reference expected_at
+                                                 cancel_by ordered_at received_at closed_short_at
+                                                 supplier_id destination_location_id created_at]
+    self.whitelisted_ransackable_scopes = %w[open closed overdue past_cancel_by]
+    self.whitelisted_ransackable_associations = %w[supplier destination_location items]
+
+    # What the supplier will invoice for everything ordered.
+    #
+    # @return [BigDecimal]
+    def subtotal
+      items.sum(&:total_cost)
+    end
+
+    # @return [Spree::Money]
+    def display_subtotal
+      Spree::Money.new(subtotal, currency: currency)
+    end
+
+    # Whether the merchant may still edit the lines. Once the order is placed
+    # with the supplier, what was ordered is a matter of record.
+    #
+    # @return [Boolean]
+    def editable?
+      draft?
+    end
+
+    def event_serializer_class
+      'Spree::Api::V3::PurchaseOrderEventSerializer'.safe_constantize
+    end
+
+    private
+
+    # A foreign-currency purchase order is legitimate, so this is a default
+    # rather than a derived value: pass `currency` to override it.
+    def ensure_currency
+      self.currency ||= store&.default_currency
+    end
+  end
+end

data/app/models/spree/purchase_order_item.rb

@@ -0,0 +1,40 @@
+module Spree
+  # One SKU on a purchase order: how many were ordered, how many have arrived,
+  # and what the merchant agreed to pay per unit.
+  class PurchaseOrderItem < Spree.base_class
+    has_prefix_id :poi
+
+    include Spree::ReceivableItem
+
+    expects_quantity_in :quantity_ordered
+
+    belongs_to :purchase_order, class_name: 'Spree::PurchaseOrder', inverse_of: :items, touch: true
+
+    validates :quantity_ordered, numericality: { greater_than: 0, only_integer: true }
+    validates :unit_cost, numericality: { greater_than_or_equal_to: 0 }
+    validates :variant_id, uniqueness: { scope: :purchase_order_id }
+
+    delegate :currency, to: :purchase_order, allow_nil: true
+
+    self.whitelisted_ransackable_attributes = %w[variant_id quantity_ordered quantity_received quantity_rejected unit_cost]
+    self.whitelisted_ransackable_associations = %w[variant]
+
+    # What the whole line costs at the agreed unit price. Ordered rather than
+    # received quantity: this is what the supplier will invoice.
+    #
+    # @return [BigDecimal]
+    def total_cost
+      unit_cost.to_d * quantity_ordered.to_i
+    end
+
+    # @return [Spree::Money]
+    def display_unit_cost
+      Spree::Money.new(unit_cost, currency: currency)
+    end
+
+    # @return [Spree::Money]
+    def display_total_cost
+      Spree::Money.new(total_cost, currency: currency)
+    end
+  end
+end

data/app/models/spree/quantity_rule.rb

@@ -0,0 +1,114 @@
+module Spree
+  # A resolved pair of purchasing rules for one variant and one buyer: the
+  # least they may order and the increment they must land on. MOQ 48 with
+  # multiple 24 admits 48, 72, 96 and refuses 50.
+  #
+  # Resolution (variant base -> catalog default -> catalog x variant
+  # override) happens in {Spree::Catalogs::ResolveQuantityRules}; this object
+  # is only the answer and the arithmetic over it, so the same rules apply
+  # identically wherever a quantity is checked or a stepper is drawn.
+  class QuantityRule
+    include ActiveModel::Model
+    include ActiveModel::Attributes
+
+    attribute :minimum_order_quantity, :integer
+    attribute :order_multiple, :integer
+
+    # @return [Integer] the least quantity that may be ordered
+    def minimum
+      value = minimum_order_quantity.to_i
+      value.positive? ? value : 1
+    end
+
+    # @return [Integer] the increment quantities must land on
+    def multiple
+      value = order_multiple.to_i
+      value.positive? ? value : 1
+    end
+
+    # True when neither rule narrows anything — the shape a retail buyer sees,
+    # and what a variant with empty columns resolves to.
+    # @return [Boolean]
+    def unrestricted?
+      minimum == 1 && multiple == 1
+    end
+
+    # @param quantity [Integer]
+    # @return [Boolean]
+    def satisfied_by?(quantity)
+      quantity = quantity.to_i
+      quantity >= minimum && ((quantity - offset) % multiple).zero?
+    end
+
+    # The largest valid quantity at or below the given one, or nil when the
+    # minimum is already above it.
+    # @param quantity [Integer]
+    # @return [Integer, nil]
+    def previous_valid(quantity)
+      quantity = quantity.to_i
+      return nil if quantity < minimum
+
+      quantity - ((quantity - offset) % multiple)
+    end
+
+    # The smallest valid quantity at or above the given one.
+    # @param quantity [Integer]
+    # @return [Integer]
+    def next_valid(quantity)
+      quantity = quantity.to_i
+      return minimum if quantity <= minimum
+
+      remainder = (quantity - offset) % multiple
+      remainder.zero? ? quantity : quantity + (multiple - remainder)
+    end
+
+    # The valid quantities either side of an invalid one, used to tell a buyer
+    # what they may order instead. Both are present unless the quantity is
+    # below the minimum, where there is nothing lower to offer.
+    #
+    # @param quantity [Integer]
+    # @return [Array<Integer>] one or two ascending quantities
+    def nearest_valid(quantity)
+      [previous_valid(quantity), next_valid(quantity)].compact.uniq
+    end
+
+    # Why a quantity was refused, naming what may be ordered instead — nil
+    # when the quantity is fine. Lives here beside the arithmetic so the two
+    # cart workflows and the completion check all refuse in the same words;
+    # the server never rounds, so the neighbours are the whole answer.
+    #
+    # @param name [String] what the buyer called for
+    # @param quantity [Integer]
+    # @return [String, nil]
+    def violation_message(name, quantity)
+      return nil if satisfied_by?(quantity)
+
+      Spree.t('cart_line_item.quantity_rule_violated',
+              li_name: name, quantities: nearest_valid(quantity).to_sentence)
+    end
+
+    # Steps are counted from a DECLARED minimum rather than from zero, so a
+    # rule of "at least 50, in 24s" offers 50 / 74 / 98 instead of refusing
+    # its own minimum.
+    #
+    # Only a declared one: the implicit minimum of 1 is the absence of a rule,
+    # and letting it set the offset would turn "sold in packs of 5" into
+    # 1 / 6 / 11, refusing a buyer who orders exactly one pack. A minimum that
+    # already sits on the multiple leaves this at 0 either way, and the
+    # arithmetic is the plain modulo it looks like.
+    def offset
+      return 0 unless minimum_order_quantity.to_i.positive?
+
+      minimum % multiple
+    end
+
+    def ==(other)
+      other.is_a?(self.class) && minimum == other.minimum && multiple == other.multiple
+    end
+    alias eql? ==
+
+    def hash
+      [minimum, multiple].hash
+    end
+  end
+end

data/app/models/spree/refresh_token.rb

@@ -7,10 +7,18 @@ module Spree
     has_secure_token :token
 
     validates :user, :expires_at, presence: true
+    # On create only: rows minted before the column exists keep their NULL and
+    # stay loadable (they are simply unredeemable), while nothing new is born
+    # without the surface it belongs to.
+    validates :audience, presence: true, on: :create
 
     scope :active, -> { where('expires_at > ?', Time.current) }
     scope :expired, -> { where('expires_at <= ?', Time.current) }
 
+    # Tokens minted for one API surface. Always narrow a refresh lookup with
+    # this — a token is only redeemable on the surface that issued it.
+    scope :for_audience, ->(audience) { where(audience: audience) }
+
     def expired?
       expires_at <= Time.current
     end
@@ -22,6 +30,7 @@ module Spree
       transaction do
         new_token = self.class.create!(
           user: user,
+          audience: audience,
           expires_at: self.class.default_expiry.from_now,
           ip_address: request_env[:ip_address] || ip_address,
           user_agent: request_env[:user_agent] || user_agent
@@ -31,10 +40,19 @@ module Spree
       new_token
     end
 
-    # Create a refresh token for a user
-    def self.create_for(user, request_env: {})
+    # Create a refresh token for a user.
+    #
+    # @param user [Object] the principal the token authenticates
+    # @param audience [String] the API surface the token may be redeemed on
+    #   (`Spree::Api::V3::JwtAuthentication::JWT_AUDIENCE_ADMIN` and friends).
+    #   Required: every redemption path narrows by audience, so an unstamped
+    #   token authenticates a login and then fails its first refresh.
+    # @param request_env [Hash]
+    # @return [Spree::RefreshToken]
+    def self.create_for(user, audience:, request_env: {})
       create!(
         user: user,
+        audience: audience,
         expires_at: default_expiry.from_now,
         ip_address: request_env[:ip_address],
         user_agent: request_env[:user_agent]

data/app/models/spree/refund.rb

@@ -2,39 +2,45 @@ module Spree
   class Refund < Spree.base_class
     has_prefix_id :re  # Stripe: re_
 
-    include Spree::Metafields
+    include Spree::ActedBy
+    include Spree::HasCustomFields
     include Spree::Metadata
+    include Spree::InstrumentsGatewayCalls
     if defined?(Spree::Security::Refunds)
       include Spree::Security::Refunds
     end
 
     publishes_lifecycle_events
 
-    with_options inverse_of: :refunds do
-      belongs_to :payment
-      belongs_to :reimbursement, optional: true
-    end
+    belongs_to :payment, inverse_of: :refunds
+    # Which order is being put right. A refund against an ordinary payment
+    # takes the payment's order automatically; one against a payment shared by
+    # a split checkout must name the child order it applies to, since the
+    # payment covers several and only one of them is being refunded.
+    belongs_to :order, class_name: 'Spree::Order', optional: true, inverse_of: :refunds
     belongs_to :reason, class_name: 'Spree::RefundReason', foreign_key: :refund_reason_id
-    belongs_to :refunder, class_name: Spree.admin_user_class.to_s, optional: true
-
-    has_many :log_entries, as: :source
+    acted_by :refunder
+    # What triggered this refund — a Spree::Return today, later an Exchange
+    # or Claim; nil for a manual refund. Deliberately polymorphic: the set is
+    # small and closed, and refunds are never bulk-queried in a hot path.
+    belongs_to :originator, polymorphic: true, optional: true
 
     with_options presence: true do
-      validates :payment, :reason
-      # can't require this on create because the perform! in after_create needs to run first
+      # not required on create — perform! sets it after the gateway credit
       validates :transaction_id, on: :update
       validates :amount, numericality: { greater_than: 0, allow_nil: true }
     end
     validate :amount_is_less_than_or_equal_to_allowed_amount, on: :create, if: :amount
-
-    after_create :perform!
-    after_create :create_log_entry
-
-    scope :non_reimbursement, -> { where(reimbursement_id: nil) }
+    validate :order_is_covered_by_payment, on: :create
 
     attr_reader :response
 
-    delegate :order, :currency, to: :payment
+    delegate :currency, to: :payment
+
+    # A refund always knows its order, so every reader — the scopes, the
+    # ledger, the split's share — can rely on the column rather than walking
+    # back through a payment that may belong to several orders.
+    before_validation :assign_order_from_payment, on: :create
 
     def amount=(amount)
       self[:amount] = Spree::LocalizedNumber.parse(amount)
@@ -45,36 +51,48 @@ module Spree
     end
     alias display_amount money
 
-    class << self
-      def total_amount_reimbursed_for(reimbursement)
-        reimbursement.refunds.to_a.sum(&:amount)
-      end
-    end
-
     def description
       payment.payment_method.name
     end
 
-    # return items for the refund
+    # The lines this refund paid for, when it came from a return.
+    #
+    # @return [Array<Spree::ReturnLineItem>]
+    def return_line_items
+      return [] unless originator.is_a?(Spree::Return)
+
+      originator.return_line_items.to_a
+    end
+
+    # What this refund paid for, line by line, when whatever caused it can say.
+    # Empty for a manual refund or a cancellation, which name no originator, and
+    # for an exchange, whose credit is a net price difference across the swap
+    # rather than the value of the units that came back.
     #
-    # @return [Array<Spree::ReturnItem>]
-    def return_items
-      return [] unless reimbursement.present?
+    # @return [Hash{Integer => BigDecimal}] line item id => amount
+    def refunded_line_amounts
+      return {} unless originator.respond_to?(:refunded_line_amounts)
 
-      reimbursement.customer_return&.return_items || reimbursement.return_items
+      originator.refunded_line_amounts
     end
 
     # Returns true if the refund is editable.
     #
+    # Read through the refund's own order: a payment shared by a split checkout
+    # belongs to no single order, so asking the payment would answer nil.
+    #
     # @return [Boolean]
     def editable?
-      !payment.order.canceled?
+      order.present? && !order.canceled?
     end
 
-    private
-
-    # attempts to perform the refund.
-    # raises an error if the refund fails.
+    # Credits the refund back at the gateway — the money movement, called
+    # explicitly from a workflow's external_step, never from a callback. A
+    # blank transaction_id means the credit has not happened yet; a present
+    # one makes this a no-op, so replays are safe.
+    #
+    # @raise [Spree::Core::GatewayError] when the gateway declines or is down
+    # @return [true]
     def perform!
       return true if transaction_id.present?
 
@@ -85,17 +103,54 @@ module Spree
       self.transaction_id = @response.authorization
       update_columns(transaction_id: transaction_id)
       update_order
+      true
+    end
+
+    private
+
+    # A payment belonging to one order answers this for itself; a payment
+    # shared by a split checkout cannot, so the caller has to have said which
+    # order it is refunding.
+    def assign_order_from_payment
+      self.order_id ||= payment&.order_id
+    end
+
+    # A refund may only put right an order the payment actually paid for.
+    # Without this a caller can name any order: the gateway credits this
+    # payment while the totals of an unrelated one are recomputed, and on a
+    # shared payment the share that should have recorded the refund is never
+    # found.
+    def order_is_covered_by_payment
+      return if payment.blank?
+
+      # A shared payment cannot say which of its orders is being put right, so
+      # the caller has to — and nothing can fill it in afterwards. Left blank,
+      # the gateway would be credited while no child's totals or share moved.
+      if order_id.blank?
+        errors.add(:order, :blank) if payment.grouped?
+        return
+      end
+
+      covered = if payment.grouped?
+                  payment.payment_splits.exists?(order_id: order_id)
+                else
+                  payment.order_id == order_id
+                end
+
+      errors.add(:order, :invalid) unless covered
     end
 
     # return a payment response object if successful or else raise an error
     def process!(credit_cents)
       refund_total_in_cents = calculate_refund_amount(credit_cents)
 
-      response = if payment.payment_method.payment_profiles_supported?
-                   payment.payment_method.credit(refund_total_in_cents, payment.source, payment.transaction_id, originator: self)
-                 else
-                   payment.payment_method.credit(refund_total_in_cents, payment.transaction_id, originator: self)
-                 end
+      response = instrument_gateway_call(:credit, payment.payment_method) do
+        if payment.payment_method.payment_profiles_supported?
+          payment.payment_method.credit(refund_total_in_cents, payment.source, payment.transaction_id, originator: self)
+        else
+          payment.payment_method.credit(refund_total_in_cents, payment.transaction_id, originator: self)
+        end
+      end
 
       if response.success?
         track_order_as_refunded(refund_total_in_cents)
@@ -120,18 +175,17 @@ module Spree
       # You can track refunds here
     end
 
-    def create_log_entry
-      log_entries.create!(details: @response.to_yaml)
-    end
-
     def amount_is_less_than_or_equal_to_allowed_amount
       if amount > payment.credit_allowed
         errors.add(:amount, :greater_than_allowed)
       end
     end
 
+    # Re-sums the order this refund put right. Read through the refund's own
+    # order rather than the payment's: a payment shared by a split checkout
+    # belongs to no single order, and it is this one order's money that moved.
     def update_order
-      payment.order.updater.update
+      order&.recalculate_totals!
     end
   end
 end

data/app/models/spree/refund_reason.rb

@@ -1,25 +1,46 @@
 module Spree
+  # Why money went back — "Return processing", "Order Canceled". Store-owned
+  # like {Spree::ReturnReason} and {Spree::ClaimReason}.
   class RefundReason < Spree.base_class
     has_prefix_id :rr
 
     include Spree::NamedType
 
-    RETURN_PROCESSING_REASON = 'Return processing'
-    ORDER_CANCELED_REASON = 'Order Canceled'
-    SHIPMENT_CANCELED_REASON = 'Shipment Canceled'
+    self.whitelisted_ransackable_attributes = %w[name active]
 
-    has_many :refunds, dependent: :restrict_with_error
+    RETURN_PROCESSING_REASON = 'Return processing'.freeze
+    ORDER_CANCELED_REASON = 'Order Canceled'.freeze
+    SHIPMENT_CANCELED_REASON = 'Shipment Canceled'.freeze
 
-    def self.return_processing_reason
-      find_or_create_by(name: RETURN_PROCESSING_REASON, mutable: false)
-    end
+    has_many :refunds, class_name: 'Spree::Refund', dependent: :restrict_with_error
 
-    def self.order_canceled_reason
-      find_or_create_by(name: ORDER_CANCELED_REASON, mutable: false)
+    # Mirrors what `dependent: :restrict_with_error` enforces, so the dashboard
+    # can hide the delete control rather than offer one the model will refuse.
+    #
+    # @return [Boolean]
+    def can_be_deleted?
+      !refunds.exists?
     end
 
-    def self.shipment_canceled_reason
-      find_or_create_by(name: SHIPMENT_CANCELED_REASON, mutable: false)
+    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)
+        where(store: store).find_or_create_by(name: RETURN_PROCESSING_REASON)
+      end
+
+      def order_canceled_reason(store = Spree::Current.store)
+        where(store: store).find_or_create_by(name: ORDER_CANCELED_REASON)
+      end
+
+      def shipment_canceled_reason(store = Spree::Current.store)
+        where(store: store).find_or_create_by(name: SHIPMENT_CANCELED_REASON)
+      end
     end
   end
 end