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.

Fix: placed order keeps its old payment status after its total is edited (#14754)

Łukasz Adamczykd256e3319d4d
diff --git a/docs/plans/6.0-cart-order-split.md b/docs/plans/6.0-cart-order-split.md
index c9e4c19a1a..d5964b4003 100644
--- a/docs/plans/6.0-cart-order-split.md
+++ b/docs/plans/6.0-cart-order-split.md
@@ -64,7 +64,7 @@ Every competitor treats this as load-bearing. `Spree::Carts::Complete`:
**(b) Transition-triggered recalculation → recalculation-on-write.** Today tax/prices/shipment rebuilds fire *only* on state transitions (4 call sites) — an address changed in place at `payment` never re-runs tax. The Cart model recalculates explicitly on the writes that matter: address/market change → re-price, re-tax, rebuild delivery proposals (the destructive `create_proposed_shipments` behavior becomes an idempotent cart-side rebuild; the order's fulfillments are a frozen copy, never rebuilt); item changes → totals + reservations (the existing Release/Reserve/Extend dispatch in `Carts::Update` carries over). The stale memoized `tax_zone` hazard dies with the memoized order context.
-**(c) Statuses → derive-then-persist (OSS platform B's hybrid, explicitly not OSS platform A's pure derivation).** OSS platform A derives payment/fulfillment status at read time and has open bugs to show for it (can't filter/sort admin order lists — #14095; status stuck after full return — #13882); the hosted market leader has the analogous `financial_status:expired` filter-index bug. Spree's admin is Ransack-heavy — pure derivation breaks order-list filtering on day one. So: `payment_status` and `fulfillment_status` are **stored, indexed string columns** (names per the normalize plan), recomputed by a single `Spree::Orders::UpdateStatuses` service triggered from payment/fulfillment/refund/store-credit/return event subscribers. One writer, many triggers. Rules that competitors learned the hard way: quantize money to currency precision **before** comparing; subtract granted/pending refunds from the total before comparing, counting refunds paid as store credit alongside the gateway rows (2026-09-22 — credit writes no `Spree::Refund`, so counting those alone left a fully credited order reading `paid`); include `overcharged` (OSS platform B) and `voided` (the hosted market leader) in the payment domain; define the returns interplay explicitly (where OSS platform A's derivation broke). The `fulfillment_status` domain (incl. `backorder`) is owned by `6.0-fulfillment-and-delivery.md`.
+**(c) Statuses → derive-then-persist (OSS platform B's hybrid, explicitly not OSS platform A's pure derivation).** OSS platform A derives payment/fulfillment status at read time and has open bugs to show for it (can't filter/sort admin order lists — #14095; status stuck after full return — #13882); the hosted market leader has the analogous `financial_status:expired` filter-index bug. Spree's admin is Ransack-heavy — pure derivation breaks order-list filtering on day one. So: `payment_status` and `fulfillment_status` are **stored, indexed string columns** (names per the normalize plan), recomputed by a single `Spree::Orders::UpdateStatuses` service triggered from payment/fulfillment/refund/store-credit/return event subscribers, and by each service that edits a placed order's money (fees, discounts, items) once it has re-summed the totals (2026-09-25 — no event announces a total moving, so those edits left a paid order reading `paid` with money owed). One writer, many triggers. Rules that competitors learned the hard way: quantize money to currency precision **before** comparing; subtract granted/pending refunds from the total before comparing, counting refunds paid as store credit alongside the gateway rows (2026-09-22 — credit writes no `Spree::Refund`, so counting those alone left a fully credited order reading `paid`); include `overcharged` (OSS platform B) and `voided` (the hosted market leader) in the payment domain; define the returns interplay explicitly (where OSS platform A's derivation broke). The `fulfillment_status` domain (incl. `backorder`) is owned by `6.0-fulfillment-and-delivery.md`.
### 6. Order lifecycle stays on Order, without a machine
diff --git a/docs/plans/decisions.md b/docs/plans/decisions.md
index 32704050e2..eaca1c9da1 100644
--- a/docs/plans/decisions.md
+++ b/docs/plans/decisions.md
@@ -1,3 +1,15 @@
+## 2026-09-25: Editing a placed order's money re-derives its payment status
+
+**Context:** Adding a charge to a paid order left it reading `paid` with money owed (V-3638). Reproduced on `main`: order R1001, total $205.00, paid $205.00; a $50.00 fee took the total to $255.00 and `amount_due` to $50.00 while `payment_status` stayed `paid`, and `update_statuses!` answered `partially_paid` at once. The stale status then stuck through every later edit: deleting the fee left a fully paid order reading `partially_paid`, and cutting a quantity until the customer had paid $100.00 over the total still read `partially_paid` rather than `overcharged`. The cause is a gap in the trigger list. `UpdateStatuses` runs from payment, refund, store credit, fulfillment and return events, and the post-placement edit services (fees, manual discounts, items) re-sum the totals and stop, because no event announces a total moving. Changing a fulfillment's delivery rate was the one edit that worked: `Fulfillments::Update` calls `update_statuses!` itself.
+
+**Decision:** Each service that edits an order's money calls `order.update_statuses!` after it re-sums the totals: `Orders::Fees::{Create,Update,Destroy}`, `Orders::Discounts::{Create,Update,Destroy}`, `Orders::Update`, `Orders::UpdateItem` and `Orders::AddItem`. The fee and discount services make the call inside their own order lock. The other three rely on the lock their API controllers take, and `AddItem` makes it after its transaction has committed. The call is unconditional, as the event subscriber's is, so a draft order's statuses stay derived as well. Edits that save a payment or fulfillment row (gift cards, store credit, fulfillment create and move) are already covered, since those events fire after commit, once the new total is in place.
+
+Rejected: deriving the statuses inside the totals workflow, which would cover every caller at once but give up that workflow's money-only contract; and publishing a new "totals changed" event for the subscriber, which adds a public event name to answer something the edit services already know.
+
+**Consequences:** A new service that edits a placed order's money has to make the same call, because nothing else will. `Orders::RemoveLineItem` does not, and is left alone deliberately. It routes through `Orders::UpsertItems`, which never recalculates totals, so `DELETE /api/v3/admin/orders/:id/items/:id` currently removes the line and leaves the total where it was. Deriving a status from that stale total would change nothing, and the missing recalculation is a defect of its own. `Exchanges::Fulfill` and `Claims::Resolve` are not covered either: they recalculate totals as their last step, after their refund and fulfillment events have already derived the statuses. Whether that final recalculation moves the total, for example by charging delivery on a replacement, was not established here. `amount_due` never goes below zero, so an overpaid order shows an outstanding balance of $0.00 and only the `overcharged` status says a refund is owed.
+
+**Plans amended:** `6.0-cart-order-split.md` (the derive-then-persist triggers).
+
## 2026-09-23: The free-gift action prices its own gift, and covers the copy the shopper already has
**Context:** The `Create line items` action added its variant at full price and wrote no discount, so the promotion raised the bill: a cart of 2 x $89.99 became $269.97 when an automatic gift promotion applied, with no line saying why, and the shopper could not delete the gift because every recalculation put it back (V-3666). The action was the only one describing itself in the docs without saying how the money worked - "Free items", "free items in the cart", "Free gift with purchase" - while `discount_scope` answered nil, which is what excluded it from `Spree::Adjusters::Promotion`. The documented workaround, pairing it with an order discount set to the gift's price, was tested and fails three ways: the order-level amount prorates across every line, so the gift reads as an $8.57 purchase and the $20 item beside it as $11.43; the discount still pays out when the gift is out of stock, because `Promotion#activate` maps over actions independently ($20 cart, $15 off, no gift); and the compensation competes for the order group under 6.0 winner-only, so a larger promotion deletes it and the bill goes back up ($2.00 to $17.00 on entering a free-gift coupon).
diff --git a/spree/core/app/services/spree/orders/discounts/create.rb b/spree/core/app/services/spree/orders/discounts/create.rb
index deb72b4d75..a65f6c77ff 100644
--- a/spree/core/app/services/spree/orders/discounts/create.rb
+++ b/spree/core/app/services/spree/orders/discounts/create.rb
@@ -23,7 +23,10 @@ module Spree
rows = order.with_lock do
created = line_item ? [line_item_row(order, line_item, label, value, value_type)].compact : distributed_rows(order, label, value, value_type)
- Spree.order_recalculate_totals_workflow.call(order: order) if created.any?
+ if created.any?
+ Spree.order_recalculate_totals_workflow.call(order: order)
+ order.update_statuses!
+ end
created
end
diff --git a/spree/core/app/services/spree/orders/discounts/destroy.rb b/spree/core/app/services/spree/orders/discounts/destroy.rb
index 76cee015f8..c5f2c924d5 100644
--- a/spree/core/app/services/spree/orders/discounts/destroy.rb
+++ b/spree/core/app/services/spree/orders/discounts/destroy.rb
@@ -15,6 +15,7 @@ module Spree
order.with_lock do
discount.destroy!
Spree.order_recalculate_totals_workflow.call(order: order)
+ order.update_statuses!
end
success(discount)
diff --git a/spree/core/app/services/spree/orders/discounts/update.rb b/spree/core/app/services/spree/orders/discounts/update.rb
index abdd4608cd..e66484fd97 100644
--- a/spree/core/app/services/spree/orders/discounts/update.rb
+++ b/spree/core/app/services/spree/orders/discounts/update.rb
@@ -18,6 +18,7 @@ module Spree
next false unless discount.update(attributes)
Spree.order_recalculate_totals_workflow.call(order: order)
+ order.update_statuses!
true
end
diff --git a/spree/core/app/services/spree/orders/fees/create.rb b/spree/core/app/services/spree/orders/fees/create.rb
index 0a873d8f60..eb70c4cd61 100644
--- a/spree/core/app/services/spree/orders/fees/create.rb
+++ b/spree/core/app/services/spree/orders/fees/create.rb
@@ -17,6 +17,7 @@ module Spree
next false unless fee.save
Spree.order_recalculate_totals_workflow.call(order: order)
+ order.update_statuses!
true
end
diff --git a/spree/core/app/services/spree/orders/fees/destroy.rb b/spree/core/app/services/spree/orders/fees/destroy.rb
index 112ebfbd77..acd2ba579b 100644
--- a/spree/core/app/services/spree/orders/fees/destroy.rb
+++ b/spree/core/app/services/spree/orders/fees/destroy.rb
@@ -12,6 +12,7 @@ module Spree
order.with_lock do
fee.destroy!
Spree.order_recalculate_totals_workflow.call(order: order)
+ order.update_statuses!
end
success(fee)
diff --git a/spree/core/app/services/spree/orders/fees/update.rb b/spree/core/app/services/spree/orders/fees/update.rb
index 3ddfe48a3c..824ea3451f 100644
--- a/spree/core/app/services/spree/orders/fees/update.rb
+++ b/spree/core/app/services/spree/orders/fees/update.rb
@@ -14,6 +14,7 @@ module Spree
next false unless fee.update(attributes)
Spree.order_recalculate_totals_workflow.call(order: order)
+ order.update_statuses!
true
end
diff --git a/spree/core/app/services/spree/orders/update.rb b/spree/core/app/services/spree/orders/update.rb
index 39736ad3b2..dc644b766b 100644
--- a/spree/core/app/services/spree/orders/update.rb
+++ b/spree/core/app/services/spree/orders/update.rb
@@ -30,6 +30,7 @@ module Spree
end
@order.recalculate_totals!
+ @order.update_statuses!
end
success(@order.reload)
diff --git a/spree/core/app/services/spree/orders/update_item.rb b/spree/core/app/services/spree/orders/update_item.rb
index 878af7fa05..a81520eaf6 100644
--- a/spree/core/app/services/spree/orders/update_item.rb
+++ b/spree/core/app/services/spree/orders/update_item.rb
@@ -47,7 +47,10 @@ module Spree
ActiveRecord::Base.transaction do
return failure(line_item) unless line_item.update(attributes)
- Spree::Orders::Recalculate.call(order: order, line_item: line_item) if quantity_changing || price_provided
+ if quantity_changing || price_provided
+ Spree::Orders::Recalculate.call(order: order, line_item: line_item)
+ order.update_statuses!
+ end
end
success(line_item)
diff --git a/spree/core/app/services/spree/orders/update_statuses.rb b/spree/core/app/services/spree/orders/update_statuses.rb
index 5e162a7cc0..86a770d6a7 100644
--- a/spree/core/app/services/spree/orders/update_statuses.rb
+++ b/spree/core/app/services/spree/orders/update_statuses.rb
@@ -4,7 +4,9 @@ module Spree
# Derive-then-persist: statuses are recomputed from payment/refund/
# fulfillment records and stored in indexed columns so admin filtering
# keeps working. Triggered from payment/refund/fulfillment/return event
- # subscribers — never inline from controllers.
+ # subscribers, and by each edit service that moves an order's total
+ # (fees, discounts, items) once it has re-summed — no event announces
+ # that change. Never inline from controllers.
class UpdateStatuses
prepend Spree::ServiceModule::Base
diff --git a/spree/core/app/workflows/spree/orders/add_item.rb b/spree/core/app/workflows/spree/orders/add_item.rb
index ffc30a725e..fe2b055961 100644
--- a/spree/core/app/workflows/spree/orders/add_item.rb
+++ b/spree/core/app/workflows/spree/orders/add_item.rb
@@ -5,7 +5,11 @@ module Spree
# behavior can diverge without branching one implementation.
class AddItem < Spree::Carts::AddItem
def perform(order:, **rest)
- super(cart: order, **rest)
+ result = super(cart: order, **rest)
+ # Placed orders take items through here too, and their payment
+ # status is measured against the total that just moved.
+ order.update_statuses!
+ result
end
end
end
diff --git a/spree/core/spec/services/spree/orders/discounts/create_spec.rb b/spree/core/spec/services/spree/orders/discounts/create_spec.rb
index 0cd2ef0c1c..92a97c872b 100644
--- a/spree/core/spec/services/spree/orders/discounts/create_spec.rb
+++ b/spree/core/spec/services/spree/orders/discounts/create_spec.rb
@@ -88,6 +88,19 @@ module Spree
expect(result.error.to_s).to eq(Spree.t('errors.messages.discount_value_type_invalid'))
end
end
+
+ context 'when the order has been paid in full' do
+ before do
+ create(:payment, amount: order.total, order: order, status: 'completed')
+ order.update_statuses!
+ end
+
+ it 'reads overcharged once the total falls below what was paid' do
+ expect do
+ described_class.call(order: order, label: 'Goodwill', value: 3, line_item: line_item)
+ end.to change { order.reload.payment_status }.from('paid').to('overcharged')
+ end
+ end
end
end
end
diff --git a/spree/core/spec/services/spree/orders/discounts/destroy_spec.rb b/spree/core/spec/services/spree/orders/discounts/destroy_spec.rb
index 1b62e8a3ed..a6b8e33ceb 100644
--- a/spree/core/spec/services/spree/orders/discounts/destroy_spec.rb
+++ b/spree/core/spec/services/spree/orders/discounts/destroy_spec.rb
@@ -19,6 +19,19 @@ module Spree
end.to change { order.reload.total }.by(2).and change { order.discounts.count }.by(-1)
end
+ context 'when the order has been paid in full' do
+ before do
+ create(:payment, amount: order.total, order: order, status: 'completed')
+ order.update_statuses!
+ end
+
+ it 'reads partially paid once the total rises above what was paid' do
+ expect do
+ described_class.call(order: order, discount: discount)
+ end.to change { order.reload.payment_status }.from('paid').to('partially_paid')
+ end
+ end
+
it 'refuses promotion-sourced rows' do
discount.update_columns(kind: 'promotion')
diff --git a/spree/core/spec/services/spree/orders/discounts/update_spec.rb b/spree/core/spec/services/spree/orders/discounts/update_spec.rb
index fa3bbd3ec6..45679e7ade 100644
--- a/spree/core/spec/services/spree/orders/discounts/update_spec.rb
+++ b/spree/core/spec/services/spree/orders/discounts/update_spec.rb
@@ -32,6 +32,21 @@ module Spree
expect(result).to be_failure
end.not_to change { order.reload.total }
end
+
+ context 'when the order has been paid in full' do
+ before do
+ discount
+ order.recalculate_totals!
+ create(:payment, amount: order.total, order: order, status: 'completed')
+ order.update_statuses!
+ end
+
+ it 'reads overcharged once the total falls below what was paid' do
+ expect do
+ described_class.call(order: order, discount: discount, attributes: { amount: -5 })
+ end.to change { order.reload.payment_status }.from('paid').to('overcharged')
+ end
+ end
end
end
end
diff --git a/spree/core/spec/services/spree/orders/fees/create_spec.rb b/spree/core/spec/services/spree/orders/fees/create_spec.rb
index 0a57c7eee8..c973876cac 100644
--- a/spree/core/spec/services/spree/orders/fees/create_spec.rb
+++ b/spree/core/spec/services/spree/orders/fees/create_spec.rb
@@ -29,6 +29,19 @@ module Spree
expect(result.value.errors[:amount]).to be_present
end.not_to change { [order.fees.count, order.reload.total] }
end
+
+ context 'when the order has been paid in full' do
+ before do
+ create(:payment, amount: order.total, order: order, status: 'completed')
+ order.update_statuses!
+ end
+
+ it 'reads partially paid once the fee raises the total' do
+ expect do
+ described_class.call(order: order, attributes: { label: 'Freight', amount: 50 })
+ end.to change { order.reload.payment_status }.from('paid').to('partially_paid')
+ end
+ end
end
end
end
diff --git a/spree/core/spec/services/spree/orders/fees/destroy_spec.rb b/spree/core/spec/services/spree/orders/fees/destroy_spec.rb
index 5b5aa7f039..ff9e47f499 100644
--- a/spree/core/spec/services/spree/orders/fees/destroy_spec.rb
+++ b/spree/core/spec/services/spree/orders/fees/destroy_spec.rb
@@ -16,6 +16,19 @@ module Spree
expect(result).to be_success
end.to change { order.reload.total }.by(-4).and change { order.fees.count }.by(-1)
end
+
+ context 'when the order has been paid in full' do
+ before do
+ create(:payment, amount: order.total, order: order, status: 'completed')
+ order.update_statuses!
+ end
+
+ it 'reads overcharged once the total falls below what was paid' do
+ expect do
+ described_class.call(order: order, fee: fee)
+ end.to change { order.reload.payment_status }.from('paid').to('overcharged')
+ end
+ end
end
end
end
diff --git a/spree/core/spec/services/spree/orders/fees/update_spec.rb b/spree/core/spec/services/spree/orders/fees/update_spec.rb
index a4bc8a35ba..b36a148998 100644
--- a/spree/core/spec/services/spree/orders/fees/update_spec.rb
+++ b/spree/core/spec/services/spree/orders/fees/update_spec.rb
@@ -25,6 +25,19 @@ module Spree
expect(result).to be_failure
end.not_to change { order.reload.total }
end
+
+ context 'when the order has been paid in full' do
+ before do
+ create(:payment, amount: order.total, order: order, status: 'completed')
+ order.update_statuses!
+ end
+
+ it 'reads partially paid once the fee raises the total' do
+ expect do
+ described_class.call(order: order, fee: fee, attributes: { amount: 6 })
+ end.to change { order.reload.payment_status }.from('paid').to('partially_paid')
+ end
+ end
end
end
end
diff --git a/spree/core/spec/services/spree/orders/item_services_spec.rb b/spree/core/spec/services/spree/orders/item_services_spec.rb
index 5035c28bb0..c9077f66e9 100644
--- a/spree/core/spec/services/spree/orders/item_services_spec.rb
+++ b/spree/core/spec/services/spree/orders/item_services_spec.rb
@@ -159,4 +159,21 @@ RSpec.describe 'draft order item services' do
expect(add_result.error.to_s).to include('placed order')
end
end
+
+ describe 'on an order that has been paid in full' do
+ before do
+ Spree::Orders::AddItem.call(order: order, variant: variant, quantity: 1)
+ order.update_columns(status: 'placed', completed_at: Time.current)
+ create(:payment, amount: order.reload.total, order: order, status: 'completed')
+ order.update_statuses!
+ end
+
+ it 'measures what has been paid against the total a quantity change leaves' do
+ line_item = order.line_items.sole
+
+ expect do
+ Spree::Orders::UpdateItem.call(order: order, line_item: line_item, quantity: 2)
+ end.to change { order.reload.payment_status }.from('paid').to('partially_paid')
+ end
+ end
end
diff --git a/spree/core/spec/services/spree/orders/update_spec.rb b/spree/core/spec/services/spree/orders/update_spec.rb
index feda0b0390..43c80a53c8 100644
--- a/spree/core/spec/services/spree/orders/update_spec.rb
+++ b/spree/core/spec/services/spree/orders/update_spec.rb
@@ -307,6 +307,13 @@ module Spree
expect(order.shipments.map(&:id)).to match_array(old_shipment_ids)
expect(order.fulfillments.first.fulfillment_items.sum(:quantity)).to eq(3)
end
+
+ it 'measures what has been paid against the new total' do
+ create(:payment, amount: order.total, order: order, status: 'completed')
+ order.update_statuses!
+
+ expect { subject }.to change { order.reload.payment_status }.from('paid').to('partially_paid')
+ end
end
end
diff --git a/spree/core/spec/workflows/spree/orders/add_item_spec.rb b/spree/core/spec/workflows/spree/orders/add_item_spec.rb
index b4e21d69cf..63f6e64f07 100644
--- a/spree/core/spec/workflows/spree/orders/add_item_spec.rb
+++ b/spree/core/spec/workflows/spree/orders/add_item_spec.rb
@@ -45,6 +45,19 @@ module Spree
subject.call(order: order, variant: variant, quantity: 1)
end.not_to change { Spree::StockReservation.count }
end
+
+ context 'when the order has been paid in full' do
+ before do
+ create(:payment, amount: order.total, order: order, status: 'completed')
+ order.update_statuses!
+ end
+
+ it 'reads partially paid once the new item raises the total' do
+ expect do
+ subject.call(order: order, variant: variant, quantity: 1)
+ end.to change { order.reload.payment_status }.from('paid').to('partially_paid')
+ end
+ end
end
end
end