spree_api 5.4.0.beta3 → 5.4.0.beta4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00acdb80bb37236902858e0cf919b67cdbc8de40f54669d01db8b91ce87691d6
-  data.tar.gz: 81f453d6ab3a5e4083263d67e6c383a3aa4a3f64e67f2077fda8a4ad6eec4e2f
+  metadata.gz: e8154a8dd735a006cee415621ff4d95bfdfb4f30935e139bcc72b3d665868ae3
+  data.tar.gz: d013be2887432f12fd2dc3440aa14d7fd5d831ebdedc4f814c93c6925dc6b450
 SHA512:
-  metadata.gz: 56e2fbc855fd3dc4acc1655ec2cbfce11c89dbcc356404d4b19e872fa9c8e6d85f36525f7b9789de5f13c20b75b4b1c8415fdd56047005ad36cd418636850573
-  data.tar.gz: 4879e2c6c20455ed8054afcc40653f2774412caed5f19de054655b70e616d98cedb50dd8a7698980044314e51b9a9ddef6eb4013ffbc3f8352b048cb95e128ca
+  metadata.gz: ec930921c59d1e904c643ae363efa3cd40c634567ab7a1daf696e35014efae10e6197c0b3f657d0ff537a05ed36b165e34316eb11a25a83fe2d5352793d0afb2
+  data.tar.gz: 92175956237d07cbf778b29d7bb2bd562f0e39cbef764d9f608e01c69c849fdc648727750f52a2370d228a8e79df7080d1c84e2802f585ac1ca2303a36d8acb6

data/app/controllers/concerns/spree/api/v3/error_handler.rb

@@ -23,6 +23,7 @@ module Spree
           order_cannot_transition: 'order_cannot_transition',
           order_empty: 'order_empty',
           order_invalid_state: 'order_invalid_state',
+          order_already_updated: 'order_already_updated',
 
           # Line item errors
           line_item_not_found: 'line_item_not_found',
@@ -192,6 +193,7 @@ module Spree
           )
         end
 
+
         private
 
         # Format validation errors for details field

data/app/controllers/concerns/spree/api/v3/http_caching.rb

@@ -12,7 +12,7 @@ module Spree
         extend ActiveSupport::Concern
 
         included do
-          before_action :set_vary_headers
+          after_action :set_vary_headers
         end
 
         protected
@@ -69,15 +69,15 @@ module Spree
         private
 
         # Build a cache key for a collection
-        # Includes: query params, pagination, includes, currency, locale
-        # Strips order to avoid PostgreSQL errors with DISTINCT + subquery ORDER BY expressions
+        # Includes: latest updated_at, total count, query params, pagination, expand, currency, locale
         def collection_cache_key(collection)
           parts = [
-            collection.reorder(nil).cache_key_with_version,
-            params[:include],
-            params[:q],
+            collection.map(&:updated_at).max&.to_i,
+            @pagy&.count,
+            params[:expand],
+            params[:q]&.to_json,
             params[:page],
-            params[:per_page],
+            params[:limit],
             current_currency,
             current_locale
           ]

data/app/controllers/concerns/spree/api/v3/order_lock.rb

@@ -0,0 +1,42 @@
+module Spree
+  module Api
+    module V3
+      module OrderLock
+        extend ActiveSupport::Concern
+
+        included do
+          rescue_from ActiveRecord::Deadlocked, with: :handle_order_lock_conflict
+          rescue_from ActiveRecord::LockWaitTimeout, with: :handle_order_lock_conflict
+        end
+
+        private
+
+        def with_order_lock
+          order = @order || @parent
+
+          order.with_lock do
+            # Persist increment within the transaction so reloads inside yield see the new version
+            new_version = order.state_lock_version + 1
+            order.update_column(:state_lock_version, new_version)
+
+            yield
+
+            if performed? && response.status >= 400
+              # Operation failed — revert the increment
+              order.update_column(:state_lock_version, new_version - 1)
+            end
+          end
+        end
+
+        def handle_order_lock_conflict(exception)
+          Rails.error.report(exception, context: { order_id: (@order || @parent)&.id }, source: 'spree.api.v3')
+          render_error(
+            code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:order_already_updated],
+            message: Spree.t(:order_already_updated),
+            status: :conflict
+          )
+        end
+      end
+    end
+  end
+end

data/app/controllers/concerns/spree/api/v3/resource_serializer.rb

@@ -23,17 +23,17 @@ module Spree
             store: current_store,
             user: current_user,
             locale: current_locale,
-            includes: include_list
+            expand: expand_list
           }
         end
 
-        # Parse include parameter into list
-        # Supports: ?include=variants,images or ?includes=variants,images
-        def include_list
-          include_param = params[:include].presence || params[:includes].presence
-          return [] unless include_param
+        # Parse expand parameter into list
+        # Supports: ?expand=variants,images
+        def expand_list
+          expand_param = params[:expand].presence
+          return [] unless expand_param
 
-          include_param.to_s.split(',').map(&:strip)
+          expand_param.to_s.split(',').map(&:strip)
         end
       end
     end

data/app/controllers/spree/api/v3/resource_controller.rb

@@ -103,6 +103,7 @@ module Spree
         end
 
         # Override in subclass to disable distinct (e.g., for custom sorting with computed columns)
+        # @return [Boolean] whether to apply distinct to the collection
         def collection_distinct?
           true
         end
@@ -112,6 +113,8 @@ module Spree
           collection
         end
 
+        # Override in subclass to specify collection includes
+        # @return [Array<Symbol>] the includes to apply to the collection
         def collection_includes
           []
         end
@@ -122,16 +125,19 @@ module Spree
         end
 
         # Pagination parameters
+        # @return [Integer] the current page number
         def page
           params[:page]&.to_i || 1
         end
 
+        # @return [Integer] the number of items per page
         def limit
-          limit_param = params[:per_page]&.to_i || params[:limit]&.to_i || 25
+          limit_param = params[:limit]&.to_i || 25
           [limit_param, 100].min # Max 100 per page
         end
 
         # Metadata for collection responses
+        # @return [Hash] pagination metadata
         def collection_meta(_collection)
           return {} unless @pagy
 

data/app/controllers/spree/api/v3/store/markets/countries_controller.rb

@@ -0,0 +1,39 @@
+module Spree
+  module Api
+    module V3
+      module Store
+        module Markets
+          class CountriesController < Store::BaseController
+            before_action :load_market
+
+            # GET /api/v3/store/markets/:market_id/countries
+            def index
+              countries = @market.countries.order(:name)
+
+              render json: {
+                data: countries.map { |country| serialize_country(country) }
+              }
+            end
+
+            # GET /api/v3/store/markets/:market_id/countries/:id
+            def show
+              country = @market.countries.find_by!(iso: params[:id].upcase)
+
+              render json: serialize_country(country)
+            end
+
+            private
+
+            def load_market
+              @market = current_store.markets.find_by_prefix_id!(params[:market_id])
+            end
+
+            def serialize_country(country)
+              Spree.api.country_serializer.new(country, params: serializer_params).to_h
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+module Spree
+  module Api
+    module V3
+      module Store
+        class MarketsController < Store::BaseController
+          # GET /api/v3/store/markets
+          def index
+            markets = current_store.markets.includes(:countries).order(:position)
+
+            render json: {
+              data: markets.map { |market| serialize_market(market) }
+            }
+          end
+
+          # GET /api/v3/store/markets/:id
+          def show
+            market = current_store.markets.includes(:countries).find_by_prefix_id!(params[:id])
+
+            render json: serialize_market(market)
+          end
+
+          # GET /api/v3/store/markets/resolve?country=DE
+          def resolve
+            country_iso = params[:country]&.upcase
+            country = Spree::Country.find_by!(iso: country_iso)
+            market = current_store.market_for_country(country)
+
+            raise ActiveRecord::RecordNotFound unless market
+
+            render json: serialize_market(market)
+          end
+
+          private
+
+          def serialize_market(market)
+            Spree.api.market_serializer.new(market, params: serializer_params.merge(expand: expand_list + ['countries'])).to_h
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/store/orders/coupon_codes_controller.rb

@@ -5,6 +5,7 @@ module Spree
         module Orders
           class CouponCodesController < ResourceController
             include Spree::Api::V3::OrderConcern
+            include Spree::Api::V3::OrderLock
 
             before_action :authorize_order_access!
             skip_before_action :set_resource
@@ -12,14 +13,16 @@ module Spree
             # POST  /api/v3/store/orders/:order_id/coupon_codes
             # Apply a coupon code to the order
             def create
-              @parent.coupon_code = permitted_params[:code]
+              with_order_lock do
+                @parent.coupon_code = permitted_params[:code]
 
-              coupon_handler.apply
+                coupon_handler.apply
 
-              if coupon_handler.successful?
-                render_order(status: :created)
-              else
-                render_errors(coupon_handler.error)
+                if coupon_handler.successful?
+                  render_order(status: :created)
+                else
+                  render_errors(coupon_handler.error)
+                end
               end
             end
 
@@ -27,15 +30,17 @@ module Spree
             # Remove a coupon code from the order
             # :id is the promotion prefix_id (e.g., promo_xxx)
             def destroy
-              @resource = scope.find_by_prefix_id!(params[:id])
-              coupon_code = @resource.code.presence || @resource.name
+              with_order_lock do
+                @resource = scope.find_by_prefix_id!(params[:id])
+                coupon_code = @resource.code.presence || @resource.name
 
-              coupon_handler.remove(coupon_code)
+                coupon_handler.remove(coupon_code)
 
-              if coupon_handler.successful?
-                render_order
-              else
-                render_errors(coupon_handler.error)
+                if coupon_handler.successful?
+                  render_order
+                else
+                  render_errors(coupon_handler.error)
+                end
               end
             end
 

data/app/controllers/spree/api/v3/store/orders/line_items_controller.rb

@@ -5,63 +5,70 @@ module Spree
         module Orders
           class LineItemsController < ResourceController
             include Spree::Api::V3::OrderConcern
+            include Spree::Api::V3::OrderLock
 
             skip_before_action :set_resource
             before_action :authorize_order_access!
 
             # POST  /api/v3/store/orders/:order_id/line_items
             def create
-              result = Spree.cart_add_item_service.call(
-                order: @parent,
-                variant: variant,
-                quantity: permitted_params[:quantity] || 1,
-                metadata: permitted_params[:metadata] || {},
-                options: permitted_params[:options] || {}
-              )
-
-              if result.success?
-                render_order(status: :created)
-              else
-                render_service_error(result.error, code: ERROR_CODES[:insufficient_stock])
+              with_order_lock do
+                result = Spree.cart_add_item_service.call(
+                  order: @parent,
+                  variant: variant,
+                  quantity: permitted_params[:quantity] || 1,
+                  metadata: permitted_params[:metadata] || {},
+                  options: permitted_params[:options] || {}
+                )
+
+                if result.success?
+                  render_order(status: :created)
+                else
+                  render_service_error(result.error, code: ERROR_CODES[:insufficient_stock])
+                end
               end
             end
 
             # PATCH  /api/v3/store/orders/:order_id/line_items/:id
             def update
-              @line_item = scope.find_by_prefix_id!(params[:id])
-
-              @line_item.metadata = @line_item.metadata.merge(permitted_params[:metadata].to_h) if permitted_params[:metadata].present?
-
-              if permitted_params[:quantity].present?
-                result = Spree.cart_set_item_quantity_service.call(
-                  order: @parent,
-                  line_item: @line_item,
-                  quantity: permitted_params[:quantity]
-                )
-
-                if result.success?
+              with_order_lock do
+                @line_item = scope.find_by_prefix_id!(params[:id])
+
+                @line_item.metadata = @line_item.metadata.merge(permitted_params[:metadata].to_h) if permitted_params[:metadata].present?
+
+                if permitted_params[:quantity].present?
+                  result = Spree.cart_set_item_quantity_service.call(
+                    order: @parent,
+                    line_item: @line_item,
+                    quantity: permitted_params[:quantity]
+                  )
+
+                  if result.success?
+                    render_order
+                  else
+                    render_service_error(result.error, code: ERROR_CODES[:invalid_quantity])
+                  end
+                elsif @line_item.changed?
+                  @line_item.save!
                   render_order
                 else
-                  render_service_error(result.error, code: ERROR_CODES[:invalid_quantity])
+                  render_order
                 end
-              elsif @line_item.changed?
-                @line_item.save!
-                render_order
-              else
-                render_order
               end
             end
 
             # DELETE  /api/v3/store/orders/:order_id/line_items/:id
             def destroy
-              @line_item = scope.find_by_prefix_id!(params[:id])
+              with_order_lock do
+                @line_item = scope.find_by_prefix_id!(params[:id])
 
-              Spree.cart_remove_line_item_service.call(
-                order: @parent,
-                line_item: @line_item
-              )
+                Spree.cart_remove_line_item_service.call(
+                  order: @parent,
+                  line_item: @line_item
+                )
 
-              render_order
+                render_order
+              end
             end
 
             protected

data/app/controllers/spree/api/v3/store/orders/shipments_controller.rb

@@ -5,6 +5,7 @@ module Spree
         module Orders
           class ShipmentsController < ResourceController
             include Spree::Api::V3::OrderConcern
+            include Spree::Api::V3::OrderLock
 
             before_action :authorize_order_access!
             skip_before_action :set_resource
@@ -12,13 +13,15 @@ module Spree
 
             # PATCH /api/v3/store/orders/:order_id/shipments/:id
             def update
-              if permitted_params[:selected_shipping_rate_id].present?
-                shipping_rate = @resource.shipping_rates.find_by_prefix_id!(permitted_params[:selected_shipping_rate_id])
-                @resource.selected_shipping_rate_id = shipping_rate.id
-                @resource.save!
+              with_order_lock do
+                if permitted_params[:selected_shipping_rate_id].present?
+                  shipping_rate = @resource.shipping_rates.find_by_prefix_id!(permitted_params[:selected_shipping_rate_id])
+                  @resource.selected_shipping_rate_id = shipping_rate.id
+                  @resource.save!
+                end
+
+                render_order
               end
-
-              render_order
             end
 
             protected

data/app/controllers/spree/api/v3/store/orders/store_credits_controller.rb

@@ -5,6 +5,7 @@ module Spree
         module Orders
           class StoreCreditsController < Store::BaseController
             include Spree::Api::V3::OrderConcern
+            include Spree::Api::V3::OrderLock
 
             before_action :require_authentication!
             before_action :set_parent
@@ -12,26 +13,30 @@ module Spree
 
             # POST /api/v3/store/orders/:order_id/store_credits
             def create
-              result = Spree.checkout_add_store_credit_service.call(
-                order: @parent,
-                amount: params[:amount].try(:to_f)
-              )
+              with_order_lock do
+                result = Spree.checkout_add_store_credit_service.call(
+                  order: @parent,
+                  amount: params[:amount].try(:to_f)
+                )
 
-              if result.success?
-                render_order
-              else
-                render_service_error(result.error)
+                if result.success?
+                  render_order
+                else
+                  render_service_error(result.error)
+                end
               end
             end
 
             # DELETE /api/v3/store/orders/:order_id/store_credits
             def destroy
-              result = Spree.checkout_remove_store_credit_service.call(order: @parent)
+              with_order_lock do
+                result = Spree.checkout_remove_store_credit_service.call(order: @parent)
 
-              if result.success?
-                render_order
-              else
-                render_service_error(result.error)
+                if result.success?
+                  render_order
+                else
+                  render_service_error(result.error)
+                end
               end
             end
           end

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

@@ -4,6 +4,7 @@ module Spree
       module Store
         class OrdersController < ResourceController
           include Spree::Api::V3::OrderConcern
+          include Spree::Api::V3::OrderLock
 
           # Skip base controller's set_resource and define our own complete list
           skip_before_action :set_resource
@@ -20,48 +21,56 @@ module Spree
           #   }
           #
           def update
-            result = Spree::Api::V3::Orders::Update.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])
+            with_order_lock do
+              result = Spree::Api::V3::Orders::Update.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
-            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])
+            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
-            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])
+            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
           end
 
           # PATCH  /api/v3/store/orders/:id/complete
           def complete
-            result = Spree.checkout_complete_service.call(order: @order)
-
-            if result.success?
-              render json: serialize_resource(@order)
-            else
-              render_service_error(result.error, code: ERROR_CODES[:order_already_completed])
+            with_order_lock do
+              result = Spree.checkout_complete_service.call(order: @order)
+
+              if result.success?
+                render json: serialize_resource(@order)
+              else
+                render_service_error(result.error, code: ERROR_CODES[:order_already_completed])
+              end
             end
           end
 
@@ -117,7 +126,7 @@ module Spree
             [
               :id, :firstname, :lastname, :address1, :address2,
               :city, :zipcode, :phone, :company,
-              :country_iso, :state_abbr, :state_name
+              :country_iso, :state_abbr, :state_name, :quick_checkout
             ]
           end
         end

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

@@ -3,9 +3,11 @@ module Spree
     module V3
       module Store
         class ProductsController < ResourceController
-          SORT_OPTIONS = {
-            'price-low-to-high' => :ascend_by_price,
-            'price-high-to-low' => :descend_by_price
+          # Sort values that require special scopes (not plain Ransack column sorts).
+          CUSTOM_SORT_SCOPES = {
+            'price asc' => :ascend_by_price,
+            'price desc' => :descend_by_price,
+            'best_selling' => :by_best_selling
           }.freeze
 
           protected
@@ -48,24 +50,41 @@ module Spree
             !custom_sort_requested?
           end
 
-          # Apply custom sorting scopes for price/best-selling
+          # Applies sorting from the unified `sort` param.
+          # Custom values ('price asc', 'best_selling') use product-specific scopes.
+          # Standard Ransack values ('name asc', 'created_at desc') are passed to q[s].
           def apply_collection_sort(collection)
-            sort_by = params.dig(:q, :sort_by) || params[:sort_by]
-            return collection unless sort_by.present?
+            sort_value = sort_param
+            return collection unless sort_value.present?
 
-            return collection.distinct(false).reorder(nil).by_best_selling if sort_by == 'best-selling'
+            scope_method = CUSTOM_SORT_SCOPES[sort_value]
+            return collection unless scope_method
 
-            scope_method = SORT_OPTIONS[sort_by]
-            return collection.reorder(nil).send(scope_method) if scope_method.present?
+            sorted = collection.reorder(nil)
+            sort_value == 'best_selling' ? sorted.distinct(false).send(scope_method) : sorted.send(scope_method)
+          end
+
+          # Inject sort into ransack params when it's a standard Ransack sort
+          def ransack_params
+            rp = super
+            sort_value = sort_param
+
+            if sort_value.present? && !CUSTOM_SORT_SCOPES.key?(sort_value)
+              rp = rp.respond_to?(:to_unsafe_h) ? rp.to_unsafe_h : rp.dup
+              rp['s'] = sort_value
+            end
 
-            collection
+            rp
           end
 
           private
 
+          def sort_param
+            params[:sort] || params.dig(:q, :s)
+          end
+
           def custom_sort_requested?
-            sort_by = params.dig(:q, :sort_by) || params[:sort_by]
-            SORT_OPTIONS.key?(sort_by)
+            CUSTOM_SORT_SCOPES.key?(sort_param)
           end
         end
       end

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

@@ -6,11 +6,12 @@ module Spree
                  address1: [:string, nullable: true], address2: [:string, nullable: true],
                  city: [:string, nullable: true], zipcode: [:string, nullable: true], phone: [:string, nullable: true],
                  company: [:string, nullable: true], state_abbr: [:string, nullable: true], state_name: [:string, nullable: true],
-                 state_text: [:string, nullable: true], country_iso: :string, country_name: :string
+                 state_text: [:string, nullable: true], country_iso: :string, country_name: :string,
+                 quick_checkout: :boolean
 
         attributes :firstname, :lastname, :full_name, :address1, :address2,
                    :city, :zipcode, :phone, :company, :country_name, :country_iso, :state_text,
-                   :state_abbr
+                   :state_abbr, :quick_checkout
 
         # State name - used for countries without predefined states
         attribute :state_name do |address|

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

@@ -33,7 +33,7 @@ module Spree
 
           many :orders,
                resource: Spree.api.admin_order_serializer,
-               if: proc { params[:includes]&.include?('orders') }
+               if: proc { params[:expand]&.include?('orders') }
 
           # TODO: Add store_credits association when Admin API is implemented
         end

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

@@ -36,7 +36,7 @@ module Spree
 
           one :user,
               resource: Spree.api.admin_customer_serializer,
-              if: proc { params[:includes]&.include?('user') }
+              if: proc { params[:expand]&.include?('user') }
 
           # TODO: Add adjustments associations when Admin API is implemented
         end

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

@@ -26,20 +26,20 @@ module Spree
           # Admin uses admin variant serializer
           many :variants,
                resource: Spree.api.admin_variant_serializer,
-               if: proc { params[:includes]&.include?('variants') }
+               if: proc { params[:expand]&.include?('variants') }
 
           one :default_variant,
               resource: Spree.api.admin_variant_serializer,
-              if: proc { params[:includes]&.include?('default_variant') }
+              if: proc { params[:expand]&.include?('default_variant') }
 
           one :master,
               key: :master_variant,
               resource: Spree.api.admin_variant_serializer,
-              if: proc { params[:includes]&.include?('master_variant') }
+              if: proc { params[:expand]&.include?('master_variant') }
 
           many :metafields,
                resource: Spree.api.admin_metafield_serializer,
-               if: proc { params[:includes]&.include?('metafields') }
+               if: proc { params[:expand]&.include?('metafields') }
         end
       end
     end

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

@@ -12,7 +12,7 @@ module Spree
 
           many :metafields,
                resource: Spree.api.admin_metafield_serializer,
-               if: proc { params[:includes]&.include?('metafields') }
+               if: proc { params[:expand]&.include?('metafields') }
         end
       end
     end

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

@@ -7,7 +7,7 @@ module Spree
         class TaxonomySerializer < V3::TaxonomySerializer
           many :metafields,
                resource: Spree.api.admin_metafield_serializer,
-               if: proc { params[:includes]&.include?('metafields') }
+               if: proc { params[:expand]&.include?('metafields') }
         end
       end
     end

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

@@ -30,11 +30,11 @@ module Spree
           # All prices for this variant (for admin management)
           many :prices,
                resource: Spree.api.admin_price_serializer,
-               if: proc { params[:includes]&.include?('prices') }
+               if: proc { params[:expand]&.include?('prices') }
 
           many :metafields,
                resource: Spree.api.admin_metafield_serializer,
-               if: proc { params[:includes]&.include?('metafields') }
+               if: proc { params[:expand]&.include?('metafields') }
 
           # TODO: Add stock_items association when Admin API is implemented
         end

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

@@ -33,24 +33,24 @@ module Spree
           params[:locale]
         end
 
-        def includes
-          @includes ||= Array(params[:includes] || [])
+        def expands
+          @expands ||= Array(params[:expand] || [])
         end
 
-        # Check if an association should be included
-        def include?(name)
-          includes.include?(name.to_s)
+        # Check if an association should be expanded
+        def expand?(name)
+          expands.include?(name.to_s)
         end
 
-        # Get nested includes for a given parent
-        def nested_includes_for(parent)
+        # Get nested expands for a given parent
+        def nested_expands_for(parent)
           prefix = "#{parent}."
-          includes.select { |i| i.start_with?(prefix) }.map { |i| i.sub(prefix, '') }
+          expands.select { |i| i.start_with?(prefix) }.map { |i| i.sub(prefix, '') }
         end
 
         # Build nested params for child serializers
         def nested_params(parent = nil)
-          params.merge(includes: parent ? nested_includes_for(parent) : [])
+          params.merge(expand: parent ? nested_expands_for(parent) : [])
         end
 
         # Returns price for a variant using full Price List resolution

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

@@ -5,30 +5,19 @@ module Spree
         include Alba::Resource
         include Typelizer::DSL
 
-        # ISO 3166-1 codes - iso is the identifier, no redundant id field
         typelize iso: :string, iso3: :string, name: :string,
-                 states_required: :boolean, zipcode_required: :boolean,
-                 currency: [:string, nullable: true],
-                 default_locale: [:string, nullable: true],
-                 supported_locales: [:string, multi: true]
+                 states_required: :boolean, zipcode_required: :boolean
 
         attributes :iso, :iso3, :name, :states_required, :zipcode_required
 
-        attribute :currency do |country|
-          country.market_currency
-        end
-
-        attribute :default_locale do |country|
-          country.market_locale
-        end
-
-        attribute :supported_locales do |country|
-          country.market_supported_locales
-        end
-
         many :states,
              resource: Spree.api.state_serializer,
-             if: proc { params[:includes]&.include?('states') }
+             if: proc { params[:expand]&.include?('states') }
+
+        attribute :market, if: proc { params[:expand]&.include?('market') } do |country|
+          m = country.current_market
+          m ? Spree.api.market_serializer.new(m, params: params).to_h : nil
+        end
       end
     end
   end

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

@@ -0,0 +1,23 @@
+module Spree
+  module Api
+    module V3
+      class MarketSerializer < BaseSerializer
+        typelize name: :string, currency: :string,
+                 default_locale: :string,
+                 supported_locales: [:string, multi: true],
+                 tax_inclusive: :boolean,
+                 default: :boolean
+
+        attributes :name, :currency, :default_locale, :tax_inclusive, :default
+
+        attribute :supported_locales do |market|
+          market.supported_locales_list
+        end
+
+        many :countries,
+             resource: Spree.api.country_serializer,
+             if: proc { expand?(:countries) }
+      end
+    end
+  end
+end

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

@@ -6,7 +6,7 @@ module Spree
       class OrderSerializer < BaseSerializer
         typelize number: :string, state: :string, token: :string, email: [:string, nullable: true],
                  special_instructions: [:string, nullable: true], currency: :string, locale: [:string, nullable: true], item_count: :number,
-                 shipment_state: [:string, nullable: true], payment_state: [:string, nullable: true],
+                 state_lock_version: :number, 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,
@@ -18,7 +18,7 @@ module Spree
                  bill_address: { nullable: true }, ship_address: { nullable: true }
 
         attributes :number, :state, :token, :email, :special_instructions,
-                   :currency, :locale, :item_count, :shipment_state, :payment_state,
+                   :currency, :locale, :item_count, :state_lock_version, :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,

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

@@ -71,37 +71,37 @@ module Spree
         many :variant_images,
              key: :images,
              resource: Spree.api.image_serializer,
-             if: proc { params[:includes]&.include?('images') }
+             if: proc { params[:expand]&.include?('images') }
 
         many :variants,
              resource: Spree.api.variant_serializer,
-             if: proc { params[:includes]&.include?('variants') }
+             if: proc { params[:expand]&.include?('variants') }
 
         one :default_variant,
             resource: Spree.api.variant_serializer,
-            if: proc { params[:includes]&.include?('default_variant') }
+            if: proc { params[:expand]&.include?('default_variant') }
 
         one :master,
             key: :master_variant,
             resource: Spree.api.variant_serializer,
-            if: proc { params[:includes]&.include?('master_variant') }
+            if: proc { params[:expand]&.include?('master_variant') }
 
         many :option_types,
              resource: Spree.api.option_type_serializer,
-             if: proc { params[:includes]&.include?('option_types') }
+             if: proc { params[:expand]&.include?('option_types') }
 
         many :taxons,
              proc { |taxons, params|
                taxons.select { |t| t.taxonomy.store_id == params[:store].id }
              },
              resource: Spree.api.taxon_serializer,
-             if: proc { params[:includes]&.include?('taxons') },
-             params: { includes: [] }
+             if: proc { params[:expand]&.include?('taxons') },
+             params: { expand: [] }
 
         many :public_metafields,
              key: :metafields,
              resource: Spree.api.metafield_serializer,
-             if: proc { params[:includes]&.include?('metafields') }
+             if: proc { params[:expand]&.include?('metafields') }
       end
     end
   end

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

@@ -51,27 +51,27 @@ module Spree
         end
 
         # Conditional associations
-        # Note: We pass empty includes to nested taxons to prevent infinite recursion
+        # Note: We pass empty expand to nested taxons to prevent infinite recursion
         # (e.g., ancestors trying to load their own ancestors)
         one :parent,
             resource: Spree.api.taxon_serializer,
-            if: proc { params[:includes]&.include?('parent') },
-            params: { includes: [] }
+            if: proc { params[:expand]&.include?('parent') },
+            params: { expand: [] }
 
         many :children,
              resource: Spree.api.taxon_serializer,
-             if: proc { params[:includes]&.include?('children') },
-             params: { includes: [] }
+             if: proc { params[:expand]&.include?('children') },
+             params: { expand: [] }
 
         many :ancestors,
              resource: Spree.api.taxon_serializer,
-             if: proc { params[:includes]&.include?('ancestors') },
-             params: { includes: [] }
+             if: proc { params[:expand]&.include?('ancestors') },
+             params: { expand: [] }
 
         many :public_metafields,
              key: :metafields,
              resource: Spree.api.metafield_serializer,
-             if: proc { params[:includes]&.include?('metafields') }
+             if: proc { params[:expand]&.include?('metafields') }
       end
     end
   end

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

@@ -12,21 +12,21 @@ module Spree
         end
 
         # Conditional associations
-        # Note: We pass empty includes to nested taxons to prevent infinite recursion
+        # Note: We pass empty expand to nested taxons to prevent infinite recursion
         one :root,
             resource: Spree.api.taxon_serializer,
-            if: proc { params[:includes]&.include?('root') },
-            params: { includes: [] }
+            if: proc { params[:expand]&.include?('root') },
+            params: { expand: [] }
 
         many :taxons,
              resource: Spree.api.taxon_serializer,
-             if: proc { params[:includes]&.include?('taxons') },
-             params: { includes: [] }
+             if: proc { params[:expand]&.include?('taxons') },
+             params: { expand: [] }
 
         many :public_metafields,
              key: :metafields,
              resource: Spree.api.metafield_serializer,
-             if: proc { params[:includes]&.include?('metafields') }
+             if: proc { params[:expand]&.include?('metafields') }
       end
     end
   end

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

@@ -72,14 +72,14 @@ module Spree
         # Conditional associations
         many :images,
              resource: Spree.api.image_serializer,
-             if: proc { params[:includes]&.include?('images') }
+             if: proc { params[:expand]&.include?('images') }
 
         many :option_values, resource: Spree.api.option_value_serializer
 
         many :public_metafields,
              key: :metafields,
              resource: Spree.api.metafield_serializer,
-             if: proc { params[:includes]&.include?('metafields') }
+             if: proc { params[:expand]&.include?('metafields') }
       end
     end
   end

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

@@ -18,7 +18,7 @@ module Spree
         many :wished_items,
              key: :items,
              resource: Spree.api.wished_item_serializer,
-             if: proc { params[:includes]&.include?('items') }
+             if: proc { params[:expand]&.include?('items') }
       end
     end
   end

data/app/services/spree/api/v3/filters_aggregator.rb

@@ -2,16 +2,7 @@ module Spree
   module Api
     module V3
       class FiltersAggregator
-        SORT_OPTION_IDS = %w[
-          manual
-          best-selling
-          price-low-to-high
-          price-high-to-low
-          newest-first
-          oldest-first
-          name-a-z
-          name-z-a
-        ].freeze
+        SORT_OPTION_IDS = Spree::Taxon::SORT_ORDERS
 
         # @param scope [ActiveRecord::Relation] Base product scope (already filtered by store, availability, taxon, etc.)
         # @param currency [String] Currency for price range
@@ -43,11 +34,10 @@ module Spree
         end
 
         def sort_options
-          SORT_OPTION_IDS.map do |id|
-            { id: id, label: Spree.t("products_sort_options.#{id.underscore}") }
-          end
+          SORT_OPTION_IDS.map { |id| { id: id } }
         end
 
+
         def price_filter
           # Remove ordering to avoid PostgreSQL DISTINCT + ORDER BY conflicts
           prices = Spree::Price.for_products(@scope.reorder(''), @currency)
@@ -58,7 +48,6 @@ module Spree
           {
             id: 'price',
             type: 'price_range',
-            label: Spree.t(:price),
             min: min.to_f,
             max: max.to_f,
             currency: @currency
@@ -74,10 +63,9 @@ module Spree
           {
             id: 'availability',
             type: 'availability',
-            label: Spree.t(:availability),
             options: [
-              { id: 'in_stock', label: Spree.t(:in_stock), count: in_stock_count },
-              { id: 'out_of_stock', label: Spree.t(:out_of_stock), count: out_of_stock_count }
+              { id: 'in_stock', count: in_stock_count },
+              { id: 'out_of_stock', count: out_of_stock_count }
             ]
           }
         end
@@ -90,8 +78,8 @@ module Spree
             {
               id: option_type.prefixed_id,
               type: 'option',
-              label: option_type.presentation,
               name: option_type.name,
+              presentation: option_type.presentation,
               options: values.map { |ov| option_value_data(option_type, ov) }
             }
           end
@@ -110,8 +98,8 @@ module Spree
 
           {
             id: option_value.prefixed_id,
-            label: option_value.presentation,
             name: option_value.name,
+            presentation: option_value.presentation,
             position: option_value.position,
             count: count
           }
@@ -135,7 +123,6 @@ module Spree
           {
             id: 'taxons',
             type: 'taxon',
-            label: Spree.t(:category),
             options: child_taxons.map { |t| taxon_option_data(t) }
           }
         end
@@ -145,7 +132,7 @@ module Spree
 
           {
             id: taxon.prefixed_id,
-            label: taxon.name,
+            name: taxon.name,
             permalink: taxon.permalink,
             count: count
           }

data/config/routes.rb

@@ -11,6 +11,14 @@ Spree::Core::Engine.add_routes do
         # Store
         resource :store, only: [:show]
 
+        # Markets
+        resources :markets, only: [:index, :show] do
+          collection do
+            get :resolve
+          end
+          resources :countries, only: [:index, :show], controller: 'markets/countries'
+        end
+
         # Countries, Currencies, Locales (flat, market-aware)
         resources :countries, only: [:index, :show]
         resources :currencies, only: [:index]

data/lib/spree/api/dependencies.rb

@@ -107,6 +107,7 @@ module Spree
         address_serializer: 'Spree::Api::V3::AddressSerializer',
         customer_serializer: 'Spree::Api::V3::CustomerSerializer',
         country_serializer: 'Spree::Api::V3::CountrySerializer',
+        market_serializer: 'Spree::Api::V3::MarketSerializer',
         state_serializer: 'Spree::Api::V3::StateSerializer',
         store_serializer: 'Spree::Api::V3::StoreSerializer',
         wishlist_serializer: 'Spree::Api::V3::WishlistSerializer',

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: spree_api
 version: !ruby/object:Gem::Version
-  version: 5.4.0.beta3
+  version: 5.4.0.beta4
 platform: ruby
 authors:
 - Vendo Connect Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-02 00:00:00.000000000 Z
+date: 2026-03-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rswag-specs
@@ -86,14 +86,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 5.4.0.beta3
+        version: 5.4.0.beta4
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 5.4.0.beta3
+        version: 5.4.0.beta4
 description: Spree's API
 email:
 - hello@spreecommerce.org
@@ -109,6 +109,7 @@ files:
 - app/controllers/concerns/spree/api/v3/jwt_authentication.rb
 - app/controllers/concerns/spree/api/v3/locale_and_currency.rb
 - app/controllers/concerns/spree/api/v3/order_concern.rb
+- app/controllers/concerns/spree/api/v3/order_lock.rb
 - app/controllers/concerns/spree/api/v3/resource_serializer.rb
 - app/controllers/concerns/spree/api/v3/security_headers.rb
 - app/controllers/spree/api/v3/base_controller.rb
@@ -126,6 +127,8 @@ files:
 - app/controllers/spree/api/v3/store/customer/payment_setup_sessions_controller.rb
 - app/controllers/spree/api/v3/store/digitals_controller.rb
 - app/controllers/spree/api/v3/store/locales_controller.rb
+- app/controllers/spree/api/v3/store/markets/countries_controller.rb
+- app/controllers/spree/api/v3/store/markets_controller.rb
 - app/controllers/spree/api/v3/store/orders/coupon_codes_controller.rb
 - app/controllers/spree/api/v3/store/orders/line_items_controller.rb
 - app/controllers/spree/api/v3/store/orders/payment_methods_controller.rb
@@ -173,6 +176,7 @@ files:
 - app/serializers/spree/api/v3/invitation_serializer.rb
 - app/serializers/spree/api/v3/line_item_serializer.rb
 - app/serializers/spree/api/v3/locale_serializer.rb
+- app/serializers/spree/api/v3/market_serializer.rb
 - app/serializers/spree/api/v3/metafield_serializer.rb
 - app/serializers/spree/api/v3/newsletter_subscriber_serializer.rb
 - app/serializers/spree/api/v3/option_type_serializer.rb
@@ -235,9 +239,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.beta3
+  changelog_uri: https://github.com/spree/spree/releases/tag/v5.4.0.beta4
   documentation_uri: https://docs.spreecommerce.org/
-  source_code_uri: https://github.com/spree/spree/tree/v5.4.0.beta3
+  source_code_uri: https://github.com/spree/spree/tree/v5.4.0.beta4
 post_install_message:
 rdoc_options: []
 require_paths: