spree_core 5.4.0.beta6 → 5.4.0.beta7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1e118b3f3198080c2006abcd4956ae76608cf6a6a99ed7f16df2380839fe98f
-  data.tar.gz: 8f05ff3e72814788a15c7c145ea62f1f9efb603b5dcd18fcedcd07774274db7a
+  metadata.gz: 9a75c8667f68e7a71143adec2c78694c99308dbc73fa9afd625e1c5e339e2fb8
+  data.tar.gz: '04229df0b73d148776d498157514ed592db0ffb551dc347a2aca782cafb80f01'
 SHA512:
-  metadata.gz: b6b0596bb455d278630cf6df3e1927034c703f15e4319c856cec8eaa798e871ec671597a3bf07f3cb20846b775a460f77df8e828184fc2b1200c4a394760c361
-  data.tar.gz: c3693f84de9a1b1c26e3572f8c350a498050765242453b3b2a95d3a6956d06476a54db89ec3f21c0ba4bd0eea27edad7da2a2b1ada5f79d9a1eaf70a44084a28
+  metadata.gz: b237c3ae83b130df90180833997bd0301335689e620e2da1956f67881bb44031962895c5de052d807d886ae00682a35c3b1c6fea5541acdbde4347abd871875a
+  data.tar.gz: d57fc57c99f2a3466e482965bc1a6bec9a40f91b277669ae2c24dfa93d1b68790f95bb3d50f15f2648abb32b1cf5c3f99cd646bfecf7b34c3d0949417550e25f

data/app/jobs/spree/payments/handle_webhook_job.rb

@@ -0,0 +1,22 @@
+module Spree
+  module Payments
+    class HandleWebhookJob < Spree::BaseJob
+      queue_as Spree.queues.payment_webhooks
+
+      retry_on ActiveRecord::Deadlocked, wait: 5.seconds, attempts: 3
+      retry_on ActiveRecord::LockWaitTimeout, wait: 5.seconds, attempts: 3
+      discard_on ActiveRecord::RecordNotFound
+
+      def perform(payment_method_id:, action:, payment_session_id:)
+        payment_method = Spree::PaymentMethod.find(payment_method_id)
+        payment_session = Spree::PaymentSession.find(payment_session_id)
+
+        Spree::Dependencies.payments_handle_webhook_service.constantize.call(
+          payment_method: payment_method,
+          action: action.to_sym,
+          payment_session: payment_session
+        )
+      end
+    end
+  end
+end

data/app/models/concerns/spree/user_methods.rb

@@ -35,6 +35,7 @@ module Spree
       has_many :promotion_rule_users, class_name: 'Spree::PromotionRuleUser', foreign_key: :user_id, dependent: :destroy
       has_many :promotion_rules, through: :promotion_rule_users, class_name: 'Spree::PromotionRule'
       has_many :orders, foreign_key: :user_id, class_name: 'Spree::Order'
+      has_many :carts, -> { incomplete }, foreign_key: :user_id, class_name: 'Spree::Order'
       has_many :completed_orders, -> { complete }, foreign_key: :user_id, class_name: 'Spree::Order'
       has_many :store_credits, class_name: 'Spree::StoreCredit', foreign_key: :user_id, dependent: :destroy
       has_many :wishlists, class_name: 'Spree::Wishlist', foreign_key: :user_id, dependent: :destroy

data/app/models/spree/cart_promotion.rb

@@ -0,0 +1,7 @@
+module Spree
+  # Cart-facing view of an OrderPromotion.
+  # Same table, different prefix ID (cp_) for the Cart API.
+  class CartPromotion < OrderPromotion
+    has_prefix_id :cpromo
+  end
+end

data/app/models/spree/checkout/default_requirements.rb

@@ -0,0 +1,51 @@
+module Spree
+  module Checkout
+    # Built-in checkout requirements that map to the standard Spree checkout flow.
+    #
+    # Checks line items, email, shipping address, shipping method, and payment.
+    # In Spree 6 these same checks will read from the +Cart+ model instead of
+    # the state machine — the API contract stays identical.
+    #
+    # @see Requirements
+    class DefaultRequirements
+      # @param order [Spree::Order]
+      def initialize(order)
+        @order = order
+      end
+
+      # @return [Array<Hash{Symbol => String}>] unmet default requirements as
+      #   +{ step:, field:, message: }+ hashes
+      def call
+        [].tap do |r|
+          r << req('cart', 'line_items', Spree.t('checkout_requirements.line_items_required')) unless @order.line_items.any?
+          r << req('address', 'email', Spree.t('checkout_requirements.email_required')) unless @order.email.present?
+          r << req('address', 'ship_address', Spree.t('checkout_requirements.ship_address_required')) if @order.requires_ship_address? && @order.ship_address.blank?
+          r << req('delivery', 'shipping_method', Spree.t('checkout_requirements.shipping_method_required')) if delivery_required? && !shipping_method_selected?
+          r << req('payment', 'payment', Spree.t('checkout_requirements.payment_required')) if payment_required? && !payment_satisfied?
+        end
+      end
+
+      private
+
+      def delivery_required?
+        @order.has_checkout_step?('delivery') && @order.delivery_required?
+      end
+
+      def shipping_method_selected?
+        @order.shipments.any? && @order.shipments.all? { |s| s.shipping_method.present? }
+      end
+
+      def payment_required?
+        @order.has_checkout_step?('payment') && @order.payment_required?
+      end
+
+      def payment_satisfied?
+        @order.payments.valid.any?
+      end
+
+      def req(step, field, message)
+        { step: step, field: field, message: message }
+      end
+    end
+  end
+end

data/app/models/spree/checkout/registry.rb

@@ -0,0 +1,112 @@
+module Spree
+  module Checkout
+    # Global registry for custom checkout steps and requirements.
+    #
+    # Provides a composable extension point so developers can add, remove, or
+    # reorder checkout steps and attach extra requirements to existing steps —
+    # all without subclassing or monkey-patching.
+    #
+    # Registered steps and requirements are evaluated by {Requirements} at
+    # serialization time to produce the +requirements+ array on the Cart API.
+    #
+    # @example Add a custom step
+    #   Spree::Checkout::Registry.register_step(
+    #     name: :loyalty,
+    #     before: :payment,
+    #     satisfied: ->(order) { order.loyalty_verified? },
+    #     requirements: ->(order) { [{ step: 'loyalty', field: 'loyalty_number', message: 'Required' }] }
+    #   )
+    #
+    # @example Add a requirement to an existing step
+    #   Spree::Checkout::Registry.add_requirement(
+    #     step: :payment,
+    #     field: :po_number,
+    #     message: 'PO number is required',
+    #     satisfied: ->(order) { order.po_number.present? }
+    #   )
+    #
+    # @example Remove a step
+    #   Spree::Checkout::Registry.remove_step(:loyalty)
+    class Registry
+      class << self
+        # Register a new custom checkout step.
+        #
+        # @param name [String, Symbol] unique step identifier
+        # @param satisfied [Proc] lambda accepting an order, returns true when step is complete
+        # @param requirements [Proc] lambda accepting an order, returns Array of requirement hashes
+        # @param options [Hash] additional options forwarded to {Step} (+:before+, +:after+, +:applicable+)
+        # @return [Array<Step>] the updated steps list
+        def register_step(name:, satisfied:, requirements:, **options)
+          steps << Step.new(name: name, satisfied: satisfied, requirements: requirements, **options)
+        end
+
+        # Add an extra requirement to an existing checkout step.
+        #
+        # @param step [String, Symbol] checkout step this requirement belongs to
+        # @param field [String, Symbol] field identifier
+        # @param message [String] human-readable validation message
+        # @param satisfied [Proc] lambda accepting an order, returns true when met
+        # @param options [Hash] additional options forwarded to {Requirement} (+:applicable+)
+        # @return [Array<Requirement>] the updated requirements list
+        def add_requirement(step:, field:, message:, satisfied:, **options)
+          requirements << Requirement.new(step: step, field: field, message: message, satisfied: satisfied, **options)
+        end
+
+        # Remove a previously registered step by name.
+        #
+        # @param name [String, Symbol] step name to remove
+        # @return [Array<Step>] the updated steps list
+        def remove_step(name)
+          steps.reject! { |s| s.name == name.to_s }
+        end
+
+        # Remove a previously registered requirement by step and field.
+        #
+        # @param step [String, Symbol] checkout step the requirement belongs to
+        # @param field [String, Symbol] field identifier
+        # @return [Array<Requirement>] the updated requirements list
+        def remove_requirement(step:, field:)
+          requirements.reject! { |r| r.step == step.to_s && r.field == field.to_s }
+        end
+
+        # Returns steps sorted by +before+/+after+ constraints relative to the checkout flow.
+        #
+        # The sort order is derived from {Spree::Order.checkout_step_names} so it
+        # stays in sync with any customizations to the checkout state machine.
+        # Steps with +before:+/+after:+ anchors are ordered by the anchor's position;
+        # steps without constraints are appended at the end.
+        #
+        # @return [Array<Step>] steps in display order
+        def ordered_steps
+          return steps if steps.empty?
+
+          step_order = Spree::Order.checkout_step_names.map(&:to_s)
+          positioned, unpositioned = steps.partition { |s| s.before || s.after }
+
+          sorted = positioned.sort_by do |s|
+            anchor = s.before || s.after
+            idx = step_order.index(anchor)
+            # before: inserts just before the anchor, after: just after
+            idx ? (s.before ? idx - 0.5 : idx + 0.5) : Float::INFINITY
+          end
+
+          sorted + unpositioned
+        end
+
+        # @return [Array<Step>] all registered steps
+        def steps = (@steps ||= [])
+
+        # @return [Array<Requirement>] all registered requirements
+        def requirements = (@requirements ||= [])
+
+        # Clear all registered steps and requirements. Intended for testing.
+        #
+        # @return [void]
+        def reset!
+          @steps = []
+          @requirements = []
+        end
+      end
+    end
+  end
+end

data/app/models/spree/checkout/requirement.rb

@@ -0,0 +1,49 @@
+module Spree
+  module Checkout
+    # Value object representing a single additional requirement registered via {Registry}.
+    #
+    # Unlike {Step}, a Requirement attaches extra validation to an *existing* checkout step
+    # rather than introducing a new step.
+    #
+    # @example Require a PO number for B2B orders at the payment step
+    #   Spree::Checkout::Registry.add_requirement(
+    #     step: :payment,
+    #     field: :po_number,
+    #     message: 'PO number is required for business accounts',
+    #     satisfied: ->(order) { order.po_number.present? },
+    #     applicable: ->(order) { order.account&.business? }
+    #   )
+    class Requirement
+      # @return [String] checkout step this requirement belongs to
+      attr_reader :step
+
+      # @return [String] field identifier (e.g. +"po_number"+, +"tax_id"+)
+      attr_reader :field
+
+      # @return [String] human-readable message shown when the requirement is not met
+      attr_reader :message
+
+      # @param step [String, Symbol] checkout step this requirement belongs to
+      # @param field [String, Symbol] field identifier
+      # @param message [String] human-readable validation message
+      # @param satisfied [Proc] lambda accepting an order, returns true when met
+      # @param applicable [Proc] lambda accepting an order, returns true when this requirement applies
+      #   (defaults to always applicable)
+      def initialize(step:, field:, message:, satisfied:, applicable: ->(_) { true })
+        @step = step.to_s
+        @field = field.to_s
+        @message = message
+        @satisfied_proc = satisfied
+        @applicable_proc = applicable
+      end
+
+      # @param order [Spree::Order]
+      # @return [Boolean] whether the requirement has been met
+      def satisfied?(order) = @satisfied_proc.call(order)
+
+      # @param order [Spree::Order]
+      # @return [Boolean] whether this requirement applies to the given order
+      def applicable?(order) = @applicable_proc.call(order)
+    end
+  end
+end

data/app/models/spree/checkout/requirements.rb

@@ -0,0 +1,56 @@
+module Spree
+  module Checkout
+    # Aggregates all checkout requirements for an order.
+    #
+    # Combines built-in checks from {DefaultRequirements} with custom steps and
+    # requirements registered in {Registry}. The resulting array of hashes is
+    # exposed on the Cart API as the +requirements+ attribute.
+    #
+    # Each requirement hash has the shape:
+    #   { step: String, field: String, message: String }
+    #
+    # @example
+    #   reqs = Spree::Checkout::Requirements.new(order)
+    #   reqs.call  # => [{ step: "address", field: "email", message: "Email address is required" }]
+    #   reqs.met?  # => false
+    class Requirements
+      # @param order [Spree::Order]
+      def initialize(order)
+        @order = order
+      end
+
+      # @return [Array<Hash{Symbol => String}>] all unmet requirements
+      def call
+        default + from_registered_steps + from_additional_requirements
+      end
+
+      # @return [Boolean] true when all requirements are satisfied
+      def met?
+        call.empty?
+      end
+
+      private
+
+      # @return [Array<Hash>] built-in checkout requirements
+      def default
+        DefaultRequirements.new(@order).call
+      end
+
+      # @return [Array<Hash>] requirements from unsatisfied registered steps
+      def from_registered_steps
+        Registry.ordered_steps
+          .select { |s| s.applicable?(@order) }
+          .reject { |s| s.satisfied?(@order) }
+          .flat_map { |s| s.requirements(@order) }
+      end
+
+      # @return [Array<Hash>] requirements from unsatisfied registered requirements
+      def from_additional_requirements
+        Registry.requirements
+          .select { |r| r.applicable?(@order) }
+          .reject { |r| r.satisfied?(@order) }
+          .map { |r| { step: r.step, field: r.field, message: r.message } }
+      end
+    end
+  end
+end

data/app/models/spree/checkout/step.rb

@@ -0,0 +1,52 @@
+module Spree
+  module Checkout
+    # Value object representing a custom checkout step registered via {Registry}.
+    #
+    # @example Register a loyalty step before payment
+    #   Spree::Checkout::Registry.register_step(
+    #     name: :loyalty,
+    #     before: :payment,
+    #     satisfied: ->(order) { order.loyalty_verified? },
+    #     requirements: ->(order) { [{ step: 'loyalty', field: 'loyalty_number', message: 'Enter loyalty number' }] }
+    #   )
+    class Step
+      # @return [String] step name
+      attr_reader :name
+
+      # @return [String, nil] name of the checkout step this should be placed after
+      attr_reader :after
+
+      # @return [String, nil] name of the checkout step this should be placed before
+      attr_reader :before
+
+      # @param name [String, Symbol] unique step identifier
+      # @param satisfied [Proc] lambda accepting an order, returns true when the step is complete
+      # @param requirements [Proc] lambda accepting an order, returns Array of requirement hashes
+      #   (+{ step:, field:, message: }+) describing what is still needed
+      # @param applicable [Proc] lambda accepting an order, returns true when this step applies
+      #   (defaults to always applicable)
+      # @param after [String, Symbol, nil] place this step after the named checkout step
+      # @param before [String, Symbol, nil] place this step before the named checkout step
+      def initialize(name:, satisfied:, requirements:, applicable: ->(_) { true }, after: nil, before: nil)
+        @name = name.to_s
+        @after = after&.to_s
+        @before = before&.to_s
+        @satisfied_proc = satisfied
+        @requirements_proc = requirements
+        @applicable_proc = applicable
+      end
+
+      # @param order [Spree::Order]
+      # @return [Boolean] whether the step's conditions have been met
+      def satisfied?(order) = @satisfied_proc.call(order)
+
+      # @param order [Spree::Order]
+      # @return [Array<Hash{Symbol => String}>] outstanding requirement hashes (+{ step:, field:, message: }+)
+      def requirements(order) = @requirements_proc.call(order)
+
+      # @param order [Spree::Order]
+      # @return [Boolean] whether this step applies to the given order
+      def applicable?(order) = @applicable_proc.call(order)
+    end
+  end
+end

data/app/models/spree/order/checkout.rb

@@ -227,6 +227,24 @@ module Spree
             self.checkout_steps.index(step).to_i
           end
 
+          # Customer-facing checkout step derived from the internal state machine state.
+          # Maps +'cart'+ to +'address'+ since cart is not a user-facing checkout step.
+          #
+          # @return [String] current checkout step name (e.g. +"address"+, +"delivery"+, +"payment"+)
+          def current_checkout_step
+            state == 'cart' ? 'address' : state
+          end
+
+          # Checkout steps that have already been completed, i.e. all steps before
+          # {#current_checkout_step}. Does not include +'complete'+.
+          #
+          # @return [Array<String>] completed step names in order
+          def completed_checkout_steps
+            steps = checkout_steps.reject { |s| s == 'complete' }
+            idx = steps.index(current_checkout_step) || 0
+            steps.first(idx)
+          end
+
           def can_go_to_state?(state)
             return false unless has_checkout_step?(self.state) && has_checkout_step?(state)
 

data/app/models/spree/order.rb

@@ -139,6 +139,7 @@ module Spree
              inverse_of: :order
 
     has_many :order_promotions, class_name: 'Spree::OrderPromotion'
+    has_many :cart_promotions, class_name: 'Spree::CartPromotion', foreign_key: :order_id
     has_many :promotions, through: :order_promotions, class_name: 'Spree::Promotion'
 
     has_many :shipments, class_name: 'Spree::Shipment', dependent: :destroy, inverse_of: :order do
@@ -148,6 +149,8 @@ module Spree
     end
     has_many :shipment_adjustments, through: :shipments, source: :adjustments
 
+    alias items line_items
+
     accepts_nested_attributes_for :line_items
     accepts_nested_attributes_for :bill_address
     accepts_nested_attributes_for :ship_address

data/app/models/spree/order_promotion.rb

@@ -1,5 +1,7 @@
 module Spree
   class OrderPromotion < Spree.base_class
+    has_prefix_id :oprom
+
     belongs_to :order, class_name: 'Spree::Order'
     belongs_to :promotion, class_name: 'Spree::Promotion'
 

data/app/models/spree/payment_method.rb

@@ -71,10 +71,44 @@ module Spree
 
     # Completes a payment session via the provider.
     # Override in gateway subclasses to implement provider-specific session completion.
+    #
+    # Responsibilities:
+    # - Verify payment status with the provider
+    # - Create/update the Spree::Payment record
+    # - Patch order data from provider (e.g. wallet billing address)
+    # - Transition payment session to completed/failed
+    #
+    # Must NOT complete the order — that is handled by Carts::Complete
+    # (called by the frontend or by the webhook handler).
     def complete_payment_session(payment_session:, params: {})
       raise ::NotImplementedError, 'You must implement complete_payment_session method for this gateway.'
     end
 
+    # Parses an incoming webhook payload from the payment provider.
+    # Override in gateway subclasses to implement provider-specific webhook parsing.
+    #
+    # @param raw_body [String] the raw request body
+    # @param headers [Hash] the request headers
+    # @return [Hash, nil] normalized result or nil for unsupported events
+    #   { action: :captured/:authorized/:failed/:canceled,
+    #     payment_session: <Spree::PaymentSession>,
+    #     metadata: {} }
+    # @raise [Spree::PaymentMethod::WebhookSignatureError] if signature is invalid
+    def parse_webhook_event(raw_body, headers)
+      raise ::NotImplementedError, 'You must implement parse_webhook_event method for this gateway.'
+    end
+
+    # Returns the webhook URL for this payment method.
+    # @return [String, nil]
+    def webhook_url
+      store = stores.first
+      return nil unless store
+
+      "#{store.url_or_custom_domain}/api/v3/webhooks/payments/#{prefixed_id}"
+    end
+
+    class WebhookSignatureError < StandardError; end
+
     # Whether this payment method supports setup sessions (saving payment methods for future use).
     # Override in gateway subclasses that support tokenization without a payment.
     def setup_session_supported?

data/app/models/spree/payment_session.rb

@@ -76,6 +76,24 @@ module Spree
       expires_at.present? && expires_at <= Time.current
     end
 
+    # Creates or finds the Spree::Payment record for this session.
+    # Gateway subclasses can override this in their PaymentSession subclass
+    # to handle gateway-specific source creation (credit cards, wallets, etc).
+    #
+    # @param metadata [Hash] gateway-specific metadata
+    # @return [Spree::Payment] the payment record
+    def find_or_create_payment!(metadata = {})
+      return payment if payment.present?
+
+      order.payments.find_or_create_by!(
+        payment_method: payment_method,
+        response_code: external_id,
+      ) do |p|
+        p.amount = amount
+        p.skip_source_requirement = true
+      end
+    end
+
     private
 
     def publish_processing_event

data/app/models/spree/shipment.rb

@@ -354,6 +354,7 @@ module Spree
       return if order.completed?
 
       update_amounts
+      reload # reload to pick up cost set by update_columns in update_amounts
       order.set_shipments_cost
     end
 

data/app/models/spree/store.rb

@@ -58,6 +58,7 @@ module Spree
     #
     # Associations
     #
+    has_many :carts, -> { incomplete }, class_name: 'Spree::Order', inverse_of: :store
     has_many :checkouts, -> { incomplete }, class_name: 'Spree::Order', inverse_of: :store
     has_many :orders, class_name: 'Spree::Order'
     has_many :line_items, through: :orders, class_name: 'Spree::LineItem'

data/app/services/spree/cart/create.rb

@@ -3,49 +3,22 @@ module Spree
     class Create
       prepend Spree::ServiceModule::Base
 
-      # @param user [Spree.user_class, nil] the user to associate with the cart
-      # @param store [Spree::Store] the store for the cart
-      # @param currency [String, nil] ISO currency code, defaults to store's default currency
-      # @param locale [String, nil] locale for the cart (e.g. 'en', 'fr'), defaults to Spree::Current.locale
-      # @param public_metadata [Hash] public metadata for the order
-      # @param private_metadata [Hash] private metadata for the order
-      # @param order_params [Hash] additional order attributes
-      # @param line_items [Array<Hash>] line items to add, each with :variant_id (prefixed) and :quantity
-      # @return [Spree::ServiceModule::Result]
-      def call(user:, store:, currency:, locale: nil, metadata: {}, public_metadata: {}, private_metadata: {}, order_params: {}, line_items: [])
+      def call(user:, store:, currency:, public_metadata: {}, private_metadata: {}, order_params: {})
         order_params ||= {}
-        line_items ||= []
 
         # we cannot create an order without store
         return failure(:store_is_required) if store.nil?
 
-        resolved_metadata = metadata.presence || private_metadata
-
         default_params = {
           user: user,
           currency: currency || store.default_currency,
-          locale: locale || Spree::Current.locale,
           token: Spree::GenerateToken.new.call(Spree::Order),
           public_metadata: public_metadata.to_h,
-          private_metadata: resolved_metadata.to_h
+          private_metadata: private_metadata.to_h
         }
 
-        order = nil
-
-        ApplicationRecord.transaction do
-          order = store.orders.create!(default_params.merge(order_params))
-
-          if line_items.present?
-            result = Spree.cart_upsert_items_service.call(order: order, line_items: line_items)
-            raise StandardError, result.error.to_s if result.failure?
-          end
-        end
-
+        order = store.orders.create!(default_params.merge(order_params))
         success(order)
-      rescue ActiveRecord::RecordNotFound
-        raise
-      rescue StandardError => e
-        failure(order, e.message)
       end
     end
   end

data/app/services/spree/carts/complete.rb

@@ -0,0 +1,46 @@
+# In Spree 6 this servoice will complete the Spree::Cart, and create a Spree::Order
+# created based on the contents of the cart.
+module Spree
+  module Carts
+    class Complete
+      prepend Spree::ServiceModule::Base
+
+      # Completes the cart and creates a Spree::Order based on its contents.
+      # @return [Spree::Order]
+      def call(cart:)
+        return success(cart) if cart.completed?
+        return failure(cart, 'Order is canceled') if cart.canceled?
+
+        cart.with_lock do
+          process_payments!(cart) if cart.payment_required?
+
+          return failure(cart, cart.errors.full_messages.to_sentence) if cart.errors.any?
+
+          advance_to_complete!(cart)
+
+          if cart.reload.complete?
+            success(cart)
+          else
+            failure(cart, cart.errors.full_messages.to_sentence.presence || 'Could not complete checkout')
+          end
+        end
+      end
+
+      private
+
+      def process_payments!(cart)
+        # If payments were already processed by the payment session
+        # (e.g. Stripe charged the card during complete_payment_session),
+        # skip re-processing. Only process unprocessed (checkout state) payments.
+        return if cart.payment_total >= cart.total
+        return if cart.payments.valid.any?(&:completed?) && cart.unprocessed_payments.empty?
+
+        cart.process_payments!
+      end
+
+      def advance_to_complete!(cart)
+        cart.next until cart.complete? || cart.errors.present?
+      end
+    end
+  end
+end

data/app/services/spree/carts/create.rb

@@ -0,0 +1,32 @@
+module Spree
+  module Carts
+    class Create
+      prepend Spree::ServiceModule::Base
+
+      def call(params: {})
+        @params = params.to_h.deep_symbolize_keys
+
+        store = @params.delete(:store)
+        return failure(:store_is_required) if store.nil?
+
+        cart = store.carts.create!(
+          user: @params.delete(:user),
+          currency: @params.delete(:currency) || store.default_currency,
+          locale: @params.delete(:locale) || Spree::Current.locale
+        )
+
+        # Delegate all attribute/address/item processing to Carts::Update
+        if @params.present?
+          result = Spree::Carts::Update.call(cart: cart, params: @params)
+          return result if result.failure?
+        end
+
+        success(cart.reload)
+      rescue ActiveRecord::RecordNotFound
+        raise
+      rescue StandardError => e
+        failure(nil, e.message)
+      end
+    end
+  end
+end

data/app/services/spree/carts/update.rb

@@ -0,0 +1,115 @@
+module Spree
+  module Carts
+    class Update
+      prepend Spree::ServiceModule::Base
+
+      def call(cart:, params:)
+        @cart = cart
+        @params = params.to_h.deep_symbolize_keys
+
+        ApplicationRecord.transaction do
+          assign_cart_attributes
+          assign_address(:ship_address)
+          assign_address(:bill_address)
+
+          cart.save!
+
+          process_items
+        end
+
+        try_advance
+
+        success(cart)
+      rescue ActiveRecord::RecordNotFound
+        raise
+      rescue ActiveRecord::RecordInvalid => e
+        failure(cart, e.record.errors.full_messages.to_sentence)
+      rescue StandardError => e
+        failure(cart, e.message)
+      end
+
+      private
+
+      attr_reader :cart, :params
+
+      def assign_cart_attributes
+        cart.email = params[:email] if params[:email].present?
+        cart.special_instructions = params[:special_instructions] if params.key?(:special_instructions)
+        cart.currency = params[:currency].upcase if params[:currency].present?
+        cart.locale = params[:locale] if params[:locale].present?
+        cart.metadata = cart.metadata.merge(params[:metadata].to_h) if params[:metadata].present?
+      end
+
+      def assign_address(address_type)
+        address_id_param = params[:"#{address_type}_id"]
+        address_params = params[address_type]
+
+        if address_id_param.present?
+          address_id = resolve_address_id(address_id_param)
+          cart.public_send(:"#{address_type}_id=", address_id) if address_id
+          return
+        end
+
+        return unless address_params.is_a?(Hash)
+
+        if address_params[:id].present?
+          address_id = resolve_address_id(address_params[:id])
+          cart.public_send(:"#{address_type}_id=", address_id) if address_id
+        else
+          # Only revert to address state when shipping address changes.
+          # Billing address updates (e.g. during payment) should not
+          # destroy shipments and reset the checkout flow.
+          revert_to_address_state if address_type == :ship_address && cart.has_checkout_step?('address')
+          cart.public_send(:"#{address_type}_attributes=", address_params)
+        end
+      end
+
+      def process_items
+        return unless params[:items].is_a?(Array)
+
+        result = Spree::Carts::UpsertItems.call(
+          cart: cart,
+          items: params[:items]
+        )
+
+        raise StandardError, result.error.to_s if result.failure?
+      end
+
+      def resolve_address_id(prefixed_id)
+        return unless cart.user
+
+        decoded = Spree::Address.decode_prefixed_id(prefixed_id)
+        decoded ? cart.user.addresses.find_by(id: decoded)&.id : nil
+      end
+
+      def revert_to_address_state
+        return if ['cart', 'address'].include?(cart.state)
+
+        cart.state = 'address'
+      end
+
+      # Auto-advance as far as the checkout state machine allows.
+      # Loops cart.next until the cart can't progress further (e.g. missing
+      # payment) or reaches confirm/complete. Stops at the first step whose
+      # before_transition guard fails — the `requirements` array in the
+      # serialized response tells the frontend what's still missing.
+      # Failure is swallowed — the update itself already succeeded.
+      def try_advance
+        return if cart.complete? || cart.canceled?
+
+        loop do
+          break unless cart.next
+          break if cart.confirm? || cart.complete?
+        end
+      rescue StandardError => e
+        Rails.error.report(e, context: { order_id: cart.id, state: cart.state }, source: 'spree.checkout')
+      ensure
+        begin
+          cart.reload
+        rescue StandardError # rubocop:disable Lint/SuppressedException
+          # reload failure must not mask the original result
+        end
+      end
+    end
+  end
+end

data/app/services/spree/{cart → carts}/upsert_items.rb

@@ -1,21 +1,17 @@
 module Spree
-  module Cart
-    # Bulk upsert line items on an order.
+  module Carts
+    # Bulk upsert line items on a cart.
     #
-    # For each entry in +line_items+:
-    # - If a line item for the variant already exists → sets its quantity
-    # - If no line item exists → creates one with the given quantity
+    # For each entry in +items+:
+    # - If a line item for the variant already exists -> sets its quantity
+    # - If no line item exists -> creates one with the given quantity
     #
-    # After all items are processed the order is recalculated once.
-    #
-    # Price calculation and tax adjustments are handled by LineItem model callbacks
-    # (copy_price, update_adjustments, update_tax_charge), so we only need to
-    # save each item and run a single order recalculation at the end.
+    # After all items are processed the cart is recalculated once.
     #
     # @example
-    #   Spree::Cart::UpsertItems.call(
-    #     order: order,
-    #     line_items: [
+    #   Spree::Carts::UpsertItems.new.call(
+    #     cart: cart,
+    #     items: [
     #       { variant_id: "variant_k5nR8xLq", quantity: 2 },
     #       { variant_id: "variant_m3Rp9wXz", quantity: 1 }
     #     ]
@@ -24,39 +20,39 @@ module Spree
     class UpsertItems
       prepend Spree::ServiceModule::Base
 
-      def call(order:, line_items:)
-        line_items = Array(line_items)
-        return success(order) if line_items.empty?
+      def call(cart:, items:)
+        items = Array(items)
+        return success(cart) if items.empty?
 
-        store = order.store || Spree::Current.store
+        store = cart.store || Spree::Current.store
 
         ApplicationRecord.transaction do
-          line_items.each do |item_params|
+          items.each do |item_params|
             item_params = item_params.to_h.deep_symbolize_keys
             variant = resolve_variant(store, item_params[:variant_id])
             next unless variant
 
             quantity = (item_params[:quantity] || 1).to_i
 
-            return failure(variant, "#{variant.name} is not available in #{order.currency}") if variant.amount_in(order.currency).nil?
+            return failure(variant, "#{variant.name} is not available in #{cart.currency}") if variant.amount_in(cart.currency).nil?
 
-            line_item = Spree.line_item_by_variant_finder.new.execute(order: order, variant: variant)
+            line_item = Spree.line_item_by_variant_finder.new.execute(order: cart, variant: variant)
 
             if line_item
               line_item.quantity = quantity
               line_item.metadata = line_item.metadata.merge(item_params[:metadata].to_h) if item_params[:metadata].present?
             else
-              line_item = order.line_items.new(quantity: quantity, variant: variant, options: { currency: order.currency })
+              line_item = cart.items.new(quantity: quantity, variant: variant, options: { currency: cart.currency })
               line_item.metadata = item_params[:metadata].to_h if item_params[:metadata].present?
             end
 
             return failure(line_item) unless line_item.save
           end
 
-          order.update_with_updater!
+          cart.update_with_updater!
         end
 
-        success(order)
+        success(cart)
       end
 
       private

data/app/services/spree/payments/handle_webhook.rb

@@ -0,0 +1,58 @@
+module Spree
+  module Payments
+    class HandleWebhook
+      prepend Spree::ServiceModule::Base
+
+      # @param payment_method [Spree::PaymentMethod] the payment method that received the webhook
+      # @param action [Symbol] normalized action (:captured, :authorized, :failed, :canceled)
+      # @param payment_session [Spree::PaymentSession] the payment session associated with the webhook
+      # @param metadata [Hash] gateway-specific metadata (e.g. charge data, psp reference)
+      def call(payment_method:, action:, payment_session:, metadata: {})
+        return success(nil) if payment_session.nil?
+
+        order = payment_session.order
+
+        case action
+        when :captured, :authorized
+          handle_success(payment_session, order, metadata)
+        when :failed
+          payment_session.fail if payment_session.can_fail?
+          success(payment_session)
+        when :canceled
+          payment_session.cancel if payment_session.can_cancel?
+          success(payment_session)
+        else
+          failure(payment_session, "Unknown webhook action: #{action}")
+        end
+      end
+
+      private
+
+      def handle_success(payment_session, order, metadata)
+        order.with_lock do
+          # Ensure payment record exists
+          payment = payment_session.find_or_create_payment!(metadata)
+
+          # Mark payment as completed — the webhook confirms the gateway processed it
+          if payment.present? && !payment.completed?
+            payment.started_processing! if payment.checkout?
+            payment.complete! if payment.can_complete?
+          end
+
+          # Mark session as completed
+          payment_session.complete if payment_session.can_complete?
+
+          # Complete order if not already done
+          unless order.reload.completed?
+            Spree::Dependencies.carts_complete_service.constantize.call(cart: order)
+          end
+        end
+
+        success(payment_session)
+      rescue StandardError => e
+        Rails.error.report(e, context: { payment_session_id: payment_session.id, order_id: order.id }, source: 'spree.payments.webhook')
+        failure(payment_session, e.message)
+      end
+    end
+  end
+end

data/config/locales/en.yml

@@ -837,6 +837,7 @@ en:
     card_type: Brand
     card_type_is: Card type is
     cart: Cart
+    cart_already_updated: The cart has already been updated.
     cart_line_item:
       discontinued: "%{li_name} was removed because it was discontinued"
       out_of_stock: "%{li_name} was removed because it was sold out"
@@ -864,6 +865,12 @@ en:
     charged: Charged
     checkout: Checkout
     checkout_message: Checkout message
+    checkout_requirements:
+      email_required: Email address is required
+      line_items_required: Add at least one item to your cart
+      payment_required: Add a payment method
+      ship_address_required: Shipping address is required
+      shipping_method_required: Select a shipping method for all shipments
     choose_a_customer: Choose a customer
     choose_a_taxon_to_sort_products_for: Choose a taxon to sort products for
     choose_currency: Choose Currency
@@ -1559,8 +1566,6 @@ en:
     order: Order
     order_adjustments: Order adjustments
     order_again: Order again
-    order_already_completed: Order already completed
-    order_already_updated: The order has already been updated.
     order_approved: Order approved
     order_canceled: Order canceled
     order_details: Order Details

data/lib/spree/core/dependencies.rb

@@ -16,7 +16,6 @@ module Spree
         cart_remove_item_service: 'Spree::Cart::RemoveItem',
         cart_remove_line_item_service: 'Spree::Cart::RemoveLineItem',
         cart_set_item_quantity_service: 'Spree::Cart::SetQuantity',
-        cart_upsert_items_service: 'Spree::Cart::UpsertItems',
         cart_estimate_shipping_rates_service: 'Spree::Cart::EstimateShippingRates',
         cart_empty_service: 'Spree::Cart::Empty',
         cart_destroy_service: 'Spree::Cart::Destroy',
@@ -24,6 +23,9 @@ module Spree
         cart_change_currency_service: 'Spree::Cart::ChangeCurrency',
         cart_remove_out_of_stock_items_service: 'Spree::Cart::RemoveOutOfStockItems',
 
+        # carts
+        carts_complete_service: 'Spree::Carts::Complete',
+
         # checkout
         checkout_next_service: 'Spree::Checkout::Next',
         checkout_advance_service: 'Spree::Checkout::Advance',
@@ -42,7 +44,6 @@ module Spree
         # order
         order_approve_service: 'Spree::Orders::Approve',
         order_cancel_service: 'Spree::Orders::Cancel',
-        order_update_service: 'Spree::Orders::Update',
         order_updater: 'Spree::OrderUpdater',
 
         # shipment
@@ -87,6 +88,7 @@ module Spree
         line_item_destroy_service: 'Spree::LineItems::Destroy',
 
         payment_create_service: 'Spree::Payments::Create',
+        payments_handle_webhook_service: 'Spree::Payments::HandleWebhook',
 
         # finders
         address_finder: 'Spree::Addresses::Find',

data/lib/spree/core/version.rb

@@ -1,5 +1,5 @@
 module Spree
-  VERSION = '5.4.0.beta6'.freeze
+  VERSION = '5.4.0.beta7'.freeze
 
   def self.version
     VERSION

data/lib/spree/core.rb

@@ -109,6 +109,7 @@ module Spree
       addresses: :default,
       gift_cards: :default,
       webhooks: :default,
+      payment_webhooks: :default,
       api_keys: :default
     )
   end

data/lib/spree/testing_support/factories/order_factory.rb

@@ -22,6 +22,9 @@ FactoryBot.define do
       end
     end
 
+    factory :cart, class: Spree::Order do
+    end
+
     factory :order_with_totals do
       after(:create) do |order, evaluator|
         create(:line_item, order: order, price: evaluator.line_items_price)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: spree_core
 version: !ruby/object:Gem::Version
-  version: 5.4.0.beta6
+  version: 5.4.0.beta7
 platform: ruby
 authors:
 - Sean Schofield
@@ -10,7 +10,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-11 00:00:00.000000000 Z
+date: 2026-03-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: i18n-tasks
@@ -840,6 +840,7 @@ files:
 - app/jobs/spree/images/save_from_url_job.rb
 - app/jobs/spree/imports/create_rows_job.rb
 - app/jobs/spree/imports/process_rows_job.rb
+- app/jobs/spree/payments/handle_webhook_job.rb
 - app/jobs/spree/products/auto_match_taxons_job.rb
 - app/jobs/spree/products/refresh_metrics_job.rb
 - app/jobs/spree/products/touch_taxons_job.rb
@@ -921,7 +922,13 @@ files:
 - app/models/spree/calculator/shipping/price_sack.rb
 - app/models/spree/calculator/tiered_flat_rate.rb
 - app/models/spree/calculator/tiered_percent.rb
+- app/models/spree/cart_promotion.rb
 - app/models/spree/category.rb
+- app/models/spree/checkout/default_requirements.rb
+- app/models/spree/checkout/registry.rb
+- app/models/spree/checkout/requirement.rb
+- app/models/spree/checkout/requirements.rb
+- app/models/spree/checkout/step.rb
 - app/models/spree/classification.rb
 - app/models/spree/country.rb
 - app/models/spree/coupon_code.rb
@@ -1201,7 +1208,10 @@ files:
 - app/services/spree/cart/remove_out_of_stock_items.rb
 - app/services/spree/cart/set_quantity.rb
 - app/services/spree/cart/update.rb
-- app/services/spree/cart/upsert_items.rb
+- app/services/spree/carts/complete.rb
+- app/services/spree/carts/create.rb
+- app/services/spree/carts/update.rb
+- app/services/spree/carts/upsert_items.rb
 - app/services/spree/checkout/add_store_credit.rb
 - app/services/spree/checkout/advance.rb
 - app/services/spree/checkout/complete.rb
@@ -1233,9 +1243,9 @@ files:
 - app/services/spree/orders/approve.rb
 - app/services/spree/orders/cancel.rb
 - app/services/spree/orders/create_user_account.rb
-- app/services/spree/orders/update.rb
 - app/services/spree/orders/update_contact_information.rb
 - app/services/spree/payments/create.rb
+- app/services/spree/payments/handle_webhook.rb
 - app/services/spree/products/auto_match_taxons.rb
 - app/services/spree/products/duplicator.rb
 - app/services/spree/products/prepare_nested_attributes.rb
@@ -1656,9 +1666,9 @@ licenses:
 - BSD-3-Clause
 metadata:
   bug_tracker_uri: https://github.com/spree/spree/issues
-  changelog_uri: https://github.com/spree/spree/releases/tag/v5.4.0.beta6
+  changelog_uri: https://github.com/spree/spree/releases/tag/v5.4.0.beta7
   documentation_uri: https://docs.spreecommerce.org/
-  source_code_uri: https://github.com/spree/spree/tree/v5.4.0.beta6
+  source_code_uri: https://github.com/spree/spree/tree/v5.4.0.beta7
 post_install_message:
 rdoc_options: []
 require_paths:

data/app/services/spree/orders/update.rb

@@ -1,121 +0,0 @@
-module Spree
-  module Orders
-    # Core order update service with modern conventions:
-    # - Flat parameter structure (no wrapping in "order" key)
-    # - snake_case field names without "_attributes" suffix
-    # - Automatic state management based on what's being updated
-    # - Support for line_items with prefixed variant IDs
-    #
-    # @example Update order with line items
-    #   Spree::Orders::Update.call(
-    #     order: order,
-    #     params: {
-    #       email: "customer@example.com",
-    #       line_items: [
-    #         { variant_id: "variant_123", quantity: 2 },
-    #         { variant_id: "variant_456", quantity: 1 }
-    #       ],
-    #       ship_address: {
-    #         firstname: "John",
-    #         lastname: "Doe",
-    #         address1: "123 Main St",
-    #         city: "New York",
-    #         zipcode: "10001",
-    #         country_iso: "US",
-    #         state_abbr: "NY"
-    #       }
-    #     }
-    #   )
-    #
-    class Update
-      prepend Spree::ServiceModule::Base
-
-      def call(order:, params:)
-        @order = order
-        @params = params.to_h.deep_symbolize_keys
-
-        ApplicationRecord.transaction do
-          assign_order_attributes
-          assign_address(:ship_address)
-          assign_address(:bill_address)
-
-          order.save!
-
-          process_line_items
-        end
-
-        success(order.reload)
-      rescue ActiveRecord::RecordNotFound
-        raise
-      rescue ActiveRecord::RecordInvalid => e
-        failure(order, e.record.errors.full_messages.to_sentence)
-      rescue StandardError => e
-        failure(order, e.message)
-      end
-
-      private
-
-      attr_reader :order, :params
-
-      def assign_order_attributes
-        order.email = params[:email] if params[:email].present?
-        order.special_instructions = params[:special_instructions] if params.key?(:special_instructions)
-        order.currency = params[:currency].upcase if params[:currency].present?
-        order.locale = params[:locale] if params[:locale].present?
-        order.metadata = order.metadata.merge(params[:metadata].to_h) if params[:metadata].present?
-      end
-
-      def assign_address(address_type)
-        address_id_param = params[:"#{address_type}_id"]
-        address_params = params[address_type]
-
-        # Priority 1: Direct address ID reference (ship_address_id / bill_address_id)
-        if address_id_param.present?
-          address_id = resolve_address_id(address_id_param)
-          order.public_send(:"#{address_type}_id=", address_id) if address_id
-          return
-        end
-
-        # Priority 2: Nested address params (ship_address / bill_address)
-        return unless address_params.is_a?(Hash)
-
-        if address_params[:id].present?
-          # Using existing address by ID within nested params
-          address_id = resolve_address_id(address_params[:id])
-          order.public_send(:"#{address_type}_id=", address_id) if address_id
-        else
-          # Creating/updating address with provided attributes
-          revert_to_address_state if order.has_checkout_step?('address')
-          order.public_send(:"#{address_type}_attributes=", address_params)
-        end
-      end
-
-      def process_line_items
-        return unless params[:line_items].is_a?(Array)
-
-        result = Spree.cart_upsert_items_service.call(
-          order: order,
-          line_items: params[:line_items]
-        )
-
-        raise StandardError, result.error.to_s if result.failure?
-      end
-
-      # Translate prefixed ID to internal id
-      def resolve_address_id(prefixed_id)
-        return unless order.user
-
-        decoded = Spree::Address.decode_prefixed_id(prefixed_id)
-        decoded ? order.user.addresses.find_by(id: decoded)&.id : nil
-      end
-
-      # Revert order state to 'address' when address changes
-      # This ensures shipments are recreated when transitioning back to delivery
-      def revert_to_address_state
-        return if ['cart', 'address'].include?(order.state)
-
-        order.state = 'address'
-      end
-    end
-  end
-end