Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Re-organize API controllers, support slugs/permalinks for Products/Taxons

Damian Legawieccc4436a53791
diff --git a/api/app/controllers/concerns/spree/api/v3/order_concern.rb b/api/app/controllers/concerns/spree/api/v3/order_concern.rb
index 7d37becef4..869067013d 100644
--- a/api/app/controllers/concerns/spree/api/v3/order_concern.rb
+++ b/api/app/controllers/concerns/spree/api/v3/order_concern.rb
@@ -13,12 +13,12 @@ module Spree
protected
def order_token
- # Check X-Spree-Order-Token header first
- header = request.headers['X-Spree-Order-Token']
+ # Check x-spree-order-token header first (lowercase for consistency)
+ header = request.headers['x-spree-order-token']
return header if header.present?
- # Fallback to query param
- params[:token]
+ # Fallback to query params (support both token and order_token)
+ params[:order_token].presence || params[:token]
end
end
end
diff --git a/api/app/controllers/spree/api/v3/store/addresses_controller.rb b/api/app/controllers/spree/api/v3/store/addresses_controller.rb
index 0e7742cd43..9008e89237 100644
--- a/api/app/controllers/spree/api/v3/store/addresses_controller.rb
+++ b/api/app/controllers/spree/api/v3/store/addresses_controller.rb
@@ -5,6 +5,34 @@ module Spree
class AddressesController < Store::ResourceController
prepend_before_action :require_authentication!
+ # POST /api/v3/store/customers/me/addresses
+ def create
+ result = Spree.address_create_service.call(
+ address_params: permitted_params,
+ user: current_user
+ )
+
+ if result.success?
+ render json: serialize_resource(result.value), status: :created
+ else
+ render_errors(result.value.errors)
+ end
+ end
+
+ # PATCH /api/v3/store/customers/me/addresses/:id
+ def update
+ result = Spree.address_update_service.call(
+ address: @resource,
+ address_params: permitted_params
+ )
+
+ if result.success?
+ render json: serialize_resource(result.value)
+ else
+ render_errors(result.value.errors)
+ end
+ end
+
protected
def set_parent
@@ -24,7 +52,10 @@ module Spree
end
def permitted_params
- params.require(:address).permit(Spree::PermittedAttributes.address_attributes)
+ params.require(:address).permit(
+ :firstname, :lastname, :address1, :address2, :city,
+ :zipcode, :phone, :company, :country_iso, :state_code
+ )
end
end
end
diff --git a/api/app/controllers/spree/api/v3/store/line_items_controller.rb b/api/app/controllers/spree/api/v3/store/line_items_controller.rb
deleted file mode 100644
index 00168391c3..0000000000
--- a/api/app/controllers/spree/api/v3/store/line_items_controller.rb
+++ /dev/null
@@ -1,90 +0,0 @@
-module Spree
- module Api
- module V3
- module Store
- class LineItemsController < Store::ResourceController
- include Spree::Api::V3::OrderConcern
-
- 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,
- options: permitted_params[:options] || {}
- )
-
- if result.success?
- @line_item = result.value
- render json: serialize_resource(@line_item), status: :created
- else
- render_service_error(result.error, code: ERROR_CODES[:insufficient_stock])
- end
- end
-
- # PATCH /api/v3/store/orders/:order_id/line_items/:id
- def update
- @line_item = scope.find(params[:id])
-
- 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 json: serialize_resource(@line_item)
- else
- render_service_error(result.error, code: ERROR_CODES[:invalid_quantity])
- end
- else
- render json: serialize_resource(@line_item)
- end
- end
-
- # DELETE /api/v3/store/orders/:order_id/line_items/:id
- def destroy
- @line_item = scope.find(params[:id])
-
- Spree.cart_remove_line_item_service.call(
- order: @parent,
- line_item: @line_item
- )
-
- head :no_content
- end
-
- protected
-
- def set_parent
- @parent = current_store.orders.friendly.find(params[:order_id])
- end
-
- def parent_association
- :line_items
- end
-
- def variant
- current_store.variants.accessible_by(current_ability).find(permitted_params[:variant_id])
- end
-
- def model_class
- Spree::LineItem
- end
-
- def serializer_class
- Spree.api.line_item_serializer
- end
-
- def permitted_params
- params.require(:line_item).permit(Spree::PermittedAttributes.line_item_attributes + [{ options: {} }])
- end
- end
- end
- end
- end
-end
diff --git a/api/app/controllers/spree/api/v3/store/order_promotions_controller.rb b/api/app/controllers/spree/api/v3/store/order_promotions_controller.rb
deleted file mode 100644
index 6d3ab5b3a4..0000000000
--- a/api/app/controllers/spree/api/v3/store/order_promotions_controller.rb
+++ /dev/null
@@ -1,65 +0,0 @@
-module Spree
- module Api
- module V3
- module Store
- class OrderPromotionsController < Store::ResourceController
- include Spree::Api::V3::OrderConcern
-
- before_action :authorize_order_access!
-
- # POST /api/v3/store/orders/:order_id/order_promotions
- def create
- @parent.coupon_code = permitted_params[:coupon_code]
-
- promotion_handler.apply
-
- if promotion_handler.successful?
- head :no_content, status: :created
- else
- render_errors(promotion_handler.error)
- end
- end
-
- # DELETE /api/v3/store/orders/:order_id/order_promotions/:id
- def destroy
- coupon_code = @resource.code.presence || @resource.name
-
- promotion_handler.remove(coupon_code)
-
- if promotion_handler.successful?
- head :no_content
- else
- render_errors(promotion_handler.error)
- end
- end
-
- protected
-
- def set_parent
- @parent = current_store.orders.friendly.find(params[:order_id])
- end
-
- def parent_association
- :order_promotions
- end
-
- def promotion_handler
- @promotion_handler ||= Spree::PromotionHandler::Coupon.new(@parent)
- end
-
- def permitted_params
- params.require(:order_promotion).permit(:coupon_code)
- end
-
- def model_class
- Spree::OrderPromotion
- end
-
- def serializer_class
- Spree.api.order_promotion_serializer
- end
- end
- end
- end
- end
-end
diff --git a/api/app/controllers/spree/api/v3/store/orders/line_items_controller.rb b/api/app/controllers/spree/api/v3/store/orders/line_items_controller.rb
new file mode 100644
index 0000000000..937bfadbc4
--- /dev/null
+++ b/api/app/controllers/spree/api/v3/store/orders/line_items_controller.rb
@@ -0,0 +1,100 @@
+module Spree
+ module Api
+ module V3
+ module Store
+ module Orders
+ class LineItemsController < Store::ResourceController
+ include Spree::Api::V3::OrderConcern
+
+ 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,
+ options: permitted_params[:options] || {}
+ )
+
+ if result.success?
+ @line_item = result.value
+ render json: serialize_resource(@line_item), status: :created
+ else
+ render_service_error(result.error, code: ERROR_CODES[:insufficient_stock])
+ end
+ end
+
+ # PATCH /api/v3/store/orders/:order_id/line_items/:id
+ def update
+ @line_item = scope.find_by!(prefix_id: params[:id])
+
+ 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 json: serialize_resource(@line_item)
+ else
+ render_service_error(result.error, code: ERROR_CODES[:invalid_quantity])
+ end
+ else
+ render json: serialize_resource(@line_item)
+ end
+ end
+
+ # DELETE /api/v3/store/orders/:order_id/line_items/:id
+ def destroy
+ @line_item = scope.find_by!(prefix_id: params[:id])
+
+ Spree.cart_remove_line_item_service.call(
+ order: @parent,
+ line_item: @line_item
+ )
+
+ head :no_content
+ end
+
+ protected
+
+ def set_parent
+ @parent = current_store.orders.friendly.find(params[:order_id])
+ end
+
+ def parent_association
+ :line_items
+ end
+
+ def variant
+ variants = current_store.variants.accessible_by(current_ability)
+ variant_id = permitted_params[:variant_id]
+
+ # Support both prefix_id (variant_xxx) and database ID
+ if variant_id.to_s.start_with?('variant_')
+ variants.find_by!(prefix_id: variant_id)
+ else
+ variants.find(variant_id)
+ end
+ end
+
+ def model_class
+ Spree::LineItem
+ end
+
+ def serializer_class
+ Spree.api.line_item_serializer
+ end
+
+ def permitted_params
+ params.require(:line_item).permit(Spree::PermittedAttributes.line_item_attributes + [{ options: {} }])
+ end
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/controllers/spree/api/v3/store/orders/payment_methods_controller.rb b/api/app/controllers/spree/api/v3/store/orders/payment_methods_controller.rb
new file mode 100644
index 0000000000..8254b69890
--- /dev/null
+++ b/api/app/controllers/spree/api/v3/store/orders/payment_methods_controller.rb
@@ -0,0 +1,51 @@
+module Spree
+ module Api
+ module V3
+ module Store
+ module Orders
+ class PaymentMethodsController < Store::BaseController
+ include Spree::Api::V3::OrderConcern
+
+ before_action :set_order, only: [:index]
+
+ # GET /api/v3/store/orders/:order_id/payment_methods
+ # Returns available payment methods for the current order
+ def index
+ payment_methods = @order.collect_frontend_payment_methods
+ render json: {
+ data: serialize_collection(payment_methods),
+ meta: { count: payment_methods.size }
+ }
+ end
+
+ protected
+
+ def set_order
+ @order = current_store.orders.friendly.find(params[:order_id])
+ # Order access is verified through order ownership or token
+ unless can?(:show, @order) || order_token == @order.token
+ raise CanCan::AccessDenied, 'You are not authorized to access this page.'
+ end
+ end
+
+ def serializer_class
+ Spree.api.payment_method_serializer
+ end
+
+ def serialize_collection(collection)
+ collection.map { |item| serializer_class.new(item, params: serializer_params).to_h }
+ end
+
+ def serializer_params
+ {
+ currency: current_currency,
+ store: current_store,
+ user: current_user
+ }
+ end
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/controllers/spree/api/v3/store/orders/payments_controller.rb b/api/app/controllers/spree/api/v3/store/orders/payments_controller.rb
new file mode 100644
index 0000000000..a20e5760af
--- /dev/null
+++ b/api/app/controllers/spree/api/v3/store/orders/payments_controller.rb
@@ -0,0 +1,77 @@
+module Spree
+ module Api
+ module V3
+ module Store
+ module Orders
+ class PaymentsController < Store::BaseController
+ include Spree::Api::V3::OrderConcern
+ include Spree::Api::V3::ResourceSerializer
+
+ before_action :set_order
+ before_action :set_payment, only: [:show]
+
+ # GET /api/v3/store/orders/:order_id/payments
+ def index
+ payments = @order.payments.includes(:payment_method)
+ render json: {
+ data: serialize_payments(payments),
+ meta: {}
+ }
+ end
+
+ # GET /api/v3/store/orders/:order_id/payments/:id
+ def show
+ render json: serialize_resource(@payment)
+ end
+
+ # POST /api/v3/store/orders/:order_id/payments
+ def create
+ result = create_payment_service.call(order: @order, params: payment_params)
+
+ if result.success?
+ render json: serialize_order(@order.reload), status: :created
+ else
+ render_service_error(result.error)
+ end
+ end
+
+ protected
+
+ def set_order
+ @order = current_store.orders.friendly.find(params[:order_id])
+ authorize!(:update, @order, order_token)
+ end
+
+ def set_payment
+ @payment = @order.payments.find_by!(prefix_id: params[:id])
+ end
+
+ def payment_params
+ params.permit(
+ :payment_method_id,
+ :amount,
+ source_attributes: Spree::PermittedAttributes.source_attributes
+ )
+ end
+
+ def create_payment_service
+ Spree::Api::Dependencies.storefront_payment_create_service.constantize
+ end
+
+ def serializer_class
+ Spree.api.payment_serializer
+ end
+
+ def serialize_payments(payments)
+ payments.map { |p| serializer_class.new(p, params: serializer_params).to_h }
+ end
+
+ def serialize_order(order)
+ Spree.api.order_serializer.new(order, params: serializer_params).to_h
+ end
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/controllers/spree/api/v3/store/orders/promotions_controller.rb b/api/app/controllers/spree/api/v3/store/orders/promotions_controller.rb
new file mode 100644
index 0000000000..b1b14caa5c
--- /dev/null
+++ b/api/app/controllers/spree/api/v3/store/orders/promotions_controller.rb
@@ -0,0 +1,67 @@
+module Spree
+ module Api
+ module V3
+ module Store
+ module Orders
+ class PromotionsController < Store::ResourceController
+ include Spree::Api::V3::OrderConcern
+
+ before_action :authorize_order_access!
+
+ # POST /api/v3/store/orders/:order_id/promotions
+ def create
+ @parent.coupon_code = permitted_params[:coupon_code]
+
+ promotion_handler.apply
+
+ if promotion_handler.successful?
+ head :no_content, status: :created
+ else
+ render_errors(promotion_handler.error)
+ end
+ end
+
+ # DELETE /api/v3/store/orders/:order_id/promotions/:id
+ def destroy
+ coupon_code = @resource.code.presence || @resource.name
+
+ promotion_handler.remove(coupon_code)
+
+ if promotion_handler.successful?
+ head :no_content
+ else
+ render_errors(promotion_handler.error)
+ end
+ end
+
+ protected
+
+ def set_parent
+ @parent = current_store.orders.friendly.find(params[:order_id])
+ end
+
+ def parent_association
+ :order_promotions
+ end
+
+ def promotion_handler
+ @promotion_handler ||= Spree::PromotionHandler::Coupon.new(@parent)
+ end
+
+ def permitted_params
+ params.require(:promotion).permit(:coupon_code)
+ end
+
+ def model_class
+ Spree::OrderPromotion
+ end
+
+ def serializer_class
+ Spree.api.order_promotion_serializer
+ end
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/controllers/spree/api/v3/store/orders/shipments_controller.rb b/api/app/controllers/spree/api/v3/store/orders/shipments_controller.rb
new file mode 100644
index 0000000000..f2f4fe4a13
--- /dev/null
+++ b/api/app/controllers/spree/api/v3/store/orders/shipments_controller.rb
@@ -0,0 +1,57 @@
+module Spree
+ module Api
+ module V3
+ module Store
+ module Orders
+ class ShipmentsController < Store::ResourceController
+ include Spree::Api::V3::OrderConcern
+
+ before_action :authorize_order_access!
+ skip_before_action :set_resource
+ before_action :set_shipment, only: [:show, :update]
+
+ # 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!
+ end
+
+ render json: serialize_resource(@resource)
+ end
+
+ protected
+
+ def set_parent
+ @parent = current_store.orders.friendly.find(params[:order_id])
+ end
+
+ def parent_association
+ :shipments
+ end
+
+ def model_class
+ Spree::Shipment
+ end
+
+ def serializer_class
+ Spree.api.shipment_serializer
+ end
+
+ def permitted_params
+ params.require(:shipment).permit(:selected_shipping_rate_id)
+ end
+
+ private
+
+ # Find shipment without additional authorization - order access already verified
+ def set_shipment
+ @resource = scope.find_by_prefix_id!(params[:id])
+ end
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/controllers/spree/api/v3/store/orders/store_credits_controller.rb b/api/app/controllers/spree/api/v3/store/orders/store_credits_controller.rb
new file mode 100644
index 0000000000..e34adde07d
--- /dev/null
+++ b/api/app/controllers/spree/api/v3/store/orders/store_credits_controller.rb
@@ -0,0 +1,61 @@
+module Spree
+ module Api
+ module V3
+ module Store
+ module Orders
+ class StoreCreditsController < Store::BaseController
+ include Spree::Api::V3::OrderConcern
+ include Spree::Api::V3::ResourceSerializer
+
+ before_action :require_authentication!
+ before_action :set_order
+
+ # POST /api/v3/store/orders/:order_id/store_credits
+ def create
+ result = add_store_credit_service.call(
+ order: @order,
+ amount: params[:amount].try(:to_f)
+ )
+
+ if result.success?
+ render json: serialize_resource(@order.reload)
+ else
+ render_service_error(result.error)
+ end
+ end
+
+ # DELETE /api/v3/store/orders/:order_id/store_credits
+ def destroy
+ result = remove_store_credit_service.call(order: @order)
+
+ if result.success?
+ render json: serialize_resource(@order.reload)
+ else
+ render_service_error(result.error)
+ end
+ end
+
+ protected
+
+ def set_order
+ @order = current_store.orders.friendly.find(params[:order_id])
+ authorize!(:update, @order, order_token)
+ end
+
+ def serializer_class
+ Spree.api.order_serializer
+ end
+
+ def add_store_credit_service
+ Spree::Api::Dependencies.storefront_checkout_add_store_credit_service.constantize
+ end
+
+ def remove_store_credit_service
+ Spree::Api::Dependencies.storefront_checkout_remove_store_credit_service.constantize
+ end
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/controllers/spree/api/v3/store/orders_controller.rb b/api/app/controllers/spree/api/v3/store/orders_controller.rb
index ad55e79156..5e7088ed7e 100644
--- a/api/app/controllers/spree/api/v3/store/orders_controller.rb
+++ b/api/app/controllers/spree/api/v3/store/orders_controller.rb
@@ -5,8 +5,9 @@ module Spree
class OrdersController < Store::ResourceController
include Spree::Api::V3::OrderConcern
- # Override authorization for orders
- skip_before_action :set_resource, only: [:index, :create]
+ # Skip base controller's set_resource and define our own complete list
+ skip_before_action :set_resource
+ before_action :set_resource, only: [:show, :update, :destroy, :next, :advance, :complete]
prepend_before_action :require_authentication!, only: [:index]
# POST /api/v3/store/orders (public - guest checkout)
@@ -64,12 +65,6 @@ module Spree
end
end
- # PATCH /api/v3/store/orders/:id/cancel
- def cancel
- @order.cancel!
- render json: serialize_resource(@order)
- end
-
protected
# Override scope to avoid accessible_by (Order permissions use blocks)
@@ -85,8 +80,15 @@ module Spree
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)
- authorize!(action, resource, order_token)
+ 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
diff --git a/api/app/controllers/spree/api/v3/store/products_controller.rb b/api/app/controllers/spree/api/v3/store/products_controller.rb
index 64295ba4cf..61c4c6346a 100644
--- a/api/app/controllers/spree/api/v3/store/products_controller.rb
+++ b/api/app/controllers/spree/api/v3/store/products_controller.rb
@@ -13,6 +13,16 @@ module Spree
Spree.api.product_serializer
end
+ # Find product by slug or prefix_id with i18n scope for SEO-friendly URLs
+ def find_resource
+ id = params[:id]
+ if id.to_s.start_with?('prod_')
+ scope.find_by!(prefix_id: id)
+ else
+ scope.i18n.find_by!(slug: id)
+ end
+ end
+
def scope
super.available
end
diff --git a/api/app/controllers/spree/api/v3/store/shipments_controller.rb b/api/app/controllers/spree/api/v3/store/shipments_controller.rb
deleted file mode 100644
index 182b18c79c..0000000000
--- a/api/app/controllers/spree/api/v3/store/shipments_controller.rb
+++ /dev/null
@@ -1,35 +0,0 @@
-module Spree
- module Api
- module V3
- module Store
- class ShipmentsController < Store::ResourceController
- include Spree::Api::V3::OrderConcern
-
- before_action :authorize_order_access!
-
- protected
-
- def set_parent
- @parent = current_store.orders.friendly.find(params[:order_id])
- end
-
- def parent_association
- :shipments
- end
-
- def model_class
- Spree::Shipment
- end
-
- def serializer_class
- Spree.api.shipment_serializer
- end
-
- def permitted_params
- params.require(:shipment).permit(:selected_shipping_rate_id)
- end
- end
- end
- end
- end
-end
diff --git a/api/app/controllers/spree/api/v3/store/taxons_controller.rb b/api/app/controllers/spree/api/v3/store/taxons_controller.rb
index fa9d36f098..ebfc41c717 100644
--- a/api/app/controllers/spree/api/v3/store/taxons_controller.rb
+++ b/api/app/controllers/spree/api/v3/store/taxons_controller.rb
@@ -12,6 +12,16 @@ module Spree
def serializer_class
Spree.api.taxon_serializer
end
+
+ # Find taxon by permalink or prefix_id with i18n scope for SEO-friendly URLs
+ def find_resource
+ id = params[:id]
+ if id.to_s.start_with?('txn_')
+ scope.find_by!(prefix_id: id)
+ else
+ scope.i18n.find_by!(permalink: id)
+ end
+ end
end
end
end
diff --git a/api/app/controllers/spree/api/v3/store/wishlist_items_controller.rb b/api/app/controllers/spree/api/v3/store/wishlist_items_controller.rb
index c88a69e3e6..844a00e6c6 100644
--- a/api/app/controllers/spree/api/v3/store/wishlist_items_controller.rb
+++ b/api/app/controllers/spree/api/v3/store/wishlist_items_controller.rb
@@ -8,7 +8,7 @@ module Spree
protected
def set_parent
- @parent = current_user.wishlists.find(params[:wishlist_id])
+ @parent = current_user.wishlists.find_by!(prefix_id: params[:wishlist_id])
end
def parent_association
diff --git a/api/app/serializers/spree/api/v3/address_serializer.rb b/api/app/serializers/spree/api/v3/address_serializer.rb
index 52e6905667..4925de44e3 100644
--- a/api/app/serializers/spree/api/v3/address_serializer.rb
+++ b/api/app/serializers/spree/api/v3/address_serializer.rb
@@ -5,13 +5,23 @@ module Spree
typelize firstname: 'string | null', lastname: 'string | null', full_name: :string,
address1: 'string | null', address2: 'string | null',
city: 'string | null', zipcode: 'string | null', phone: 'string | null',
- company: 'string | null', state_id: 'string | null',
- state_text: 'string | null', country_id: :string,
- country_iso: :string, country_name: :string
+ company: 'string | null', state_code: 'string | null',
+ state_text: 'string | null', country_iso: :string, country_name: :string
attributes :firstname, :lastname, :full_name, :address1, :address2,
- :city, :zipcode, :phone, :company, :state_id,
- :state_text, :country_id, :country_iso, :country_name
+ :city, :zipcode, :phone, :company, :state_text, :country_name
+
+ # Country code (ISO 3166-1 alpha-2)
+ attribute :country_iso do |address|
+ address.country_iso
+ end
+
+ # State code in ISO 3166-2 format (e.g., "US-CA", "DE-BY")
+ attribute :state_code do |address|
+ next nil unless address.state
+
+ "#{address.country&.iso}-#{address.state.abbr}"
+ end
end
end
end
diff --git a/api/app/serializers/spree/api/v3/admin/order_serializer.rb b/api/app/serializers/spree/api/v3/admin/order_serializer.rb
index a8e36ce103..713343f13a 100644
--- a/api/app/serializers/spree/api/v3/admin/order_serializer.rb
+++ b/api/app/serializers/spree/api/v3/admin/order_serializer.rb
@@ -11,8 +11,6 @@ module Spree
store_owner_notification_delivered: :boolean,
internal_note: 'string | null', approver_id: 'string | null',
canceler_id: 'string | null', created_by_id: 'string | null',
- public_metadata: 'Record<string, unknown> | null',
- private_metadata: 'Record<string, unknown> | null',
canceled_at: 'string | null', approved_at: 'string | null'
# Admin-only attributes
@@ -29,14 +27,6 @@ module Spree
order.created_by_id
end
- attribute :public_metadata do |order|
- order.public_metadata
- end
-
- attribute :private_metadata do |order|
- order.private_metadata
- end
-
one :user,
resource: Spree::Api::V3::Admin::UserSerializer,
if: proc { params[:includes]&.include?('user') }
diff --git a/api/app/serializers/spree/api/v3/base_serializer.rb b/api/app/serializers/spree/api/v3/base_serializer.rb
index e644067bde..6e78b44174 100644
--- a/api/app/serializers/spree/api/v3/base_serializer.rb
+++ b/api/app/serializers/spree/api/v3/base_serializer.rb
@@ -11,6 +11,7 @@ module Spree
# Use prefixed IDs (Stripe-style) for all API v3 serializers
# e.g., prod_abc123, var_xyz789, or_def456
attribute :id do |object|
+ next nil unless object.respond_to?(:prefix_id)
object.prefix_id
end
diff --git a/api/app/serializers/spree/api/v3/line_item_serializer.rb b/api/app/serializers/spree/api/v3/line_item_serializer.rb
index 1635cef0ba..09b7d04e35 100644
--- a/api/app/serializers/spree/api/v3/line_item_serializer.rb
+++ b/api/app/serializers/spree/api/v3/line_item_serializer.rb
@@ -3,14 +3,14 @@ module Spree
module V3
class LineItemSerializer < BaseSerializer
typelize variant_id: :string, quantity: :number, name: :string, slug: :string, options_text: :string,
- price: :number, display_price: :string, total: :number, display_total: :string,
- adjustment_total: :number, display_adjustment_total: :string,
- additional_tax_total: :number, display_additional_tax_total: :string,
- included_tax_total: :number, display_included_tax_total: :string,
- promo_total: :number, display_promo_total: :string,
- pre_tax_amount: :number, display_pre_tax_amount: :string,
- discounted_amount: :number, display_discounted_amount: :string,
- compare_at_amount: 'number | null', display_compare_at_amount: 'string | null'
+ price: :string, display_price: :string, total: :string, display_total: :string,
+ adjustment_total: :string, display_adjustment_total: :string,
+ additional_tax_total: :string, display_additional_tax_total: :string,
+ included_tax_total: :string, display_included_tax_total: :string,
+ promo_total: :string, display_promo_total: :string,
+ pre_tax_amount: :string, display_pre_tax_amount: :string,
+ discounted_amount: :string, display_discounted_amount: :string,
+ compare_at_amount: 'string | null', display_compare_at_amount: 'string | null'
attribute :variant_id do |line_item|
line_item.variant&.prefix_id
@@ -24,9 +24,15 @@ module Spree
:promo_total, :display_promo_total,
:pre_tax_amount, :display_pre_tax_amount,
:discounted_amount, :display_discounted_amount,
- :compare_at_amount, :display_compare_at_amount,
+ :display_compare_at_amount,
created_at: :iso8601, updated_at: :iso8601
+ # Return compare_at_amount as string, nil if zero
+ attribute :compare_at_amount do |line_item|
+ amount = line_item.compare_at_amount
+ amount.present? && amount.positive? ? amount.to_s : nil
+ end
+
many :images, resource: Spree.api.image_serializer
many :option_values, resource: Spree.api.option_value_serializer
end
diff --git a/api/app/serializers/spree/api/v3/order_promotion_serializer.rb b/api/app/serializers/spree/api/v3/order_promotion_serializer.rb
index 2b4ab96a59..5ec6ca8e89 100644
--- a/api/app/serializers/spree/api/v3/order_promotion_serializer.rb
+++ b/api/app/serializers/spree/api/v3/order_promotion_serializer.rb
@@ -3,7 +3,7 @@ module Spree
module V3
class OrderPromotionSerializer < BaseSerializer
typelize name: :string, description: 'string | null', code: 'string | null',
- amount: :number, display_amount: :string, promotion_id: :string
+ amount: :string, display_amount: :string, promotion_id: :string
attribute :promotion_id do |order_promotion|
order_promotion.promotion&.prefix_id
diff --git a/api/app/serializers/spree/api/v3/order_serializer.rb b/api/app/serializers/spree/api/v3/order_serializer.rb
index f5fff4cf76..c5ade54909 100644
--- a/api/app/serializers/spree/api/v3/order_serializer.rb
+++ b/api/app/serializers/spree/api/v3/order_serializer.rb
@@ -7,14 +7,15 @@ module Spree
typelize number: :string, state: :string, token: :string, email: 'string | null',
special_instructions: 'string | null', currency: :string, item_count: :number,
shipment_state: 'string | null', payment_state: 'string | null',
- item_total: :number, display_item_total: :string,
- ship_total: :number, display_ship_total: :string,
- adjustment_total: :number, display_adjustment_total: :string,
- promo_total: :number, display_promo_total: :string,
- tax_total: :number, display_tax_total: :string,
- included_tax_total: :number, display_included_tax_total: :string,
- additional_tax_total: :number, display_additional_tax_total: :string,
- total: :number, display_total: :string, completed_at: 'string | null'
+ 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, completed_at: 'string | null',
+ payment_methods: 'StorePaymentMethod[]'
attributes :number, :state, :token, :email, :special_instructions,
:currency, :item_count, :shipment_state, :payment_state,
@@ -48,8 +49,12 @@ module Spree
resource: Spree.api.address_serializer,
if: proc { params[:includes]&.include?('ship_address') }
- many :payment_methods,
- resource: Spree.api.payment_method_serializer
+ attribute :payment_methods do |order|
+ pms = order.payment_methods rescue []
+ (pms || []).compact.select { |pm| pm.respond_to?(:prefix_id) }.map do |pm|
+ { id: pm.prefix_id, name: pm.name, description: pm.description, type: pm.type }
+ end
+ end
end
end
end
diff --git a/api/app/serializers/spree/api/v3/payment_serializer.rb b/api/app/serializers/spree/api/v3/payment_serializer.rb
index c31b7cd1fe..4b5d11c4a2 100644
--- a/api/app/serializers/spree/api/v3/payment_serializer.rb
+++ b/api/app/serializers/spree/api/v3/payment_serializer.rb
@@ -3,7 +3,7 @@ module Spree
module V3
class PaymentSerializer < BaseSerializer
typelize state: :string, payment_method_id: :string, response_code: 'string | null',
- number: :string, amount: :number, display_amount: :string
+ number: :string, amount: :string, display_amount: :string
attribute :payment_method_id do |payment|
payment.payment_method&.prefix_id
diff --git a/api/app/serializers/spree/api/v3/shipment_serializer.rb b/api/app/serializers/spree/api/v3/shipment_serializer.rb
index 2acf38a829..5b49e2e9dd 100644
--- a/api/app/serializers/spree/api/v3/shipment_serializer.rb
+++ b/api/app/serializers/spree/api/v3/shipment_serializer.rb
@@ -4,18 +4,11 @@ module Spree
class ShipmentSerializer < BaseSerializer
typelize number: :string, state: :string, tracking: 'string | null',
tracking_url: 'string | null', shipped_at: 'string | null',
- cost: :number, display_cost: :string,
- adjustment_total: :number, display_adjustment_total: :string,
- additional_tax_total: :number, display_additional_tax_total: :string,
- promo_total: :number, display_promo_total: :string,
- included_tax_total: :number, display_included_tax_total: :string,
- total: :number, display_total: :string
+ cost: :string, display_cost: :string
- attributes :number, :state, :tracking, :tracking_url, :shipped_at,
- :cost, :display_cost, :adjustment_total, :display_adjustment_total,
- :additional_tax_total, :display_additional_tax_total, :promo_total, :display_promo_total,
- :included_tax_total, :display_included_tax_total, :total, :display_total,
- created_at: :iso8601, updated_at: :iso8601
+ attributes :number, :state, :tracking, :tracking_url,
+ :cost, :display_cost,
+ shipped_at: :iso8601, created_at: :iso8601, updated_at: :iso8601
one :shipping_method, resource: Spree.api.shipping_method_serializer
one :stock_location, resource: Spree.api.stock_location_serializer
diff --git a/api/app/serializers/spree/api/v3/taxon_serializer.rb b/api/app/serializers/spree/api/v3/taxon_serializer.rb
index 9a3669e88c..76a51d6ae2 100644
--- a/api/app/serializers/spree/api/v3/taxon_serializer.rb
+++ b/api/app/serializers/spree/api/v3/taxon_serializer.rb
@@ -12,9 +12,17 @@ module Spree
attributes :name, :permalink, :position, :lft, :rgt, :depth,
:meta_title, :meta_description, :meta_keywords,
- :parent_id, :taxonomy_id, :children_count,
+ :children_count,
created_at: :iso8601, updated_at: :iso8601
+ attribute :parent_id do |taxon|
+ taxon.parent&.prefix_id
+ end
+
+ attribute :taxonomy_id do |taxon|
+ taxon.taxonomy&.prefix_id
+ end
+
attribute :description do |taxon|
taxon.description.to_plain_text
end
diff --git a/api/app/serializers/spree/api/v3/user_serializer.rb b/api/app/serializers/spree/api/v3/user_serializer.rb
index 23869ffdbd..1a2e3e0aed 100644
--- a/api/app/serializers/spree/api/v3/user_serializer.rb
+++ b/api/app/serializers/spree/api/v3/user_serializer.rb
@@ -4,7 +4,8 @@ module Spree
# Store API User Serializer
# Customer-facing user data
class UserSerializer < BaseSerializer
- typelize email: :string, first_name: 'string | null', last_name: 'string | null'
+ typelize email: :string, first_name: 'string | null', last_name: 'string | null',
+ default_billing_address: 'StoreAddress | null', default_shipping_address: 'StoreAddress | null'
attributes :email, :first_name, :last_name,
created_at: :iso8601, updated_at: :iso8601
diff --git a/api/config/routes.rb b/api/config/routes.rb
index 2ef4be2318..c164679ccd 100644
--- a/api/config/routes.rb
+++ b/api/config/routes.rb
@@ -229,27 +229,30 @@ Spree::Core::Engine.add_routes do
# Store
get 'store', to: 'stores#current'
- # Geography
+ # Geography - countries include nested states from checkout zone
resources :countries, only: [:index, :show]
# Catalog
resources :products, only: [:index, :show]
resources :taxonomies, only: [:index, :show]
- resources :taxons, only: [:show]
+ resources :taxons, only: [:show], id: /.+/
# Orders
resources :orders do
- # State transitions
member do
+ # State transitions
patch :next # Move to next checkout step
patch :advance # Advance through all steps
patch :complete # Complete the order
- patch :cancel # Cancel the order
end
# Nested resources - all require order access
- resources :line_items, only: [:create, :update, :destroy]
- resources :order_promotions, only: [:create, :destroy]
+ resource :store_credits, only: [:create, :destroy], controller: 'orders/store_credits'
+ resources :line_items, only: [:create, :update, :destroy], controller: 'orders/line_items'
+ resources :promotions, only: [:create, :destroy], controller: 'orders/promotions'
+ resources :payments, only: [:index, :show, :create], controller: 'orders/payments'
+ resources :payment_methods, only: [:index], controller: 'orders/payment_methods'
+ resources :shipments, only: [:index, :show, :update], controller: 'orders/shipments'
end
# Customer
diff --git a/api/lib/spree/api/openapi/schema_helper.rb b/api/lib/spree/api/openapi/schema_helper.rb
new file mode 100644
index 0000000000..14950ad2dd
--- /dev/null
+++ b/api/lib/spree/api/openapi/schema_helper.rb
@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Spree
+ module Api
+ module OpenAPI
+ # Helper module to reference Typelizer-generated schemas in rswag specs
+ module SchemaHelper
+ extend self
+
+ # Reference a schema by name (e.g., 'StoreProduct', 'StoreOrder')
+ def ref(schema_name)
+ { '$ref' => "#/components/schemas/#{schema_name}" }
+ end
+
+ # Paginated response wrapper
+ def paginated(schema_name)
+ {
+ type: :object,
+ properties: {
+ data: {
+ type: :array,
+ items: ref(schema_name)
+ },
+ meta: ref('PaginationMeta')
+ },
+ required: %w[data meta]
+ }
+ end
+
+ # Error response schema
+ def error_response
+ ref('ErrorResponse')
+ end
+
+ # Common schemas that are not from serializers
+ def common_schemas
+ {
+ PaginationMeta: {
+ type: :object,
+ properties: {
+ page: { type: :integer, example: 1 },
+ limit: { type: :integer, example: 25 },
+ count: { type: :integer, example: 100 },
+ pages: { type: :integer, example: 4 }
+ },
+ required: %w[page limit count pages]
+ },
+ ErrorResponse: {
+ type: :object,
+ properties: {
+ error: {
+ type: :object,
+ properties: {
+ code: { type: :string, example: 'record_not_found' },
+ message: { type: :string, example: 'Record not found' },
+ details: {
+ type: :object,
+ additionalProperties: {
+ type: :array,
+ items: { type: :string }
+ },
+ nullable: true
+ }
+ },
+ required: %w[code message]
+ }
+ },
+ required: %w[error]
+ },
+ AuthResponse: {
+ type: :object,
+ properties: {
+ token: { type: :string, description: 'JWT access token' },
+ user: { '$ref' => '#/components/schemas/StoreUser' }
+ },
+ required: %w[token user]
+ }
+ }
+ end
+
+ # Get all schemas (Typelizer + common)
+ def all_schemas
+ schemas = common_schemas
+
+ begin
+ schemas.merge!(TypelizerConverter.generate_schemas)
+ rescue StandardError => e
+ Rails.logger.warn "Failed to load Typelizer schemas: #{e.message}"
+ end
+
+ schemas
+ end
+ end
+ end
+ end
+end
diff --git a/api/lib/spree/api/openapi/typelizer_converter.rb b/api/lib/spree/api/openapi/typelizer_converter.rb
new file mode 100644
index 0000000000..b2d3594d28
--- /dev/null
+++ b/api/lib/spree/api/openapi/typelizer_converter.rb
@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+module Spree
+ module Api
+ module OpenAPI
+ # Converts Typelizer interface data to OpenAPI 3.0 schemas
+ # This allows us to generate OpenAPI schemas from the same Alba serializers
+ # that generate TypeScript types, keeping them in sync.
+ class TypelizerConverter
+ # Force enable Typelizer for schema generation
+ # Typelizer is normally disabled in test/production, but we need it
+ # to generate OpenAPI schemas
+ def self.with_typelizer_enabled
+ original_env = ENV['DISABLE_TYPELIZER']
+ ENV['DISABLE_TYPELIZER'] = 'false'
+ yield
+ ensure
+ ENV['DISABLE_TYPELIZER'] = original_env
+ end
+
+ TYPESCRIPT_TO_OPENAPI_TYPES = {
+ 'string' => { type: :string },
+ 'number' => { type: :number },
+ 'boolean' => { type: :boolean },
+ 'null' => { type: :string, nullable: true },
+ 'unknown' => { type: :object },
+ 'any' => { type: :object }
+ }.freeze
+
+ class << self
+ # Generate OpenAPI schemas hash from all Typelizer serializers
+ def generate_schemas
+ schemas = {}
+
+ interfaces.each do |interface|
+ name = interface.name
+ schemas[name] = interface_to_schema(interface)
+ end
+
+ schemas
+ end
+
+ # Get all Typelizer interfaces
+ # Note: No caching to ensure fresh schemas when serializers change
+ def interfaces
+ load_serializers
+ context = ::Typelizer::WriterContext.new
+ serializers = target_serializers
+
+ serializers.map { |klass| context.interface_for(klass) }
+ end
+
+ # Convert a single interface to OpenAPI schema
+ def interface_to_schema(interface)
+ schema = {
+ type: :object,
+ properties: {},
+ 'x-typelizer': true
+ }
+
+ required = []
+
+ # Get typelize hints from the serializer class for nullable overrides
+ typelize_hints = {}
+ if interface.serializer.respond_to?(:_typelizer_attributes)
+ typelize_hints = interface.serializer._typelizer_attributes || {}
+ end
+
+ interface.properties.each do |prop|
+ # Check if typelize hint indicates nullable
+ hint = typelize_hints[prop.name.to_sym]
+ nullable_from_hint = hint && hint[:type].to_s.include?('| null')
+
+ prop_schema = property_to_schema(prop, nullable_override: nullable_from_hint)
+ schema[:properties][prop.name.to_sym] = prop_schema
+
+ # Track required fields (non-optional, non-nullable)
+ is_nullable = prop.optional || prop_schema[:nullable] || nullable_from_hint
+ required << prop.name unless is_nullable
+ end
+
+ schema[:required] = required if required.any?
+ schema
+ end
+
+ # Convert a Typelizer property to OpenAPI property schema
+ def property_to_schema(prop, nullable_override: false)
+ # Get the type - can be an Interface object or a string
+ type_value = prop.type
+
+ # Determine if nullable from prop or override
+ is_nullable = prop.nullable || nullable_override
+
+ # Handle Interface types (associations to other serializers)
+ if type_value.respond_to?(:name) && type_value.is_a?(::Typelizer::Interface)
+ ref = { '$ref' => "#/components/schemas/#{type_value.name}" }
+ if prop.multi
+ schema = { type: :array, items: ref }
+ schema[:nullable] = true if is_nullable
+ elsif is_nullable
+ # OpenAPI 3.0: nullable $ref needs allOf wrapper
+ schema = { allOf: [ref], nullable: true }
+ else
+ schema = ref
+ end
+ return schema
+ end
+
+ # Get type string - handle both direct strings and other objects
+ type_string = type_value.to_s.strip
+
+ # Handle union types (e.g., "string | null", "number | null")
+ if type_string.include?('|')
+ schema = parse_union_type(type_string, prop)
+ schema = { type: :array, items: schema } if prop.multi && schema[:type]&.to_s != 'array'
+ return schema
+ end
+
+ # Handle array types (e.g., "Array<string>", "string[]")
+ if type_string.match?(/Array<(.+)>/) || type_string.end_with?('[]')
+ return parse_array_type(type_string, prop)
+ end
+
+ # Handle basic types
+ if TYPESCRIPT_TO_OPENAPI_TYPES.key?(type_string)
+ schema = TYPESCRIPT_TO_OPENAPI_TYPES[type_string].dup
+ schema = { type: :array, items: schema } if prop.multi
+ schema[:nullable] = true if prop.nullable
+ return schema
+ end
+
+ # Handle references to other types (serializer associations)
+ if type_string.match?(/^[A-Z]/)
+ ref = { '$ref' => "#/components/schemas/#{type_string}" }
+ if prop.multi
+ schema = { type: :array, items: ref }
+ schema[:nullable] = true if prop.nullable
+ elsif prop.nullable
+ # OpenAPI 3.0: nullable $ref needs allOf wrapper
+ schema = { allOf: [ref], nullable: true }
+ else
+ schema = ref
+ end
+ return schema
+ end
+
+ # Default to object
+ schema = { type: :object }
+ schema = { type: :array, items: schema } if prop.multi
+ schema[:nullable] = true if prop.nullable
+ schema
+ end
+
+ private
+
+ def parse_union_type(type_string, prop)
+ types = type_string.split('|').map(&:strip)
+
+ # Check if nullable
+ nullable = types.include?('null') || types.include?('undefined')
+ types = types.reject { |t| t == 'null' || t == 'undefined' }
+
+ if types.size == 1
+ schema = property_type_to_schema(types.first, nullable: nullable)
+ return schema
+ end
+
+ # Multiple non-null types - use oneOf
+ {
+ oneOf: types.map { |t| property_type_to_schema(t) },
+ nullable: nullable || nil
+ }.compact
+ end
+
+ def parse_array_type(type_string, prop)
+ # Extract inner type from Array<T> or T[]
+ inner_type = if type_string.match(/Array<(.+)>/)
+ Regexp.last_match(1)
+ else
+ type_string.sub(/\[\]$/, '')
+ end
+
+ {
+ type: :array,
+ items: property_type_to_schema(inner_type)
+ }
+ end
+
+ def property_type_to_schema(type_string, nullable: false)
+ type_string = type_string.strip
+
+ if TYPESCRIPT_TO_OPENAPI_TYPES.key?(type_string)
+ schema = TYPESCRIPT_TO_OPENAPI_TYPES[type_string].dup
+ schema[:nullable] = true if nullable
+ return schema
+ end
+
+ # Reference type - in OpenAPI 3.0, nullable $ref needs allOf wrapper
+ if type_string.match?(/^[A-Z]/)
+ ref = { '$ref' => "#/components/schemas/#{type_string}" }
+ if nullable
+ return { allOf: [ref], nullable: true }
+ end
+ return ref
+ end
+
+ schema = { type: :object }
+ schema[:nullable] = true if nullable
+ schema
+ end
+
+ def load_serializers
+ # Ensure Typelizer is enabled when loading serializers so the
+ # typelize DSL actually stores type information
+ original_env = ENV['DISABLE_TYPELIZER']
+ ENV['DISABLE_TYPELIZER'] = 'false'
+
+ # Force reload of serializers with Typelizer enabled
+ ::Typelizer.dirs.flat_map { |dir| Dir["#{dir}/**/*.rb"] }.each do |file|
+ load file
+ end
+ ensure
+ ENV['DISABLE_TYPELIZER'] = original_env
+ end
+
+ def target_serializers
+ base_classes = ::Typelizer.base_classes.filter_map do |base_class|
+ Object.const_get(base_class) if Object.const_defined?(base_class)
+ end
+
+ return [] if base_classes.none?
+
+ (base_classes + base_classes.flat_map(&:descendants)).uniq
+ .reject { |serializer| ::Typelizer.reject_class.call(serializer: serializer) }
+ .select { |s| s.name&.start_with?('Spree::Api::V3::') }
+ .sort_by(&:name)
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/api/lib/spree/api/testing_support/v3/base.rb b/api/lib/spree/api/testing_support/v3/base.rb
index d52674ec16..3a50ec035c 100644
--- a/api/lib/spree/api/testing_support/v3/base.rb
+++ b/api/lib/spree/api/testing_support/v3/base.rb
@@ -21,11 +21,15 @@ end
shared_context 'API v3 Store' do
let(:store) { @default_store || create(:store, default: true) }
let(:api_key) { create(:api_key, :publishable, store: store) }
- let(:api_key_headers) { { 'X-Spree-Api-Key' => api_key.token } }
+ let(:api_key_headers) { { 'x-spree-api-key' => api_key.token } }
let(:user) { create(:user_with_addresses) }
let(:jwt_token) { Spree::Api::V3::TestingSupport.generate_jwt(user) }
let(:bearer_headers) { api_key_headers.merge('Authorization' => "Bearer #{jwt_token}") }
+
+ before do
+ allow_any_instance_of(Spree::Api::V3::BaseController).to receive(:current_store).and_return(store)
+ end
end
shared_context 'API v3 Store authenticated' do
diff --git a/api/spec/controllers/spree/api/v3/store/line_items_controller_spec.rb b/api/spec/controllers/spree/api/v3/store/orders/line_items_controller_spec.rb
similarity index 98%
rename from api/spec/controllers/spree/api/v3/store/line_items_controller_spec.rb
rename to api/spec/controllers/spree/api/v3/store/orders/line_items_controller_spec.rb
index cb615dc48b..806f8fa75b 100644
--- a/api/spec/controllers/spree/api/v3/store/line_items_controller_spec.rb
+++ b/api/spec/controllers/spree/api/v3/store/orders/line_items_controller_spec.rb
@@ -1,6 +1,6 @@
require 'spec_helper'
-RSpec.describe Spree::Api::V3::Store::LineItemsController, type: :controller do
+RSpec.describe Spree::Api::V3::Store::Orders::LineItemsController, type: :controller do
render_views
include_context 'API v3 Store'
diff --git a/api/spec/controllers/spree/api/v3/store/products_controller_spec.rb b/api/spec/controllers/spree/api/v3/store/products_controller_spec.rb
index 48cb4e88f3..1155e600ea 100644
--- a/api/spec/controllers/spree/api/v3/store/products_controller_spec.rb
+++ b/api/spec/controllers/spree/api/v3/store/products_controller_spec.rb
@@ -15,6 +15,10 @@ RSpec.describe Spree::Api::V3::Store::ProductsController, type: :controller do
request.headers['X-Spree-Api-Key'] = api_key.token
end
+ after do
+ I18n.locale = store.default_locale
+ end
+
describe 'GET #index' do
it 'returns a list of products' do
get :index
@@ -63,7 +67,7 @@ RSpec.describe Spree::Api::V3::Store::ProductsController, type: :controller do
get :index
ids = json_response['data'].map { |p| p['id'] }
- expect(ids).not_to include(draft_product.id)
+ expect(ids).not_to include(draft_product.prefix_id)
end
end
@@ -73,7 +77,7 @@ RSpec.describe Spree::Api::V3::Store::ProductsController, type: :controller do
expect(response).to have_http_status(:ok)
expect(json_response['data'].size).to eq(1)
- expect(json_response['data'].first['id']).to eq(product.id)
+ expect(json_response['data'].first['id']).to eq(product.prefix_id)
end
end
@@ -104,25 +108,81 @@ RSpec.describe Spree::Api::V3::Store::ProductsController, type: :controller do
end
describe 'GET #show' do
- it 'returns a product by id' do
- get :show, params: { id: product.id }
+ context 'finding by slug' do
+ it 'returns a product by slug' do
+ get :show, params: { id: product.slug }
- expect(response).to have_http_status(:ok)
- expect(json_response['id']).to eq(product.id)
- expect(json_response['name']).to eq(product.name)
- expect(json_response['slug']).to eq(product.slug)
+ expect(response).to have_http_status(:ok)
+ expect(json_response['id']).to eq(product.prefix_id)
+ expect(json_response['name']).to eq(product.name)
+ expect(json_response['slug']).to eq(product.slug)
+ end
end
- it 'returns a product by slug' do
- get :show, params: { id: product.slug }
+ context 'finding by prefix_id' do
+ it 'returns a product by prefix_id' do
+ get :show, params: { id: product.prefix_id }
- expect(response).to have_http_status(:ok)
- expect(json_response['id']).to eq(product.id)
+ expect(response).to have_http_status(:ok)
+ expect(json_response['id']).to eq(product.prefix_id)
+ expect(json_response['name']).to eq(product.name)
+ expect(json_response['slug']).to eq(product.slug)
+ end
+ end
+
+ context 'with translations', if: Spree::Product.include?(Spree::TranslatableResource) do
+ let!(:translated_product) do
+ create(:product, stores: [store], status: 'active', name: 'English Product', slug: 'english-product').tap do |p|
+ Mobility.with_locale(:fr) do
+ p.name = 'Produit Français'
+ p.slug = 'produit-francais'
+ p.save!
+ end
+ end
+ end
+
+ before do
+ allow(store).to receive(:supported_locales_list).and_return(%w[en fr])
+ allow(store).to receive(:default_locale).and_return('en')
+ end
+
+ it 'finds product by English slug with English locale' do
+ request.headers['x-spree-locale'] = 'en'
+ get :show, params: { id: 'english-product' }
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['name']).to eq('English Product')
+ expect(json_response['slug']).to eq('english-product')
+ end
+
+ it 'finds product by French slug with French locale' do
+ request.headers['x-spree-locale'] = 'fr'
+ get :show, params: { id: 'produit-francais' }
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['name']).to eq('Produit Français')
+ expect(json_response['slug']).to eq('produit-francais')
+ end
+
+ it 'returns translated content based on locale header' do
+ request.headers['x-spree-locale'] = 'fr'
+ get :show, params: { id: translated_product.prefix_id }
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['name']).to eq('Produit Français')
+ end
+
+ it 'returns 404 when searching French slug with English locale' do
+ request.headers['x-spree-locale'] = 'en'
+ get :show, params: { id: 'produit-francais' }
+
+ expect(response).to have_http_status(:not_found)
+ end
end
context 'error handling' do
it 'returns not found for non-existent product' do
- get :show, params: { id: 'non-existent' }
+ get :show, params: { id: 'non-existent-slug' }
expect(response).to have_http_status(:not_found)
expect(json_response['error']['code']).to eq('record_not_found')
@@ -130,18 +190,66 @@ RSpec.describe Spree::Api::V3::Store::ProductsController, type: :controller do
end
it 'returns not found for product from another store' do
- get :show, params: { id: other_store_product.id }
+ get :show, params: { id: other_store_product.slug }
expect(response).to have_http_status(:not_found)
expect(json_response['error']['code']).to eq('record_not_found')
end
it 'returns not found for draft product' do
- get :show, params: { id: draft_product.id }
+ get :show, params: { id: draft_product.slug }
expect(response).to have_http_status(:not_found)
expect(json_response['error']['code']).to eq('record_not_found')
end
end
end
+
+ describe 'locale and currency headers' do
+ context 'x-spree-locale header' do
+ before do
+ allow(store).to receive(:supported_locales_list).and_return(%w[en fr])
+ allow(store).to receive(:default_locale).and_return('en')
+ end
+
+ it 'sets locale from header' do
+ request.headers['x-spree-locale'] = 'fr'
+ get :index
+
+ expect(response).to have_http_status(:ok)
+ expect(I18n.locale).to eq(:fr)
+ end
+
+ it 'falls back to default locale for unsupported locale' do
+ request.headers['x-spree-locale'] = 'de'
+ get :index
+
+ expect(response).to have_http_status(:ok)
+ expect(I18n.locale).to eq(:en)
+ end
+ end
+
+ context 'x-spree-currency header' do
+ before do
+ allow(store).to receive(:supported_currencies_list).and_return([Money::Currency.find('USD'), Money::Currency.find('EUR')])
+ allow(store).to receive(:default_currency).and_return('USD')
+ end
+
+ it 'sets currency from header' do
+ request.headers['x-spree-currency'] = 'EUR'
+ get :index
+
+ expect(response).to have_http_status(:ok)
+ expect(controller.send(:current_currency)).to eq('EUR')
+ end
+
+ it 'falls back to default currency for unsupported currency' do
+ request.headers['x-spree-currency'] = 'GBP'
+ get :index
+
+ expect(response).to have_http_status(:ok)
+ expect(controller.send(:current_currency)).to eq('USD')
+ end
+ end
+ end
end
diff --git a/api/spec/controllers/spree/api/v3/store/taxons_controller_spec.rb b/api/spec/controllers/spree/api/v3/store/taxons_controller_spec.rb
index 9a22a54ed5..d3f1ba53ed 100644
--- a/api/spec/controllers/spree/api/v3/store/taxons_controller_spec.rb
+++ b/api/spec/controllers/spree/api/v3/store/taxons_controller_spec.rb
@@ -16,30 +16,108 @@ RSpec.describe Spree::Api::V3::Store::TaxonsController, type: :controller do
request.headers['X-Spree-Api-Key'] = api_key.token
end
+ after do
+ I18n.locale = store.default_locale
+ end
+
describe 'GET #show' do
- it 'returns the taxon' do
- get :show, params: { id: taxon.id }
+ context 'finding by permalink' do
+ it 'returns the taxon by permalink' do
+ get :show, params: { id: taxon.permalink }
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['id']).to eq(taxon.prefix_id)
+ expect(json_response['name']).to eq(taxon.name)
+ expect(json_response['permalink']).to eq(taxon.permalink)
+ end
- expect(response).to have_http_status(:ok)
- expect(json_response['id']).to eq(taxon.id)
- expect(json_response['name']).to eq(taxon.name)
+ it 'returns nested taxon by full permalink path' do
+ get :show, params: { id: child_taxon.permalink }
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['id']).to eq(child_taxon.prefix_id)
+ expect(json_response['name']).to eq(child_taxon.name)
+ end
+ end
+
+ context 'finding by prefix_id' do
+ it 'returns the taxon by prefix_id' do
+ get :show, params: { id: taxon.prefix_id }
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['id']).to eq(taxon.prefix_id)
+ expect(json_response['name']).to eq(taxon.name)
+ expect(json_response['permalink']).to eq(taxon.permalink)
+ end
end
it 'returns taxon attributes' do
- get :show, params: { id: taxon.id }
+ get :show, params: { id: taxon.permalink }
expect(json_response).to include('id', 'name', 'permalink')
end
- it 'includes parent information' do
- get :show, params: { id: child_taxon.id }
+ it 'includes parent information for child taxon' do
+ get :show, params: { id: child_taxon.permalink }
expect(response).to have_http_status(:ok)
+ expect(json_response['parent_id']).to eq(taxon.prefix_id)
+ end
+
+ context 'with translations', if: Spree::Taxon.include?(Spree::TranslatableResource) do
+ let!(:translated_taxon) do
+ create(:taxon, taxonomy: taxonomy, name: 'Clothing', permalink: 'clothing').tap do |t|
+ Mobility.with_locale(:fr) do
+ t.name = 'Vêtements'
+ t.permalink = 'vetements'
+ t.save!
+ end
+ end
+ end
+
+ before do
+ allow(store).to receive(:supported_locales_list).and_return(%w[en fr])
+ allow(store).to receive(:default_locale).and_return('en')
+ end
+
+ it 'finds taxon by English permalink with English locale' do
+ request.headers['x-spree-locale'] = 'en'
+ get :show, params: { id: translated_taxon.permalink }
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['name']).to eq('Clothing')
+ expect(json_response['permalink']).to eq(translated_taxon.permalink)
+ end
+
+ it 'finds taxon by French permalink with French locale' do
+ french_permalink = Mobility.with_locale(:fr) { translated_taxon.permalink }
+ request.headers['x-spree-locale'] = 'fr'
+ get :show, params: { id: french_permalink }
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['name']).to eq('Vêtements')
+ expect(json_response['permalink']).to eq(french_permalink)
+ end
+
+ it 'returns translated content based on locale header' do
+ request.headers['x-spree-locale'] = 'fr'
+ get :show, params: { id: translated_taxon.prefix_id }
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['name']).to eq('Vêtements')
+ end
+
+ it 'returns 404 when searching French permalink with English locale' do
+ request.headers['x-spree-locale'] = 'en'
+ get :show, params: { id: 'vetements' }
+
+ expect(response).to have_http_status(:not_found)
+ end
end
context 'error handling' do
it 'returns not found for non-existent taxon' do
- get :show, params: { id: 0 }
+ get :show, params: { id: 'non-existent-permalink' }
expect(response).to have_http_status(:not_found)
expect(json_response['error']['code']).to eq('record_not_found')
@@ -47,14 +125,14 @@ RSpec.describe Spree::Api::V3::Store::TaxonsController, type: :controller do
end
it 'returns not found for taxon from another store' do
- get :show, params: { id: other_store_taxon.id }
+ get :show, params: { id: other_store_taxon.permalink }
expect(response).to have_http_status(:not_found)
expect(json_response['error']['code']).to eq('record_not_found')
end
- it 'returns not found for invalid id' do
- get :show, params: { id: 'invalid' }
+ it 'returns not found for invalid prefix_id' do
+ get :show, params: { id: 'txn_invalid123' }
expect(response).to have_http_status(:not_found)
expect(json_response['error']['code']).to eq('record_not_found')
@@ -65,7 +143,7 @@ RSpec.describe Spree::Api::V3::Store::TaxonsController, type: :controller do
before { request.headers['X-Spree-Api-Key'] = nil }
it 'returns unauthorized' do
- get :show, params: { id: taxon.id }
+ get :show, params: { id: taxon.permalink }
expect(response).to have_http_status(:unauthorized)
expect(json_response['error']['code']).to eq('invalid_token')
@@ -73,4 +151,52 @@ RSpec.describe Spree::Api::V3::Store::TaxonsController, type: :controller do
end
end
end
+
+ describe 'locale and currency headers' do
+ context 'x-spree-locale header' do
+ before do
+ allow(store).to receive(:supported_locales_list).and_return(%w[en fr])
+ allow(store).to receive(:default_locale).and_return('en')
+ end
+
+ it 'sets locale from header' do
+ request.headers['x-spree-locale'] = 'fr'
+ get :show, params: { id: taxon.prefix_id }
+
+ expect(response).to have_http_status(:ok)
+ expect(I18n.locale).to eq(:fr)
+ end
+
+ it 'falls back to default locale for unsupported locale' do
+ request.headers['x-spree-locale'] = 'de'
+ get :show, params: { id: taxon.prefix_id }
+
+ expect(response).to have_http_status(:ok)
+ expect(I18n.locale).to eq(:en)
+ end
+ end
+
+ context 'x-spree-currency header' do
+ before do
+ allow(store).to receive(:supported_currencies_list).and_return([Money::Currency.find('USD'), Money::Currency.find('EUR')])
+ allow(store).to receive(:default_currency).and_return('USD')
+ end
+
+ it 'sets currency from header' do
+ request.headers['x-spree-currency'] = 'EUR'
+ get :show, params: { id: taxon.permalink }
+
+ expect(response).to have_http_status(:ok)
+ expect(controller.send(:current_currency)).to eq('EUR')
+ end
+
+ it 'falls back to default currency for unsupported currency' do
+ request.headers['x-spree-currency'] = 'GBP'
+ get :show, params: { id: taxon.permalink }
+
+ expect(response).to have_http_status(:ok)
+ expect(controller.send(:current_currency)).to eq('USD')
+ end
+ end
+ end
end
diff --git a/api/spec/integration/spree/api/v3/store/addresses_spec.rb b/api/spec/integration/spree/api/v3/store/addresses_spec.rb
new file mode 100644
index 0000000000..3717970f1d
--- /dev/null
+++ b/api/spec/integration/spree/api/v3/store/addresses_spec.rb
@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Addresses API', type: :request, swagger_doc: 'api-reference/store.yaml' do
+ include_context 'API v3 Store'
+
+ let!(:country) { create(:country, states_required: true) }
+ let!(:state) { create(:state, country: country) }
+ let!(:address) { create(:address, user: user, country: country, state: state) }
+
+ path '/api/v3/store/customers/me/addresses' do
+ get 'List customer addresses' do
+ tags 'Addresses'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Returns all addresses in the customer address book'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: true
+ parameter name: :page, in: :query, type: :integer, required: false
+ parameter name: :per_page, in: :query, type: :integer, required: false
+
+ response '200', 'addresses found' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+
+ schema type: :object,
+ properties: {
+ data: { type: :array, items: { '$ref' => '#/components/schemas/StoreAddress' } },
+ meta: { '$ref' => '#/components/schemas/PaginationMeta' }
+ }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data']).to be_an(Array)
+ end
+ end
+
+ response '401', 'unauthorized' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { '' }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+
+ post 'Create an address' do
+ tags 'Addresses'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Adds a new address to the customer address book'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: true
+ parameter name: :body, in: :body, schema: {
+ type: :object,
+ properties: {
+ address: {
+ type: :object,
+ properties: {
+ firstname: { type: :string },
+ lastname: { type: :string },
+ address1: { type: :string },
+ address2: { type: :string },
+ city: { type: :string },
+ zipcode: { type: :string },
+ phone: { type: :string },
+ country_iso: { type: :string, description: 'ISO country code (e.g., "US", "DE")' },
+ state_code: { type: :string, description: 'State abbreviation/code (e.g., "CA", "NY") - required if country has states' }
+ },
+ required: %w[firstname lastname address1 city zipcode phone country_iso]
+ }
+ }
+ }
+
+ response '201', 'address created' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:body) do
+ {
+ address: {
+ firstname: 'John',
+ lastname: 'Doe',
+ address1: '123 Main St',
+ city: 'New York',
+ zipcode: '10001',
+ phone: '+1 555 123 4567',
+ country_iso: country.iso,
+ state_code: state.abbr
+ }
+ }
+ end
+
+ schema '$ref' => '#/components/schemas/StoreAddress'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['firstname']).to eq('John')
+ expect(data['city']).to eq('New York')
+ expect(data['country_iso']).to eq(country.iso)
+ end
+ end
+
+ response '422', 'validation error' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:body) { { address: { firstname: '' } } }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+ end
+
+ path '/api/v3/store/customers/me/addresses/{id}' do
+ get 'Get an address' do
+ tags 'Addresses'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: true
+ parameter name: :id, in: :path, type: :string, required: true
+
+ response '200', 'address found' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:id) { address.prefix_id }
+
+ schema '$ref' => '#/components/schemas/StoreAddress'
+
+ run_test!
+ end
+
+ response '404', 'address not found' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:id) { 'non-existent' }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+
+ patch 'Update an address' do
+ tags 'Addresses'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: true
+ parameter name: :id, in: :path, type: :string, required: true
+ parameter name: :body, in: :body, schema: {
+ type: :object,
+ properties: {
+ address: {
+ type: :object,
+ properties: {
+ firstname: { type: :string },
+ lastname: { type: :string },
+ address1: { type: :string },
+ city: { type: :string }
+ }
+ }
+ }
+ }
+
+ response '200', 'address updated' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:id) { address.prefix_id }
+ let(:body) { { address: { city: 'Los Angeles' } } }
+
+ schema '$ref' => '#/components/schemas/StoreAddress'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['city']).to eq('Los Angeles')
+ end
+ end
+ end
+
+ delete 'Delete an address' do
+ tags 'Addresses'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: true
+ parameter name: :id, in: :path, type: :string, required: true
+
+ response '204', 'address deleted' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:id) { address.prefix_id }
+
+ run_test!
+ end
+
+ response '404', 'address not found' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:id) { 'non-existent' }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+ end
+end
diff --git a/api/spec/integration/spree/api/v3/store/auth_spec.rb b/api/spec/integration/spree/api/v3/store/auth_spec.rb
new file mode 100644
index 0000000000..e0990611be
--- /dev/null
+++ b/api/spec/integration/spree/api/v3/store/auth_spec.rb
@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Authentication API', type: :request, swagger_doc: 'api-reference/store.yaml' do
+ include_context 'API v3 Store'
+
+ let(:existing_user) { create(:user, email: '[email protected]', password: 'password123') }
+
+ path '/api/v3/store/auth/login' do
+ post 'Login' do
+ tags 'Authentication'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: []]
+ description 'Authenticates a customer with email/password and returns a JWT token'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :body, in: :body, schema: {
+ type: :object,
+ properties: {
+ provider: { type: :string, example: 'email', description: 'Authentication provider (default: email)' },
+ email: { type: :string, format: 'email', example: '[email protected]' },
+ password: { type: :string, example: 'password123' }
+ },
+ required: %w[email password]
+ }
+
+ response '200', 'login successful' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:body) { { email: existing_user.email, password: 'password123' } }
+
+ schema '$ref' => '#/components/schemas/AuthResponse'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['token']).to be_present
+ expect(data['user']).to be_present
+ expect(data['user']['email']).to eq(existing_user.email)
+ end
+ end
+
+ response '401', 'invalid credentials' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:body) { { email: existing_user.email, password: 'wrong_password' } }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+
+ response '401', 'user not found' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:body) { { email: '[email protected]', password: 'password123' } }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+
+ response '401', 'missing API key' do
+ let(:'x-spree-api-key') { 'invalid' }
+ let(:body) { { email: existing_user.email, password: 'password123' } }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+ end
+
+ path '/api/v3/store/auth/register' do
+ post 'Register' do
+ tags 'Authentication'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: []]
+ description 'Creates a new customer account and returns a JWT token'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :body, in: :body, schema: {
+ type: :object,
+ properties: {
+ user: {
+ type: :object,
+ properties: {
+ email: { type: :string, format: 'email' },
+ password: { type: :string, minLength: 6 },
+ password_confirmation: { type: :string },
+ first_name: { type: :string },
+ last_name: { type: :string }
+ },
+ required: %w[email password]
+ }
+ },
+ required: %w[user]
+ }
+
+ response '201', 'registration successful' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:body) do
+ {
+ user: {
+ email: '[email protected]',
+ password: 'password123',
+ first_name: 'John',
+ last_name: 'Doe'
+ }
+ }
+ end
+
+ schema '$ref' => '#/components/schemas/AuthResponse'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['token']).to be_present
+ expect(data['user']).to be_present
+
+ # Verify user was created
+ new_user = Spree.user_class.find_by(email: '[email protected]')
+ expect(new_user).to be_present
+ expect(new_user.first_name).to eq('John')
+ end
+ end
+
+ response '422', 'email already taken' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:body) do
+ {
+ user: {
+ email: existing_user.email,
+ password: 'password123'
+ }
+ }
+ end
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['error']['code']).to eq('validation_error')
+ end
+ end
+ end
+ end
+
+ path '/api/v3/store/auth/refresh' do
+ post 'Refresh token' do
+ tags 'Authentication'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Generates a new JWT token for the authenticated user'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: true,
+ description: 'Bearer token'
+
+ response '200', 'token refreshed' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:jwt_token) { Spree::Api::V3::TestingSupport.generate_jwt(existing_user) }
+
+ schema '$ref' => '#/components/schemas/AuthResponse'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['token']).to be_present
+ expect(data['user']).to be_present
+ end
+ end
+
+ response '401', 'missing or invalid token' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { 'Bearer invalid_token' }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+ end
+end
diff --git a/api/spec/integration/spree/api/v3/store/customers_spec.rb b/api/spec/integration/spree/api/v3/store/customers_spec.rb
new file mode 100644
index 0000000000..07c2bd68e8
--- /dev/null
+++ b/api/spec/integration/spree/api/v3/store/customers_spec.rb
@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Customers API', type: :request, swagger_doc: 'api-reference/store.yaml' do
+ include_context 'API v3 Store'
+
+ path '/api/v3/store/customers/me' do
+ get 'Get current customer profile' do
+ tags 'Customers'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Returns the profile of the currently authenticated customer'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: true,
+ description: 'Bearer JWT token'
+
+ response '200', 'profile found' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+
+ schema '$ref' => '#/components/schemas/StoreUser'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['email']).to eq(user.email)
+ end
+ end
+
+ response '401', 'unauthorized - no token' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { '' }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+
+ response '401', 'unauthorized - invalid token' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { 'Bearer invalid_token' }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+
+ patch 'Update current customer profile' do
+ tags 'Customers'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Updates the profile of the currently authenticated customer'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: true
+ parameter name: :body, in: :body, schema: {
+ type: :object,
+ properties: {
+ user: {
+ type: :object,
+ properties: {
+ first_name: { type: :string },
+ last_name: { type: :string },
+ email: { type: :string, format: 'email' },
+ password: { type: :string },
+ password_confirmation: { type: :string }
+ }
+ }
+ }
+ }
+
+ response '200', 'profile updated' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:body) { { user: { first_name: 'Updated', last_name: 'Name' } } }
+
+ schema '$ref' => '#/components/schemas/StoreUser'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['first_name']).to eq('Updated')
+ expect(data['last_name']).to eq('Name')
+ end
+ end
+
+ response '422', 'validation error' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:body) { { user: { email: '' } } }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+ end
+end
diff --git a/api/spec/integration/spree/api/v3/store/line_items_spec.rb b/api/spec/integration/spree/api/v3/store/line_items_spec.rb
new file mode 100644
index 0000000000..1296897991
--- /dev/null
+++ b/api/spec/integration/spree/api/v3/store/line_items_spec.rb
@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Line Items API', type: :request, swagger_doc: 'api-reference/store.yaml' do
+ include_context 'API v3 Store'
+
+ let!(:order) { create(:order, store: store, user: user) }
+ let!(:product) { create(:product, stores: [store]) }
+ let!(:variant) { product.master }
+ let!(:line_item) { create(:line_item, order: order, variant: variant, quantity: 1) }
+
+ path '/api/v3/store/orders/{order_id}/line_items' do
+ post 'Add item to cart' do
+ tags 'Line Items'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Adds a variant to the order. Creates a new line item or increases quantity if variant already in cart.'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: false,
+ description: 'Bearer token for authenticated customers'
+ parameter name: :order_id, in: :path, type: :string, required: true,
+ description: 'Order ID or number'
+ parameter name: :order_token, in: :query, type: :string, required: false,
+ description: 'Order token for guest access'
+ parameter name: :body, in: :body, schema: {
+ type: :object,
+ properties: {
+ variant_id: { type: :string, description: 'Variant ID to add' },
+ quantity: { type: :integer, description: 'Quantity to add (default: 1)' }
+ },
+ required: %w[variant_id]
+ }
+
+ response '201', 'line item created' do
+ let(:new_product) { create(:product, stores: [store]) }
+ let(:new_variant) { new_product.master }
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:order_id) { order.number }
+ let(:body) { { line_item: { variant_id: new_variant.prefix_id, quantity: 2 } } }
+
+ schema '$ref' => '#/components/schemas/StoreLineItem'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['quantity']).to eq(2)
+ end
+ end
+
+ response '404', 'variant not found' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:order_id) { order.number }
+ let(:body) { { line_item: { variant_id: 'invalid', quantity: 1 } } }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+
+ response '404', 'order not found' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:order_id) { 'non-existent' }
+ let(:body) { { line_item: { variant_id: variant.prefix_id, quantity: 1 } } }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+ end
+
+ path '/api/v3/store/orders/{order_id}/line_items/{id}' do
+ patch 'Update line item quantity' do
+ tags 'Line Items'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Updates the quantity of a line item in the cart'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: false
+ parameter name: :order_id, in: :path, type: :string, required: true
+ parameter name: :id, in: :path, type: :string, required: true, description: 'Line item ID'
+ parameter name: :order_token, in: :query, type: :string, required: false
+ parameter name: :body, in: :body, schema: {
+ type: :object,
+ properties: {
+ quantity: { type: :integer, minimum: 1 }
+ },
+ required: %w[quantity]
+ }
+
+ response '200', 'line item updated' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:order_id) { order.number }
+ let(:id) { line_item.prefix_id }
+ let(:body) { { line_item: { quantity: 5 } } }
+
+ schema '$ref' => '#/components/schemas/StoreLineItem'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['quantity']).to eq(5)
+ end
+ end
+
+ end
+
+ delete 'Remove line item from cart' do
+ tags 'Line Items'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Removes a line item from the order'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: false
+ parameter name: :order_id, in: :path, type: :string, required: true
+ parameter name: :id, in: :path, type: :string, required: true
+ parameter name: :order_token, in: :query, type: :string, required: false
+
+ response '204', 'line item removed' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:order_id) { order.number }
+ let(:id) { line_item.prefix_id }
+
+ run_test! do
+ expect(order.reload.line_items).to be_empty
+ end
+ end
+
+ response '404', 'line item not found' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:order_id) { order.number }
+ let(:id) { 'non-existent' }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+ end
+end
diff --git a/api/spec/integration/spree/api/v3/store/orders_spec.rb b/api/spec/integration/spree/api/v3/store/orders_spec.rb
new file mode 100644
index 0000000000..39d1474585
--- /dev/null
+++ b/api/spec/integration/spree/api/v3/store/orders_spec.rb
@@ -0,0 +1,403 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Orders API', type: :request, swagger_doc: 'api-reference/store.yaml' do
+ include_context 'API v3 Store'
+
+ let(:user) { create(:user_with_addresses) }
+ let!(:order) { create(:order_with_line_items, store: store, user: user) }
+
+ path '/api/v3/store/orders' do
+ get 'List orders' do
+ tags 'Orders'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Returns a paginated list of orders for the authenticated customer'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: true
+ parameter name: :page, in: :query, type: :integer, required: false
+ parameter name: :per_page, in: :query, type: :integer, required: false
+ parameter name: 'q[state_eq]', in: :query, type: :string, required: false,
+ description: 'Filter by order state'
+ parameter name: 'q[completed_at_gte]', in: :query, type: :string, required: false,
+ description: 'Filter by completion date (after)'
+
+ response '200', 'orders found' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+
+ schema type: :object,
+ properties: {
+ data: { type: :array, items: { '$ref' => '#/components/schemas/StoreOrder' } },
+ meta: { '$ref' => '#/components/schemas/PaginationMeta' }
+ }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data']).to be_an(Array)
+ end
+ end
+
+ response '401', 'unauthorized - authentication required' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { '' }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+
+ post 'Create a cart' do
+ tags 'Orders'
+ produces 'application/json'
+ security [api_key: []]
+ description <<~DESC
+ Creates a new order (shopping cart). Can be created by guests or authenticated customers.
+ Returns an `order_token` that must be used for guest access to the order.
+ DESC
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: false,
+ description: 'Bearer JWT token (optional - for authenticated customers)'
+
+ response '201', 'cart created (guest)' do
+ let(:'x-spree-api-key') { api_key.token }
+
+ schema type: :object,
+ allOf: [
+ { '$ref' => '#/components/schemas/StoreOrder' },
+ {
+ type: :object,
+ properties: {
+ order_token: { type: :string, description: 'Token for guest access to this order' }
+ }
+ }
+ ]
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['number']).to be_present
+ expect(data['state']).to eq('cart')
+ expect(data['order_token']).to be_present
+ end
+ end
+
+ response '201', 'cart created (authenticated)' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+
+ schema type: :object,
+ allOf: [
+ { '$ref' => '#/components/schemas/StoreOrder' },
+ { type: :object, properties: { order_token: { type: :string } } }
+ ]
+
+ run_test!
+ end
+
+ response '401', 'unauthorized - invalid API key' do
+ let(:'x-spree-api-key') { 'invalid' }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+ end
+
+ path '/api/v3/store/orders/{id}' do
+ get 'Get an order' do
+ tags 'Orders'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Returns a single order by ID or number. Guests must provide order_token.'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: false
+ parameter name: :id, in: :path, type: :string, required: true,
+ description: 'Order ID (prefixed) or order number'
+ parameter name: :order_token, in: :query, type: :string, required: false,
+ description: 'Order token for guest access'
+ parameter name: :includes, in: :query, type: :string, required: false,
+ description: 'Include associations (line_items, shipments, payments)'
+
+ response '200', 'order found (authenticated)' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:id) { order.number }
+
+ schema '$ref' => '#/components/schemas/StoreOrder'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['number']).to eq(order.number)
+ end
+ end
+
+ response '200', 'order found (guest with token)' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:id) { order.number }
+ let(:order_token) { order.token }
+
+ schema '$ref' => '#/components/schemas/StoreOrder'
+
+ run_test!
+ end
+
+ response '404', 'order not found' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:id) { 'R999999999' }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+
+ response '403', 'forbidden - order belongs to another user' do
+ let(:other_user) { create(:user) }
+ let(:other_order) { create(:order, store: store, user: other_user) }
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:id) { other_order.number }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+
+ patch 'Update an order' do
+ tags 'Orders'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Updates order attributes like email, special instructions, or addresses'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: false
+ parameter name: :id, in: :path, type: :string, required: true
+ parameter name: :order_token, in: :query, type: :string, required: false
+ parameter name: :body, in: :body, schema: {
+ type: :object,
+ properties: {
+ order: {
+ type: :object,
+ properties: {
+ email: { type: :string, format: 'email' },
+ special_instructions: { type: :string },
+ bill_address_attributes: { '$ref' => '#/components/schemas/StoreAddress' },
+ ship_address_attributes: { '$ref' => '#/components/schemas/StoreAddress' }
+ }
+ }
+ }
+ }
+
+ response '200', 'order updated' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:id) { order.number }
+ let(:body) { { order: { special_instructions: 'Leave at door' } } }
+
+ schema '$ref' => '#/components/schemas/StoreOrder'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['special_instructions']).to eq('Leave at door')
+ end
+ end
+
+ response '403', 'cannot update completed order' do
+ let(:completed_order) { create(:completed_order_with_totals, store: store, user: user) }
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:id) { completed_order.number }
+ let(:body) { { order: { special_instructions: 'Test' } } }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+ end
+
+ path '/api/v3/store/orders/{id}/next' do
+ patch 'Advance to next checkout step' do
+ tags 'Orders'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Advances the order to the next state in the checkout flow'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: false
+ parameter name: :id, in: :path, type: :string, required: true
+ parameter name: :order_token, in: :query, type: :string, required: false
+
+ response '200', 'order advanced' do
+ let(:advanceable_order) { create(:order_with_line_items, store: store, user: user) }
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:id) { advanceable_order.number }
+
+ schema '$ref' => '#/components/schemas/StoreOrder'
+
+ run_test!
+ end
+
+ response '422', 'cannot advance - validation errors' do
+ let(:invalid_order) { create(:order, store: store, user: user, state: 'address', bill_address: nil, ship_address: nil) }
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:id) { invalid_order.number }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+ end
+
+ path '/api/v3/store/orders/{id}/advance' do
+ patch 'Advance through checkout' do
+ tags 'Orders'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Advances the order through all possible checkout states'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: false
+ parameter name: :id, in: :path, type: :string, required: true
+ parameter name: :order_token, in: :query, type: :string, required: false
+
+ response '200', 'order advanced' do
+ let(:advanceable_order) { create(:order_with_line_items, store: store, user: user) }
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:id) { advanceable_order.number }
+
+ schema '$ref' => '#/components/schemas/StoreOrder'
+
+ run_test!
+ end
+ end
+ end
+
+ path '/api/v3/store/orders/{id}/complete' do
+ patch 'Complete the order' do
+ tags 'Orders'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Completes the order (finalizes the purchase)'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: false
+ parameter name: :id, in: :path, type: :string, required: true
+ parameter name: :order_token, in: :query, type: :string, required: false
+
+ response '200', 'order completed' do
+ let(:completable_order) do
+ order = create(:order_with_line_items, store: store, user: user)
+ # Advance through checkout - order_with_line_items has addresses set
+ Spree.checkout_advance_service.call(order: order)
+ # Add payment to reach confirm state
+ payment_method = create(:check_payment_method, stores: [store])
+ create(:payment, order: order, amount: order.total, payment_method: payment_method, state: 'checkout')
+ order.reload
+ end
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:id) { completable_order.number }
+
+ schema '$ref' => '#/components/schemas/StoreOrder'
+
+ run_test!
+ end
+
+ response '422', 'cannot complete' do
+ let(:incomplete_order) { create(:order_with_line_items, store: store, user: user) }
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:id) { incomplete_order.number }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+ end
+
+ path '/api/v3/store/orders/{order_id}/store_credits' do
+ post 'Add store credit' do
+ tags 'Orders'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Applies store credit to the order'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: true
+ parameter name: :order_id, in: :path, type: :string, required: true
+ parameter name: :order_token, in: :query, type: :string, required: false
+ parameter name: :body, in: :body, schema: {
+ type: :object,
+ properties: {
+ amount: { type: :number, description: 'Amount to apply (optional - defaults to max available)' }
+ }
+ }
+
+ response '200', 'store credit applied' do
+ let(:store_credit_payment_method) { create(:store_credit_payment_method, stores: [store]) }
+ let(:store_credit) { create(:store_credit, user: user, store: store, amount: 50) }
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:order_id) { order.number }
+ let(:body) { { amount: 10 } }
+
+ before do
+ store_credit_payment_method
+ store_credit
+ end
+
+ schema '$ref' => '#/components/schemas/StoreOrder'
+
+ run_test!
+ end
+
+ response '422', 'no store credit available' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:order_id) { order.number }
+ let(:body) { {} }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+
+ delete 'Remove store credit' do
+ tags 'Orders'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Removes store credit from the order'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: true
+ parameter name: :order_id, in: :path, type: :string, required: true
+ parameter name: :order_token, in: :query, type: :string, required: false
+
+ response '200', 'store credit removed' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:order_id) { order.number }
+
+ schema '$ref' => '#/components/schemas/StoreOrder'
+
+ run_test!
+ end
+ end
+ end
+end
diff --git a/api/spec/integration/spree/api/v3/store/payment_methods_spec.rb b/api/spec/integration/spree/api/v3/store/payment_methods_spec.rb
new file mode 100644
index 0000000000..389ceaf875
--- /dev/null
+++ b/api/spec/integration/spree/api/v3/store/payment_methods_spec.rb
@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Payment Methods API', type: :request, swagger_doc: 'api-reference/store.yaml' do
+ include_context 'API v3 Store'
+
+ let(:user) { create(:user) }
+ let!(:order) { create(:order_with_line_items, store: store, user: user, state: 'payment') }
+ let!(:payment_method) { create(:credit_card_payment_method, stores: [store], display_on: 'both') }
+ let!(:backend_only_pm) { create(:credit_card_payment_method, stores: [store], display_on: 'back_end') }
+
+ path '/api/v3/store/orders/{order_id}/payment_methods' do
+ get 'List available payment methods' do
+ tags 'Payment Methods'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Returns payment methods available for the order based on store configuration and order state'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: false
+ parameter name: :order_id, in: :path, type: :string, required: true
+ parameter name: :order_token, in: :query, type: :string, required: false
+
+ response '200', 'payment methods found' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:order_id) { order.number }
+
+ schema type: :object,
+ properties: {
+ data: { type: :array, items: { '$ref' => '#/components/schemas/StorePaymentMethod' } },
+ meta: {
+ type: :object,
+ properties: {
+ count: { type: :integer }
+ }
+ }
+ }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ # Only frontend-visible payment methods should be returned
+ expect(data['data'].map { |pm| pm['id'] }).to include(payment_method.prefix_id)
+ expect(data['data'].map { |pm| pm['id'] }).not_to include(backend_only_pm.prefix_id)
+ end
+ end
+
+ response '404', 'order not found' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:order_id) { 'non-existent' }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+
+ response '401', 'unauthorized' do
+ let(:'x-spree-api-key') { 'invalid' }
+ let(:order_id) { order.number }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+ end
+end
diff --git a/api/spec/integration/spree/api/v3/store/payments_spec.rb b/api/spec/integration/spree/api/v3/store/payments_spec.rb
new file mode 100644
index 0000000000..cd528a64d8
--- /dev/null
+++ b/api/spec/integration/spree/api/v3/store/payments_spec.rb
@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Payments API', type: :request, swagger_doc: 'api-reference/store.yaml' do
+ include_context 'API v3 Store'
+
+ let(:user) { create(:user) }
+ let!(:order) { create(:order_with_line_items, store: store, user: user, state: 'payment') }
+ let!(:payment_method) { create(:credit_card_payment_method, stores: [store]) }
+ let!(:payment) { create(:payment, order: order, payment_method: payment_method) }
+
+ path '/api/v3/store/orders/{order_id}/payments' do
+ get 'List payments for an order' do
+ tags 'Payments'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Returns all payments associated with the order'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: false
+ parameter name: :order_id, in: :path, type: :string, required: true
+ parameter name: :order_token, in: :query, type: :string, required: false
+
+ response '200', 'payments found' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:order_id) { order.number }
+
+ schema type: :object,
+ properties: {
+ data: { type: :array, items: { '$ref' => '#/components/schemas/StorePayment' } }
+ },
+ required: ['data']
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data']).to be_an(Array)
+ end
+ end
+
+ response '404', 'order not found' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:order_id) { 'non-existent' }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+
+ post 'Create a payment' do
+ tags 'Payments'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Creates a new payment for the order using the specified payment method'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: false
+ parameter name: :order_id, in: :path, type: :string, required: true
+ parameter name: :order_token, in: :query, type: :string, required: false
+ parameter name: :body, in: :body, schema: {
+ type: :object,
+ properties: {
+ payment_method_id: { type: :string, description: 'Payment method ID' },
+ amount: { type: :number, description: 'Payment amount (optional, defaults to order total)' },
+ source_attributes: {
+ type: :object,
+ description: 'Payment source details (card info, etc.)',
+ properties: {
+ number: { type: :string },
+ month: { type: :string },
+ year: { type: :string },
+ verification_value: { type: :string },
+ name: { type: :string }
+ }
+ }
+ },
+ required: %w[payment_method_id]
+ }
+
+ response '201', 'payment created' do
+ let(:check_payment_method) { create(:check_payment_method, stores: [store]) }
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:order_id) { order.number }
+ let(:body) do
+ {
+ payment_method_id: check_payment_method.id.to_s
+ }
+ end
+
+ schema '$ref' => '#/components/schemas/StoreOrder'
+
+ run_test!
+ end
+
+ response '422', 'invalid payment method' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:order_id) { order.number }
+ let(:body) { { payment_method_id: 'invalid' } }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+ end
+
+ path '/api/v3/store/orders/{order_id}/payments/{id}' do
+ get 'Get a payment' do
+ tags 'Payments'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Returns details of a specific payment'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: false
+ parameter name: :order_id, in: :path, type: :string, required: true
+ parameter name: :id, in: :path, type: :string, required: true, description: 'Payment ID'
+ parameter name: :order_token, in: :query, type: :string, required: false
+
+ response '200', 'payment found' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:order_id) { order.number }
+ let(:id) { payment.prefix_id }
+
+ schema '$ref' => '#/components/schemas/StorePayment'
+
+ run_test!
+ end
+
+ response '404', 'payment not found' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:order_id) { order.number }
+ let(:id) { 'non-existent' }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+ end
+end
diff --git a/api/spec/integration/spree/api/v3/store/products_spec.rb b/api/spec/integration/spree/api/v3/store/products_spec.rb
new file mode 100644
index 0000000000..b865f21262
--- /dev/null
+++ b/api/spec/integration/spree/api/v3/store/products_spec.rb
@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Products API', type: :request, swagger_doc: 'api-reference/store.yaml' do
+ include_context 'API v3 Store'
+
+ let!(:product) { create(:product, stores: [store], status: 'active') }
+ let!(:product2) { create(:product, stores: [store], status: 'active') }
+ let!(:draft_product) { create(:product, stores: [store], status: 'draft') }
+ let!(:other_store) { create(:store) }
+ let!(:other_store_product) { create(:product, stores: [other_store]) }
+
+ path '/api/v3/store/products' do
+ get 'List products' do
+ tags 'Products'
+ produces 'application/json'
+ security [api_key: []]
+ description 'Returns a paginated list of active products for the current store'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true,
+ description: 'Publishable API key'
+ parameter name: :page, in: :query, type: :integer, required: false,
+ description: 'Page number (default: 1)'
+ parameter name: :per_page, in: :query, type: :integer, required: false,
+ description: 'Number of items per page (default: 25, max: 100)'
+ parameter name: 'q[name_cont]', in: :query, type: :string, required: false,
+ description: 'Filter by name containing string'
+ parameter name: 'q[taxons_id_eq]', in: :query, type: :string, required: false,
+ description: 'Filter by taxon ID'
+ parameter name: :includes, in: :query, type: :string, required: false,
+ description: 'Comma-separated associations to include (variants, images, taxons, option_types)'
+
+ response '200', 'products found' do
+ let(:'x-spree-api-key') { api_key.token }
+
+ schema type: :object,
+ properties: {
+ data: { type: :array, items: { '$ref' => '#/components/schemas/StoreProduct' } },
+ meta: { '$ref' => '#/components/schemas/PaginationMeta' }
+ },
+ required: %w[data meta]
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data'].size).to eq(2)
+ expect(data['meta']).to include('page', 'limit', 'count', 'pages')
+ end
+ end
+
+ response '401', 'unauthorized - invalid or missing API key' do
+ let(:'x-spree-api-key') { 'invalid' }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['error']['code']).to eq('invalid_token')
+ end
+ end
+ end
+ end
+
+ path '/api/v3/store/products/{id}' do
+ get 'Get a product' do
+ tags 'Products'
+ produces 'application/json'
+ security [api_key: []]
+ description 'Returns a single product by slug or prefix ID'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true,
+ description: 'Publishable API key'
+ parameter name: :id, in: :path, type: :string, required: true,
+ description: 'Product slug (e.g., ruby-on-rails-tote) or prefix ID (e.g., product_abc123)'
+ parameter name: :includes, in: :query, type: :string, required: false,
+ description: 'Comma-separated associations to include'
+
+ response '200', 'product found by slug' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:id) { product.slug }
+
+ schema '$ref' => '#/components/schemas/StoreProduct'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['id']).to eq(product.prefix_id)
+ expect(data['name']).to eq(product.name)
+ expect(data['slug']).to eq(product.slug)
+ end
+ end
+
+ response '200', 'product found by prefix ID' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:id) { product.prefix_id }
+
+ schema '$ref' => '#/components/schemas/StoreProduct'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['id']).to eq(product.prefix_id)
+ end
+ end
+
+ response '404', 'product not found' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:id) { 'nonexistent-product' }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['error']['code']).to eq('record_not_found')
+ end
+ end
+
+ response '404', 'product from another store' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:id) { other_store_product.slug }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+
+ response '404', 'draft product not visible' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:id) { draft_product.slug }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+
+ end
+ end
+end
diff --git a/api/spec/integration/spree/api/v3/store/shipments_spec.rb b/api/spec/integration/spree/api/v3/store/shipments_spec.rb
new file mode 100644
index 0000000000..41b7e742c9
--- /dev/null
+++ b/api/spec/integration/spree/api/v3/store/shipments_spec.rb
@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Shipments API', type: :request, swagger_doc: 'api-reference/store.yaml' do
+ include_context 'API v3 Store'
+
+ let!(:order) { create(:order_with_line_items, store: store, user: user, state: 'delivery') }
+ let!(:shipment) { order.shipments.first }
+
+ path '/api/v3/store/orders/{order_id}/shipments' do
+ get 'List shipments for an order' do
+ tags 'Shipments'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Returns all shipments associated with the order'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: false
+ parameter name: :order_id, in: :path, type: :string, required: true
+ parameter name: :token, in: :query, type: :string, required: false, description: 'Order token for guest access'
+
+ response '200', 'shipments found' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:order_id) { order.number }
+
+ schema type: :object,
+ properties: {
+ data: { type: :array, items: { '$ref' => '#/components/schemas/StoreShipment' } },
+ meta: { '$ref' => '#/components/schemas/PaginationMeta' }
+ }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data']).to be_an(Array)
+ expect(data['data'].size).to be >= 1
+ end
+ end
+
+ response '404', 'order not found' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:order_id) { 'R999999999' }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+ end
+
+ path '/api/v3/store/orders/{order_id}/shipments/{id}' do
+ get 'Get a shipment' do
+ tags 'Shipments'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Returns details of a specific shipment'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: false
+ parameter name: :order_id, in: :path, type: :string, required: true
+ parameter name: :id, in: :path, type: :string, required: true, description: 'Shipment ID'
+ parameter name: :token, in: :query, type: :string, required: false, description: 'Order token for guest access'
+ parameter name: :includes, in: :query, type: :string, required: false,
+ description: 'Include shipping_rates'
+
+ response '200', 'shipment found' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:order_id) { order.number }
+ let(:id) { shipment.prefix_id }
+ let(:token) { order.token }
+
+ schema '$ref' => '#/components/schemas/StoreShipment'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['number']).to eq(shipment.number)
+ end
+ end
+
+ response '404', 'shipment not found' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:order_id) { order.number }
+ let(:id) { 'shp_nonexistent' }
+ let(:token) { order.token }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+
+ patch 'Select shipping rate for shipment' do
+ tags 'Shipments'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Selects a shipping rate for the shipment'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: false
+ parameter name: :order_id, in: :path, type: :string, required: true
+ parameter name: :id, in: :path, type: :string, required: true, description: 'Shipment ID'
+ parameter name: :token, in: :query, type: :string, required: false, description: 'Order token for guest access'
+ parameter name: :body, in: :body, schema: {
+ type: :object,
+ properties: {
+ shipment: {
+ type: :object,
+ properties: {
+ selected_shipping_rate_id: { type: :string, description: 'Shipping rate ID to select' }
+ },
+ required: %w[selected_shipping_rate_id]
+ }
+ },
+ required: %w[shipment]
+ }
+
+ response '200', 'shipping rate selected' do
+ let(:shipping_rate) { shipment.shipping_rates.first }
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:order_id) { order.number }
+ let(:id) { shipment.prefix_id }
+ let(:token) { order.token }
+ let(:body) { { shipment: { selected_shipping_rate_id: shipping_rate.prefix_id } } }
+
+ schema '$ref' => '#/components/schemas/StoreShipment'
+
+ run_test!
+ end
+
+ response '404', 'shipping rate not found' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:order_id) { order.number }
+ let(:id) { shipment.prefix_id }
+ let(:token) { order.token }
+ let(:body) { { shipment: { selected_shipping_rate_id: 'shprt_invalid' } } }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+ end
+end
diff --git a/api/spec/integration/spree/api/v3/store/stores_spec.rb b/api/spec/integration/spree/api/v3/store/stores_spec.rb
new file mode 100644
index 0000000000..ed045318fd
--- /dev/null
+++ b/api/spec/integration/spree/api/v3/store/stores_spec.rb
@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Store API', type: :request, swagger_doc: 'api-reference/store.yaml' do
+ include_context 'API v3 Store'
+
+ path '/api/v3/store/store' do
+ get 'Get current store' do
+ tags 'Store'
+ produces 'application/json'
+ security [api_key: []]
+ description 'Returns information about the current store based on the API key'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+
+ response '200', 'store found' do
+ let(:'x-spree-api-key') { api_key.token }
+
+ schema '$ref' => '#/components/schemas/StoreStore'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['id']).to be_present
+ expect(data['name']).to eq(store.name)
+ expect(data['url']).to eq(store.url)
+ expect(data['default_currency']).to eq(store.default_currency)
+ end
+ end
+
+ response '401', 'unauthorized - invalid API key' do
+ let(:'x-spree-api-key') { 'invalid_key' }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['error']['code']).to eq('invalid_token')
+ end
+ end
+
+ response '401', 'unauthorized - missing API key' do
+ let(:'x-spree-api-key') { '' }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+ end
+end
diff --git a/api/spec/integration/spree/api/v3/store/taxonomies_spec.rb b/api/spec/integration/spree/api/v3/store/taxonomies_spec.rb
new file mode 100644
index 0000000000..9843a617e3
--- /dev/null
+++ b/api/spec/integration/spree/api/v3/store/taxonomies_spec.rb
@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Taxonomies API', type: :request, swagger_doc: 'api-reference/store.yaml' do
+ include_context 'API v3 Store'
+
+ let!(:taxonomy) { create(:taxonomy, store: store) }
+ let!(:taxonomy2) { create(:taxonomy, store: store) }
+ let!(:other_store) { create(:store) }
+ let!(:other_taxonomy) { create(:taxonomy, store: other_store) }
+
+ path '/api/v3/store/taxonomies' do
+ get 'List taxonomies' do
+ tags 'Taxonomies'
+ produces 'application/json'
+ security [api_key: []]
+ description 'Returns a list of taxonomies (category hierarchies) for the current store'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :page, in: :query, type: :integer, required: false
+ parameter name: :per_page, in: :query, type: :integer, required: false
+ parameter name: :includes, in: :query, type: :string, required: false,
+ description: 'Include root taxon'
+
+ response '200', 'taxonomies found' do
+ let(:'x-spree-api-key') { api_key.token }
+
+ schema type: :object,
+ properties: {
+ data: { type: :array, items: { '$ref' => '#/components/schemas/StoreTaxonomy' } },
+ meta: { '$ref' => '#/components/schemas/PaginationMeta' }
+ }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data'].size).to be >= 2
+ end
+ end
+
+ response '401', 'unauthorized' do
+ let(:'x-spree-api-key') { 'invalid' }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+ end
+
+ path '/api/v3/store/taxonomies/{id}' do
+ get 'Get a taxonomy' do
+ tags 'Taxonomies'
+ produces 'application/json'
+ security [api_key: []]
+ description 'Returns a single taxonomy with its taxon tree'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :id, in: :path, type: :string, required: true,
+ description: 'Taxonomy ID (prefixed)'
+ parameter name: :includes, in: :query, type: :string, required: false,
+ description: 'Include taxons'
+
+ response '200', 'taxonomy found' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:id) { taxonomy.prefix_id }
+
+ schema '$ref' => '#/components/schemas/StoreTaxonomy'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['name']).to eq(taxonomy.name)
+ end
+ end
+
+ response '404', 'taxonomy not found' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:id) { 'tax_nonexistent' }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+
+ response '404', 'taxonomy from other store' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:id) { other_taxonomy.prefix_id }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+ end
+end
diff --git a/api/spec/integration/spree/api/v3/store/taxons_spec.rb b/api/spec/integration/spree/api/v3/store/taxons_spec.rb
new file mode 100644
index 0000000000..27ed8f324d
--- /dev/null
+++ b/api/spec/integration/spree/api/v3/store/taxons_spec.rb
@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Taxons API', type: :request, swagger_doc: 'api-reference/store.yaml' do
+ include_context 'API v3 Store'
+
+ let!(:taxonomy) { create(:taxonomy, store: store) }
+ let!(:root_taxon) { taxonomy.root }
+ let!(:taxon) { create(:taxon, taxonomy: taxonomy, parent: root_taxon) }
+ let!(:child_taxon) { create(:taxon, taxonomy: taxonomy, parent: taxon) }
+ let!(:other_store) { create(:store) }
+ let!(:other_taxonomy) { create(:taxonomy, store: other_store) }
+ let!(:other_taxon) { create(:taxon, taxonomy: other_taxonomy) }
+
+ path '/api/v3/store/taxons/{id}' do
+ get 'Get a taxon' do
+ tags 'Taxons'
+ produces 'application/json'
+ security [api_key: []]
+ description 'Returns a single taxon by permalink or prefix ID'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :id, in: :path, type: :string, required: true,
+ description: 'Taxon permalink (e.g., categories/clothing/shirts) or prefix ID (e.g., taxon_abc123)'
+ parameter name: :includes, in: :query, type: :string, required: false,
+ description: 'Include associations (children, products, parent)'
+
+ response '200', 'taxon found by permalink' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:id) { taxon.permalink }
+
+ schema '$ref' => '#/components/schemas/StoreTaxon'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['name']).to eq(taxon.name)
+ end
+ end
+
+ response '200', 'taxon found by prefix ID' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:id) { taxon.prefix_id }
+
+ schema '$ref' => '#/components/schemas/StoreTaxon'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['name']).to eq(taxon.name)
+ end
+ end
+
+ response '404', 'taxon not found' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:id) { 'non-existent-permalink' }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+
+ response '404', 'taxon from other store not accessible' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:id) { other_taxon.permalink }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+
+ response '401', 'unauthorized' do
+ let(:'x-spree-api-key') { 'invalid' }
+ let(:id) { taxon.permalink }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+ end
+end
diff --git a/api/spec/integration/spree/api/v3/store/wishlists_spec.rb b/api/spec/integration/spree/api/v3/store/wishlists_spec.rb
new file mode 100644
index 0000000000..0dc1fd4628
--- /dev/null
+++ b/api/spec/integration/spree/api/v3/store/wishlists_spec.rb
@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Wishlists API', type: :request, swagger_doc: 'api-reference/store.yaml' do
+ include_context 'API v3 Store'
+
+ let!(:wishlist) { create(:wishlist, user: user, store: store, name: 'My Wishlist') }
+ let!(:product) { create(:product, stores: [store]) }
+ let!(:variant) { product.master }
+ let!(:wished_item) { create(:wished_item, wishlist: wishlist, variant: variant) }
+
+ path '/api/v3/store/wishlists' do
+ get 'List wishlists' do
+ tags 'Wishlists'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Returns all wishlists for the authenticated customer'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: true
+ parameter name: :page, in: :query, type: :integer, required: false
+ parameter name: :per_page, in: :query, type: :integer, required: false
+
+ response '200', 'wishlists found' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+
+ schema type: :object,
+ properties: {
+ data: { type: :array, items: { '$ref' => '#/components/schemas/StoreWishlist' } },
+ meta: { '$ref' => '#/components/schemas/PaginationMeta' }
+ }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data'].size).to be >= 1
+ end
+ end
+
+ response '401', 'unauthorized' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { '' }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+
+ post 'Create a wishlist' do
+ tags 'Wishlists'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Creates a new wishlist for the customer'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: true
+ parameter name: :body, in: :body, schema: {
+ type: :object,
+ properties: {
+ wishlist: {
+ type: :object,
+ properties: {
+ name: { type: :string },
+ is_private: { type: :boolean },
+ is_default: { type: :boolean }
+ },
+ required: %w[name]
+ }
+ }
+ }
+
+ response '201', 'wishlist created' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:body) { { wishlist: { name: 'Birthday Ideas', is_private: true } } }
+
+ schema '$ref' => '#/components/schemas/StoreWishlist'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['name']).to eq('Birthday Ideas')
+ expect(data['is_private']).to be true
+ end
+ end
+
+ response '422', 'validation error' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:body) { { wishlist: { name: '' } } }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+ end
+
+ path '/api/v3/store/wishlists/{id}' do
+ get 'Get a wishlist' do
+ tags 'Wishlists'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: true
+ parameter name: :id, in: :path, type: :string, required: true
+ parameter name: :includes, in: :query, type: :string, required: false,
+ description: 'Include wished_items'
+
+ response '200', 'wishlist found' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:id) { wishlist.prefix_id }
+
+ schema '$ref' => '#/components/schemas/StoreWishlist'
+
+ run_test!
+ end
+
+ response '404', 'wishlist not found' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:id) { 'non-existent' }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+
+ patch 'Update a wishlist' do
+ tags 'Wishlists'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: true
+ parameter name: :id, in: :path, type: :string, required: true
+ parameter name: :body, in: :body, schema: {
+ type: :object,
+ properties: {
+ wishlist: {
+ type: :object,
+ properties: {
+ name: { type: :string },
+ is_private: { type: :boolean },
+ is_default: { type: :boolean }
+ }
+ }
+ }
+ }
+
+ response '200', 'wishlist updated' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:id) { wishlist.prefix_id }
+ let(:body) { { wishlist: { name: 'Updated Name' } } }
+
+ schema '$ref' => '#/components/schemas/StoreWishlist'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['name']).to eq('Updated Name')
+ end
+ end
+ end
+
+ delete 'Delete a wishlist' do
+ tags 'Wishlists'
+ security [api_key: [], bearer_auth: []]
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: true
+ parameter name: :id, in: :path, type: :string, required: true
+
+ response '204', 'wishlist deleted' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:id) { wishlist.prefix_id }
+
+ run_test!
+ end
+ end
+ end
+
+ path '/api/v3/store/wishlists/{wishlist_id}/items' do
+ post 'Add item to wishlist' do
+ tags 'Wishlists'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Adds a variant to the wishlist'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: true
+ parameter name: :wishlist_id, in: :path, type: :string, required: true
+ parameter name: :body, in: :body, schema: {
+ type: :object,
+ properties: {
+ variant_id: { type: :string },
+ quantity: { type: :integer }
+ },
+ required: %w[variant_id]
+ }
+
+ response '201', 'item added' do
+ let(:new_product) { create(:product, stores: [store]) }
+ let(:new_variant) { new_product.master }
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:wishlist_id) { wishlist.prefix_id }
+ let(:body) { { wished_item: { variant_id: new_variant.id.to_s, quantity: 1 } } }
+
+ schema '$ref' => '#/components/schemas/StoreWishedItem'
+
+ run_test!
+ end
+ end
+ end
+
+ path '/api/v3/store/wishlists/{wishlist_id}/items/{id}' do
+ delete 'Remove item from wishlist' do
+ tags 'Wishlists'
+ security [api_key: [], bearer_auth: []]
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: true
+ parameter name: :wishlist_id, in: :path, type: :string, required: true
+ parameter name: :id, in: :path, type: :string, required: true
+
+ response '204', 'item removed' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:wishlist_id) { wishlist.prefix_id }
+ let(:id) { wished_item.prefix_id }
+
+ run_test!
+ end
+
+ response '404', 'item not found' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:wishlist_id) { wishlist.prefix_id }
+ let(:id) { 'non-existent' }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+ end
+end
diff --git a/core/app/models/spree/store_credit.rb b/core/app/models/spree/store_credit.rb
index 5febf9a411..5034d42cc7 100644
--- a/core/app/models/spree/store_credit.rb
+++ b/core/app/models/spree/store_credit.rb
@@ -1,6 +1,6 @@
module Spree
class StoreCredit < Spree.base_class
- has_prefix_id :scred
+ has_prefix_id :credit
include Spree::SingleStoreResource
include Spree::Metafields
diff --git a/core/app/models/spree/variant.rb b/core/app/models/spree/variant.rb
index 99f8c6fa3f..0d9a3d0438 100644
--- a/core/app/models/spree/variant.rb
+++ b/core/app/models/spree/variant.rb
@@ -1,6 +1,6 @@
module Spree
class Variant < Spree.base_class
- has_prefix_id :var # Spree-specific: variant
+ has_prefix_id :variant
acts_as_paranoid
acts_as_list scope: :product
diff --git a/sdk/src/types/generated/AdminOrder.ts b/sdk/src/types/generated/AdminOrder.ts
index 6902872228..b385f6121c 100644
--- a/sdk/src/types/generated/AdminOrder.ts
+++ b/sdk/src/types/generated/AdminOrder.ts
@@ -1,7 +1,7 @@
-// Typelizer digest f30445d0211bc3258c9241884f88b62b
+// Typelizer digest 5adb22dbb6a386d73a6b7b9e0c26ab65
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
-import type {StoreOrderPromotion, StoreLineItem, StoreShipment, StorePayment, StoreAddress, StorePaymentMethod, AdminUser} from '@/types'
+import type {StorePaymentMethod, StoreOrderPromotion, StoreLineItem, StoreShipment, StorePayment, StoreAddress, AdminUser} from '@/types'
type AdminOrder = {
id: string;
@@ -14,21 +14,21 @@ type AdminOrder = {
item_count: number;
shipment_state: string | null;
payment_state: string | null;
- item_total: number;
+ item_total: string;
display_item_total: string;
- ship_total: number;
+ ship_total: string;
display_ship_total: string;
- adjustment_total: number;
+ adjustment_total: string;
display_adjustment_total: string;
- promo_total: number;
+ promo_total: string;
display_promo_total: string;
- tax_total: number;
+ tax_total: string;
display_tax_total: string;
- included_tax_total: number;
+ included_tax_total: string;
display_included_tax_total: string;
- additional_tax_total: number;
+ additional_tax_total: string;
display_additional_tax_total: string;
- total: number;
+ total: string;
display_total: string;
completed_at: string | null;
created_at: string;
@@ -51,8 +51,6 @@ type AdminOrder = {
approved_at: string | null;
canceler_id: string | null;
created_by_id: string | null;
- public_metadata: Record<string, unknown> | null;
- private_metadata: Record<string, unknown> | null;
user?: AdminUser;
}
diff --git a/sdk/src/types/generated/StoreAddress.ts b/sdk/src/types/generated/StoreAddress.ts
index cbee65965d..e7959b9f71 100644
--- a/sdk/src/types/generated/StoreAddress.ts
+++ b/sdk/src/types/generated/StoreAddress.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 0e22a1587ad253d9ece62f2afd4bd161
+// Typelizer digest 5625baecb7d36641a0990de91c3c03c7
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
@@ -13,11 +13,10 @@ type StoreAddress = {
zipcode: string | null;
phone: string | null;
company: string | null;
- state_id: string | null;
state_text: string | null;
- country_id: string;
- country_iso: string;
country_name: string;
+ country_iso: string;
+ state_code: string | null;
}
export default StoreAddress;
diff --git a/sdk/src/types/generated/StoreLineItem.ts b/sdk/src/types/generated/StoreLineItem.ts
index dd56eb5c67..0712fc8708 100644
--- a/sdk/src/types/generated/StoreLineItem.ts
+++ b/sdk/src/types/generated/StoreLineItem.ts
@@ -1,4 +1,4 @@
-// Typelizer digest b3608247c683989cf434e620b17b4894
+// Typelizer digest 163ec6334fcadbf4bd409c5bb099ea39
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {StoreImage, StoreOptionValue} from '@/types'
@@ -10,26 +10,26 @@ type StoreLineItem = {
name: string;
slug: string;
options_text: string;
- price: number;
+ price: string;
display_price: string;
- total: number;
+ total: string;
display_total: string;
- adjustment_total: number;
+ adjustment_total: string;
display_adjustment_total: string;
- additional_tax_total: number;
+ additional_tax_total: string;
display_additional_tax_total: string;
- included_tax_total: number;
+ included_tax_total: string;
display_included_tax_total: string;
- promo_total: number;
+ promo_total: string;
display_promo_total: string;
- pre_tax_amount: number;
+ pre_tax_amount: string;
display_pre_tax_amount: string;
- discounted_amount: number;
+ discounted_amount: string;
display_discounted_amount: string;
- compare_at_amount: number | null;
display_compare_at_amount: string | null;
created_at: string;
updated_at: string;
+ compare_at_amount: string | null;
images: Array<StoreImage>;
option_values: Array<StoreOptionValue>;
}
diff --git a/sdk/src/types/generated/StoreOrder.ts b/sdk/src/types/generated/StoreOrder.ts
index 38af0732a6..6476b21f4c 100644
--- a/sdk/src/types/generated/StoreOrder.ts
+++ b/sdk/src/types/generated/StoreOrder.ts
@@ -1,7 +1,7 @@
-// Typelizer digest 793fa9bb41e04b63e300247ac068d0b1
+// Typelizer digest b5cc88020fb4fc8480c30b8d21a49740
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
-import type {StoreOrderPromotion, StoreLineItem, StoreShipment, StorePayment, StoreAddress, StorePaymentMethod} from '@/types'
+import type {StorePaymentMethod, StoreOrderPromotion, StoreLineItem, StoreShipment, StorePayment, StoreAddress} from '@/types'
type StoreOrder = {
id: string;
@@ -14,21 +14,21 @@ type StoreOrder = {
item_count: number;
shipment_state: string | null;
payment_state: string | null;
- item_total: number;
+ item_total: string;
display_item_total: string;
- ship_total: number;
+ ship_total: string;
display_ship_total: string;
- adjustment_total: number;
+ adjustment_total: string;
display_adjustment_total: string;
- promo_total: number;
+ promo_total: string;
display_promo_total: string;
- tax_total: number;
+ tax_total: string;
display_tax_total: string;
- included_tax_total: number;
+ included_tax_total: string;
display_included_tax_total: string;
- additional_tax_total: number;
+ additional_tax_total: string;
display_additional_tax_total: string;
- total: number;
+ total: string;
display_total: string;
completed_at: string | null;
created_at: string;
diff --git a/sdk/src/types/generated/StoreOrderPromotion.ts b/sdk/src/types/generated/StoreOrderPromotion.ts
index c8dc72b15b..f303400681 100644
--- a/sdk/src/types/generated/StoreOrderPromotion.ts
+++ b/sdk/src/types/generated/StoreOrderPromotion.ts
@@ -1,4 +1,4 @@
-// Typelizer digest a208eaf1ac4c16e670c392c3dae4e68c
+// Typelizer digest 1e351da4ee55f780f2826b9fade335f3
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
@@ -8,7 +8,7 @@ type StoreOrderPromotion = {
name: string;
description: string | null;
code: string | null;
- amount: number;
+ amount: string;
display_amount: string;
}
diff --git a/sdk/src/types/generated/StorePayment.ts b/sdk/src/types/generated/StorePayment.ts
index 4d457881c7..2389def05d 100644
--- a/sdk/src/types/generated/StorePayment.ts
+++ b/sdk/src/types/generated/StorePayment.ts
@@ -1,4 +1,4 @@
-// Typelizer digest a3bd4e8ed4dd75213fb847f02138979e
+// Typelizer digest 7a21e92c1fb7baff425d01d268049be6
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {StorePaymentMethod} from '@/types'
@@ -9,7 +9,7 @@ type StorePayment = {
state: string;
response_code: string | null;
number: string;
- amount: number;
+ amount: string;
display_amount: string;
created_at: string;
updated_at: string;
diff --git a/sdk/src/types/generated/StoreShipment.ts b/sdk/src/types/generated/StoreShipment.ts
index c21b195446..9d336862db 100644
--- a/sdk/src/types/generated/StoreShipment.ts
+++ b/sdk/src/types/generated/StoreShipment.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 4963e975ebaaec9528495f04ea8970e3
+// Typelizer digest 805228a71c20601252d565283b9db525
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {StoreShippingMethod, StoreStockLocation, StoreShippingRate} from '@/types'
@@ -9,19 +9,9 @@ type StoreShipment = {
state: string;
tracking: string | null;
tracking_url: string | null;
- shipped_at: string | null;
- cost: number;
+ cost: string;
display_cost: string;
- adjustment_total: number;
- display_adjustment_total: string;
- additional_tax_total: number;
- display_additional_tax_total: string;
- promo_total: number;
- display_promo_total: string;
- included_tax_total: number;
- display_included_tax_total: string;
- total: number;
- display_total: string;
+ shipped_at: string | null;
created_at: string;
updated_at: string;
shipping_method: StoreShippingMethod;
diff --git a/sdk/src/types/generated/StoreTaxon.ts b/sdk/src/types/generated/StoreTaxon.ts
index ad664fe131..27282fdd5c 100644
--- a/sdk/src/types/generated/StoreTaxon.ts
+++ b/sdk/src/types/generated/StoreTaxon.ts
@@ -1,4 +1,4 @@
-// Typelizer digest ebb971f33eb14e681530040edf3d3b00
+// Typelizer digest 42131c861f718a660df479516981f135
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
@@ -13,11 +13,11 @@ type StoreTaxon = {
meta_title: string | null;
meta_description: string | null;
meta_keywords: string | null;
- parent_id: string | null;
- taxonomy_id: string;
children_count: number;
created_at: string;
updated_at: string;
+ parent_id: string | null;
+ taxonomy_id: string;
description: string;
description_html: string;
image_url: string | null;