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.

Do not mark cart as complete as long as order has not been placed (#14590)

Kacper Mękarski451287e80eff
diff --git a/docs/plans/6.0-cart-order-split.md b/docs/plans/6.0-cart-order-split.md
index 287cff1b34..ca2e4e5a4b 100644
--- a/docs/plans/6.0-cart-order-split.md
+++ b/docs/plans/6.0-cart-order-split.md
@@ -56,7 +56,7 @@ Every competitor treats this as load-bearing. `Spree::Carts::Complete`:
**(a) Checkout progression → Requirements.** `current_step`/`completed_steps`/`requirements` are computed by `Checkout::Requirements` against cart data. `Checkout::Registry` becomes the extension surface (`register_step`, `add_requirement` with before/after anchors), replacing the `checkout_flow`/`insert_checkout_step` class-attribute API, and owns its own ordered step list. The full battery runs at completion via `Checkout::Requirements` (completion mode) (lines present + in stock + not discontinued, email, addresses, delivery selected, payment coverage, guest policy) returning structured per-field errors with stable codes — also exposed read-only so storefronts can render checkout readiness without attempting completion (OSS platform B's model; OSS platform C's five `ArrangingPayment` guards expressed as data).
-**Checkout doctrine (settled 2026-08-01).** The backend enforces exactly **one hard gate** — `Carts::Complete` — and everything else about checkout is advisory. There is no server-side step sequencing: clients may write any checkout field in any order; "steps" are only a grouping label on requirements (which frontend page surfaces the error) plus serializer sugar (`current_checkout_step` = first unmet requirement). Sequencing is a frontend concern by design — the 5.x pain of hopping between backend flow definitions and frontend pages came from the backend owning the sequence, and it no longer does. Consequences, each with one home:
+**Checkout doctrine (settled 2026-08-01).** The backend enforces exactly **one hard gate** — `Carts::Complete` — and everything else about checkout is advisory. There is no server-side step sequencing: clients may write any checkout field in any order; "steps" are only a grouping label on requirements (which frontend page surfaces the error) plus serializer sugar (`current_checkout_step` = first unmet requirement, falling back to the last step before `complete` when nothing is outstanding — only a completed cart reports `complete`, since an open cart that meets every requirement is ready to be placed rather than placed). Sequencing is a frontend concern by design — the 5.x pain of hopping between backend flow definitions and frontend pages came from the backend owning the sequence, and it no longer does. Consequences, each with one home:
- **One completion truth:** every check is declared in `Checkout::DefaultRequirements` (completion-only checks — per-item stock, discontinued, guest policy — behind `completion: true` so the advisory feed on cart reads stays cheap) or registered via `Checkout::Registry.add_requirement`. `Requirements#call(completion: true)` *is* the completion answer — `Carts::Complete` calls it directly (the `Carts::Validate` shell was deleted once it became a one-liner), so the API `requirements` array (now carrying stable `code`s) and the completion gate can never disagree.
- **One step vocabulary:** `Registry.base_steps` — an ordered `{name => applicability-proc}` hash — is the sole declaration of built-in steps; `Purchase::CheckoutSteps#checkout_steps` delegates to `Registry.step_names_for(record)`, which splices applicable registered custom steps at their `before:`/`after:` anchors. Installs customize by mutating `base_steps` (replace a predicate, delete `confirm`) or registering steps — no constants, no subclassing.
- **Customization surface:** extra requirement → one `Registry.add_requirement` line (appears in the API feed *and* blocks completion, zero frontend changes for feed-rendering storefronts); "logic between steps" intentionally has no backend home — side effects hang off data writes (workflow hooks: `Carts::AddItem#after_item_added`, `Carts::Complete#before_finalize`) and events (`cart.updated`, `order.placed`). If step-entry side effects ever demand extensibility, `Carts::Update` graduates to the workflow tier per the services doctrine.
diff --git a/spree/api/spec/controllers/spree/api/v3/store/carts/gift_card_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/store/carts/gift_card_controller_spec.rb
index 00b1588a3d..bbd8d7e3c6 100644
--- a/spree/api/spec/controllers/spree/api/v3/store/carts/gift_card_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/store/carts/gift_card_controller_spec.rb
@@ -90,6 +90,35 @@ RSpec.describe Spree::Api::V3::Store::Carts::GiftCardsController, type: :control
end
end
+ context 'on a cart that is otherwise ready to be placed' do
+ let!(:order) { create(:cart_ready_for_delivery, store: store, customer: user) }
+
+ context 'when the card covers the whole basket' do
+ let!(:gift_card) { create(:gift_card, store: store, amount: order.total, code: 'giftcard123') }
+
+ it 'leaves the customer on the payment step with nothing outstanding' do
+ post :create, params: { cart_id: order.prefixed_id, code: 'giftcard123' }
+
+ expect(response).to have_http_status(:created)
+ expect(json_response['amount_due']).to eq('0.0')
+ expect(json_response['current_step']).to eq('payment')
+ expect(json_response['requirements']).to be_empty
+ end
+ end
+
+ context 'when a balance remains' do
+ let!(:gift_card) { create(:gift_card, store: store, amount: order.total - 1, code: 'giftcard123') }
+
+ it 'keeps asking for the rest of the money' do
+ post :create, params: { cart_id: order.prefixed_id, code: 'giftcard123' }
+
+ expect(response).to have_http_status(:created)
+ expect(json_response['current_step']).to eq('payment')
+ expect(json_response['requirements']).to include(a_hash_including('field' => 'payment'))
+ end
+ end
+ end
+
context 'with guest spree token' do
let(:guest_order) { create(:cart_with_line_items, store: store, customer: nil) }
diff --git a/spree/core/app/models/concerns/spree/purchase/checkout_steps.rb b/spree/core/app/models/concerns/spree/purchase/checkout_steps.rb
index eede340520..589feade69 100644
--- a/spree/core/app/models/concerns/spree/purchase/checkout_steps.rb
+++ b/spree/core/app/models/concerns/spree/purchase/checkout_steps.rb
@@ -33,15 +33,25 @@ module Spree
# missing line items — is not customer-facing and reports as
# 'address').
#
+ # Only a completed cart reports 'complete'. An open cart with nothing
+ # outstanding is not finished, it is ready to be placed, so it waits
+ # on {#final_checkout_step}
# @return [String]
def current_checkout_step
return 'complete' if completed?
first_unmet = Spree::Checkout::Requirements.new(self).call.first
- step = first_unmet ? first_unmet[:step].to_s : 'complete'
+ return final_checkout_step if first_unmet.nil?
+
+ step = first_unmet[:step].to_s
step == 'cart' ? 'address' : step
end
+ # @return [String]
+ def final_checkout_step
+ checkout_steps.reject { |step| step == 'complete' }.last || 'address'
+ end
+
# Checkout steps before {#current_checkout_step}; never includes
# 'complete'.
#
diff --git a/spree/core/app/models/spree/checkout/default_requirements.rb b/spree/core/app/models/spree/checkout/default_requirements.rb
index 56c52eeb4d..972aaa8364 100644
--- a/spree/core/app/models/spree/checkout/default_requirements.rb
+++ b/spree/core/app/models/spree/checkout/default_requirements.rb
@@ -99,7 +99,7 @@ module Spree
end
def payment_satisfied?
- @cart.payments.valid.any?
+ @cart.payments.valid.sum(:amount) >= @cart.total
end
# Advisory rather than completion-only: the buyer has to be told the
diff --git a/spree/core/spec/models/spree/cart_spec.rb b/spree/core/spec/models/spree/cart_spec.rb
index 30a393a85e..0752d3a90d 100644
--- a/spree/core/spec/models/spree/cart_spec.rb
+++ b/spree/core/spec/models/spree/cart_spec.rb
@@ -77,6 +77,52 @@ describe Spree::Cart, type: :model do
end
end
+ describe '#current_checkout_step' do
+ let(:cart) { build(:cart, store: store) }
+ let(:unmet) { [] }
+
+ before do
+ allow(cart).to receive_messages(delivery_step_required?: true, payment_required?: true,
+ confirmation_required?: false)
+ allow(Spree::Checkout::Requirements).to receive(:new).with(cart).
+ and_return(instance_double(Spree::Checkout::Requirements, call: unmet))
+ end
+
+ context 'when something is still outstanding' do
+ let(:unmet) { [{ step: 'delivery', field: 'delivery_method' }] }
+
+ it 'reports the step that thing belongs to' do
+ expect(cart.current_checkout_step).to eq('delivery')
+ end
+ end
+
+ context 'when the missing thing is the basket itself' do
+ let(:unmet) { [{ step: 'cart', field: 'line_items' }] }
+
+ it 'reports address, since the customer never sees a cart step' do
+ expect(cart.current_checkout_step).to eq('address')
+ end
+ end
+
+ context 'when nothing is outstanding' do
+ it 'waits on the last step rather than reporting completion' do
+ expect(cart.current_checkout_step).to eq('payment')
+ end
+
+ it 'waits on confirm where the checkout advertises a review pass' do
+ allow(cart).to receive_messages(confirmation_required?: true)
+
+ expect(cart.current_checkout_step).to eq('confirm')
+ end
+
+ it 'reports complete once the cart has actually completed' do
+ allow(cart).to receive_messages(completed?: true)
+
+ expect(cart.current_checkout_step).to eq('complete')
+ end
+ end
+ end
+
describe '#checkout_step_index' do
let(:cart) { build(:cart, store: store) }
diff --git a/spree/core/spec/models/spree/checkout/requirements_spec.rb b/spree/core/spec/models/spree/checkout/requirements_spec.rb
index f3a7371fbe..c15a13e303 100644
--- a/spree/core/spec/models/spree/checkout/requirements_spec.rb
+++ b/spree/core/spec/models/spree/checkout/requirements_spec.rb
@@ -110,6 +110,33 @@ RSpec.describe Spree::Checkout::Requirements do
a_hash_including(step: 'payment', field: 'payment')
)
end
+
+ it 'keeps asking for payment while one only covers part of the total' do
+ create(:payment, amount: order.total - 1, order: order)
+ order.reload
+
+ expect(subject).to include(
+ a_hash_including(step: 'payment', field: 'payment')
+ )
+ end
+
+ it 'stops asking once payments cover the total' do
+ create(:payment, amount: order.total, order: order)
+ order.reload
+
+ expect(subject).not_to include(
+ a_hash_including(step: 'payment', field: 'payment')
+ )
+ end
+
+ it 'ignores a failed payment when measuring coverage' do
+ create(:payment, amount: order.total, order: order, status: 'failed')
+ order.reload
+
+ expect(subject).to include(
+ a_hash_including(step: 'payment', field: 'payment')
+ )
+ end
end
describe 'po_number requirement' do