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
Fix: Review findings across the ledger and the split parcel
Łukasz Adamczyk689789c456cd
diff --git a/spree/api/app/controllers/spree/api/v3/admin/sellers/payouts_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/sellers/payouts_controller.rbindex e79bf57d44..1697eaeb60 100644--- a/spree/api/app/controllers/spree/api/v3/admin/sellers/payouts_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/admin/sellers/payouts_controller.rb@@ -93,7 +93,7 @@ module Spreeenddef currencies_owed- @seller.seller_transfers.unsettled.settlement_currencies+ @seller.payable_currenciesenddef serialize_payout(payout)diff --git a/spree/core/app/jobs/spree/seller_payouts/sweep_seller_job.rb b/spree/core/app/jobs/spree/seller_payouts/sweep_seller_job.rbindex 73fbc58f11..f430186658 100644--- a/spree/core/app/jobs/spree/seller_payouts/sweep_seller_job.rb+++ b/spree/core/app/jobs/spree/seller_payouts/sweep_seller_job.rb@@ -62,11 +62,8 @@ module Spree# Only the currencies this seller actually has earnings waiting in — a# marketplace trading in three currencies should not run three sweeps for# a seller who sold in one.- # The currencies the seller's account can be paid in, which is not the- # same as the currencies they sold in — a cross-border account settles- # in its own.def currencies_owed(seller)- seller.seller_transfers.unsettled.settlement_currencies+ seller.payable_currenciesendendenddiff --git a/spree/core/app/models/spree/payout_provider/base.rb b/spree/core/app/models/spree/payout_provider/base.rbindex a817db491d..e4a0d490a1 100644--- a/spree/core/app/models/spree/payout_provider/base.rb+++ b/spree/core/app/models/spree/payout_provider/base.rb@@ -181,8 +181,10 @@ module Spree# only payable once the customer's payment settles. A provider that knows# the difference answers it here, and the sweep settles what fits.#- # Nil means the provider does not know or does not care — the built-in- # one moves no money, so everything owed is payable.+ # Nil means there is no limit — the built-in provider moves no money, so+ # everything owed is payable. A provider that cannot find out must raise+ # rather than answer nil: the sweep settles the whole balance on nil, and+ # asking for more than an account holds is what this exists to prevent.## @param seller [Spree::Seller]# @param currency [String]diff --git a/spree/core/app/models/spree/seller.rb b/spree/core/app/models/spree/seller.rbindex cb9d346272..9717721c66 100644--- a/spree/core/app/models/spree/seller.rb+++ b/spree/core/app/models/spree/seller.rb@@ -276,10 +276,17 @@ module Spree# @return [BigDecimal]def balance(currency)earnings = seller_transfers.completed.settling_in(currency)- settled = Spree::SellerTransfer.arel_settlement_amount- earnings.sum(settled) -- earnings.joins(:payout).merge(Spree::SellerPayout.completed).sum(settled)+ earnings.settlement_total -+ earnings.joins(:payout).merge(Spree::SellerPayout.completed).settlement_total+ end++ # The currencies this seller can actually be paid in — the ones their+ # account settles in, which is not the same as the ones they sold in.+ #+ # @return [Array<String>]+ def payable_currencies+ seller_transfers.unsettled.settlement_currenciesend# The seller's position in every currency they have earned or been paid@@ -296,7 +303,7 @@ module Spree# @return [Array<Spree::SellerBalance>]def balancespairs = seller_transfers.where.not(status: 'failed').- distinct.pluck(:currency, Spree::SellerTransfer.arel_settlement_currency)+ distinct.pluck(:currency, :settled_currency)pairs.sort.map { |currency, settlement| Spree::SellerBalance.for(self, currency, settlement) }enddiff --git a/spree/core/app/models/spree/seller_balance.rb b/spree/core/app/models/spree/seller_balance.rbindex c7b4a016d6..be07532113 100644--- a/spree/core/app/models/spree/seller_balance.rb+++ b/spree/core/app/models/spree/seller_balance.rb@@ -41,7 +41,6 @@ module Spree# @return [Spree::SellerBalance]def self.for(seller, currency, settlement_currency = currency)transfers = seller.seller_transfers.where(currency: currency).settling_in(settlement_currency)- settled = Spree::SellerTransfer.arel_settlement_amountnew(seller: seller,@@ -49,17 +48,22 @@ module Spreesettlement_currency: settlement_currency,earned: transfers.completed.sum(:amount),pending: transfers.with_status('pending', 'processing', 'unresolved').sum(:amount),- payable: transfers.completed.sum(settled),+ payable: transfers.completed.settlement_total,# Read through the transfers a settlement claimed rather than off the# settlement's own total: two sale currencies can settle into one, and# the payout's figure would then count against both of them.paid: transfers.completed.joins(:payout).- merge(Spree::SellerPayout.completed).sum(settled)+ merge(Spree::SellerPayout.completed).settlement_total)end# What the marketplace still owes, in the currency it can actually be sent- # in — which is what the payout sweep settles.+ # in.+ #+ # A payout settles every position sharing that currency, so a seller who+ # sells in two currencies that settle into one is paid the sum of both+ # rather than either. The figures reconcile — both sides read the same+ # transfer rows — but one position is not one deposit.## @return [BigDecimal]def balancediff --git a/spree/core/app/models/spree/seller_payout.rb b/spree/core/app/models/spree/seller_payout.rbindex f5f66de4c2..e09f94362e 100644--- a/spree/core/app/models/spree/seller_payout.rb+++ b/spree/core/app/models/spree/seller_payout.rb@@ -68,7 +68,7 @@ module Spree# Summed on what the seller's account actually received, since that is# what this payout moves.def transfers_total- transfers.sum(&:settlement_amount)+ transfers.settlement_totalend# Gives up on this settlement and puts its earnings back.diff --git a/spree/core/app/models/spree/seller_transfer.rb b/spree/core/app/models/spree/seller_transfer.rbindex 4bf572fef8..1bba42cb69 100644--- a/spree/core/app/models/spree/seller_transfer.rb+++ b/spree/core/app/models/spree/seller_transfer.rb@@ -53,6 +53,15 @@ module Spreevalidates :kind, presence: true, inclusion: { in: KINDS }validates :provider, presence: true+ # A row settles in the currency it was sold in until a provider says+ # otherwise — which is the truth outright for the built-in provider, since+ # it converts nothing and moves no money. One that does convert overwrites+ # both when it reports what actually arrived.+ #+ # Written rather than worked out on read, so every query that groups or+ # sums by settlement is a plain one against a column.+ before_validation :assume_settled_as_sold, on: :create+## Statuses. No state machine: a transfer moves through the payout# workflows, which can explain a refusal, rather than through a transition@@ -84,25 +93,20 @@ module Spree# Rows whose money can be paid out in this currency. A seller's account# settles in its own currency, so what a payout can move is the settled# currency, not the one the sale was priced in.- scope :settling_in, ->(currency) { where(arel_settlement_currency.eq(currency)) }+ scope :settling_in, ->(currency) { where(settled_currency: currency) }- # COALESCE rather than two queries, so a row that predates its provider- # reporting a settlement still groups under the currency it was earned in.- def self.arel_settlement_currency- Arel::Nodes::NamedFunction.new('COALESCE', [arel_table[:settled_currency], arel_table[:currency]])- end-- # The settled figure as a summable column, so a balance over a long ledger- # stays one aggregate rather than loading every row to add them up.- def self.arel_settlement_amount- Arel::Nodes::NamedFunction.new('COALESCE', [arel_table[:settled_amount], arel_table[:amount]])+ # What these rows are worth in the currency they settle in.+ #+ # @return [BigDecimal]+ def self.settlement_total+ sum(:settled_amount)end# The currencies this seller can actually be paid in.## @return [Array<String>]def self.settlement_currencies- distinct.pluck(arel_settlement_currency)+ distinct.pluck(:settled_currency)endself.whitelisted_ransackable_attributes = %w[amount currency kind status provider reference created_at seller_id order_id payout_id]@@ -132,9 +136,9 @@ module Spree# What the seller's account actually holds for this row, and in what.## A sale is priced in the customer's currency; an account settles in its- # own, and the provider converts on the way in. Both figures are recorded- # facts — Spree holds no exchange rates and converts nothing — and these- # answer the earned side whenever no settlement was reported.+ # own, and the provider converts on the way in. Both are recorded facts —+ # Spree holds no exchange rates and converts nothing. The fallback is for+ # rows written before the columns existed; everything since carries them.## @return [BigDecimal]def settlement_amount@@ -150,5 +154,12 @@ module Spreedef converted?settled_currency.present? && settled_currency != currencyend++ private++ def assume_settled_as_sold+ self.settled_amount = amount if settled_amount.nil?+ self.settled_currency = currency if settled_currency.blank?+ endendenddiff --git a/spree/core/app/workflows/spree/fulfillments/create.rb b/spree/core/app/workflows/spree/fulfillments/create.rbindex 5f128ad024..dd3805f371 100644--- a/spree/core/app/workflows/spree/fulfillments/create.rb+++ b/spree/core/app/workflows/spree/fulfillments/create.rb@@ -303,7 +303,12 @@ module Spree# docs for pending-path re-pricing. The carrier rides along as a# selected rate.def attach_cost_and_rate(fulfillment, delivery_method, cost, inherited)- effective_cost = cost || inherited[:cost]+ # A stated price replaces the inherited one — except a zero, which says+ # "do not price this parcel" rather than "this parcel is free". A+ # drained shipment's cost is money the order already carried and whose+ # row has just been destroyed, so discarding it would drop the delivery+ # total below what the customer paid.+ effective_cost = cost.to_d.zero? ? inherited[:cost] : costmethod = delivery_method || inherited[:delivery_method]fulfillment.update_columns(cost: effective_cost) if effective_cost.positive?diff --git a/spree/core/app/workflows/spree/seller_payouts/sweep.rb b/spree/core/app/workflows/spree/seller_payouts/sweep.rbindex feb1240a09..3a1d40e0db 100644--- a/spree/core/app/workflows/spree/seller_payouts/sweep.rb+++ b/spree/core/app/workflows/spree/seller_payouts/sweep.rb@@ -62,8 +62,11 @@ module Spreedef resolve_available_payout@available = provider.available_payout(seller, currency)rescue StandardError => e+ # A refusal rather than a halt: halting reads as "nothing to settle",+ # which is what an operator pressing Settle would be told while the+ # provider was simply unreachable.Rails.error.report(e, handled: true, context: { seller_id: seller.id, currency: currency }, source: 'spree.core')- halt!(seller)+ failure(seller, e.message)end# Selected and summed on what the seller's account holds, not on what thediff --git a/spree/core/app/workflows/spree/seller_transfers/reverse.rb b/spree/core/app/workflows/spree/seller_transfers/reverse.rbindex 88894c07c7..281658aa8d 100644--- a/spree/core/app/workflows/spree/seller_transfers/reverse.rb+++ b/spree/core/app/workflows/spree/seller_transfers/reverse.rb@@ -102,8 +102,12 @@ module Spreegross = amounts.values.sum.to_dreturn if gross <= 0- earned = amounts.sum { |line_item_id, amount| line_earning(line_item_id, amount.to_d) }- quantize(earned * (refunded.to_d.abs / gross))+ # Nil from any line means the attribution cannot be trusted whole, so+ # the blend answers for the refund rather than part of it.+ earnings = amounts.map { |line_item_id, amount| line_earning(line_item_id, amount.to_d) }+ return if earnings.any?(&:nil?)++ quantize(earnings.sum * (refunded.to_d.abs / gross))enddef blended_share(refunded)@@ -123,7 +127,11 @@ module Spreedef line_earning(line_item_id, amount)line_item = order_line_items[line_item_id]paid = line_item&.amount.to_d- return amount if paid.zero?+ # A line this order does not carry, or one worth nothing, says nothing+ # about what the seller earned. Answering the gross would claw back the+ # commission and the tax they never received, which is the whole thing+ # this is here to avoid, so the caller falls back to the order's ratio.+ return if paid.zero?# Only ever a fraction of the line, so a clamped commission is divided# rather than reasoned about — the best available attribution.diff --git a/spree/core/spec/models/spree/seller_balance_spec.rb b/spree/core/spec/models/spree/seller_balance_spec.rbindex b7029eed68..0755572e7b 100644--- a/spree/core/spec/models/spree/seller_balance_spec.rb+++ b/spree/core/spec/models/spree/seller_balance_spec.rb@@ -38,6 +38,22 @@ RSpec.describe Spree::SellerBalance, type: :model doexpect(described_class.for(seller, 'USD').balance).to eq(seller.balance('USD'))end+ # Two sale currencies can settle into one account currency. That is two+ # positions and one deposit — the figures reconcile, but neither row is+ # the payout on its own.+ it 'reconciles with the payout when two sale currencies settle into one' do+ earn(100)+ earn(50, currency: 'EUR')+ Spree::SellerTransfer.where(currency: 'USD').update_all(settled_amount: 75, settled_currency: 'GBP')+ Spree::SellerTransfer.where(currency: 'EUR').update_all(settled_amount: 42, settled_currency: 'GBP')++ payable = seller.balances.select { |balance| balance.settlement_currency == 'GBP' }++ expect(payable.map(&:balance)).to contain_exactly(75, 42)+ expect(payable.sum(&:balance)).to eq(seller.balance('GBP'))+ expect(seller.balance('GBP')).to eq(117)+ end+it 'keeps another currency out' doearn(40)earn(30, currency: 'EUR')diff --git a/spree/core/spec/models/spree/seller_transfer_spec.rb b/spree/core/spec/models/spree/seller_transfer_spec.rbindex 1238a36871..582faf1a42 100644--- a/spree/core/spec/models/spree/seller_transfer_spec.rb+++ b/spree/core/spec/models/spree/seller_transfer_spec.rb@@ -57,6 +57,24 @@ RSpec.describe Spree::SellerTransfer, type: :model doexpect(transfer(settled_amount: 69.80, settled_currency: 'USD')).not_to be_convertedend+ # An aggregate over an expression carries no column type, so the adapter+ # decides what comes back — a Float on SQLite and MySQL. Money is not kept+ # in one.+ it 'sums settlement in decimal, whatever the adapter' do+ transfer(settled_amount: 51.60, settled_currency: 'GBP')++ expect(Spree::SellerTransfer.settling_in('GBP').settlement_total).to be_a(BigDecimal)+ expect(seller.balance('GBP')).to be_a(BigDecimal)+ end++ it 'sums the sale figure for rows no provider has settled' do+ transfer+ transfer(settled_amount: 51.60, settled_currency: 'GBP')++ expect(Spree::SellerTransfer.settling_in('USD').settlement_total).to eq(69.80)+ expect(Spree::SellerTransfer.settling_in('GBP').settlement_total).to eq(51.60)+ end+it 'groups by the currency a payout could send' doconverted = transfer(settled_amount: 51.60, settled_currency: 'GBP')plain = transferdiff --git a/spree/core/spec/workflows/spree/fulfillments/create_spec.rb b/spree/core/spec/workflows/spree/fulfillments/create_spec.rbindex 0a6f2e4962..d58abd3a4b 100644--- a/spree/core/spec/workflows/spree/fulfillments/create_spec.rb+++ b/spree/core/spec/workflows/spree/fulfillments/create_spec.rb@@ -231,14 +231,29 @@ module Spreeend# What a split shipping part of an order passes: delivery was bought- # once at checkout, so the second parcel carries nothing.- it 'keeps a zero cost, so a split parcel is free' do+ # once at checkout, so the parcel that breaks off carries nothing. The+ # source survives here, holding the units that did not move.+ it 'keeps a zero cost when the parcel it came from survives' doparams[:cost] = 0+ params[:items] = [{ line_item: line_items.first, quantity: 1 }]expect(execute.success?).to eq(true)expect(fulfillment.reload.cost).to eq(0)end+ # A zero says "do not price this parcel", not "this parcel is free". A+ # shipment emptied of its units is destroyed, and its cost is money the+ # order already carried — dropped here, the order's delivery total+ # falls below what the customer paid for it.+ it 'still carries the cost of a shipment it emptied' do+ original = source_shipment.cost+ params[:cost] = 0++ expect(execute.success?).to eq(true)+ expect(fulfillment.reload.cost).to eq(original)+ expect(order.reload.delivery_total).to eq(original)+ end+it 'still prices a parcel the caller did not price' doparams.delete(:cost)diff --git a/spree/core/spec/workflows/spree/seller_payouts/sweep_spec.rb b/spree/core/spec/workflows/spree/seller_payouts/sweep_spec.rbindex 0b3a754905..25e57b0caa 100644--- a/spree/core/spec/workflows/spree/seller_payouts/sweep_spec.rb+++ b/spree/core/spec/workflows/spree/seller_payouts/sweep_spec.rb@@ -188,6 +188,19 @@ RSpec.describe Spree::SellerPayouts::Sweep donot_to change { Spree::SellerPayout.count }expect(seller.seller_transfers.unsettled.sum(:amount)).to eq(40)end++ # Reported rather than halted, so an operator pressing Settle is not told+ # the seller is owed nothing while the provider is merely unreachable.+ it 'says so rather than reading as nothing to settle' do+ earn(40)+ allow_any_instance_of(Spree::PayoutProvider::System).to receive(:available_payout).+ and_raise(Spree::Core::AmbiguousGatewayError, 'timed out')++ result = described_class.call(seller: seller, currency: 'USD')++ expect(result).to be_failure+ expect(result.error.to_s).to include('timed out')+ endend# A cross-border account settles in its own currency, so what a payout candiff --git a/spree/core/spec/workflows/spree/seller_transfers/reverse_spec.rb b/spree/core/spec/workflows/spree/seller_transfers/reverse_spec.rbindex 5de90096cf..609be008a7 100644--- a/spree/core/spec/workflows/spree/seller_transfers/reverse_spec.rb+++ b/spree/core/spec/workflows/spree/seller_transfers/reverse_spec.rb@@ -165,10 +165,17 @@ RSpec.describe Spree::SellerTransfers::Reverse doexpect(described_class.call(order: order, amount: 30).value.settled_amount).to eq(-18)end- it 'records no settlement when the earning had none' do+ # Nothing converted, so the clawback settles as it was sold — the same+ # figure, in the same currency, which is what the built-in provider always+ # produces.+ it 'settles as it was sold when nothing was converted' doearn(80)- expect(described_class.call(order: order, amount: 30).value.settled_amount).to be_nil+ reversal = described_class.call(order: order, amount: 30).value++ expect(reversal.settled_amount).to eq(-24)+ expect(reversal.settled_currency).to eq('USD')+ expect(reversal).not_to be_convertedendenddiff --git a/spree/providers/stripe/app/models/spree_stripe/gateway.rb b/spree/providers/stripe/app/models/spree_stripe/gateway.rbindex 6b5b3f03b4..37ee21a7bf 100644--- a/spree/providers/stripe/app/models/spree_stripe/gateway.rb+++ b/spree/providers/stripe/app/models/spree_stripe/gateway.rb@@ -67,10 +67,10 @@ module SpreeStripe# read as every key having changed.return false if previously_new_record?- before, after = saved_change_to_preferences- return false unless before.is_a?(Hash) && after.is_a?(Hash)-- before[:secret_key] != after[:secret_key]+ # The preference macro's own reader rather than a hand-rolled diff: it+ # reads the change through indifferent access, so it answers the same+ # whether the serialized hash came back with symbol or string keys.+ preferred_secret_key_previously_changed?enddef gateway_dashboard_payment_url(payment)diff --git a/spree/providers/stripe/spec/models/spree_stripe/payout_provider_spec.rb b/spree/providers/stripe/spec/models/spree_stripe/payout_provider_spec.rbindex fb3aaabbe5..45fcdf5e87 100644--- a/spree/providers/stripe/spec/models/spree_stripe/payout_provider_spec.rb+++ b/spree/providers/stripe/spec/models/spree_stripe/payout_provider_spec.rb@@ -202,14 +202,15 @@ RSpec.describe SpreeStripe::PayoutProvider doexpect(seller_transfer).not_to be_convertedend- # Better to read the earned figure than to invent a settlement.- it 'leaves it unrecorded when Stripe did not say' do+ # Better to leave the sale's own figures standing than to invent a+ # settlement Stripe never reported.+ it 'leaves the sale figures standing when Stripe did not say' doallow(Stripe::Transfer).to receive(:create).and_return(Stripe::StripeObject.construct_from(id: 'tr_1'))described_class.new.transfer!(seller_transfer)- expect(seller_transfer.reload.settled_amount).to be_nil- expect(seller_transfer.settlement_currency).to eq('USD')+ expect(seller_transfer.reload.settled_amount).to eq(seller_transfer.amount)+ expect(seller_transfer.settled_currency).to eq('USD')endend