spree_api 5.4.0.beta5 → 5.4.0.beta7

data/app/controllers/spree/api/v3/store/carts_controller.rb

@@ -0,0 +1,176 @@
+module Spree
+  module Api
+    module V3
+      module Store
+        class CartsController < Store::ResourceController
+          include Spree::Api::V3::CartResolvable
+          include Spree::Api::V3::OrderLock
+
+          skip_before_action :set_resource
+          prepend_before_action :require_authentication!, only: [:index, :associate]
+
+          # GET /api/v3/store/carts/:id
+          # Returns cart by prefixed ID
+          # Auto-advances the checkout state machine so that shipments and
+          # payment requirements are up-to-date (temporary until Spree 6 removes
+          # the state machine).
+          def show
+            @cart = find_cart
+
+            if @cart.ship_address_id.present? && @cart.shipments.empty?
+              ActiveRecord::Base.connected_to(role: :writing) do
+                with_order_lock { Spree::Checkout::Advance.call(order: @cart) }
+              end
+            end
+
+            render_cart
+          end
+
+          # POST /api/v3/store/carts
+          # Creates a new shopping cart (order)
+          # Can be created by guests or authenticated customers
+          def create
+            result = Spree::Carts::Create.call(
+              params: permitted_params.merge(
+                user: current_user,
+                store: current_store,
+                currency: current_currency,
+                locale: current_locale
+              )
+            )
+
+            if result.success?
+              @cart = result.value
+              render_cart(status: :created)
+            else
+              render_service_error(result.error.to_s)
+            end
+          end
+
+          # PATCH /api/v3/store/carts/:id
+          # Updates cart info (email, addresses, special instructions).
+          # Auto-advances to the next checkout step when possible.
+          def update
+            find_cart!
+
+            with_order_lock do
+              result = Spree::Carts::Update.call(
+                cart: @cart,
+                params: permitted_params
+              )
+
+              if result.success?
+                render_cart
+              else
+                render_service_error(result.error, code: ERROR_CODES[:validation_error])
+              end
+            end
+          end
+
+          # DELETE /api/v3/store/carts/:id
+          # Deletes/abandons the cart
+          def destroy
+            find_cart!
+
+            result = Spree.cart_destroy_service.call(order: @cart)
+
+            if result.success?
+              head :no_content
+            else
+              render_service_error(result.error.to_s)
+            end
+          end
+
+          # PATCH /api/v3/store/carts/:id/associate
+          # Associates a guest cart with the currently authenticated user
+          # Requires: JWT authentication + cart ID in URL
+          def associate
+            @cart = find_cart_for_association
+
+            result = Spree.cart_associate_service.call(guest_order: @cart, user: current_user, guest_only: true)
+
+            if result.success?
+              render_cart
+            else
+              render_service_error(result.error.to_s)
+            end
+          end
+
+          # POST /api/v3/store/carts/:id/complete
+          # Completes the checkout — returns Order (not Cart).
+          # Idempotent: if the cart is already completed, falls back to the
+          # orders scope and returns the completed order.
+          def complete
+            find_cart!
+
+            result = Spree::Dependencies.carts_complete_service.constantize.call(cart: @cart)
+
+            if result.success?
+              @cart = result.value
+              render_order
+            else
+              render_service_error(
+                result.error.to_s.presence || 'Could not complete checkout',
+                code: ERROR_CODES[:cart_cannot_complete]
+              )
+            end
+          rescue ActiveRecord::RecordNotFound
+            @cart = current_store.orders.complete.find_by_prefix_id!(params[:id])
+            authorize!(:show, @cart, cart_token)
+
+            render_order
+          end
+
+          protected
+
+          def model_class
+            Spree::Order
+          end
+
+          def serializer_class
+            Spree.api.cart_serializer
+          end
+
+          def scope
+            current_store.carts.where(user: current_user).order(updated_at: :desc)
+          end
+
+          private
+
+          def permitted_params
+            params.permit(
+              :email,
+              :special_instructions,
+              :currency,
+              :locale,
+              :ship_address_id,
+              :bill_address_id,
+              ship_address: address_params,
+              bill_address: address_params,
+              metadata: {},
+              items: item_params
+            )
+          end
+
+          def address_params
+            [
+              :id, :firstname, :lastname, :address1, :address2,
+              :city, :zipcode, :phone, :company,
+              :country_iso, :state_abbr, :state_name, :quick_checkout
+            ]
+          end
+
+          def item_params
+            [:variant_id, :quantity, { metadata: {}, options: {} }]
+          end
+
+          # Find incomplete cart for associate action.
+          # Only finds guest carts (no user) or carts already owned by current user (idempotent).
+          def find_cart_for_association
+            current_store.carts.where(user: [nil, current_user]).find_by_prefix_id!(params[:id])
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/store/customer/orders_controller.rb

@@ -25,7 +25,7 @@ module Spree
             end
 
             def scope
-              super.for_store(current_store)
+              super.for_store(current_store).complete
             end
           end
         end

data/app/controllers/spree/api/v3/store/orders_controller.rb

@@ -2,133 +2,40 @@ module Spree
   module Api
     module V3
       module Store
-        class OrdersController < ResourceController
-          include Spree::Api::V3::OrderConcern
-          include Spree::Api::V3::OrderLock
+        class OrdersController < Store::BaseController
+          # GET /api/v3/store/orders/:id
+          # Single order lookup — accessible via order token (guests) or JWT (authenticated users)
+          before_action :find_order!
 
-          # Skip base controller's set_resource and define our own complete list
-          skip_before_action :set_resource
-          before_action :set_resource, only: [:show, :update, :next, :advance, :complete]
-
-          # PATCH  /api/v3/store/orders/:id
-          #
-          # Accepts flat parameters:
-          #   {
-          #     "email": "customer@example.com",
-          #     "currency": "EUR",
-          #     "ship_address": { "firstname": "John", "country_iso": "US", ... },
-          #     "bill_address": { "firstname": "John", "country_iso": "US", ... }
-          #   }
-          #
-          def update
-            with_order_lock do
-              result = Spree.order_update_service.call(
-                order: @order,
-                params: order_params
-              )
-
-              if result.success?
-                render json: serialize_resource(@order.reload)
-              else
-                render_service_error(result.error, code: ERROR_CODES[:validation_error])
-              end
-            end
-          end
-
-          # PATCH  /api/v3/store/orders/:id/next
-          def next
-            with_order_lock do
-              result = Spree.checkout_next_service.call(order: @order)
-
-              if result.success?
-                render json: serialize_resource(@order)
-              else
-                render_service_error(result.error, code: ERROR_CODES[:order_cannot_transition])
-              end
-            end
-          end
-
-          # PATCH  /api/v3/store/orders/:id/advance
-          def advance
-            with_order_lock do
-              result = Spree.checkout_advance_service.call(order: @order)
-
-              if result.success?
-                render json: serialize_resource(@order)
-              else
-                render_service_error(result.error, code: ERROR_CODES[:order_cannot_transition])
-              end
-            end
+          def show
+            render json: serializer_class.new(@order, params: serializer_params).to_h
           end
 
-          # PATCH  /api/v3/store/orders/:id/complete
-          def complete
-            with_order_lock do
-              result = Spree.checkout_complete_service.call(order: @order)
+          private
 
-              if result.success?
-                render json: serialize_resource(@order)
-              else
-                render_service_error(result.error, code: ERROR_CODES[:order_already_completed])
-              end
-            end
+          def find_order!
+            @order = scope.find_by_prefix_id!(params[:id])
+            authorize!(:show, @order, order_token)
           end
 
-          protected
-
-          # Override scope to avoid accessible_by (Order permissions use blocks)
           def scope
-            order_scope
-          end
-
-          # Override set_resource to scope lookup by user or order token (IDOR prevention)
-          def set_resource
-            @order = order_scope.find_by_prefix_id!(params[:id])
-            @resource = @order
-            authorize_resource!(@order)
-          end
-
-          # override authorize_resource! to pass the order token
-          # Maps custom checkout actions to appropriate permissions
-          def authorize_resource!(resource = @resource, action = action_name.to_sym)
-            mapped_action = case action
-                            when :next, :advance, :complete
-                              :update # Checkout actions require update (non-completed order)
-                            else
-                              action
-                            end
-            authorize!(mapped_action, resource, order_token)
-          end
-
-          def model_class
-            Spree::Order
+            base = current_store.orders.complete
+
+            if current_user.present?
+              base.where(user: current_user)
+            elsif order_token.present?
+              base.where(token: order_token)
+            else
+              base.none
+            end
           end
 
           def serializer_class
             Spree.api.order_serializer
           end
 
-          def order_params
-            params.permit(
-              :email,
-              :currency,
-              :locale,
-              :special_instructions,
-              :ship_address_id,
-              :bill_address_id,
-              ship_address: address_params,
-              bill_address: address_params,
-              metadata: {},
-              line_items: [:variant_id, :quantity, { metadata: {}, options: {} }]
-            )
-          end
-
-          def address_params
-            [
-              :id, :firstname, :lastname, :address1, :address2,
-              :city, :zipcode, :phone, :company,
-              :country_iso, :state_abbr, :state_name, :quick_checkout
-            ]
+          def order_token
+            request.headers['x-spree-token']
           end
         end
       end

data/app/controllers/spree/api/v3/webhooks/payments_controller.rb

@@ -0,0 +1,52 @@
+module Spree
+  module Api
+    module V3
+      module Webhooks
+        class PaymentsController < ActionController::API
+          include ActionController::RateLimiting
+
+          RATE_LIMIT_RESPONSE = -> {
+            [429, { 'Content-Type' => 'application/json', 'Retry-After' => '60' },
+             [{ error: { code: 'rate_limit_exceeded', message: 'Too many requests' } }.to_json]]
+          }
+
+          rate_limit to: 120, within: 1.minute,
+                     store: Rails.cache,
+                     by: -> { request.remote_ip },
+                     with: RATE_LIMIT_RESPONSE
+
+          # POST /api/v3/webhooks/payments/:payment_method_id
+          #
+          # Verifies the webhook signature synchronously (returns 401 if invalid),
+          # then enqueues async processing and returns 200 immediately.
+          def create
+            payment_method = Spree::PaymentMethod.find_by_prefix_id!(params[:payment_method_id])
+
+            # Signature verification must be synchronous — invalid = 401
+            result = payment_method.parse_webhook_event(request.raw_post, request.headers)
+
+            # Unsupported event — acknowledge receipt
+            return head :ok if result.nil?
+
+            # Process asynchronously — gateways have timeout limits and will
+            # retry on timeouts, so we must return 200 quickly.
+            Spree::Payments::HandleWebhookJob.perform_later(
+              payment_method_id: payment_method.id,
+              action: result[:action].to_s,
+              payment_session_id: result[:payment_session].id
+            )
+
+            head :ok
+          rescue Spree::PaymentMethod::WebhookSignatureError
+            head :unauthorized
+          rescue ActiveRecord::RecordNotFound
+            head :not_found
+          rescue StandardError => e
+            Rails.error.report(e, source: 'spree.webhooks.payments')
+            head :ok
+          end
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/order_serializer.rb

@@ -43,8 +43,8 @@ module Spree
           end
 
           # Override inherited associations to use admin serializers
-          many :order_promotions, resource: Spree.api.admin_order_promotion_serializer, if: proc { expand?('order_promotions') }
-          many :line_items, resource: Spree.api.admin_line_item_serializer, if: proc { expand?('line_items') }
+          many :order_promotions, key: :promotions, resource: Spree.api.admin_order_promotion_serializer, if: proc { expand?('promotions') }
+          many :line_items, key: :items, resource: Spree.api.admin_line_item_serializer, if: proc { expand?('items') }
           many :shipments, resource: Spree.api.admin_shipment_serializer, if: proc { expand?('shipments') }
           many :payments, resource: Spree.api.admin_payment_serializer, if: proc { expand?('payments') }
 

data/app/serializers/spree/api/v3/cart_promotion_serializer.rb

@@ -0,0 +1,18 @@
+module Spree
+  module Api
+    module V3
+      # Cart-facing promotion serializer.
+      # Same data as OrderPromotionSerializer but IDs use the cp_ prefix.
+      class CartPromotionSerializer < BaseSerializer
+        typelize name: :string, description: [:string, nullable: true], code: [:string, nullable: true],
+                 amount: :string, display_amount: :string, promotion_id: :string
+
+        attribute :promotion_id do |cart_promotion|
+          cart_promotion.promotion&.prefixed_id
+        end
+
+        attributes :name, :description, :code, :amount, :display_amount
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/cart_serializer.rb

@@ -0,0 +1,56 @@
+module Spree
+  module Api
+    module V3
+      # Store API Cart Serializer
+      # Pre-purchase cart data with checkout progression info
+      class CartSerializer < BaseSerializer
+        typelize number: :string, current_step: :string, completed_steps: 'string[]', token: :string, email: [:string, nullable: true],
+                 special_instructions: [:string, nullable: true], currency: :string, locale: [:string, nullable: true], item_count: :number,
+                 requirements: 'Array<{step: string, field: string, message: string}>',
+                 item_total: :string, display_item_total: :string,
+                 ship_total: :string, display_ship_total: :string,
+                 adjustment_total: :string, display_adjustment_total: :string,
+                 promo_total: :string, display_promo_total: :string,
+                 tax_total: :string, display_tax_total: :string,
+                 included_tax_total: :string, display_included_tax_total: :string,
+                 additional_tax_total: :string, display_additional_tax_total: :string,
+                 total: :string, display_total: :string,
+                 bill_address: { nullable: true }, ship_address: { nullable: true }
+
+        # Override ID to use cart_ prefix
+        attribute :id do |order|
+          "cart_#{Spree::PrefixedId::SQIDS.encode([order.id])}"
+        end
+
+        attributes :number, :token, :email, :special_instructions,
+                   :currency, :locale, :item_count,
+                   :item_total, :display_item_total, :ship_total, :display_ship_total,
+                   :adjustment_total, :display_adjustment_total, :promo_total, :display_promo_total,
+                   :tax_total, :display_tax_total, :included_tax_total, :display_included_tax_total,
+                   :additional_tax_total, :display_additional_tax_total, :total, :display_total,
+                   created_at: :iso8601, updated_at: :iso8601
+
+        attribute :current_step do |order|
+          order.current_checkout_step
+        end
+
+        attribute :completed_steps do |order|
+          order.completed_checkout_steps
+        end
+
+        attribute :requirements do |order|
+          Spree::Checkout::Requirements.new(order).call
+        end
+
+        many :cart_promotions, key: :promotions, resource: Spree.api.cart_promotion_serializer
+        many :line_items, key: :items, resource: Spree.api.line_item_serializer
+        many :shipments, resource: Spree.api.shipment_serializer
+        many :payments, resource: Spree.api.payment_serializer
+        one :bill_address, resource: Spree.api.address_serializer
+        one :ship_address, resource: Spree.api.address_serializer
+
+        many :payment_methods, resource: Spree.api.payment_method_serializer
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/order_serializer.rb

@@ -2,11 +2,11 @@ module Spree
   module Api
     module V3
       # Store API Order Serializer
-      # Customer-facing order data
+      # Post-purchase order data (completed orders)
       class OrderSerializer < BaseSerializer
-        typelize number: :string, state: :string, checkout_steps: 'string[]', token: :string, email: [:string, nullable: true],
+        typelize number: :string, email: :string,
                  special_instructions: [:string, nullable: true], currency: :string, locale: [:string, nullable: true], item_count: :number,
-                 state_lock_version: :number, shipment_state: [:string, nullable: true], payment_state: [:string, nullable: true],
+                 shipment_state: [:string, nullable: true], payment_state: [:string, nullable: true],
                  item_total: :string, display_item_total: :string,
                  ship_total: :string, display_ship_total: :string,
                  adjustment_total: :string, display_adjustment_total: :string,
@@ -17,22 +17,20 @@ module Spree
                  total: :string, display_total: :string, completed_at: [:string, nullable: true],
                  bill_address: { nullable: true }, ship_address: { nullable: true }
 
-        attributes :number, :state, :checkout_steps, :token, :email, :special_instructions,
-                   :currency, :locale, :item_count, :state_lock_version, :shipment_state, :payment_state,
+        attributes :number, :email, :special_instructions,
+                   :currency, :locale, :item_count, :shipment_state, :payment_state,
                    :item_total, :display_item_total, :ship_total, :display_ship_total,
                    :adjustment_total, :display_adjustment_total, :promo_total, :display_promo_total,
                    :tax_total, :display_tax_total, :included_tax_total, :display_included_tax_total,
                    :additional_tax_total, :display_additional_tax_total, :total, :display_total,
                    completed_at: :iso8601, created_at: :iso8601, updated_at: :iso8601
 
-        many :order_promotions, resource: Spree.api.order_promotion_serializer
-        many :line_items, resource: Spree.api.line_item_serializer
+        many :order_promotions, key: :promotions, resource: Spree.api.order_promotion_serializer
+        many :line_items, key: :items, resource: Spree.api.line_item_serializer
         many :shipments, resource: Spree.api.shipment_serializer
         many :payments, resource: Spree.api.payment_serializer
         one :bill_address, resource: Spree.api.address_serializer
         one :ship_address, resource: Spree.api.address_serializer
-
-        many :payment_methods, resource: Spree.api.payment_method_serializer
       end
     end
   end

data/config/locales/en.yml

@@ -24,6 +24,10 @@ en:
       shipment_transfer_success: Variants successfully transferred
       stock_location_required: A stock_location_id parameter must be provided in order to retrieve stock movements.
       unauthorized: You are not authorized to perform that action.
+      v3:
+        payments:
+          session_required: This payment method requires a payment session. Use the payment sessions endpoint instead.
+          method_unavailable: This payment method is not available for this order.
       v2:
         cart:
           no_coupon_code: No coupon code provided and the Order doesn't have any coupon code promotions applied

data/config/routes.rb

@@ -7,9 +7,6 @@ Spree::Core::Engine.add_routes do
         post 'auth/refresh', to: 'auth#refresh'
         post 'auth/oauth/callback', to: 'auth#oauth_callback'
 
-        # Customer registration
-        resources :customers, only: [:create]
-
         # Markets
         resources :markets, only: [:index, :show] do
           collection do
@@ -33,46 +30,41 @@ Spree::Core::Engine.add_routes do
           resources :products, only: [:index], controller: 'categories/products'
         end
 
-        # Cart
-        resource :cart, only: [:show, :create], controller: 'cart' do
-          patch :associate
-        end
-
-        # Orders - individual order management and checkout
-        resources :orders, only: [:show, :update] do
+        # Carts
+        resources :carts, only: [:index, :show, :create, :update, :destroy] do
           member do
-            # State transitions
-            patch :next       # Move to next checkout step
-            patch :advance    # Advance through all steps
-            patch :complete   # Complete the order
+            patch :associate
+            post :complete
           end
-
-          # Nested resources - all require order access
-          resource :store_credits, only: [:create, :destroy], controller: 'orders/store_credits'
-          resources :line_items, only: [:create, :update, :destroy], controller: 'orders/line_items'
-          resources :coupon_codes, only: [:create, :destroy], controller: 'orders/coupon_codes'
-          resources :payments, only: [:index, :show], controller: 'orders/payments'
-          resources :payment_methods, only: [:index], controller: 'orders/payment_methods'
-          resources :payment_sessions, only: [:create, :show, :update], controller: 'orders/payment_sessions' do
+          resources :items, only: [:create, :update, :destroy], controller: 'carts/items'
+          resources :coupon_codes, only: [:create, :destroy], controller: 'carts/coupon_codes'
+          resources :shipments, only: [:index, :update], controller: 'carts/shipments'
+          resources :payment_methods, only: [:index], controller: 'carts/payment_methods'
+          resources :payments, only: [:index, :show, :create], controller: 'carts/payments'
+          resources :payment_sessions, only: [:create, :show, :update], controller: 'carts/payment_sessions' do
             member do
               patch :complete
             end
           end
-          resources :shipments, only: [:index, :show, :update], controller: 'orders/shipments'
+          resource :store_credits, only: [:create, :destroy], controller: 'carts/store_credits'
         end
 
+        # Orders (single order lookup, guest-accessible via order token)
+        resources :orders, only: [:show]
+
         # Customer (current user profile)
+        resources :customers, only: [:create]
         get 'customer', to: 'customers#show'
         patch 'customer', to: 'customers#update'
 
         # Customer nested resources
         namespace :customer, path: 'customer' do
+          resources :orders, only: [:index, :show]
           resources :addresses, only: [:index, :show, :create, :update, :destroy] do
             member do
               patch :mark_as_default
             end
           end
-          resources :orders, only: [:index]
           resources :credit_cards, only: [:index, :show, :destroy]
           resources :gift_cards, only: [:index, :show]
           resources :payment_setup_sessions, only: [:create, :show] do
@@ -92,6 +84,11 @@ Spree::Core::Engine.add_routes do
         get 'digitals/:token', to: 'digitals#show', as: :digital_download
 
       end
+
+      # Webhooks (outside of store namespace — no API key authentication)
+      namespace :webhooks do
+        post 'payments/:payment_method_id', to: 'payments#create', as: :payment_webhook
+      end
     end
   end
 end

data/lib/spree/api/dependencies.rb

@@ -4,6 +4,7 @@ module Spree
   module Api
     class ApiDependencies
       INJECTION_POINTS_WITH_DEFAULTS = {
+        # Legacy API v2 dependencies - will be removed in Spree 6
         # cart services
         storefront_cart_create_service: -> { Spree::Dependencies.cart_create_service },
         storefront_cart_add_item_service: -> { Spree::Dependencies.cart_add_item_service },
@@ -66,6 +67,8 @@ module Spree
         storefront_estimated_shipment_serializer: 'Spree::V2::Storefront::EstimatedShippingRateSerializer',
         storefront_store_serializer: 'Spree::V2::Storefront::StoreSerializer',
         storefront_policy_serializer: 'Spree::V2::Storefront::PolicySerializer',
+        storefront_post_category_serializer: 'Spree::V2::Storefront::PostCategorySerializer',
+        storefront_post_serializer: 'Spree::V2::Storefront::PostSerializer',
         storefront_order_serializer: 'Spree::V2::Storefront::OrderSerializer',
         storefront_variant_serializer: 'Spree::V2::Storefront::VariantSerializer',
         storefront_image_serializer: 'Spree::V2::Storefront::ImageSerializer',
@@ -96,6 +99,7 @@ module Spree
         image_serializer: 'Spree::Api::V3::ImageSerializer',
         option_type_serializer: 'Spree::Api::V3::OptionTypeSerializer',
         option_value_serializer: 'Spree::Api::V3::OptionValueSerializer',
+        cart_serializer: 'Spree::Api::V3::CartSerializer',
         order_serializer: 'Spree::Api::V3::OrderSerializer',
         line_item_serializer: 'Spree::Api::V3::LineItemSerializer',
         payment_serializer: 'Spree::Api::V3::PaymentSerializer',
@@ -116,6 +120,7 @@ module Spree
         shipping_rate_serializer: 'Spree::Api::V3::ShippingRateSerializer',
         stock_location_serializer: 'Spree::Api::V3::StockLocationSerializer',
         category_serializer: 'Spree::Api::V3::CategorySerializer',
+        cart_promotion_serializer: 'Spree::Api::V3::CartPromotionSerializer',
         order_promotion_serializer: 'Spree::Api::V3::OrderPromotionSerializer',
         digital_link_serializer: 'Spree::Api::V3::DigitalLinkSerializer',
         gift_card_serializer: 'Spree::Api::V3::GiftCardSerializer',