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
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.mdindex 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.rbindex 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: :controlendend+ 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' dolet(: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.rbindex 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_stepreturn '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_sstep == 'cart' ? 'address' : stepend+ # @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.rbindex 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 Spreeenddef payment_satisfied?- @cart.payments.valid.any?+ @cart.payments.valid.sum(:amount) >= @cart.totalend# Advisory rather than completion-only: the buyer has to be told thediff --git a/spree/core/spec/models/spree/cart_spec.rb b/spree/core/spec/models/spree/cart_spec.rbindex 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 doendend+ 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' dolet(: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.rbindex 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 doa_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')+ )+ endenddescribe 'po_number requirement' do