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.
Cart/Order Split
Status: Implemented via the core-rewrite waves (Waves 1+5, 2026-07-29) — Spree::Cart owns checkout end to end, the Order state machine and spree_orders.state are gone, the Carts::Complete three-phase pipeline is live and Orders::UpdateStatuses is the sole status writer. Wave 7's data migration (incomplete orders → carts) landed with the rest. Remaining: Phase 6 cleanup only, scoped to 6.1 (drop the deprecation aliases and the migration task; null: false on spree_orders.market_id/channel_id)
Target: Spree 6.0
Depends on: API v3 conventions. Gates (they depend on this plan): 6.0-6.1-split-adjustments.md (typed-line owner), 6.0-fulfillment-and-delivery.md (fulfillment/rate owner), 6.0-multi-vendor-marketplace.md Phase 3 (seller attribution fires inside Orders::Complete, the one finalize home — moved there 2026-09-17, V-3643), 6.0-normalize-state-to-status.md (Order.state removed here). This was the most upstream 6.0 refactor; all four gated plans have since shipped on top of it.
Author: Damian + Claude
Last updated: 2026-08-27
Summary
Cart and Order become separate models. A Spree::Cart owns the shopping/checkout phase; completing checkout copies it into an immutable Spree::Order (cart.complete! → Spree::Carts::Complete). The Order state machine is removed: checkout progression is answered by the (already shipped) Spree::Checkout::Requirements, and order-level payment/fulfillment statuses are derived-then-persisted — one recompute service writing indexed columns.
Industry (2026-07-27 review, primary sources): separate cart/order with copy-on-completion is the majority pattern — OSS platform A (Cart module → Order module, parallel tables, cart retained with completed_at), OSS platform B (Checkout → Order via checkoutComplete, idempotent on checkout_token), the hosted market leader (which deleted its intermediate Checkout API entirely in 2025 in favor of Cart → Order). OSS platform C is the lone single-entity dissenter, and its workarounds (active flag, orderPlacedAt, orderPlacedQuantity snapshots, Modifying states that re-open placed orders) are the argument for splitting.
What already exists (verified 2026-07-27)
The codebase is further along than the old stub implied — the split formalizes seams that are already drawn:
- The v3 Store API is already cart-shaped.
Spree::Carts::{Create,Update,UpsertItems,Complete}exist with explicit "In Spree 6 …" comments; routes are/store/carts/...+ read-only/store/orders/:id. This plan rewritesCarts::Complete's internals — the public surface barely moves. - The API contract is step-shaped, not state-shaped.
CartSerializerexposes onlycurrent_step,completed_steps,requirements,warnings— never rawstate.OrderSerializerexposespayment_status/fulfillment_status/completed_at— no state, no steps. Spree::Checkout::Requirements+Checkout::Registryalready compute "what's missing to complete" with zero reads oforder.state(default_requirements.rb:6-7says the 6.0 intent verbatim). One fix needed:Registry#ordered_stepscurrently derives ordering fromOrder.checkout_step_names— that circular dependency gets cut (the registry owns its own step list).- The query layer already draws the boundary on
completed_at.Order.complete/.incomplete(the dominant scopes) key oncompleted_at, notstate;Store#carts/#checkoutsareincomplete-scoped. Only four rawwhere(state:)sites exist against orders, all trivially re-expressible. Order#status(draft/placed/canceled) already exists and is maintained byfinalize!/after_cancel/after_resume— the lifecycle column survives; the checkoutstatecolumn does not.LineItemhas half the owner pattern already —belongs_to :orderwith presence validation and a realorder_idFK. Under the unified dual-FK owner design (Key Decision 2), Phase 1 only adds nullablecart_idand relaxes presence to exactly-one;order_idstays forever. The old constraint "useline_item.owner" was unimplementable until then;ownerships as a method.
Key Decisions (do not deviate without discussion)
1. Spree::Cart model; Order keeps its table
Spree::Cart (prefix cart_, spree_carts) owns the pre-completion phase: store/market/channel/currency/locale/customer binding (settling today's three inconsistent creation paths — current_order creates orders without market/channel/locale and would fail multi-market validation), email, ship/bill address references, accept_marketing, special instructions, its own has_secure_token, metadata, completed_at, completing_at (completion lock). Carts have no status column (OSS platform A: completed_at is the only lifecycle marker). Order keeps spree_orders; its state column is dropped, status stays.
2. One owner pattern everywhere: dual concrete FKs (cart_id/order_id, exactly-one) — NOT polymorphic
Supersedes the original stub's "polymorphic owner" (decision 2026-07-27). 6.0's design language is concrete FKs over polymorphic type strings (split-adjustments removes adjustable_type, typed-stock-movements removes originator_type) — LineItem doesn't get to reintroduce the pattern the release removes. So every cart-or-order-owned table uses the same shape: nullable cart_id + nullable order_id, exactly-one validation, #owner as a method (order || cart). That covers spree_line_items (which only gains cart_id — order_id already exists and stays permanently; the cheapest possible migration), the typed money lines (TaxLine/Discount/Fee — split-adjustments), and Fulfillment (fulfillment plan). DeliveryRate carries no owner columns (settled 2026-07-28): a rate belongs to its fulfillment and derives the owner through it — spree_shipping_rates has neither FK today, and duplicating the pair would be drift risk at every completion re-pointing.
Provenance needs no second FK on the row. Order#cart_id (unique — the idempotency key) links every order to its cart; the retained cart keeps its own rows as the frozen at-checkout snapshot, so "which cart did this come from" is answered through the order, and post-placement additions are distinguishable (rows the order has that its cart never had). Both-columns-set was considered and rejected: order-side copies carrying cart_id would collide with the cart's own rows in every cart.line_items-style association.
LineItem's 22 internal + 14 external order reads move to owner (pricing context, tax zone, inventory, promo allocation, guest-token permission checks); order-owned items keep answering line_item.order natively.
3. Copy-on-completion — copy everything, share nothing
At completion the order receives copies: line items (with new IDs; typed money lines re-pointed per the split-adjustments copy contract), fulfillments + selected delivery rates, and addresses (never shared rows — OSS platform B copies addresses precisely so a later cart/profile edit can't corrupt order history). The cart is retained with completed_at + the order link (OSS platform A's choice, not the hosted leader's deletion) — retention is what makes idempotent replay natural and preserves abandoned-cart analytics. The guest token is carried onto the order so the confirmation page works with the credential the guest already holds.
4. Idempotent completion (the top gap in the old stub)
Every competitor treats this as load-bearing. Spree::Carts::Complete:
spree_orders.cart_idwith a unique index — stronger than OSS platform B'sfilter().first()under true concurrency.- On entry: if an order exists for this cart, return it as success — a double-clicked Place Order or a retry after a lost response must get the order back, never an error (OSS platform B ships three separate recovery paths for exactly this).
cart.with_lock+completing_atguard against parallel attempts.- Order created before payment capture (OSS platform A, verbatim rationale: minimizes the window in which an authorized/captured payment must be rolled back); compensation voids on post-payment failure. Applies to external gateways; offline methods (Check, net terms, COD, manual) have no external window and complete in a single transaction.
- Usage counters (coupon codes, gift cards, promotion
credits_countinputs) guarded by persisted flags (OSS platform B'sis_voucher_usage_increased) — counters are the classic double-count victim on retry. - The payment-webhook completion path stays (
Payments::HandleWebhook→ same service): with the unique index + lock, the two-writer race (synchronous complete vs. webhook) is safe by construction, not by the current 30-second job delay.
5. State machine removed — three replacements, not one
(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, 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 — behindcompletion: trueso the advisory feed on cart reads stays cheap) or registered viaCheckout::Registry.add_requirement.Requirements#call(completion: true)is the completion answer —Carts::Completecalls it directly (theCarts::Validateshell was deleted once it became a one-liner), so the APIrequirementsarray (now carrying stablecodes) 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_stepsdelegates toRegistry.step_names_for(record), which splices applicable registered custom steps at theirbefore:/after:anchors. Installs customize by mutatingbase_steps(replace a predicate, deleteconfirm) or registering steps — no constants, no subclassing. - Customization surface: extra requirement → one
Registry.add_requirementline (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::Updategraduates to the workflow tier per the services doctrine. - One finalize home: the order-side completion (payments when needed, fulfillment finalize, place, side effects, auto-fulfill, statuses,
order.placed) is theSpree::Orders::Completeworkflow — named steps, serving both checkout (Carts::Completedelegates its FINALIZE phase) and admin/B2B drafts (order_complete_workflow, legacyorder_complete_servicekey bridged);Order#finalize!is a deprecated 6.1-removal shell. Doctrine rider: services/workflows never hide behavior behind model business methods — logic is written inline in named steps (models keep data, validations, predicates, persistence primitives).
(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, 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
status:draft/placed/canceled(existing column;partially_canceledbecomes a derived predicate over child cancellations, not a status value).completed?≡completed_at.present?;canceled?≡ status.can_ship?,uneditable?,allow_cancel?re-expressed overstatus+completed_at+ fulfillment/return data.- Cancel/resume/approve remain services (
Orders::Cancel/Resume/Approve— approve is already machine-free) flippingstatusand running today's side effects (restock/void/refund branches preserved verbatim).awaiting_return/returnedstates are not carried over — that lifecycle belongs to6.0-returns-exchanges-claims.md's first-class Return models. - The
confirmation_required?self-reference (the|| confirm?hack from #4117) dies with the machine: whether the confirm/review step exists is computed from data only (Spree::Config[:always_include_confirm_step]or any selected payment method requiring confirmation). A confirm-stage failure no longer "falls back" to an earlier state — there are no states; the client stays on review with the failure inrequirements/errors. - Order
state_changesaudit rows are dropped in favor of lifecycle events (order.placed,order.canceled,order.resumed,order.approved— already published today).Payment/fulfillment machines keep their ownSuperseded 2026-08-07:StateChangerows.Spree::StateChange(andSpree::LogEntry) are removed entirely — lifecycle events are the audit everywhere; the tables survive to 6.1 as legacy data (see decisions.md). - Event naming after the split (settled 2026-07-29, revised same day): carts publish their own
cart.created/cart.updated/cart.deletedlifecycle events (restoring the 5.x abandonment signal that incomplete orders'order.*events used to provide; Shopifycarts/*parity). The placement event isorder.placed— renamed from the historicalorder.completed(Medusa's exact term; avoids Medusa'sorder.completed= "fulfillment finished" collision and reads right to newcomers, the primary audience). 6.0 dual-emits the legacy name withdeprecated_alias_ofmetadata; dropped in 6.1.order.createdcannot take that role because it fires for every order row, including admin drafts and the pre-payment draft copy insideCarts::Complete(a failed payment then emitsorder.deletedfor it). Admin confirmation resends publish the targetedorder.resend_confirmation_email, no longer re-blasting the placement event to all consumers. The order event payload carriescart_idso abandonment tooling can cancel flows on conversion (BigCommercestore/cart/convertedparity). - Price-freeze guarantee (what OSS platform C's
ArrangingPaymentlock provided):completing_atrejects cart mutations while payment is in flight, and the completed Order is immutable per split-adjustments' order-level freeze. Auditable price-at-completion also serves EU Omnibus.
7. Cart hygiene — new, and newly necessary
- Tiered expiry reaper (none exists today — verified): guest carts 30d, customer carts 90d, empty carts hours — configurable, measured on an indexed
updated_at, batched. Carts with money attached (authorized/pending payment sessions or transactions) are never reaped (OSS platform B's exclusion — never garbage-collect a cart mid-authorization). - Cart merging becomes a swappable strategy (
Spree::Dependencies.cart_merge_strategy; OSS platform C ships four strategies because there's no universally right answer). The default preserves currentOrderMergerbehavior minus its bugs: no silent dropping of different-currency items without surfacing it, no hard-destroy of the >10 cart overflow with only a log line.
8. Legacy Spree::Cart::* services removed; Carts::* become the registered seam
Of the 14 Spree::Cart::* services, 8 are dead weight (DI-registered, zero callers) and are deleted. The 6 with real callers re-home onto the Cart model/Carts::* namespace (AddItem/SetQuantity/RemoveLineItem → the carts items flow; Associate; Empty; RemoveOutOfStockItems; CompareLineItems → the merge strategy). Carts::{Create,Update,UpsertItems} get DI registration (today only carts_complete_service is registered and controllers reference the others as hard constants). controller_helpers/order.rb's current_order becomes current_cart built through Carts::Create (fixing its missing market/channel/locale binding).
9. Breaking surface, stated plainly
order.state, the checkout state machine,checkout_flow/insert_checkout_step/remove_checkout_step,next!/advance, andcan_go_to_state?are removed. Extension authors migrate toCheckout::Registry+ requirements.- Ransack:
stateleaves the whitelist (invisible-but-real surface: any admin table filter or API list query usingstate_eq).status,payment_status,fulfillment_statusare filterable stored columns — the replacement is strictly more useful. OrderLock'sstate_lock_versionoptimistic counter is renamedlock_versionsemantics-preserving (it never depended on the state machine, only on the column name).order_walkthrough+ order factories (publictesting_supportAPI) are rewritten cart-first.- The emails gem survives untouched except
checkout_state_url(token, :payment)in the payment-link email → a cart checkout URL.
Design Details
Completion (Spree::Carts::Complete) — pipeline, edge cases, recovery
Completion is a three-phase pipeline with explicit transaction boundaries. External payment I/O never runs inside a DB transaction; everything after a successful charge is small, idempotent, and resumable.
PHASE P — PREPARE (one transaction)
P1. Replay check: completion_result(cart) → return success(order|order_group)
P2. cart.with_lock; reject if completing_at fresh (409 completion_in_progress);
treat completing_at older than TTL (default 5 min) as stale → take over
P3. In-lock recalculation (prices, promotions, tax estimate) — the totals about
to be charged are computed HERE, not trusted from earlier requests
P4. Drift guard: if client sent expected_total and it ≠ cart.total
→ 409 cart_changed { current_total } (client re-renders, confirms, retries)
P5. Carts::Validate — full battery, structured errors (see API contract)
P6. Final availability check against reservations (extend holds through completion)
P7. Create Order with status: 'draft' + copies (line items owner re-pointed,
typed money lines, fulfillments + selected rates, address COPIES,
email/currency/locale/market/channel, guest token carried, number 'R…');
write orders.cart_id (unique); stamp completing_at
— invisible everywhere: storefront lists use placed_orders; the admin
Drafts list is scoped to cart_id: nil (backoffice draft orders have no
cart), so a mid-completion 'draft' order never surfaces there
PHASE Y — PAYMENT (transaction boundary depends on the method — see below)
Y1. Skip when not payment_required? (zero total, or store credit + gift card
fully cover — the covered-by-credit path must never auto-complete earlier
than this point; see Carts::Update's try_advance note)
Y2. Process payments against the DRAFT ORDER's totals, per method class:
• OFFLINE (Check, on-account/terms, cash-on-delivery, bank transfer,
manual/backoffice-recorded): no external I/O — the method returns a
local success response and the payment lands `pending`/`completed`
per auto_capture?. Runs INSIDE the FINALIZE transaction (no separate
phase, nothing to compensate).
• EXTERNAL GATEWAY (payment sessions, redirect/3DS, card capture):
no transaction; compensation on failure.
Y3. External failure → compensate: destroy draft order + copies, clear
completing_at, return 422 payment_failed { code, message } — cart stays
active, nothing external happened. (Only pre-capture failures compensate
this way; post-capture failures never destroy the order — see FINALIZE.)
PHASE F — FINALIZE (one transaction; every step idempotent)
F1. Inventory: finalize units (pending: false), unstock, release stock
reservations (single home — fixes today's asymmetry where the admin
completion path never releases reservations)
F2. Usage counters behind persisted flags: coupon codes, gift card redeem,
promotion credits (each checks-then-sets its flag — retry-safe)
F3. Vendor split hook (multi-vendor Phase 3): partition → child orders +
OrderGroup; completion_result becomes the group
F4. order.status: 'draft' → 'placed'; cart.completed_at stamped;
completing_at cleared; UpdateStatuses
F5. after_commit: publish order.placed / order.completed (notify_customer
honored), digital fulfillment via FulfillmentProvider::Digital,
user-account creation + newsletter subscribe (non-fatal side jobs)
Resumability is structural, not bookkept. The order's status: 'draft' + cart.completed_at: nil IS the "finalize pending" marker — no separate completion-state column. A retried Complete call resumes: replay check finds the draft order → skips PREPARE, re-verifies payment coverage (Y), re-runs FINALIZE (every step guards itself). Events fire only in after_commit of the transaction that flips draft → placed, so a rolled-back finalize never leaks an order.completed event or confirmation email.
Per-step idempotency (what makes retry safe):
| Step | Guard |
|---|---|
| Order creation | unique orders.cart_id (DB constraint, not a lookup) |
| Payment | payment records checked before processing (skip when a valid completed payment covers the total — today's Carts::Complete guard, kept) |
| Inventory finalize | pending flag on units; unstock only pending units |
| Coupon/gift-card/promo counters | persisted per-cart flags, check-then-set |
| Digital links | find_or_create per line item per quantity (fixes today's non-idempotent one-per-line-item callback) |
| Events/email | fired on the draft → placed flip only; confirmation_delivered? guard stays |
Not every payment method is an external gateway. Offline methods — PaymentMethod::Check, B2B on-account/net-terms, cash on delivery, bank transfer, and anything recorded through the manual payments API — already flow through the same process_payments! seam but perform no external I/O: the method returns a local success response, and auto_capture? decides whether the payment lands pending (authorized, captured later by an admin when the invoice is settled) or completed. Consequences for this pipeline:
- Offline payments collapse PAYMENT into FINALIZE. With no network call there is nothing to compensate and no partial-failure window, so the whole completion is a single transaction. The three-phase shape exists for external gateways; offline methods take the degenerate path.
payment_required?is not "must be paid now". A net-terms order completes withpayment_total: 0and apendingpayment — that is a successfully completed, unpaid order, not a failure. Completion must gate on "a valid payment exists covering the total" (today'spending_payments.any? && unprocessed_payments.empty?guard), never onpaid?.UpdateStatusesreportspayment_status: none/authorized; dunning and capture are post-completion admin/AR concerns.- Store credit and gift cards are offline by the same rule — store-credit payments are voided last on compensation. A gift card's payment follows the total in
Carts::RecalculateTotals, which P3's in-lock recalculation runs, so it is current when Y processes it (decisions.md 2026-09-24). - Mixed offline + external (deposit on card, remainder on terms): any external component forces the external path; the offline components are processed inside the same phase and voided alongside on compensation.
- B2B/backoffice orders created through the Admin API bypass this pipeline's checkout ergonomics but must reuse the same service so idempotency, inventory finalization, and reservation release stay in one place — fixing today's asymmetry where
Orders::Completenever releases reservations. allow_checkout_on_gateway_errorkeeps its meaning for external methods only; it must not mask offline failures (which indicate a bug or a rule violation, not a flaky network).
Payment edge cases (external gateways):
- Async success (3DS / redirect / webhook). Both writers call the same service: the customer's return-page
POST /completeandPayments::HandleWebhook. Whoever runs first creates the order; the other replays it. The webhook keeps itsorder.with_lock+ replay check, but safety comes from the unique index — the current 30-second job delay becomes a latency optimization, not a correctness mechanism. - Webhook says failed. Mark the payment session failed; do not compensate an order unless one exists in
draftwith no other valid payment — then compensate as Y3. Cart stays active for another attempt. - Payment captured, finalize keeps failing (e.g. DB partition). The order exists as
draftwith a successful payment. Never auto-refund on transient failure. A completion-recovery sweeper retries FINALIZE for staledraftorders with paid coverage; persistent failures alert operators. This is the precise scenario the order-before-payment ordering minimizes. - Partial store credit or gift card + external payment. A gift card's payment is resized by every totals recalculation, P3's included, and released when the total reaches zero. Applied store credit keeps the amount the buyer applied until it is applied again; nothing resizes it, so a total that falls below it overcharges the credit (open, decisions.md 2026-09-24). The two are never combined on one order. The external session covers the remainder; Y2 processes both, store credit last-voided on compensation.
- Zero-total carts (100% promo, gift card): Y is skipped entirely; F runs. The "never auto-complete during address updates" rule stays in
Carts::Update#try_advance— only an explicitCompletecall reaches this pipeline. - Late webhook after cart expiry. Cannot happen by construction: the reaper never deletes carts with authorized/pending payment sessions (money-safety exclusion, Key Decision 7).
Drift and mutation guards:
completing_atrejects cart mutations (items, addresses, discounts) with 409cart_lockedwhile payment is in flight — the price-freeze guarantee. TTL-stale locks are reclaimable so a crashed process never bricks a cart.- Recalculation happens inside the lock (P3): expired promotions drop out, price-list changes apply, tax re-estimates. The
expected_totalguard (P4) turns silent drift into an explicit client confirmation loop instead of charging an amount the customer never saw. - Stock: reservations are held/extended through completion; the P6 check catches reservation-less installs. Backorderable variants complete with backordered units (today's semantics — backorder is a fulfillment status, not a completion failure).
- Optimistic concurrency:
state_lock_versionis renamedlock_versionwith identical increment-on-write semantics; a stale client gets 409stale_carton mutation, andCompleteitself relies on the row lock instead.
Multi-vendor interaction. The idempotency lookup is completion_result(cart): exactly one of cart.order (single-partition — bare order, cart_id on it) or cart.order_group (multi-partition — cart_id on the group, child orders linked through it). The split runs inside FINALIZE (F3), i.e. after payment: a mid-split crash resumes like any finalize failure, and the replay returns the group once it exists.
API contract (POST /store/carts/:id/complete):
| Outcome | Response |
|---|---|
| Completed (including replay of an already-completed cart) | 200 { order } (or { order_group }) |
| Validation failed | 422 { errors: [{ step, field, code, message }] } — same shape as the requirements attribute |
| Payment declined / failed pre-capture | 422 { error: { code: 'payment_failed', … } } |
| Totals changed since client render | 409 { error: { code: 'cart_changed', current_total } } |
| Another completion in flight | 409 { error: { code: 'completion_in_progress' } } — client polls/retries; replay returns the order when done |
| Cart mutated while locked | 409 cart_locked (on the mutation endpoints, not on complete) |
Status recomputation
Spree::Orders::UpdateStatuses.call(order:) # the ONLY writer of both columns
# payment_status: quantized(captured + charged) vs quantized(total − granted_refunds)
# → none/authorized/partially_paid/paid/partially_refunded/refunded/
# overcharged/voided
# fulfillment_status: aggregated from fulfillment records incl. backorder
# (domain owned by the fulfillment plan)
Triggered by subscribers on payment, refund, fulfillment, and return events — never inline from controllers.
Completion side-effect parity checklist
Everything today's finalize! + after_transition to: :complete chain does is accounted for in the flow above or explicitly relocated: adjustment freeze (→ split-adjustments order-level freeze), payment/shipment status updates (→ UpdateStatuses), status: 'placed', completed_at, update hooks, risk check (considered_risky + order.updated), order.completed event, coupon-code use, gift-card redeem, newsletter subscribe, user-account creation, digital links (→ FulfillmentProvider::Digital, idempotent + per-quantity — fixing the current checkout-callback's non-idempotent one-per-line-item behavior), confirmation email (already event-driven via the emails subscriber; unchanged for a checkout that does not split — a split one confirms once from its OrderGroup instead, see 6.0-multi-vendor-marketplace.md).
Migration Path
Phase 1 — schema (additive)
spree_carts; nullable cart_id on spree_line_items (order_id stays; presence validation relaxes to exactly-one); spree_orders.cart_id (unique); stored status columns per the normalize plan. spree_orders.state survives untouched until Phase 4.
Phase 2 — data (rake task)
Existing incomplete orders convert to Cart rows (they are today's carts): one Cart per incomplete order carrying token/binding/addresses; line items re-owned to the cart (cart_id set, order_id nulled); the hollow order row deleted. Incomplete orders mid-payment (valid payment sessions/authorizations) are converted last with their sessions re-linked. Completed orders are untouched except cart_id: nil. Batched, idempotent, resumable.
Phase 3 — model + services
Cart model + recalculation-on-write; Carts::Complete rewrite (flow above); Registry step-list ownership; legacy Cart::* deletion/re-homing; current_cart; merge strategy; reaper; predicates re-expressed (LINE_ITEM_REMOVABLE_STATES et al.).
Phase 4 — remove the machine
Delete Order::Checkout, the state column, checkout_flow API, order state_changes writes; Ransack whitelist swap; UpdateStatuses + subscribers; the six out-of-band state writers (address services etc.) become cart-recalculation triggers.
Phase 5 — API/SDK/dashboard/docs
Contract is already step-shaped, so this is thin: carts/fulfillments_controller's cart.next loop → requirements-driven; serializers unchanged in shape; typelizer/Zod/OpenAPI regeneration; order_walkthrough/factories; extension-migration guide (checkout_flow → Registry); emails payment-link URL.
Phase 6 — cleanup (6.1)
Drop deprecation aliases and the migration task. (spree_line_items.order_id is NOT dropped — it's half of the permanent dual-FK owner pattern.)
Also in 6.1 (2026-07-29): spree_orders.market_id and spree_orders.channel_id gain null: false — the 6.0 upgrade manifest's spree:backfill_order_markets step (plus the 5.4→5.5 channels backfill) guarantees every install has resolved values by then. spree_carts already enforces both at the DB from creation.
Constraints on Current Work
- Any new code touching line items uses
line_item.owner, notline_item.order—owneris a method (order || cart); until Phase 1 lands it simply returnsorder, so the constraint is implementable today. - Don't add checkout states, transitions, or
checkout_flowsteps — extendCheckout::Registryinstead. - Don't read or filter on
order.statein new code — usecompleted_at/statuspredicates and the requirements API. - New money/fulfillment tables are born with the cart/order owner XOR (already honored by split-adjustments and fulfillment plans).
- Don't build on
state_changesrows at all — the model is gone (2026-08-07); subscribe to lifecycle events. - An order's address copy is made with
Spree::Address#snapshot, neverdup(2026-08-31): the copy records where the parcel went and belongs to the order, so it carries no owner and no label.dupkept the owner, which added two fresh copies of the buyer's saved address to their address book on every order they placed. Reuse of an existing address row is confined to the buyer's own book — the ownerless rows are other people's cart addresses and the snapshots placed orders keep. - Address copying and address equality are two questions, and each has exactly one answer (2026-08-31).
#snapshotmakes the copy;#==/value_attributes/EXCLUDED_KEYS_FOR_COMPARISONanswer whether two rows mean the same place, and nothing that makes a copy may read them — otherwise editing equality semantics silently changes what orders record.Spree::Address#clonewas the third answer and is deprecated: it becomes the standard RubyObject#clonein 6.1, so don't call it and don't build on it.
Resolved Questions
Order before payment (OSS platform A's ordering) — minimizes authorized-money rollback; compensation voids on post-payment failure.
Cart retained, not deleted (OSS platform A over the hosted market leader) — idempotency, analytics, debugging.
Statuses stored, not read-time-derived (OSS platform B over OSS platform A) — with the four hard-won derivation rules above.
confirmation_required?self-reference eliminated — confirm-step existence computed from config + payment-method data only.Existing incomplete orders migrate to carts in Phase 2 — no dual-model serving window; the API façade means clients never notice.
Guest token carried cart → order; permission sets check the same credential.
Order
state_changesdropped for lifecycle events; payment/fulfillment rows followed on 2026-08-07 whenSpree::StateChangewas removed entirely.awaiting_return/returnedare not order statuses — returns lifecycle belongs to the returns plan.Completion resumability is structural:
order.status: 'draft'+orders.cart_idpresent +cart.completed_at: nilis the "finalize pending" marker — no completion-state column. Mid-completion drafts are excluded from the admin Drafts list bycart_id: nilscoping (backoffice drafts have no cart).A completion-recovery sweeper retries FINALIZE for stale
draftorders with paid coverage and alerts on persistent failure; transient failures never trigger auto-refund. Pre-capture payment failures compensate by destroying the draft order; post-capture failures never do.Offline payment methods are first-class, not a gateway special case. Check, B2B on-account/net-terms, COD, bank transfer, store credit, gift cards, and manual-API-recorded payments perform no external I/O, so PAYMENT collapses into the FINALIZE transaction with nothing to compensate. Completion gates on "a valid payment covers the total", not on
paid?— a net-terms order completes unpaid with apendingpayment andpayment_status: none/authorized; capture and dunning are post-completion AR concerns.allow_checkout_on_gateway_errorapplies to external methods only.checkout_flowis hard-removed in 6.0 — no shim (2026-07-28). Extensions migrate toCheckout::Registry(register_step/add_requirement) via the migration guide; a translation shim would be leaky (machine transitions have no registry equivalent) and would prolong the dual API.partially_canceledis a derived predicate (2026-07-28) computed over child cancellations; the storedstatusdomain staysdraft/placed/canceled. Ransack filtering, if needed, goes through a whitelisted scope.Reaper defaults: guest 30d, customer 90d, empty carts 48h (2026-07-28) —
Spree::Configpreferences; the money-safety exclusion (never reap carts with authorized/pending payment sessions) is unconditional.
Open Questions
None at this time.
References
- Codebase inventory + competitor research (2026-07-27): checkout-flow anatomy (
order/checkout.rb:42-133— 14 cart-phase / 8 completion / 11 post-completion callbacks), state-consumer census (public contract is step-shaped; scopes already oncompleted_at), OSS platform AcompleteCartWorkflow, OSS platform Bcheckout_complete.py(idempotency,is_voucher_usage_increased, expiry tiers), the hosted market leader Checkout-API shutdown, OSS platform Cdefault-order-process.ts - Cautionary bugs: OSS platform A's repo#14095 (unfilterable derived status), #13882 (status stuck after return), the hosted market leader
financial_status:expiredfilter divergence - Existing seams:
spree/core/app/services/spree/carts/*.rb,spree/core/app/models/spree/checkout/{requirements,registry,default_requirements}.rb,api/app/serializers/spree/api/v3/cart_serializer.rb - Related plans:
6.0-6.1-split-adjustments.md,6.0-fulfillment-and-delivery.md,6.0-multi-vendor-marketplace.md,6.0-returns-exchanges-claims.md,6.0-normalize-state-to-status.md,6.0-stock-reservations.md