spree_api 6.0.0.rc1 → 6.0.0.rc3

data/app/controllers/spree/api/v3/seller/auth_controller.rb

@@ -35,6 +35,14 @@ module Spree
           skip_before_action :set_current_seller_context, only: [:create, :refresh, :logout, :providers]
           skip_before_action :authenticate_seller!, only: [:create, :refresh, :logout, :providers]
 
+          request_params 'LoginParams' do |body|
+            body.attribute :provider, :string,
+              choices: %w[email],
+              description: 'The authentication method. Defaults to `email`.'
+            body.attribute :email, :string, required: true, example: 'seller@example.com'
+            body.attribute :password, :string, required: true, example: 'password123'
+          end
+
           # POST /api/v3/seller/auth/login
           def create
             strategy = authentication_strategy

data/app/controllers/spree/api/v3/seller/base_controller.rb

@@ -18,6 +18,7 @@ module Spree
           before_action :authenticate_seller!
 
           include Spree::Api::V3::ScopedAuthorization
+          include Spree::Api::V3::StrictMoneyParams
         end
       end
     end

data/app/controllers/spree/api/v3/seller/countries_controller.rb

@@ -16,7 +16,7 @@ module Spree
           # Unpaginated: there are ~250 countries and an address dropdown needs
           # them all at once, which Pagy's global client_limit would prevent.
           def index
-            countries = Spree::Country.all.sort_by(&:name)
+            countries = Spree::Country.all.sort_by(&:iso)
 
             render json: {
               data: countries.map { |country| serialize_country(country) },
@@ -27,7 +27,7 @@ module Spree
           private
 
           def serialize_country(country)
-            Spree.api.country_serializer.new(
+            Spree.api.seller_country_serializer.new(
               country, params: { store: current_store, expand: ['states'] }
             ).to_h
           end

data/app/controllers/spree/api/v3/seller/delivery_methods_controller.rb

@@ -19,6 +19,42 @@ module Spree
         class DeliveryMethodsController < Seller::ResourceController
           scoped_resource :delivery_methods
 
+          # No provider fields: both are fixed for a seller's method, and
+          # permitting them would let a write fail validation for a choice the
+          # seller was never offered. No markup either — that prices a
+          # carrier's quote, and a seller has no carrier.
+          request_params :delivery_method do |body|
+            body.attribute :name, :string, required: true, on: :create
+            body.attribute :admin_name, :string, nullable: true
+            body.attribute :code, :string, nullable: true
+            body.attribute :delivery_profile_id, :id, description: "One of the marketplace's delivery profiles."
+            body.attribute :delivery_zone_id, :id,
+              nullable: true,
+              description: 'Narrows where the method ships; null serves everywhere the profile reaches.'
+            body.attribute :storefront_visible, :boolean
+            body.attribute :tracking_url, :string, nullable: true
+            body.attribute :estimated_transit_business_days_min, :integer, nullable: true
+            body.attribute :estimated_transit_business_days_max, :integer, nullable: true
+            body.attribute :calculator, :object,
+              description: "How the method is priced: a type from `/delivery_methods/calculators` and its preferences, per that type's `schema`." do |calculator|
+              calculator.attribute :type, :string, example: 'flat_rate'
+              calculator.attribute :preferences, :hash, example: { amount: '12.5' }
+            end
+            # Permitted in `permitted_params`, together with the attributes
+            # the seller's rule kinds declare on their own classes.
+            body.attribute :rules, :array,
+              permit: false,
+              as: 'DeliveryMethodRuleParams',
+              description: 'Replaces the whole set: a rule dropped here is deleted, so re-send surviving rules with their `id`. An empty list clears every condition.' do |rule|
+              rule.attribute :id, :id
+              rule.attribute :type, :string,
+                required: true,
+                description: 'A type from `/delivery_methods/rule_types`.'
+              rule.attribute :active, :boolean
+              rule.attribute :preferences, :hash
+            end
+          end
+
           # GET /api/v3/seller/delivery_methods/calculators
           # The ways a seller can price a method, with the preference schema
           # each one's form is rendered from.
@@ -29,7 +65,7 @@ module Spree
               {
                 type: calculator_class.api_type,
                 name: calculator_class.description,
-                preference_schema: calculator_class.respond_to?(:serialized_preference_schema) ? calculator_class.serialized_preference_schema : []
+                schema: calculator_class.preference_json_schema
               }
             end
 
@@ -48,7 +84,7 @@ module Spree
                 type: klass.api_type,
                 name: klass.human_name,
                 description: klass.human_description,
-                preference_schema: klass.serialized_preference_schema
+                schema: klass.preference_json_schema
               }
             end
 
@@ -64,9 +100,9 @@ module Spree
             @resource.assign_attributes(assignable_params)
             authorize_resource!(@resource, :create)
             rederive_origin_group(@resource)
-            assign_calculator(@resource)
+            @resource.assign_calculator_attributes(permitted_params[:calculator])
 
-            if @resource.errors.empty? && @resource.save
+            if @resource.save
               render json: serialize_resource(@resource), status: :created
             else
               render_validation_error(@resource.errors)
@@ -74,11 +110,13 @@ module Spree
           end
 
           def update
-            @resource.assign_attributes(assignable_params)
-            rederive_origin_group(@resource)
-            assign_calculator(@resource)
+            saved = save_atomically do
+              @resource.assign_attributes(assignable_params)
+              rederive_origin_group(@resource)
+              @resource.assign_calculator_attributes(permitted_params[:calculator])
+            end
 
-            if @resource.errors.empty? && @resource.save
+            if saved
               render json: serialize_resource(@resource)
             else
               render_validation_error(@resource.errors)
@@ -116,19 +154,10 @@ module Spree
             action_name == 'show' ? super : resource_scope.find_by_prefix_id!(params[:id])
           end
 
-          # No provider fields: both are fixed for a seller's method, and
-          # permitting them would let a write fail validation for a choice the
-          # seller was never offered. No markup either — that prices a
-          # carrier's quote, and a seller has no carrier.
           def permitted_params
             params.permit(
-              *model_additional_permitted_attributes,
-              :name, :admin_name, :code, :storefront_visible, :tracking_url,
-              :estimated_transit_business_days_min, :estimated_transit_business_days_max,
-              :calculator_type,
-              :delivery_profile_id, :delivery_zone_id,
-              calculator_preferences: {},
-              rules: [:id, :type, :active, { preferences: {} }, *subclassed_rule_attributes]
+              *permitted_attributes,
+              rules: [*request_params_schema.fields[:rules].schema.permit_list, *subclassed_rule_attributes]
             )
           end
 
@@ -175,7 +204,7 @@ module Spree
           # resolves its own pickers.
           def assignable_params
             attributes = permitted_params.except(
-              :delivery_profile_id, :delivery_zone_id, :calculator_type, :calculator_preferences, :rules
+              :delivery_profile_id, :delivery_zone_id, :calculator, :rules
             )
 
             if params.key?(:delivery_profile_id)
@@ -218,46 +247,6 @@ module Spree
               row
             end
           end
-
-          def assign_calculator(delivery_method)
-            calculator_type = permitted_params[:calculator_type]
-            preferences = permitted_params[:calculator_preferences]
-
-            if calculator_type.present? && delivery_method.calculator&.class&.api_type != calculator_type
-              registered = Spree::DeliveryMethod.calculators.find do |klass|
-                klass.api_type == calculator_type
-              end
-              unless registered
-                delivery_method.errors.add(:calculator_type, :invalid)
-                return
-              end
-
-              # Resolved from the registry entry's OWN name, never the
-              # request's: nothing user-supplied reaches `constantize`. Going
-              # back through the name rather than instantiating `registered`
-              # directly is what survives a reload — in development the
-              # registry holds a class from an earlier one, and an instance of
-              # it fails the association's type check.
-              delivery_method.calculator = registered.to_s.constantize.new
-            end
-
-            return if preferences.blank?
-
-            # A payload may carry preferences without naming a calculator —
-            # editing the amount on a method that already has one, or creating
-            # with the default. The model only builds the default calculator
-            # at validation, so without this the preferences land on nothing
-            # and the amount the merchant typed is silently replaced by a free
-            # rate.
-            delivery_method.ensure_calculator
-            return if delivery_method.calculator.nil?
-
-            preferences.each do |key, value|
-              next unless delivery_method.calculator.has_preference?(key)
-
-              delivery_method.calculator.set_preference(key, value)
-            end
-          end
         end
       end
     end

data/app/controllers/spree/api/v3/seller/exports_controller.rb

@@ -25,6 +25,23 @@ module Spree
 
           scoped_resource :exports
 
+          request_params 'SellerExportCreateParams' do |body|
+            body.attribute :type, :string,
+              required: true,
+              choices: ALLOWED_TYPES,
+              description: 'Which dataset to export.'
+            body.attribute :record_selection, :string,
+              choices: %w[filtered all],
+              description: '`filtered` (default) keeps `search_params`; `all` exports everything this seller owns.'
+            # Read from the raw params: an arbitrary Ransack hash with nested
+            # groupings, which `permit(k: {})` rejects.
+            body.attribute :search_params, :hash,
+              permit: false,
+              description: 'Ransack predicates, the same shape the list endpoints take. Ignored when `record_selection` is `all`.'
+            body.attribute :results_url, :string,
+              description: "Panel URL the export-done email links back to. Honored only when it matches one of the store's allowed origins."
+          end
+
           # POST /api/v3/seller/exports
           #
           # Refused before the record is built when the type is not one a
@@ -140,7 +157,7 @@ module Spree
           # `to_unsafe_h`. `:format` is deliberately dropped: only CSV exists,
           # and Rails' request format would otherwise overwrite the enum.
           def permitted_params
-            attrs = params.permit(*model_additional_permitted_attributes, :type, :record_selection, :results_url)
+            attrs = params.permit(*permitted_attributes)
             raw = params[:search_params]
             attrs[:search_params] = raw.respond_to?(:to_unsafe_h) ? raw.to_unsafe_h : raw if raw.present?
             attrs

data/app/controllers/spree/api/v3/seller/files_controller.rb

@@ -0,0 +1,27 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # A file stored here is attached to nothing until the seller sends its
+        # `signed_id` to an endpoint that checks the target is theirs, so the
+        # narrowest meaningful gate is the seller's own profile, which every
+        # member of a seller's team holds.
+        class FilesController < Seller::BaseController
+          include Spree::Api::V3::FileUploads
+
+          scoped_resource :seller_profile
+
+          request_params 'FileUploadCreateParams', action: :create do |body|
+            body.include_attributes Spree::Api::V3::FileUploadRequestSchema
+          end
+
+          private
+
+          def file_upload_serializer
+            Spree.api.seller_file_upload_serializer
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/seller/imports_controller.rb

@@ -32,10 +32,32 @@ module Spree
 
           scoped_resource :products
 
+          request_params 'ImportCreateParams' do |body|
+            body.attribute :type, :string, required: true, choices: %w[products]
+            body.attribute :attachment_signed_id, :string,
+              required: true,
+              description: "The `signed_id` of the uploaded CSV, from `POST /files` with `visibility: 'private'`."
+            body.attribute :delimiter, :string, description: 'CSV column separator. Defaults to a comma.'
+            body.attribute :results_url, :string,
+              description: "Absolute URL of the panel's imports view; the import-done email links back to it. Honored only when it matches one of the store's allowed origins."
+          end
+
+          request_params 'ImportCompleteMappingParams', action: :complete_mapping do |body|
+            body.attribute :mappings, :array,
+              permit: false,
+              description: 'Column assignments to apply before processing starts.' do |mapping|
+              mapping.attribute :schema_field, :string, required: true, description: 'Canonical schema field name.'
+              mapping.attribute :file_column, :string,
+                required: true,
+                nullable: true,
+                description: 'CSV header to read the field from; `null` unmaps the field.'
+            end
+          end
+
           # POST /api/v3/seller/imports
           #
-          # `attachment` is an ActiveStorage signed blob id from
-          # POST /api/v3/seller/direct_uploads. On success the import is
+          # `attachment_signed_id` is a signed id from
+          # POST /api/v3/seller/files. On success the import is
           # already in `mapping`, carrying the auto-assigned columns.
           def create
             @resource = build_resource
@@ -59,12 +81,6 @@ module Spree
             else
               render_errors(@resource.errors)
             end
-          rescue ActiveSupport::MessageVerifier::InvalidSignature
-            render_error(
-              code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:validation_error],
-              message: 'Invalid attachment signed id',
-              status: :unprocessable_content
-            )
           end
 
           # PATCH /api/v3/seller/imports/:id/complete_mapping
@@ -248,7 +264,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(*model_additional_permitted_attributes, :type, :attachment, :preferred_delimiter, :results_url)
+            params.permit(*permitted_attributes)
           end
 
           # The registered Import subclass matching `name`, or nil.

data/app/controllers/spree/api/v3/seller/invitation_acceptances_controller.rb

@@ -22,6 +22,14 @@ module Spree
                      only: [:lookup, :accept],
                      with: -> { render_rate_limited(limit: Spree::Api::Config[:rate_limit_login]) }
 
+          request_params 'InvitationAcceptParams', action: :accept do |body|
+            body.attribute :password, :string,
+              description: 'Sets the password of a new account, or confirms the password of an existing one.'
+            body.attribute :password_confirmation, :string
+            body.attribute :first_name, :string, description: 'Used only when the invitation creates a new account.'
+            body.attribute :last_name, :string, description: 'Used only when the invitation creates a new account.'
+          end
+
           # GET /api/v3/seller/auth/invitations/:id/lookup?token=:token
           def lookup
             return unless load_invitation
@@ -121,7 +129,7 @@ module Spree
           end
 
           def signup_params(invitation)
-            params.permit(:password, :password_confirmation, :first_name, :last_name).
+            params.permit(*declared_permitted_attributes).
               merge(email: invitation.email)
           end
 

data/app/controllers/spree/api/v3/seller/me_controller.rb

@@ -16,6 +16,17 @@ module Spree
           skip_before_action :set_current_seller_context
           before_action :require_current_user!
 
+          request_params 'AccountUpdateParams' do |body|
+            body.attribute :first_name, :string, example: 'Ada'
+            body.attribute :last_name, :string, example: 'Lovelace'
+            body.attribute :selected_locale, :string,
+              example: 'de',
+              description: "The panel's display language, as a code the panel ships."
+            body.attribute :avatar_signed_id, :string,
+              nullable: true,
+              description: 'A `signed_id` from `POST /files` to set the photo, or `null` to remove it. Omit to leave the current one alone.'
+          end
+
           def show
             render json: me_response
           end
@@ -27,8 +38,8 @@ module Spree
           # seller they are acting for.
           #
           # Distinct from PATCH /profile, which writes the seller business.
-          # `avatar` accepts an ActiveStorage direct-upload signed id to set
-          # the photo, or `null` to remove it.
+          # `avatar_signed_id` takes a signed id from POST /files to set the
+          # photo, or `null` to remove it.
           def update
             if current_user.update(permitted_params)
               render json: me_response
@@ -40,7 +51,7 @@ module Spree
           private
 
           def permitted_params
-            params.permit(:selected_locale, :first_name, :last_name, :avatar)
+            params.permit(*declared_permitted_attributes)
           end
 
           def me_response

data/app/controllers/spree/api/v3/seller/onboarding_controller.rb

@@ -12,6 +12,17 @@ module Spree
         class OnboardingController < Seller::BaseController
           scoped_resource :seller_profile
 
+          request_params 'OnboardingPayoutAccountParams', action: :payout_account do |body|
+            body.attribute :refresh_url, :string,
+              required: true,
+              format: :uri,
+              description: "Where the provider sends the seller back. Must be on the seller panel's origin; any other address is replaced with the panel's."
+            body.attribute :return_url, :string,
+              required: true,
+              format: :uri,
+              description: "Where the provider sends the seller back. Must be on the seller panel's origin; any other address is replaced with the panel's."
+          end
+
           # GET /api/v3/seller/onboarding
           def show
             render json: onboarding_payload

data/app/controllers/spree/api/v3/seller/orders/claims_controller.rb

@@ -17,6 +17,41 @@ module Spree
 
             before_action :set_resource, only: [:show, :approve, :resolve, :deny, :cancel]
 
+            request_params :claim do |body|
+              body.attribute :items, :array, required: true do |item|
+                item.attribute :line_item_id, :id, required: true
+                item.attribute :quantity, :integer, required: true
+                item.attribute :description, :string, nullable: true
+                item.attribute :send_replacement, :boolean
+                item.attribute :replacement_variant_id, :id,
+                  nullable: true,
+                  description: "One of this seller's own variants."
+                item.attribute :refund_amount, :decimal, nullable: true
+              end
+              body.attribute :reason_id, :id, nullable: true
+              body.attribute :memo, :string, nullable: true
+            end
+
+            request_params 'ClaimResolveParams', action: :resolve do |body|
+              body.attribute :resolution, :string,
+                required: true,
+                choices: %w[refund replacement refund_and_replacement]
+              body.attribute :refund_method, :string,
+                choices: %w[original_payment store_credit],
+                description: 'Defaults to `store_credit`.'
+              body.attribute :amount, :decimal, nullable: true
+              body.attribute :replacement_line_item_ids, :array, of: :id,
+                description: 'Which claimed lines to replace. Omit to keep the lines the claim was opened with.'
+            end
+
+            request_params 'ClaimDenyParams', action: :deny do |body|
+              body.attribute :reason, :string, description: 'Recorded on the claim for the customer.'
+            end
+
+            request_params 'ClaimCancelParams', action: :cancel do |body|
+              body.attribute :reason, :string, description: 'A note on why the claim was canceled.'
+            end
+
             protected
 
             def serializer_class

data/app/controllers/spree/api/v3/seller/orders/deliveries_controller.rb

@@ -16,6 +16,18 @@ module Spree
           class DeliveriesController < BaseController
             include Spree::Api::V3::Orders::DeliveryActions
 
+            # The permit list itself lives in DeliveryActions, shared with the
+            # operator's branch; this declaration documents it.
+            request_params :delivery do |body|
+              body.attribute :tracking_number, :string,
+                required: true, on: :create,
+                description: 'A carrier tracking number, a freight PRO or container number, or a full tracking link. A corrected number resets the carrier status to `pending`.'
+              body.attribute :carrier, :string,
+                description: "Free text; detected from the number's format when omitted."
+              body.attribute :service, :string
+              body.attribute :tracking_url, :string
+            end
+
             before_action :set_resource, only: [:show, :update, :destroy]
 
             protected

data/app/controllers/spree/api/v3/seller/orders/exchanges_controller.rb

@@ -17,6 +17,39 @@ module Spree
 
             before_action :set_resource, only: [:show, :approve, :receive, :fulfill, :cancel]
 
+            request_params :exchange do |body|
+              body.attribute :items, :array, required: true do |item|
+                item.attribute :fulfillment_item_id, :id, required: true
+                item.attribute :new_variant_id, :id, required: true, description: "One of this seller's own variants."
+                item.attribute :quantity, :integer, required: true
+              end
+              body.attribute :reason_id, :id, nullable: true
+              body.attribute :stock_location_id, :id,
+                nullable: true,
+                description: "One of this seller's own stock locations, where the goods are restocked."
+              body.attribute :memo, :string, nullable: true
+            end
+
+            request_params 'ExchangeReceiveParams', action: :receive do |body|
+              body.attribute :items, :array,
+                description: 'What actually arrived. Omit to receive everything as requested and resellable.' do |item|
+                item.attribute :exchange_line_item_id, :id, required: true
+                item.attribute :quantity, :integer, required: true
+                item.attribute :resellable, :boolean,
+                  description: 'Goods that cannot be resold are received but never restocked. Defaults to true.'
+              end
+            end
+
+            request_params 'ExchangeCancelParams', action: :cancel do |body|
+              body.attribute :reason, :string, description: 'A note on why the exchange was canceled.'
+            end
+
+            request_params 'ExchangeFulfillParams', action: :fulfill do |body|
+              body.attribute :refund_method, :string,
+                choices: %w[original_payment store_credit],
+                description: 'Defaults to `store_credit`.'
+            end
+
             protected
 
             def serializer_class

data/app/controllers/spree/api/v3/seller/orders/fulfillments_controller.rb

@@ -23,6 +23,33 @@ module Spree
 
             before_action :set_resource, only: [:show, :update, :fulfill, :cancel, :split]
 
+            request_params :fulfillment do |body|
+              body.attribute :tracking, :string, nullable: true
+              body.attribute :tracking_carrier, :string, nullable: true
+              body.attribute :stock_location_id, :id,
+                description: "One of this seller's own stock locations; the rates requote from there."
+              body.attribute :selected_delivery_rate_id, :id,
+                description: 'One of the rates quoted for this parcel from its current origin.'
+            end
+
+            request_params 'FulfillmentFulfillParams', action: :fulfill do |body|
+              body.attribute :tracking, :string, description: 'Carrier tracking number.'
+              body.attribute :tracking_carrier, :string, description: 'Carrier name.'
+              body.attribute :notify_customer, :boolean, description: 'Send the dispatch email (default true).'
+              body.attribute :items, :array,
+                description: 'Ship only these lines; the rest split onto a new fulfillment.' do |item|
+                item.attribute :item_id, :id, required: true, description: 'Prefixed line item ID.'
+                item.attribute :quantity, :integer, required: true
+              end
+            end
+
+            request_params 'FulfillmentSplitParams', action: :split do |body|
+              body.attribute :variant_id, :id, required: true, description: 'The variant being moved out.'
+              body.attribute :quantity, :integer, required: true
+              body.attribute :stock_location_id, :id,
+                description: "One of this seller's own stock locations. Defaults to the source fulfillment's location."
+            end
+
             protected
 
             def serializer_class
@@ -34,8 +61,7 @@ module Spree
             end
 
             def permitted_params
-              params.permit(:tracking, :tracking_carrier, :stock_location_id,
-                            :selected_delivery_rate_id)
+              params.permit(*declared_permitted_attributes)
             end
 
             private

data/app/controllers/spree/api/v3/seller/orders/labels_controller.rb

@@ -15,6 +15,27 @@ module Spree
           class LabelsController < BaseController
             include Spree::Api::V3::Orders::ShippingLabelActions
 
+            # The permit list itself lives in ShippingLabelActions, shared with
+            # the operator's branch; this declaration documents it.
+            request_params :shipping_label do |body|
+              body.attribute :file_signed_id, :string,
+                required: true,
+                description: 'A `signed_id` from `files.upload()`.'
+              body.attribute :tracking_number, :string,
+                required: true,
+                description: 'The number printed on the label.'
+              body.attribute :carrier, :string,
+                description: "Free text; a forwarder's name is as valid as a carrier slug. Detected from the number when omitted."
+              body.attribute :service, :string, description: 'Carrier service the label was bought at.'
+              body.attribute :cost, :decimal,
+                description: "What the seller paid the carrier. Accounting data only; it never touches the order's shipping charge."
+              body.attribute :currency, :currency, description: 'Currency of the cost.'
+              body.attribute :file_format, :string,
+                choices: %w[pdf png zpl],
+                description: 'Taken from the file when omitted.'
+              body.attribute :tracking_url, :string, description: 'Tracking page for the consignment the label mints.'
+            end
+
             before_action :set_resource, only: [:show, :download, :destroy]
 
             # POST .../labels
@@ -24,7 +45,7 @@ module Spree
             def create
               authorize!(:create, Spree::ShippingLabel)
 
-              if label_params[:file].blank?
+              if label_params[:file_signed_id].blank?
                 return render_error(
                   code: ERROR_CODES[:validation_error],
                   message: I18n.t('spree.shipping_labels.errors.file_required'),

data/app/controllers/spree/api/v3/seller/orders/notes_controller.rb

@@ -17,6 +17,13 @@ module Spree
             # there is no member record to fetch.
             skip_before_action :set_resource, raise: false
 
+            request_params 'OrderNotesParams' do |body|
+              body.attribute :customer_note, :string, nullable: true, description: 'What the buyer asked for.'
+              body.attribute :internal_note, :string,
+                nullable: true,
+                description: "The seller's own working note, as HTML. Sanitized on save; `internal_note_html` reads it back."
+            end
+
             # GET /api/v3/seller/orders/:order_id/notes
             def show
               render json: serialize_resource(@order)
@@ -59,7 +66,7 @@ module Spree
             # model sanitizes — the `_html` reader is its round-trip partner,
             # never a write.
             def notes_params
-              permitted = params.permit(:customer_note, :internal_note)
+              permitted = params.permit(*declared_permitted_attributes)
 
               {}.tap do |attributes|
                 attributes[:customer_note] = permitted[:customer_note] if params.key?(:customer_note)

data/app/controllers/spree/api/v3/seller/orders/returns_controller.rb

@@ -17,6 +17,38 @@ module Spree
 
             before_action :set_resource, only: [:show, :approve, :receive, :refund, :cancel]
 
+            request_params :return do |body|
+              body.attribute :items, :array, required: true do |item|
+                item.attribute :fulfillment_item_id, :id, required: true
+                item.attribute :quantity, :integer, required: true
+              end
+              body.attribute :reason_id, :id, nullable: true
+              body.attribute :stock_location_id, :id,
+                nullable: true,
+                description: "One of this seller's own stock locations, where the goods are restocked."
+              body.attribute :memo, :string, nullable: true
+            end
+
+            request_params 'ReturnReceiveParams', action: :receive do |body|
+              body.attribute :items, :array,
+                description: 'What actually arrived. Omit to receive everything as requested and resellable.' do |item|
+                item.attribute :return_line_item_id, :id, required: true
+                item.attribute :quantity, :integer, required: true
+                item.attribute :resellable, :boolean, description: 'Defaults to true.'
+              end
+            end
+
+            request_params 'ReturnRefundParams', action: :refund do |body|
+              body.attribute :amount, :decimal, nullable: true
+              body.attribute :refund_method, :string,
+                choices: %w[original_payment store_credit],
+                description: 'Defaults to `original_payment`.'
+            end
+
+            request_params 'ReturnCancelParams', action: :cancel do |body|
+              body.attribute :reason, :string, description: 'A note on why the return was canceled.'
+            end
+
             protected
 
             def serializer_class