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 the Returns workflows
Damian Legawiecad485de8efc8
diff --git a/spree/core/app/workflows/spree/returns/approve.rb b/spree/core/app/workflows/spree/returns/approve.rbnew file mode 100644index 0000000000..8df202a707--- /dev/null+++ b/spree/core/app/workflows/spree/returns/approve.rb@@ -0,0 +1,61 @@+module Spree+ module Returns+ # Authorizes a requested return, optionally producing a prepaid return+ # label from the carrier.+ class Approve < Spree::Workflow+ hooks :validate, :after_approve++ # @param return_record [Spree::Return]+ # @param approver [Object, nil] the admin approving it+ # @param generate_label [Boolean] ask the carrier for a return label+ def perform(return_record:, approver: nil, generate_label: false)+ super++ step :ensure_approvable+ run_hooks :validate++ ApplicationRecord.transaction do+ step :mark_approved+ end++ # Carrier API — never inside the transaction above.+ external_step :request_return_label if generate_label++ run_hooks :after_approve+ return_record.publish_event('return.approved')+ success(return_record.reload)+ end++ private++ def ensure_approvable+ failure(return_record, :not_requested) unless return_record.requested?+ end++ def mark_approved+ return_record.update!(+ status: 'approved',+ approved_at: Time.current,+ created_by: return_record.created_by || approver+ )+ end++ # Label generation is best-effort: a carrier outage should not undo an+ # approval the merchant already granted. The failure is reported and+ # the return stays approved without a label.+ def request_return_label+ provider = Spree::Dependencies.respond_to?(:return_label_provider) ? Spree.return_label_provider : nil+ return if provider.nil?++ url = provider.call(return_record: return_record)+ return_record.update_columns(return_label_url: url) if url.present?+ rescue StandardError => error+ Rails.error.report(+ error,+ context: { return_id: return_record.id },+ source: 'spree.returns.label'+ )+ end+ end+ end+enddiff --git a/spree/core/app/workflows/spree/returns/cancel.rb b/spree/core/app/workflows/spree/returns/cancel.rbnew file mode 100644index 0000000000..53697be7cc--- /dev/null+++ b/spree/core/app/workflows/spree/returns/cancel.rb@@ -0,0 +1,43 @@+module Spree+ module Returns+ # Withdraws a return that has not been received yet.+ #+ # Nothing is restocked and no money moves — cancelling is only valid+ # before the goods arrive. Once a return is received the merchant is+ # holding the customer's items, and the way out is a refund, not a+ # cancellation.+ class Cancel < Spree::Workflow+ hooks :validate, :after_cancel++ # @param return_record [Spree::Return]+ # @param reason [String, nil] staff- or customer-supplied note+ def perform(return_record:, reason: nil)+ super++ step :ensure_cancellable+ run_hooks :validate++ ApplicationRecord.transaction do+ step :mark_canceled+ end++ run_hooks :after_cancel+ return_record.publish_event('return.canceled')+ success(return_record.reload)+ end++ private++ def ensure_cancellable+ return if return_record.requested? || return_record.approved?++ failure(return_record, :not_cancellable)+ end++ def mark_canceled+ memo = [return_record.memo, reason].compact_blank.join("\n")+ return_record.update!(status: 'canceled', canceled_at: Time.current, memo: memo.presence)+ end+ end+ end+enddiff --git a/spree/core/app/workflows/spree/returns/create.rb b/spree/core/app/workflows/spree/returns/create.rbnew file mode 100644index 0000000000..d45d294175--- /dev/null+++ b/spree/core/app/workflows/spree/returns/create.rb@@ -0,0 +1,108 @@+module Spree+ module Returns+ # Opens a return request for fulfilled items on a completed order.+ #+ # The `validate` hook is the seam for return-eligibility policy —+ # 30-day windows, final-sale categories, per-customer-group rules,+ # regional consumer rights. That policy is the most-customized rule in+ # commerce and deliberately does not live in core.+ class Create < Spree::Workflow+ hooks :validate, :after_create++ # The created return — hook handlers read it (nil while :validate runs).+ attr_reader :return_record++ # @param order [Spree::Order] a completed order with fulfilled items+ # @param items [Array<Hash>] `[{ fulfillment_item:, quantity: }]`+ # @param stock_location [Spree::StockLocation, nil] where the goods come+ # back to; defaults to the location that shipped them+ # @param reason [Spree::ReturnAuthorizationReason, nil]+ # @param memo [String, nil] customer- or staff-supplied note+ # @param created_by [Object, nil] the admin opening it; nil for+ # customer self-service+ def perform(order:, items:, stock_location: nil, reason: nil, memo: nil, created_by: nil)+ super++ step :ensure_returnable+ step :normalize_items++ # Veto point — return-window and eligibility policy. Before anything+ # is written.+ run_hooks :validate++ ApplicationRecord.transaction do+ step :build_return+ end++ run_hooks :after_create+ return_record.publish_event('return.requested')+ success(return_record.reload)+ end++ private++ def ensure_returnable+ failure(order, :order_not_completed) unless order.completed?+ failure(order, :order_canceled) if order.canceled?+ failure(order, :no_items_to_return) if items.blank?+ end++ # Quantities are validated against what is actually still returnable —+ # units already returned on an earlier request must not come back twice.+ def normalize_items+ @normalized_items = items.map do |item|+ fulfillment_item = item[:fulfillment_item]+ quantity = item[:quantity].to_i++ failure(order, :invalid_quantity) unless quantity.positive?+ failure(order, :item_not_on_order) unless fulfillment_item&.order_id == order.id++ available = returnable_quantity_for(fulfillment_item)+ if quantity > available+ failure(order, "Only #{available} of #{fulfillment_item.variant.name} can be returned")+ end++ { fulfillment_item: fulfillment_item, quantity: quantity }+ end+ end++ def returnable_quantity_for(fulfillment_item)+ already_requested = Spree::ReturnLineItem.+ joins(:return).+ where(fulfillment_item_id: fulfillment_item.id).+ where.not(spree_returns: { status: 'canceled' }).+ sum(:quantity)++ fulfillment_item.quantity.to_i - already_requested+ end++ def build_return+ @return_record = order.returns.new(+ store: order.store,+ stock_location: stock_location || default_stock_location,+ reason: reason,+ memo: memo,+ created_by: created_by,+ status: Spree::Return.default_status+ )++ @normalized_items.each do |item|+ fulfillment_item = item[:fulfillment_item]+ @return_record.return_line_items.build(+ fulfillment_item: fulfillment_item,+ line_item: fulfillment_item.line_item,+ variant: fulfillment_item.variant,+ quantity: item[:quantity]+ )+ end++ failure(@return_record) unless @return_record.save+ end++ def default_stock_location+ @normalized_items.first[:fulfillment_item].fulfillment&.stock_location ||+ order.store.stock_locations.first+ end+ end+ end+enddiff --git a/spree/core/app/workflows/spree/returns/receive.rb b/spree/core/app/workflows/spree/returns/receive.rbnew file mode 100644index 0000000000..f34db6f6fa--- /dev/null+++ b/spree/core/app/workflows/spree/returns/receive.rb@@ -0,0 +1,94 @@+module Spree+ module Returns+ # Records what the warehouse actually received.+ #+ # Partial and damaged receipt is the normal case, not an edge case: the+ # customer said three items were coming, two arrived, one of those is not+ # resellable. Quantities and resellable flags therefore come from the+ # caller rather than from the request, which is precisely what a state+ # machine transition could not express.+ class Receive < Spree::Workflow+ hooks :validate, :before_restock, :after_receive++ # @param return_record [Spree::Return]+ # @param items [Array<Hash>, nil] `[{ return_line_item:, quantity:,+ # resellable: }]`; nil receives everything as requested and resellable+ # @param received_by [Object, nil]+ def perform(return_record:, items: nil, received_by: nil)+ super++ step :ensure_receivable+ step :normalize_items+ run_hooks :validate++ ApplicationRecord.transaction do+ step :record_receipt+ run_hooks :before_restock+ step :restock_resellable_items+ step :mark_received+ end++ run_hooks :after_receive+ return_record.publish_event('return.received')+ success(return_record.reload)+ end++ private++ def ensure_receivable+ failure(return_record, :not_approved) unless return_record.approved?+ end++ def normalize_items+ @normalized_items =+ if items.nil?+ return_record.return_line_items.map do |line|+ { return_line_item: line, quantity: line.quantity, resellable: true }+ end+ else+ items.map { |item| normalize_item(item) }+ end++ failure(return_record, :no_items_received) if @normalized_items.sum { |item| item[:quantity] }.zero?+ end++ def normalize_item(item)+ line = item[:return_line_item]+ quantity = item[:quantity].to_i++ failure(return_record, :item_not_on_return) unless line&.return_id == return_record.id+ failure(return_record, :invalid_quantity) if quantity.negative? || quantity > line.quantity++ { return_line_item: line, quantity: quantity, resellable: item.fetch(:resellable, true) }+ end++ def record_receipt+ @normalized_items.each do |item|+ item[:return_line_item].update!(+ received_quantity: item[:quantity],+ resellable: item[:resellable]+ )+ end+ end++ # Only resellable goods go back into sellable stock — a damaged return+ # is received but never restocked.+ def restock_resellable_items+ @normalized_items.each do |item|+ next unless item[:resellable]+ next unless item[:quantity].positive?++ return_record.stock_location.restock(+ item[:return_line_item].variant,+ item[:quantity],+ return_record+ )+ end+ end++ def mark_received+ return_record.update!(status: 'received', received_at: Time.current)+ end+ end+ end+enddiff --git a/spree/core/app/workflows/spree/returns/refund.rb b/spree/core/app/workflows/spree/returns/refund.rbnew file mode 100644index 0000000000..d9f63995f0--- /dev/null+++ b/spree/core/app/workflows/spree/returns/refund.rb@@ -0,0 +1,122 @@+module Spree+ module Returns+ # Gives the customer their money back.+ #+ # Not every refund is a network call. Store credit is an internal ledger+ # write, so it stays inside the transaction that marks the return+ # refunded; a gateway refund runs as an `external_step` after it. Sending+ # a pure database write outside the transaction would open a window where+ # a crash leaves a refunded return with no credit issued.+ class Refund < Spree::Workflow+ METHODS = %w[original_payment store_credit].freeze++ hooks :validate, :before_refund, :after_refund++ # Refunds created by this run — hook handlers read them.+ attr_reader :refunds++ # @param return_record [Spree::Return] must be received+ # @param amount [BigDecimal, Numeric, nil] defaults to what the return+ # is still owed+ # @param refund_method [String] 'original_payment' or 'store_credit'+ # @param refunder [Object, nil] the admin issuing it+ def perform(return_record:, amount: nil, refund_method: 'original_payment', refunder: nil)+ super++ @refunds = []+ step :ensure_refundable+ step :resolve_amount++ run_hooks :validate+ run_hooks :before_refund++ if internal_refund?+ ApplicationRecord.transaction do+ step :issue_store_credit+ step :mark_refunded+ end+ else+ external_step :refund_at_gateway+ step :mark_refunded+ end++ run_hooks :after_refund+ return_record.publish_event('return.refunded')+ success(return_record.reload)+ end++ private++ def internal_refund?+ refund_method.to_s == 'store_credit'+ end++ def ensure_refundable+ failure(return_record, :invalid_refund_method) unless METHODS.include?(refund_method.to_s)+ failure(return_record, :not_received) unless return_record.received?+ end++ # Only what actually came back is refundable — a customer who sent two+ # of three items gets two items' worth.+ def resolve_amount+ @amount_to_refund = (amount || received_total).to_d++ failure(return_record, :nothing_to_refund) unless @amount_to_refund.positive?+ failure(return_record, :refund_exceeds_balance) if @amount_to_refund > return_record.refundable_total.to_d+ end++ def received_total+ return_record.return_line_items.sum do |line|+ next 0 if line.quantity.to_i.zero?++ (line.pre_tax_amount / line.quantity) * line.received_quantity.to_i+ end+ end++ def issue_store_credit+ credit = Spree::StoreCredit.create!(+ store: return_record.store,+ user: return_record.order.user,+ amount: @amount_to_refund,+ currency: return_record.currency,+ category: Spree::StoreCreditCategory.default_reimbursement_category,+ created_by: refunder,+ originator: return_record,+ memo: "Return #{return_record.number}"+ )+ @refunds = [credit]+ end++ # Spree::Refund performs the gateway credit in an after_create callback,+ # so creating it here keeps that call out of any transaction this+ # workflow opened. Payments are drained newest-first until the amount+ # is covered — a split-tender order needs more than one refund.+ def refund_at_gateway+ remaining = @amount_to_refund++ return_record.order.payments.completed.each do |payment|+ break unless remaining.positive?++ creditable = [payment.credit_allowed.to_d, remaining].min+ next unless creditable.positive?++ @refunds << payment.refunds.create!(+ amount: creditable,+ reason: Spree::RefundReason.return_processing_reason,+ refunder: refunder,+ originator: return_record+ )+ remaining -= creditable+ end++ failure(return_record, :no_refundable_payments) if @refunds.empty?+ rescue Spree::Core::GatewayError => error+ failure(return_record, error.message)+ end++ def mark_refunded+ return_record.update!(status: 'refunded', refunded_at: Time.current)+ end+ end+ end+enddiff --git a/spree/core/lib/spree/core/dependencies.rb b/spree/core/lib/spree/core/dependencies.rbindex 5be87b40a6..540e7bfa76 100644--- a/spree/core/lib/spree/core/dependencies.rb+++ b/spree/core/lib/spree/core/dependencies.rb@@ -71,6 +71,13 @@ module Spreefulfillment_create_workflow: 'Spree::Fulfillments::Create',fulfillment_update_service: 'Spree::Fulfillments::Update',+ # returns+ return_create_workflow: 'Spree::Returns::Create',+ return_approve_workflow: 'Spree::Returns::Approve',+ return_receive_workflow: 'Spree::Returns::Receive',+ return_refund_workflow: 'Spree::Returns::Refund',+ return_cancel_workflow: 'Spree::Returns::Cancel',+# tracking numberstracking_number_service: 'Spree::TrackingNumbers::BaseService',diff --git a/spree/core/spec/workflows/spree/returns/lifecycle_spec.rb b/spree/core/spec/workflows/spree/returns/lifecycle_spec.rbnew file mode 100644index 0000000000..67ab0a1594--- /dev/null+++ b/spree/core/spec/workflows/spree/returns/lifecycle_spec.rb@@ -0,0 +1,222 @@+require 'spec_helper'++RSpec.describe 'Spree::Returns workflows' do+ let(:store) { @default_store }+ let(:order) { create(:shipped_order, store: store, line_items_count: 2) }+ let(:fulfillment_items) { order.fulfillment_items.to_a }++ before { Spree.hooks.clear! }+ after { Spree.hooks.clear! }++ def create_return(items: nil, **overrides)+ Spree::Returns::Create.call(+ order: order,+ items: items || [{ fulfillment_item: fulfillment_items.first, quantity: 1 }],+ **overrides+ )+ end++ describe Spree::Returns::Create do+ it 'opens a requested return with line items' do+ result = create_return++ expect(result).to be_success+ expect(result.value).to be_requested+ expect(result.value.return_line_items.count).to eq(1)+ end++ it 'defaults the stock location to where the goods shipped from' do+ expect(create_return.value.stock_location).to eq(order.shipments.first.stock_location)+ end++ it 'refuses an order that was never completed' do+ cart_order = create(:order, store: store)++ result = Spree::Returns::Create.call(order: cart_order, items: [])++ expect(result).to be_failure+ end++ it 'refuses to return more than was fulfilled' do+ result = create_return(items: [{ fulfillment_item: fulfillment_items.first, quantity: 99 }])++ expect(result).to be_failure+ expect(result.error.value).to include('can be returned')+ end++ # Units already covered by an open return must not come back twice.+ it 'counts quantities already requested on another return' do+ create_return++ result = create_return++ expect(result).to be_failure+ end++ it 'lets a validate handler enforce a return window' do+ Spree.hooks.register('returns.create.validate') do |workflow|+ workflow.reject!('outside the return window') if workflow.order.completed_at < 30.days.ago+ end+ order.update_columns(completed_at: 60.days.ago)++ result = create_return++ expect(result).to be_failure+ expect(result.error.value).to eq('outside the return window')+ expect(order.reload.returns).to be_empty+ end+ end++ describe Spree::Returns::Approve do+ it 'moves a requested return to approved' do+ return_record = create_return.value++ result = Spree::Returns::Approve.call(return_record: return_record)++ expect(result).to be_success+ expect(result.value).to be_approved+ expect(result.value.approved_at).to be_present+ end++ it 'refuses anything not currently requested' do+ return_record = create(:approved_return, store: store)++ expect(Spree::Returns::Approve.call(return_record: return_record)).to be_failure+ end+ end++ describe Spree::Returns::Receive do+ let(:return_record) { create(:approved_return, store: store) }+ let(:line) { return_record.return_line_items.first }++ it 'receives everything as requested by default' do+ result = Spree::Returns::Receive.call(return_record: return_record)++ expect(result).to be_success+ expect(result.value).to be_received+ expect(line.reload.received_quantity).to eq(line.quantity)+ end++ it 'restocks resellable goods' do+ variant = line.variant+ stock_item = return_record.stock_location.stock_item_or_create(variant)++ expect { Spree::Returns::Receive.call(return_record: return_record) }.+ to change { stock_item.reload.count_on_hand }.by(line.quantity)+ end++ # The whole reason receiving is a workflow and not a state transition.+ it 'records a partial, non-resellable receipt without restocking' do+ variant = line.variant+ stock_item = return_record.stock_location.stock_item_or_create(variant)++ result = Spree::Returns::Receive.call(+ return_record: return_record,+ items: [{ return_line_item: line, quantity: 1, resellable: false }]+ )++ expect(result).to be_success+ expect(line.reload.received_quantity).to eq(1)+ expect(line.resellable).to be(false)+ expect(stock_item.reload.count_on_hand).to eq(stock_item.count_on_hand)+ end++ it 'refuses to receive more than was requested' do+ result = Spree::Returns::Receive.call(+ return_record: return_record,+ items: [{ return_line_item: line, quantity: line.quantity + 5 }]+ )++ expect(result).to be_failure+ end++ it 'refuses a return that has not been approved' do+ requested = create(:return, store: store)++ expect(Spree::Returns::Receive.call(return_record: requested)).to be_failure+ end+ end++ describe Spree::Returns::Refund do+ let(:return_record) { create(:received_return, store: store) }++ it 'refuses a return that has not been received' do+ approved = create(:approved_return, store: store)++ expect(Spree::Returns::Refund.call(return_record: approved)).to be_failure+ end++ it 'refuses an unknown refund method' do+ result = Spree::Returns::Refund.call(return_record: return_record, refund_method: 'crypto')++ expect(result).to be_failure+ expect(result.error.value).to eq(:invalid_refund_method)+ end++ it 'refuses more than the return is owed' do+ result = Spree::Returns::Refund.call(return_record: return_record, amount: 10_000)++ expect(result).to be_failure+ expect(result.error.value).to eq(:refund_exceeds_balance)+ end++ context 'to store credit' do+ it 'issues credit inside the transaction and marks the return refunded' do+ result = Spree::Returns::Refund.call(return_record: return_record, refund_method: 'store_credit')++ expect(result).to be_success+ expect(result.value).to be_refunded+ credit = Spree::StoreCredit.find_by(originator: return_record)+ expect(credit).to be_present+ expect(credit.amount).to eq(return_record.refund_total)+ end++ it 'lets a validate handler veto before any credit is issued' do+ Spree.hooks.register('returns.refund.validate') { |flow| flow.reject!('refunds on hold') }++ result = Spree::Returns::Refund.call(return_record: return_record, refund_method: 'store_credit')++ expect(result).to be_failure+ expect(Spree::StoreCredit.where(originator: return_record)).to be_empty+ expect(return_record.reload).to be_received+ end+ end++ context 'to the original payment' do+ before { allow_any_instance_of(Spree::Refund).to receive(:perform!).and_return(true) }++ it 'creates a refund against the completed payment' do+ result = Spree::Returns::Refund.call(return_record: return_record)++ expect(result).to be_success+ expect(return_record.reload.refunds).to be_present+ expect(return_record.refunds.first.originator).to eq(return_record)+ end+ end+ end++ describe Spree::Returns::Cancel do+ it 'cancels a requested return' do+ return_record = create_return.value++ result = Spree::Returns::Cancel.call(return_record: return_record, reason: 'changed their mind')++ expect(result).to be_success+ expect(result.value).to be_canceled+ expect(result.value.memo).to include('changed their mind')+ end++ # Once the merchant holds the goods, the way out is a refund.+ it 'refuses a return that was already received' do+ received = create(:received_return, store: store)++ expect(Spree::Returns::Cancel.call(return_record: received)).to be_failure+ end++ it 'frees the quantity for a new return request' do+ create_return.value.then { |r| Spree::Returns::Cancel.call(return_record: r) }++ expect(create_return).to be_success+ end+ end+end