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
Make the ledger survive a failure and a repeat
Damian Legawiec994acf37f47e
diff --git a/spree/core/app/models/spree/seller_transfer.rb b/spree/core/app/models/spree/seller_transfer.rbindex 9bfc626c30..4098824f3f 100644--- a/spree/core/app/models/spree/seller_transfer.rb+++ b/spree/core/app/models/spree/seller_transfer.rb@@ -33,6 +33,9 @@ module Spree# a re-run sweep can never batch the same earning twice.belongs_to :payout, class_name: 'Spree::SellerPayout', optional: true, inverse_of: :transfersbelongs_to :reversed_from, class_name: 'Spree::SellerTransfer', optional: true, inverse_of: :reversals+ # What caused a reversal. Nil on an earning, and the reversal's natural+ # key: one clawback per refund, enforced by a unique index.+ belongs_to :refund, class_name: 'Spree::Refund', optional: truehas_many :reversals, class_name: 'Spree::SellerTransfer', foreign_key: :reversed_from_id,inverse_of: :reversed_from, dependent: :nullifydiff --git a/spree/core/app/subscribers/spree/seller_transfer_reversal_subscriber.rb b/spree/core/app/subscribers/spree/seller_transfer_reversal_subscriber.rbindex 73e42302fa..9a2932389e 100644--- a/spree/core/app/subscribers/spree/seller_transfer_reversal_subscriber.rb+++ b/spree/core/app/subscribers/spree/seller_transfer_reversal_subscriber.rb@@ -20,7 +20,7 @@ module Spreeorder = refund.orderreturn if order.nil? || order.seller_id.blank?- Spree.seller_transfer_reverse_workflow.call(order: order, amount: refund.amount)+ Spree.seller_transfer_reverse_workflow.call(order: order, amount: refund.amount, refund: refund)endendenddiff --git a/spree/core/app/workflows/spree/seller_payouts/complete.rb b/spree/core/app/workflows/spree/seller_payouts/complete.rbindex 395748d396..458b254484 100644--- a/spree/core/app/workflows/spree/seller_payouts/complete.rb+++ b/spree/core/app/workflows/spree/seller_payouts/complete.rb@@ -31,16 +31,27 @@ module Spreeprivate- # A webhook can arrive twice, and an operator can double-click.+ # A webhook can arrive twice, and an operator can double-click. The cheap+ # read catches the ordinary case; the write below catches the race.def replay_completed- halt!(seller_payout) if seller_payout.completed?+ halt!(seller_payout) if seller_payout.reload.completed?end+ # Compare-and-swap on the terminal write, because an operator marking a+ # bank transfer sent can race the provider's own webhook saying the same+ # thing. Both would pass the read above, both would write `completed`,+ # and the completion event — public API a subscriber may act on — would+ # fire twice for one settlement.def mark_completed- attributes = { status: 'completed' }+ attributes = { status: 'completed', updated_at: Time.current }attributes[:reference] = reference if reference.present?- seller_payout.update!(attributes)+ claimed = Spree::SellerPayout.where(id: seller_payout.id, status: %w[pending processing]).+ update_all(attributes)++ halt!(seller_payout.reload) if claimed.zero?++ seller_payout.reloadendendenddiff --git a/spree/core/app/workflows/spree/seller_payouts/sweep.rb b/spree/core/app/workflows/spree/seller_payouts/sweep.rbindex e0e3c85bab..ceb97ce0e2 100644--- a/spree/core/app/workflows/spree/seller_payouts/sweep.rb+++ b/spree/core/app/workflows/spree/seller_payouts/sweep.rb@@ -88,18 +88,42 @@ module Spree# lie, so this payout takes only what it actually claimed.restate_amount if claimed != @transfers.sizeend++ # The threshold was checked against what this sweep hoped to claim. If+ # a concurrent one took some of it the figure has changed, and a+ # restated payout can even come to nothing — which must not be sent: a+ # provider asked to move zero either errors or moves nothing, and+ # either way it is not a settlement.+ discard_empty_payout if @payout.amount <= 0enddef restate_amount@payout.update!(amount: @payout.transfers.sum(:amount))end+ # Nothing was claimed, so there is nothing to release and nothing to+ # record. The earnings this sweep meant to take are already in the payout+ # that won them.+ def discard_empty_payout+ @payout.transfers.update_all(payout_id: nil, updated_at: Time.current)+ @payout.destroy!+ halt!(seller)+ end+def execute_payoutprovider.pay!(payout)rescue StandardError => e- # The transfers stay stamped deliberately: retrying means re-sending- # this payout, never sweeping the same earnings into a second one.- payout.update!(status: 'failed')+ # Releasing the transfers is what makes a failure recoverable. A payout+ # is created by the sweep and by nothing else, so transfers left+ # stamped to a failed one are unreachable: the next sweep skips them+ # (`unsettled` means unstamped) while the balance still reports them+ # owed, and the seller is never paid. Released, they simply fall into+ # the next sweep — which is the retry.+ payout.transaction do+ payout.transfers.update_all(payout_id: nil, updated_at: Time.current)+ payout.update!(status: 'failed', amount: 0)+ end+Rails.error.report(e, handled: true, context: { seller_payout_id: payout.id }, source: 'spree.core')failure(payout, e.message)enddiff --git a/spree/core/app/workflows/spree/seller_transfers/reverse.rb b/spree/core/app/workflows/spree/seller_transfers/reverse.rbindex 6dc909ee96..ac6d01ea92 100644--- a/spree/core/app/workflows/spree/seller_transfers/reverse.rb+++ b/spree/core/app/workflows/spree/seller_transfers/reverse.rb@@ -18,13 +18,15 @@ module Spree# @param order [Spree::Order] the seller order being refunded# @param amount [BigDecimal, Numeric] how much of the earning to take# back; capped at what is left of it+ # @param refund [Spree::Refund, nil] what caused the clawback. The+ # reversal's natural key, so a redelivered event reverses once.# @return [Spree::ServiceModule::Result] value is the reversal, or the# order when there was nothing to reverse- def perform(order:, amount:)+ def perform(order:, amount:, refund: nil)superstep :find_earning- step :bound_amount+ step :replay_existingrun_hooks :validatestep :build_reversal@@ -43,25 +45,46 @@ module Spreehalt!(order) if @earning.nil?end- # Never more than is left of the earning, however many times an order is- # refunded: a marketplace cannot claw back more than it credited.- def bound_amount- @bounded = [amount.to_d.abs, @earning.reversible_amount].min- halt!(order) if @bounded <= 0+ # An event can be delivered twice, and a job can retry.+ def replay_existing+ return if refund.nil?++ existing = Spree::SellerTransfer.reversals_only.find_by(refund_id: refund.id)+ halt!(existing) if existing.present?end+ # Bounded and written under the earning's own lock, so two refunds+ # landing together cannot each read the same untouched earning and each+ # take the whole of it. The unique index on `refund_id` covers the other+ # race — the same refund arriving twice — and resolves to the row that+ # won rather than failing the caller.def build_reversal- @reversal = Spree::SellerTransfer.create!(- seller: @earning.seller,- order: order,- reversed_from: @earning,- # Negative, so what a seller has earned is the plain sum of the rows.- amount: -@bounded,- currency: @earning.currency,- kind: 'refund_reversal',- provider: @earning.provider,- status: 'pending'- )+ @reversal = write_reversal+ halt!(order) if @reversal.nil?+ rescue ActiveRecord::RecordNotUnique+ halt!(Spree::SellerTransfer.reversals_only.find_by!(refund_id: refund.id))+ end++ # Nil when there is nothing left to take back, which the caller turns+ # into a halt outside the transaction — `halt!` refuses to run inside one.+ def write_reversal+ @earning.with_lock do+ bounded = [amount.to_d.abs, @earning.reversible_amount].min+ next nil if bounded <= 0++ Spree::SellerTransfer.create!(+ seller: @earning.seller,+ order: order,+ reversed_from: @earning,+ refund: refund,+ # Negative, so what a seller has earned is the plain sum of the rows.+ amount: -bounded,+ currency: @earning.currency,+ kind: 'refund_reversal',+ provider: @earning.provider,+ status: 'pending'+ )+ endenddef execute_reversaldiff --git a/spree/core/db/migrate/20260822000001_create_spree_seller_transfers.rb b/spree/core/db/migrate/20260822000001_create_spree_seller_transfers.rbindex 314da562fe..e540c89127 100644--- a/spree/core/db/migrate/20260822000001_create_spree_seller_transfers.rb+++ b/spree/core/db/migrate/20260822000001_create_spree_seller_transfers.rb@@ -9,6 +9,9 @@ class CreateSpreeSellerTransfers < ActiveRecord::Migration[8.1]t.references :payout, index: true# The earning this row reverses, when a refund gave money back.t.references :reversed_from, index: true+ # Which refund caused it. The reversal's natural key — see the index+ # below.+ t.references :refund, index: falset.decimal :amount, precision: 10, scale: 2, null: false, default: 0t.string :currency, null: false@@ -34,9 +37,17 @@ class CreateSpreeSellerTransfers < ActiveRecord::Migration[8.1]add_index :spree_seller_transfers, [:seller_id, :currency, :status]add_index :spree_seller_transfers, [:seller_id, :created_at]+ # One reversal per refund. An order can be refunded many times, so the+ # order cannot be the key here — but a single refund must claw back once+ # however many times its event is delivered, and two refunds arriving+ # together must not each read the same untouched earning and both take the+ # whole of it.+ add_index :spree_seller_transfers, :refund_id, unique: true,+ name: 'index_seller_transfers_on_refund'+# A re-fired fulfillment event must find the existing row rather than# credit the seller twice. Reversals are deliberately outside the- # constraint: an order can be refunded more than once.+ # order constraint: an order can be refunded more than once.if connection.supports_partial_index?add_index :spree_seller_transfers, :order_id, unique: true,where: "kind = 'earning'",diff --git a/spree/core/spec/workflows/spree/seller_payouts/complete_spec.rb b/spree/core/spec/workflows/spree/seller_payouts/complete_spec.rbnew file mode 100644index 0000000000..37c2ffedc3--- /dev/null+++ b/spree/core/spec/workflows/spree/seller_payouts/complete_spec.rb@@ -0,0 +1,57 @@+require 'spec_helper'++RSpec.describe Spree::SellerPayouts::Complete do+ let(:store) { @default_store }+ let(:seller) { create(:seller, :approved, store: store) }+ let(:payout) { create(:seller_payout, seller: seller, amount: 40) }++ describe 'recording that the money landed' do+ it 'completes the settlement' do+ expect(described_class.call(seller_payout: payout)).to be_success+ expect(payout.reload).to be_completed+ end++ it "keeps the provider's own reference for it" do+ described_class.call(seller_payout: payout, reference: 'BACS-9912')++ expect(payout.reload.reference).to eq('BACS-9912')+ end++ it 'debits the balance, which is what completing means' do+ create(:seller_transfer, :completed, seller: seller, amount: 40, payout: payout)++ expect { described_class.call(seller_payout: payout) }.+ to change { seller.balance('USD') }.from(40).to(0)+ end+ end++ # An operator marking a bank transfer sent can race the provider's own+ # webhook saying the same thing. Both pass a plain read of the status.+ describe 'when it is recorded twice' do+ it 'announces the settlement once' do+ described_class.call(seller_payout: payout)++ expect_any_instance_of(Spree::SellerPayout).not_to receive(:publish_event)++ described_class.call(seller_payout: payout)+ end++ it 'announces it once even when both callers read it as unsettled' do+ stale = Spree::SellerPayout.find(payout.id)+ described_class.call(seller_payout: payout)++ # `stale` still believes the payout is pending, which is exactly what a+ # racing webhook holds.+ expect_any_instance_of(Spree::SellerPayout).not_to receive(:publish_event)++ described_class.call(seller_payout: stale)+ end++ it "does not let a blank second caller wipe the first one's reference" do+ described_class.call(seller_payout: payout, reference: 'BACS-9912')+ described_class.call(seller_payout: Spree::SellerPayout.find(payout.id))++ expect(payout.reload.reference).to eq('BACS-9912')+ end+ end+enddiff --git a/spree/core/spec/workflows/spree/seller_payouts/sweep_spec.rb b/spree/core/spec/workflows/spree/seller_payouts/sweep_spec.rbindex 634e6c034b..02026be252 100644--- a/spree/core/spec/workflows/spree/seller_payouts/sweep_spec.rb+++ b/spree/core/spec/workflows/spree/seller_payouts/sweep_spec.rb@@ -109,4 +109,65 @@ RSpec.describe Spree::SellerPayouts::Sweep doexpect(seller.balance('USD')).to eq(0)endend++ # A payout is created by the sweep and by nothing else, so earnings left+ # stamped to a failed one would be unreachable — skipped by every later+ # sweep while the balance still says the seller is owed them.+ describe 'when the provider will not pay' do+ before do+ allow_any_instance_of(Spree::PayoutProvider::System).to receive(:pay!).and_raise(StandardError, 'gateway down')+ end++ it 'reports the failure' do+ earn(40)++ expect(described_class.call(seller: seller, currency: 'USD')).to be_failure+ end++ it 'releases the earnings so the next sweep is the retry' do+ earn(40)+ described_class.call(seller: seller, currency: 'USD')++ expect(seller.seller_transfers.unsettled.sum(:amount)).to eq(40)+ end++ it 'still owes the seller their money' do+ earn(40)+ described_class.call(seller: seller, currency: 'USD')++ expect(seller.balance('USD')).to eq(40)+ end++ it 'settles them on the next run' do+ earn(40)+ described_class.call(seller: seller, currency: 'USD')+ allow_any_instance_of(Spree::PayoutProvider::System).to receive(:pay!).and_call_original++ expect(described_class.call(seller: seller.reload, currency: 'USD').value.amount).to eq(40)+ end+ end++ # A concurrent sweep can claim rows this one counted, leaving it holding+ # nothing. Asking a provider to move zero is not a settlement.+ describe 'when another sweep claimed everything first' do+ let(:workflow) { described_class.new }++ before do+ earn(40)+ # The other sweep wins the race: it takes the rows between this one+ # counting them and claiming them.+ allow(Spree::SellerTransfer).to receive(:where).and_return(Spree::SellerTransfer.none)+ end++ it 'sends nothing' do+ expect_any_instance_of(Spree::PayoutProvider::System).not_to receive(:pay!)++ described_class.call(seller: seller, currency: 'USD')+ end++ it 'keeps no empty settlement behind' do+ expect { described_class.call(seller: seller, currency: 'USD') }.+ not_to change { Spree::SellerPayout.count }+ end+ endenddiff --git a/spree/core/spec/workflows/spree/seller_transfers/reverse_spec.rb b/spree/core/spec/workflows/spree/seller_transfers/reverse_spec.rbindex e5fee89344..f520520bb5 100644--- a/spree/core/spec/workflows/spree/seller_transfers/reverse_spec.rb+++ b/spree/core/spec/workflows/spree/seller_transfers/reverse_spec.rb@@ -56,6 +56,59 @@ RSpec.describe Spree::SellerTransfers::Reverse doendend+ # A subscriber job retries on error, so the same refund can be handled more+ # than once. Without a key tying a reversal to its cause, each attempt would+ # take the money back again.+ describe 'when the same refund arrives twice' do+ let(:refund) { create(:refund, amount: 30) }++ it 'takes the money back once' do+ earn(80)+ described_class.call(order: order, amount: 30, refund: refund)++ expect { described_class.call(order: order, amount: 30, refund: refund) }.+ not_to change { Spree::SellerTransfer.count }++ expect(seller.balance('USD')).to eq(50)+ end++ it 'answers with the reversal that was already written' do+ earn(80)+ first = described_class.call(order: order, amount: 30, refund: refund).value++ expect(described_class.call(order: order, amount: 30, refund: refund).value).to eq(first)+ end++ # The read guard is not enough on its own — two deliveries can pass it+ # together — so the database has the last word.+ it 'refuses a second row even when the read guard is bypassed' do+ earning = earn(80)++ expect do+ Spree::SellerTransfer.create!(+ seller: seller, order: order, reversed_from: earning, refund: refund,+ amount: -30, currency: 'USD', kind: 'refund_reversal', provider: 'system', status: 'pending'+ )+ Spree::SellerTransfer.create!(+ seller: seller, order: order, reversed_from: earning, refund: refund,+ amount: -30, currency: 'USD', kind: 'refund_reversal', provider: 'system', status: 'pending'+ )+ end.to raise_error(ActiveRecord::RecordNotUnique)+ end+ end++ describe 'when two different refunds land on one order' do+ it 'never takes back more than was credited between them' do+ earn(80)++ described_class.call(order: order, amount: 60, refund: create(:refund, amount: 30))+ described_class.call(order: order, amount: 60, refund: create(:refund, amount: 30))++ expect(seller.balance('USD')).to eq(0)+ expect(Spree::SellerTransfer.reversals_only.sum(:amount)).to eq(-80)+ end+ end+# A settlement that has happened is never rewritten: the reversal is simply# unsettled, so the next sweep nets it off what comes after.describe 'when the earning was already settled' do