spree-checkout

Spree Checkout

Checkout is how a cart becomes a completed order. In Spree, an Order is the cart (while in cart state) AND the completed transaction (post-complete); the state column tracks which phase you're in.

The order state machine

Default checkout flow on an Order:

cart  →  address  →  delivery  →  payment  →  confirm  →  complete

Each step is conditional. Looking at Spree::Order.checkout_flow:

checkout_flow do
  go_to_state :address
  go_to_state :delivery, if: ->(order) { order.delivery_required? }
  go_to_state :payment,  if: ->(order) { order.payment? || order.payment_required? }
  go_to_state :confirm,  if: ->(order) { order.confirmation_required? }
  go_to_state :complete
end

So:

• All-digital orders are not skipped via delivery_required? — in core that method unconditionally returns true (decorate it to change). Instead, digital-only orders (requires_ship_address? is !digital?) still transition into delivery, then an after_transition to: :delivery hook (move_to_next_step_if_address_not_required) immediately calls next! to auto-advance past it.
• Zero-total orders (free orders) skip payment — payment_required? is simply total.to_f > 0.0. Note gift cards do NOT zero the total: applying one creates a store-credit payment for the covered amount, so a gift-card-covered order still has total > 0 and still goes through the payment step, where that payment satisfies it.
• confirm is opt-in — disabled by default; some payment integrations enable it.

The transition driver is state_machines-activerecord. Advance with order.next! (raises on failure) or order.next (returns false on failure).

cart.state                # => "cart"
cart.next!                # => transitions to "address" (if validation passes)
cart.state                # => "address"

state vs status columns

Order has BOTH state (the checkout state machine — values from the flow above) and status (the high-level lifecycle: Spree::Order::STATUSES = %w[draft placed canceled]). payment_state and shipment_state are separate denormalized columns reflecting the rollup of child Payment and Shipment states.