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.

Add Return and ReturnLineItem as first-class models

Damian Legawiec60313ffedc5d
diff --git a/spree/core/app/models/concerns/spree/has_status.rb b/spree/core/app/models/concerns/spree/has_status.rb
new file mode 100644
index 0000000000..f6203876e4
--- /dev/null
+++ b/spree/core/app/models/concerns/spree/has_status.rb
@@ -0,0 +1,65 @@
+module Spree
+ # Declarative status column for models whose transitions belong to workflows
+ # rather than a state machine (docs/plans/6.0-service-workflows.md,
+ # decision 11).
+ #
+ # class Spree::Return < Spree.base_class
+ # include Spree::HasStatus
+ # has_status :requested, :approved, :received, :refunded, :canceled,
+ # default: :requested
+ # end
+ #
+ # Generates an inclusion validation, a predicate per value (`#received?`)
+ # and a scope per value (`.received`) — nothing else. There are no events,
+ # no transition graph and no callbacks: moving a record between statuses is
+ # a workflow's job, which is what lets a transition take arguments, perform
+ # gateway I/O outside a transaction, and compensate when a later step fails.
+ #
+ # Values live in a class_attribute rather than a frozen constant so an
+ # extension can add its own without reopening core.
+ module HasStatus
+ extend ActiveSupport::Concern
+
+ class_methods do
+ # @param values [Array<Symbol, String>] the valid statuses, in order
+ # @param default [Symbol, String] applied by the creating workflow —
+ # never a database default (see the migration rules in CLAUDE.md)
+ def has_status(*values, default:)
+ values = values.map(&:to_s)
+
+ class_attribute :statuses, default: values, instance_writer: false
+ class_attribute :default_status, default: default.to_s, instance_writer: false
+
+ validates :status, inclusion: { in: ->(record) { record.class.statuses } }
+
+ values.each { |value| define_status_methods(value) }
+ end
+
+ # Appends a status. Additive by design: core workflows guard on core
+ # statuses (`Returns::Refund` requires `received?`), so allowing removal
+ # would silently break those guards — they would simply never pass.
+ #
+ # A custom status needs a custom workflow to move records into it. That
+ # is deliberate rather than a gap: validating transitions centrally
+ # would be a state machine by another name.
+ #
+ # @param value [Symbol, String]
+ # @param after [Symbol, String, nil] position in the list; appended when nil
+ def add_status(value, after: nil)
+ value = value.to_s
+ return if statuses.include?(value)
+
+ index = after ? statuses.index(after.to_s)&.succ : nil
+ self.statuses = statuses.dup.insert(index || statuses.size, value)
+ define_status_methods(value)
+ end
+
+ private
+
+ def define_status_methods(value)
+ define_method(:"#{value}?") { status == value }
+ scope value, -> { where(status: value) }
+ end
+ end
+ end
+end
diff --git a/spree/core/app/models/spree/order.rb b/spree/core/app/models/spree/order.rb
index 14564fb642..3b00c0fff4 100644
--- a/spree/core/app/models/spree/order.rb
+++ b/spree/core/app/models/spree/order.rb
@@ -163,6 +163,7 @@ module Spree
has_many :payments, class_name: 'Spree::Payment'
has_many :payment_sessions, inverse_of: :order, class_name: 'Spree::PaymentSession'
has_many :return_authorizations, inverse_of: :order, class_name: 'Spree::ReturnAuthorization'
+ has_many :returns, -> { order(:created_at) }, inverse_of: :order, class_name: 'Spree::Return'
has_many :cancellations, -> { order(:created_at) }, inverse_of: :order, class_name: 'Spree::OrderCancellation'
has_many :approvals, -> { order(:created_at) }, inverse_of: :order, class_name: 'Spree::OrderApproval'
end
diff --git a/spree/core/app/models/spree/refund.rb b/spree/core/app/models/spree/refund.rb
index e7764693ea..906f07b65e 100644
--- a/spree/core/app/models/spree/refund.rb
+++ b/spree/core/app/models/spree/refund.rb
@@ -16,6 +16,10 @@ module Spree
end
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
+ # 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
has_many :log_entries, as: :source
diff --git a/spree/core/app/models/spree/return.rb b/spree/core/app/models/spree/return.rb
new file mode 100644
index 0000000000..69d27be127
--- /dev/null
+++ b/spree/core/app/models/spree/return.rb
@@ -0,0 +1,69 @@
+module Spree
+ # A customer sends items back and gets their money back.
+ #
+ # Replaces the ReturnAuthorization → CustomerReturn → Reimbursement chain
+ # with one record that owns the whole operation
+ # (docs/plans/6.0-returns-exchanges-claims.md). The legacy chain still
+ # exists and is untouched; this is the surface new code should use.
+ #
+ # The model holds associations, validations and pure reads only. Every
+ # transition is a workflow — `Spree::Returns::Receive.call(...)`, never
+ # `return.receive!` — so receiving can take the quantities the warehouse
+ # actually counted, and refunding can call a payment gateway outside the
+ # transaction that writes the status.
+ class Return < Spree.base_class
+ has_prefix_id :ret
+
+ include Spree::Core::NumberGenerator.new(prefix: 'RET', length: 9)
+ include Spree::NumberIdentifier
+ include Spree::SingleStoreResource
+ include Spree::HasStatus
+ include Spree::Metadata
+
+ publishes_lifecycle_events
+
+ has_status :requested, :approved, :received, :refunded, :canceled,
+ default: :requested
+
+ belongs_to :store, class_name: 'Spree::Store'
+ belongs_to :order, class_name: 'Spree::Order', inverse_of: :returns
+ belongs_to :stock_location, class_name: 'Spree::StockLocation'
+ belongs_to :reason, class_name: 'Spree::ReturnAuthorizationReason', optional: true
+ # Staff only. Customer-initiated returns leave this nil — the requester
+ # is always order.customer, so no second association is needed.
+ belongs_to :created_by, class_name: Spree.admin_user_class.to_s, optional: true
+
+ has_many :return_line_items, class_name: 'Spree::ReturnLineItem',
+ dependent: :destroy, inverse_of: :return
+ has_many :refunds, class_name: 'Spree::Refund', as: :originator, dependent: :nullify
+
+ validates :order, :stock_location, presence: true
+ validates :return_line_items, presence: true, on: :create
+
+ accepts_nested_attributes_for :return_line_items, allow_destroy: true
+
+ delegate :currency, to: :order
+
+ self.whitelisted_ransackable_attributes = %w[number status created_at]
+ self.whitelisted_ransackable_associations = %w[order reason]
+
+ # What the customer is owed for the items being returned.
+ def refund_total
+ return_line_items.sum(&:pre_tax_amount)
+ end
+
+ # What has actually been refunded so far — a return can be refunded in
+ # more than one step (part to store credit, part to the card).
+ def refunded_total
+ refunds.sum(:amount)
+ end
+
+ def refundable_total
+ refund_total - refunded_total
+ end
+
+ def display_refund_total
+ Spree::Money.new(refund_total, currency: currency)
+ end
+ end
+end
diff --git a/spree/core/app/models/spree/return_line_item.rb b/spree/core/app/models/spree/return_line_item.rb
new file mode 100644
index 0000000000..77d5f27093
--- /dev/null
+++ b/spree/core/app/models/spree/return_line_item.rb
@@ -0,0 +1,44 @@
+module Spree
+ # One line on a {Spree::Return} — a quantity of a fulfilled item coming back.
+ #
+ # Named ReturnLineItem rather than ReturnItem because the legacy
+ # Spree::ReturnItem (part of the ReturnAuthorization chain) is still in
+ # service; the two coexist until the legacy chain is dropped.
+ class ReturnLineItem < Spree.base_class
+ has_prefix_id :rli
+
+ belongs_to :return, class_name: 'Spree::Return', inverse_of: :return_line_items
+ belongs_to :fulfillment_item, class_name: 'Spree::FulfillmentItem'
+ belongs_to :line_item, class_name: 'Spree::LineItem'
+ belongs_to :variant, -> { with_deleted }, class_name: 'Spree::Variant'
+
+ validates :fulfillment_item, :line_item, :variant, presence: true
+ validates :quantity, numericality: { greater_than: 0 }
+ validates :received_quantity, numericality: { greater_than_or_equal_to: 0 }
+ validates :pre_tax_amount, numericality: { greater_than_or_equal_to: 0 }
+
+ before_validation :set_defaults_from_line_item, on: :create
+
+ delegate :order, :currency, to: :return
+
+ def display_pre_tax_amount
+ Spree::Money.new(pre_tax_amount, currency: currency)
+ end
+
+ private
+
+ # The refundable amount defaults to this item's share of what the
+ # customer actually paid for the line, after discounts — refunding the
+ # list price would give back more than was taken.
+ def set_defaults_from_line_item
+ self.variant ||= line_item&.variant
+ self.pre_tax_amount = default_pre_tax_amount if pre_tax_amount.blank? || pre_tax_amount.zero?
+ end
+
+ def default_pre_tax_amount
+ return 0 if line_item.nil? || line_item.quantity.to_i.zero?
+
+ (line_item.amount / line_item.quantity) * quantity.to_i
+ end
+ end
+end
diff --git a/spree/core/db/migrate/20260802190001_create_spree_returns.rb b/spree/core/db/migrate/20260802190001_create_spree_returns.rb
new file mode 100644
index 0000000000..e62b36f4b8
--- /dev/null
+++ b/spree/core/db/migrate/20260802190001_create_spree_returns.rb
@@ -0,0 +1,50 @@
+class CreateSpreeReturns < ActiveRecord::Migration[8.1]
+ def change
+ create_table :spree_returns do |t|
+ t.string :number, null: false
+ t.references :store, null: false
+ t.references :order, null: false
+ t.references :stock_location, null: false
+ t.references :reason
+ # Staff only — customer-initiated returns leave this nil, the
+ # requester is always order.customer.
+ t.references :created_by
+ t.string :status, null: false
+ t.text :memo
+ t.string :return_label_url
+ t.datetime :approved_at
+ t.datetime :received_at
+ t.datetime :refunded_at
+ t.datetime :canceled_at
+ if t.respond_to?(:jsonb)
+ t.jsonb :metadata
+ else
+ t.json :metadata
+ end
+ t.timestamps
+ end
+
+ add_index :spree_returns, :number, unique: true
+ add_index :spree_returns, :status
+
+ create_table :spree_return_line_items do |t|
+ t.references :return, null: false
+ t.references :fulfillment_item, null: false
+ t.references :line_item, null: false
+ t.references :variant, null: false
+ t.integer :quantity, null: false, default: 1
+ t.integer :received_quantity, null: false, default: 0
+ t.decimal :pre_tax_amount, precision: 10, scale: 2, null: false, default: 0
+ t.boolean :resellable, null: false, default: true
+ t.timestamps
+ end
+
+ # Who triggered a refund: a Return, and later an Exchange or Claim.
+ # Small closed set, never bulk-queried in a hot path — the one
+ # intentional polymorphic association in this area.
+ add_column :spree_refunds, :originator_type, :string
+ add_column :spree_refunds, :originator_id, :bigint
+ add_index :spree_refunds, [:originator_type, :originator_id],
+ name: 'index_spree_refunds_on_originator'
+ end
+end
diff --git a/spree/core/lib/spree/testing_support/factories/return_factory.rb b/spree/core/lib/spree/testing_support/factories/return_factory.rb
new file mode 100644
index 0000000000..e6853f2a11
--- /dev/null
+++ b/spree/core/lib/spree/testing_support/factories/return_factory.rb
@@ -0,0 +1,44 @@
+FactoryBot.define do
+ factory :return, class: Spree::Return do
+ transient do
+ # Number of fulfilled units to return; capped at what the order has.
+ line_items_count { 1 }
+ end
+
+ association(:order, factory: :shipped_order)
+ store { order.store }
+ stock_location { order.shipments.first&.stock_location || create(:stock_location) }
+ status { Spree::Return.default_status }
+ memo { 'Item did not fit' }
+
+ after(:build) do |return_record, evaluator|
+ next if return_record.return_line_items.any?
+
+ return_record.order.fulfillment_items.limit(evaluator.line_items_count).each do |fulfillment_item|
+ return_record.return_line_items.build(
+ fulfillment_item: fulfillment_item,
+ line_item: fulfillment_item.line_item,
+ variant: fulfillment_item.variant,
+ quantity: 1
+ )
+ end
+ end
+
+ factory :approved_return do
+ status { 'approved' }
+ approved_at { Time.current }
+ end
+
+ factory :received_return do
+ status { 'received' }
+ approved_at { 1.day.ago }
+ received_at { Time.current }
+
+ after(:create) do |return_record|
+ return_record.return_line_items.each do |line|
+ line.update!(received_quantity: line.quantity)
+ end
+ end
+ end
+ end
+end
diff --git a/spree/core/spec/models/concerns/spree/has_status_spec.rb b/spree/core/spec/models/concerns/spree/has_status_spec.rb
new file mode 100644
index 0000000000..a3317802b1
--- /dev/null
+++ b/spree/core/spec/models/concerns/spree/has_status_spec.rb
@@ -0,0 +1,66 @@
+require 'spec_helper'
+
+RSpec.describe Spree::HasStatus do
+ # Spree::Return is the reference consumer; testing through it keeps the
+ # spec honest about how the concern behaves on a real model.
+ let(:model) { Spree::Return }
+
+ around do |example|
+ original = model.statuses
+ example.run
+ model.statuses = original
+ end
+
+ it 'declares the valid values and a default' do
+ expect(model.statuses).to eq(%w[requested approved received refunded canceled])
+ expect(model.default_status).to eq('requested')
+ end
+
+ it 'generates a predicate per value' do
+ record = model.new(status: 'received')
+
+ expect(record).to be_received
+ expect(record).not_to be_requested
+ end
+
+ it 'generates a scope per value' do
+ expect(model.received.to_sql).to include("'received'")
+ end
+
+ it 'rejects a status outside the list' do
+ record = model.new(status: 'teleported')
+
+ expect(record).not_to be_valid
+ expect(record.errors[:status]).to be_present
+ end
+
+ describe '.add_status' do
+ it 'appends at the end by default' do
+ model.add_status(:disputed)
+
+ expect(model.statuses.last).to eq('disputed')
+ expect(model.new(status: 'disputed')).to be_disputed
+ end
+
+ it 'inserts after a named status' do
+ model.add_status(:inspecting, after: :received)
+
+ expect(model.statuses).to eq(%w[requested approved received inspecting refunded canceled])
+ end
+
+ it 'accepts a record carrying the added status' do
+ model.add_status(:inspecting, after: :received)
+ record = model.new(status: 'inspecting')
+ record.validate
+
+ expect(record.errors[:status]).to be_empty
+ end
+
+ it 'is idempotent' do
+ model.add_status(:inspecting)
+ model.add_status(:inspecting)
+
+ expect(model.statuses.count('inspecting')).to eq(1)
+ end
+ end
+end
diff --git a/spree/core/spec/models/spree/return_spec.rb b/spree/core/spec/models/spree/return_spec.rb
new file mode 100644
index 0000000000..8c0c9ef6a8
--- /dev/null
+++ b/spree/core/spec/models/spree/return_spec.rb
@@ -0,0 +1,68 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Return do
+ let(:store) { @default_store }
+
+ it 'generates a prefixed number' do
+ expect(create(:return, store: store).number).to start_with('RET')
+ end
+
+ it 'starts as requested' do
+ expect(create(:return, store: store)).to be_requested
+ end
+
+ it 'requires at least one line item on create' do
+ order = create(:shipped_order, store: store)
+ record = described_class.new(
+ store: store,
+ order: order,
+ stock_location: order.shipments.first.stock_location,
+ status: described_class.default_status
+ )
+
+ expect(record).not_to be_valid
+ expect(record.errors[:return_line_items]).to be_present
+ end
+
+ it 'is reachable from its order' do
+ return_record = create(:return, store: store)
+
+ expect(return_record.order.reload.returns).to include(return_record)
+ end
+
+ describe 'totals' do
+ let(:return_record) { create(:return, store: store) }
+
+ it 'sums what the customer is owed from the line items' do
+ expect(return_record.refund_total).to eq(return_record.return_line_items.sum(&:pre_tax_amount))
+ end
+
+ it 'tracks how much has actually been refunded' do
+ expect(return_record.refunded_total).to eq(0)
+ expect(return_record.refundable_total).to eq(return_record.refund_total)
+ end
+ end
+
+ describe Spree::ReturnLineItem do
+ let(:return_record) { create(:return, store: store) }
+ let(:line) { return_record.return_line_items.first }
+
+ # Refunding the list price would give back more than the customer paid
+ # on a discounted line.
+ it 'defaults the refundable amount to the paid share of the line' do
+ line_item = line.line_item
+
+ expect(line.pre_tax_amount).to eq(line_item.amount / line_item.quantity)
+ end
+
+ it 'requires a positive quantity' do
+ line.quantity = 0
+
+ expect(line).not_to be_valid
+ end
+
+ it 'starts with nothing received' do
+ expect(line.received_quantity).to eq(0)
+ end
+ end
+end