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 the Returns workflows

Damian Legawiecad485de8efc8
diff --git a/spree/core/app/workflows/spree/returns/approve.rb b/spree/core/app/workflows/spree/returns/approve.rb
new file mode 100644
index 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
+end
diff --git a/spree/core/app/workflows/spree/returns/cancel.rb b/spree/core/app/workflows/spree/returns/cancel.rb
new file mode 100644
index 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
+end
diff --git a/spree/core/app/workflows/spree/returns/create.rb b/spree/core/app/workflows/spree/returns/create.rb
new file mode 100644
index 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
+end
diff --git a/spree/core/app/workflows/spree/returns/receive.rb b/spree/core/app/workflows/spree/returns/receive.rb
new file mode 100644
index 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
+end
diff --git a/spree/core/app/workflows/spree/returns/refund.rb b/spree/core/app/workflows/spree/returns/refund.rb
new file mode 100644
index 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
+end
diff --git a/spree/core/lib/spree/core/dependencies.rb b/spree/core/lib/spree/core/dependencies.rb
index 5be87b40a6..540e7bfa76 100644
--- a/spree/core/lib/spree/core/dependencies.rb
+++ b/spree/core/lib/spree/core/dependencies.rb
@@ -71,6 +71,13 @@ module Spree
fulfillment_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 numbers
tracking_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.rb
new file mode 100644
index 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