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
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.rbnew file mode 100644index 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+enddiff --git a/spree/core/app/models/spree/order.rb b/spree/core/app/models/spree/order.rbindex 14564fb642..3b00c0fff4 100644--- a/spree/core/app/models/spree/order.rb+++ b/spree/core/app/models/spree/order.rb@@ -163,6 +163,7 @@ module Spreehas_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'enddiff --git a/spree/core/app/models/spree/refund.rb b/spree/core/app/models/spree/refund.rbindex e7764693ea..906f07b65e 100644--- a/spree/core/app/models/spree/refund.rb+++ b/spree/core/app/models/spree/refund.rb@@ -16,6 +16,10 @@ module Spreeendbelongs_to :reason, class_name: 'Spree::RefundReason', foreign_key: :refund_reason_idbelongs_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: truehas_many :log_entries, as: :sourcediff --git a/spree/core/app/models/spree/return.rb b/spree/core/app/models/spree/return.rbnew file mode 100644index 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+enddiff --git a/spree/core/app/models/spree/return_line_item.rb b/spree/core/app/models/spree/return_line_item.rbnew file mode 100644index 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+enddiff --git a/spree/core/db/migrate/20260802190001_create_spree_returns.rb b/spree/core/db/migrate/20260802190001_create_spree_returns.rbnew file mode 100644index 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+enddiff --git a/spree/core/lib/spree/testing_support/factories/return_factory.rb b/spree/core/lib/spree/testing_support/factories/return_factory.rbnew file mode 100644index 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+enddiff --git a/spree/core/spec/models/concerns/spree/has_status_spec.rb b/spree/core/spec/models/concerns/spree/has_status_spec.rbnew file mode 100644index 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+enddiff --git a/spree/core/spec/models/spree/return_spec.rb b/spree/core/spec/models/spree/return_spec.rbnew file mode 100644index 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