spree_api 6.0.0.rc1 → 6.0.0.rc3

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

@@ -21,6 +21,39 @@ module Spree
 
           scoped_resource :orders
 
+          ADDRESS = Spree::Api::V3::RequestSchema.shape('OrderAddressParams') do |schema|
+            schema.attribute :first_name, :string
+            schema.attribute :last_name, :string
+            schema.attribute :address1, :string
+            schema.attribute :city, :string
+            schema.attribute :postal_code, :string
+            schema.attribute :company, :string, nullable: true
+            schema.attribute :address2, :string, nullable: true
+            schema.attribute :phone, :string, nullable: true
+            schema.attribute :alternative_phone, :string, nullable: true
+            schema.attribute :state_code, :string, nullable: true
+            schema.attribute :state_name, :string, nullable: true
+            schema.attribute :label, :string, nullable: true
+            schema.attribute :country_code, :country, example: 'US'
+          end
+
+          request_params 'OrderCancelParams', action: :cancel do |body|
+            body.attribute :cancel_reason_id, :id,
+              nullable: true,
+              description: 'A reason from the order cancellation reasons endpoint.'
+            body.attribute :cancel_note, :string, nullable: true, description: 'Free text beside the reason.'
+            body.attribute :refund_payments, :boolean,
+              description: "Hand back what the buyer paid for this order's goods."
+            body.attribute :notify_customer, :boolean, description: 'Email the customer about the cancellation.'
+          end
+
+          request_params 'OrderAddressCorrectionParams', action: :address do |body|
+            body.attribute :shipping_address, :object, shape: ADDRESS,
+              description: 'Only the lines that change; the rest of the address is carried over.'
+            body.attribute :billing_address, :object, shape: ADDRESS,
+              description: 'Only the lines that change; the rest of the address is carried over.'
+          end
+
           before_action :set_resource, only: [:show, :cancel, :address]
 
           # PATCH /api/v3/seller/orders/:id/cancel
@@ -124,10 +157,8 @@ module Spree
           # files the address in their book and makes it their default for
           # every later checkout on the marketplace.
           def sent_addresses
-            @sent_addresses ||= params.permit(
-              shipping_address: address_permitted_keys,
-              billing_address: address_permitted_keys
-            ).slice(:shipping_address, :billing_address).reject { |_key, value| value.blank? }
+            @sent_addresses ||= params.permit(*declared_permitted_attributes).
+                                slice(:shipping_address, :billing_address).reject { |_key, value| value.blank? }
           end
 
           def corrected_addresses
@@ -148,16 +179,6 @@ module Spree
             (address&.snapshot || Spree::Address.new).tap { |copy| copy.assign_attributes(sent.to_h.except('label', :label)) }
           end
 
-          def address_permitted_keys
-            [
-              :firstname, :lastname, :first_name, :last_name,
-              :address1, :address2, :city,
-              :country_code, :state_code,
-              :zipcode, :postal_code, :phone, :alternative_phone,
-              :state_name, :company, :label
-            ]
-          end
-
           # A request naming neither address has asked for nothing; saying so
           # beats a 200 that changed nothing.
           def missing_address_errors

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

@@ -18,6 +18,27 @@ module Spree
         class PackageTypesController < Seller::ResourceController
           scoped_resource :package_types
 
+          # The same set the operator's controller permits — a seller measures
+          # their own packaging, so every field on the shared form is theirs
+          # to set. `seller_id` is deliberately absent: ownership comes from
+          # the authenticated seller, never the payload.
+          request_params :package_type do |body|
+            body.attribute :name, :string, required: true, on: :create
+            body.attribute :kind, :string, choices: Spree::PackageType::KINDS
+            body.attribute :length, :number, nullable: true
+            body.attribute :width, :number, nullable: true
+            body.attribute :height, :number, nullable: true
+            body.attribute :dimensions_unit, :string, nullable: true, choices: Spree::Variant::DIMENSION_UNITS
+            body.attribute :weight, :number,
+              nullable: true,
+              description: "The empty package's own weight, added to every quote."
+            body.attribute :max_weight, :number, nullable: true
+            body.attribute :weight_unit, :string, nullable: true, choices: Spree::Variant::WEIGHT_UNITS
+            body.attribute :default, :boolean,
+              description: "Makes this the box this seller's parcels are quoted with. One default per seller, so it never displaces the marketplace's."
+            body.attribute :metadata, :hash, nullable: true
+          end
+
           protected
 
           def model_class
@@ -84,15 +105,6 @@ module Spree
               Spree::PackageType.arel_table[:name].asc
             )
           end
-
-          # The same set the operator's controller permits — a seller measures
-          # their own packaging, so every field on the shared form is theirs
-          # to set. `seller_id` is deliberately absent: ownership comes from
-          # the authenticated seller, never the payload.
-          def resource_permitted_attributes
-            [:name, :kind, :length, :width, :height, :dimensions_unit,
-             :weight, :max_weight, :weight_unit, :default, { metadata: {} }]
-          end
         end
       end
     end

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

@@ -25,6 +25,16 @@ module Spree
                      store: Rails.cache,
                      with: RATE_LIMIT_RESPONSE
 
+          request_params :password_reset do |body|
+            body.attribute :email, :string, required: true, only: :create, example: 'seller@acme.test'
+            body.attribute :redirect_url, :string,
+              only: :create,
+              example: 'https://sellers.your-store.com/reset-password',
+              description: 'Must match an allowed origin of the store; ignored otherwise.'
+            body.attribute :password, :string, required: true, only: :update, example: 'new-password-123'
+            body.attribute :password_confirmation, :string, required: true, only: :update, example: 'new-password-123'
+          end
+
           # POST /api/v3/seller/auth/password_resets
           def create
             user = Spree.admin_user_class.find_by(email: params[:email])

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

@@ -11,6 +11,18 @@ module Spree
         class PoliciesController < Seller::ResourceController
           scoped_resource :seller_profile
 
+          request_params :policy do |body|
+            body.attribute :name, :string,
+              required: true, on: :create,
+              example: 'Shipping Policy',
+              description: 'When the marketplace requires a named policy, use that exact name: the onboarding check matches on it.'
+            body.attribute :slug, :string, example: 'shipping-policy'
+            body.attribute :body, :string,
+              nullable: true,
+              example: '<p>Orders leave the workshop within two working days.</p>',
+              description: 'HTML, sanitized before it is stored. `body_html` on the response is the rendering of what was stored.'
+          end
+
           protected
 
           def model_class
@@ -21,10 +33,6 @@ module Spree
             Spree.api.seller_policy_serializer
           end
 
-          def resource_permitted_attributes
-            [:name, :slug, :body]
-          end
-
           # Accept slug or prefixed ID, matching the storefront's lookup.
           def find_resource
             if params[:id].to_s.start_with?('pol_')

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

@@ -41,8 +41,121 @@ module Spree
             'archived' => -> { Spree.product_archive_workflow }
           }.freeze
 
+          # The operator's price shape, except `currency` may be left out: the
+          # store's currency is assumed (see `default_price_currencies`).
+          PRICE = Spree::Api::V3::RequestSchema.new do |schema|
+            schema.attribute :currency, :currency,
+              example: 'USD',
+              description: "Omit to price in the store's currency. A seller has no currency of their own."
+            schema.attribute :amount, :decimal,
+              required: true,
+              example: '24.00',
+              description: 'A canonical decimal string (`"1234.56"`: period decimal, no grouping). The API does not parse localized input.'
+            schema.attribute :compare_at_amount, :decimal, nullable: true, example: '30.00'
+          end
+
           scoped_resource :products
 
+          request_params :product do |body|
+            body.attribute :name, :string, required: true, on: :create, example: 'Hand-thrown mug'
+            body.attribute :description, :string
+            body.attribute :slug, :string, example: 'hand-thrown-mug'
+            body.attribute :meta_title, :string
+            body.attribute :meta_description, :string
+            body.attribute :meta_keywords, :string
+            body.attribute :metadata, :hash
+            body.attribute :product_type_id, :id,
+              nullable: true,
+              description: "The marketplace's product type this product is listed against, from the product types endpoint. Null detaches it. Saving with a type seeds its option types onto the product."
+            body.attribute :delivery_profile_id, :id,
+              description: "Which of the marketplace's delivery profiles the product ships under. A new product sent without one lands on the profile marked default."
+            body.attribute :prices, :array, of: PRICE,
+              description: "Shorthand for a simple (no-options) product: per-currency prices that forward to the product's sole variant."
+            # `external_url` stays out for the same reason it does on the
+            # operator's endpoint: it would make the server fetch a URL the
+            # caller chose.
+            body.attribute :media, :array,
+              as: 'SellerProductMediaParams',
+              description: 'The gallery, as a whole: a file absent from the list is removed. `signed_id` attaches a fresh upload; `id` updates one already there.' do |media_item|
+              media_item.attribute :id, :id
+              media_item.attribute :signed_id, :string, description: 'A `signed_id` from `POST /files`.'
+              media_item.include_attributes Spree::Api::V3::MediaRequestSchema
+              media_item.attribute :variant_ids, :array, of: :id,
+                description: 'Replaces the variants this media is linked to. An empty list clears them.'
+            end
+            # Narrower than the operator's variant set: `seller_id` would let a
+            # payload hand a variant to somebody else, and
+            # `tax_category_id`/`delivery_profile_id` are marketplace
+            # configuration.
+            body.attribute :variants, :array,
+              as: 'SellerProductVariantParams',
+              description: 'The variants, as a whole: one absent from the list is removed. Pass `id` to update an existing variant.' do |variant|
+              variant.attribute :id, :id
+              variant.attribute :sku, :string
+              variant.attribute :barcode, :string
+              variant.attribute :cost_price, :decimal, nullable: true
+              variant.attribute :cost_currency, :currency
+              variant.attribute :weight, :number, nullable: true
+              variant.attribute :height, :number, nullable: true
+              variant.attribute :width, :number, nullable: true
+              variant.attribute :depth, :number, nullable: true
+              variant.attribute :weight_unit, :string, choices: Spree::Variant::WEIGHT_UNITS
+              variant.attribute :dimensions_unit, :string, choices: Spree::Variant::DIMENSION_UNITS
+              variant.attribute :hs_code, :string
+              variant.attribute :customs_description, :string
+              variant.attribute :country_of_origin, :country
+              variant.attribute :minimum_order_quantity, :integer, nullable: true
+              variant.attribute :order_multiple, :integer, nullable: true
+              variant.attribute :purchase_unit, :string
+              variant.attribute :units_per_carton, :integer,
+                nullable: true,
+                description: 'How many units fill one carton.'
+              variant.attribute :carton_package_type_id, :id,
+                nullable: true,
+                description: 'The carton this variant is packed into: a package type of kind `carton`.'
+              variant.attribute :carton_weight, :number,
+                nullable: true,
+                description: "What one packed carton weighs, in the variant's weight unit."
+              variant.attribute :cartons_per_pallet, :integer,
+                nullable: true,
+                description: 'How many cartons stack on one pallet.'
+              variant.attribute :track_inventory, :boolean
+              variant.attribute :preorderable, :boolean
+              variant.attribute :preorder_ships_at, :datetime,
+                nullable: true,
+                description: 'The "ships by" date shown to customers while the variant is a pre-order. Null clears it.'
+              variant.attribute :backorder_limit, :integer,
+                nullable: true,
+                description: 'Maximum units sellable beyond available stock, capping backorders and pre-orders. Null is unlimited.'
+              variant.attribute :position, :integer
+              variant.attribute :options, :array, of: Spree::Api::V3::VariantOptionRequestSchema,
+                description: 'One pair per option type the variant takes part in (size, color).'
+              variant.attribute :prices, :array, of: PRICE, description: 'Per-currency prices. Upserted by currency.'
+              variant.attribute :stock_levels, :array, of: Spree::Api::V3::StockLevelRequestSchema,
+                description: "Stock per location, at this seller's own locations only: a location belonging to anyone else is ignored."
+            end
+          end
+
+          request_params 'ProductBulkSubmitParams', action: :bulk_submit do |body|
+            body.attribute :ids, :array, of: :id,
+              required: true,
+              description: 'Only drafts and rejected listings are submitted; the rest are counted in `skipped_count`.'
+          end
+
+          request_params 'ProductBulkDestroyParams', action: :bulk_destroy do |body|
+            body.attribute :ids, :array, of: :id,
+              required: true,
+              description: "Ids outside this seller's catalog are ignored; products the store refuses to delete are counted in `skipped_count`."
+          end
+
+          request_params 'ProductBulkStatusParams', action: :bulk_status_update do |body|
+            body.attribute :ids, :array, of: :id, required: true, example: ['prod_UkLWZg9DAJ']
+            body.attribute :status, :string,
+              required: true,
+              choices: SELLER_BULK_STATUS_WORKFLOWS.keys,
+              description: 'A listing goes on sale only when the marketplace approves it, so there is no bulk route onto `active`.'
+          end
+
           before_action :set_status_resource, only: [:submit, :draft, :archive]
           before_action :require_ids!, only: [:bulk_submit, :bulk_status_update, :bulk_destroy]
 
@@ -165,34 +278,7 @@ module Spree
           end
 
           def permitted_params
-            attrs = params.permit(
-              *model_class.additional_seller_permitted_attributes,
-              :name, :description, :slug,
-              :meta_title, :meta_description, :meta_keywords,
-              :product_type_id, :delivery_profile_id,
-              metadata: {},
-              prices: [:amount, :compare_at_amount, :currency],
-              # Inline media, the same shape the operator sends. `external_url`
-              # stays out for the same reason it does there — it would make the
-              # server fetch a URL the caller chose.
-              media: [*Spree::Media::WRITABLE_ATTRIBUTES, :id, :signed_id, { variant_ids: [] }],
-              # A seller's variants. Narrower than the operator's set:
-              # `seller_id` would let a payload hand a variant to somebody else,
-              # and `tax_category_id`/`delivery_profile_id` are marketplace
-              # configuration.
-              variants: [
-                :id, :sku, :barcode,
-                :cost_price, :cost_currency,
-                :weight, :height, :width, :depth, :weight_unit, :dimensions_unit,
-                :hs_code, :country_of_origin, :customs_description,
-                :minimum_order_quantity, :order_multiple, :purchase_unit, :units_per_carton,
-                :carton_package_type_id, :carton_weight, :cartons_per_pallet,
-                :track_inventory, :preorderable, :preorder_ships_at, :backorder_limit, :position,
-                options: [:name, :value],
-                prices: [:amount, :compare_at_amount, :currency],
-                stock_levels: [:id, :stock_location_id, :count_on_hand, :backorderable]
-              ]
-            )
+            attrs = params.permit(*permitted_attributes)
 
             # Assigned only when present: writing a nil `prices` or
             # `stock_levels` key reaches the association setter as nil, which

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

@@ -20,6 +20,38 @@ module Spree
 
           scoped_resource :seller_profile
 
+          # Enumerated rather than borrowing the legacy global list, which
+          # permits :id, :user_id and :deleted_at.
+          request_params 'ProfileUpdateParams' do |body|
+            body.attribute :name, :string, example: 'Acme Supplies'
+            body.attribute :contact_email, :string, nullable: true, format: :email
+            body.attribute :billing_email, :string, nullable: true, format: :email
+            body.attribute :about, :string,
+              nullable: true,
+              description: "Sanitized HTML: the seller's public description."
+            body.attribute :legal_name, :string,
+              nullable: true,
+              description: 'The business a commission invoice is made out to.'
+            body.attribute :registration_number, :string, nullable: true
+            body.attribute :logo_signed_id, :string,
+              nullable: true,
+              description: 'A `signed_id` from `POST /files`; `null` removes the image.'
+            body.attribute :square_logo_signed_id, :string,
+              nullable: true,
+              description: 'A `signed_id` from `POST /files`; `null` removes the image.'
+            body.attribute :cover_photo_signed_id, :string,
+              nullable: true,
+              description: 'A `signed_id` from `POST /files`; `null` removes the image.'
+            body.attribute :billing_address, :object, as: 'SellerAddressParams' do |billing_address|
+              billing_address.include_attributes Spree::Api::V3::AddressRequestSchema
+            end
+            body.attribute :custom_fields, :array, of: Spree::Api::V3::CustomFieldValueRequestSchema,
+              description: "Answers to the custom fields this marketplace's onboarding asks for. A field nothing asked for is ignored rather than written."
+            body.attribute :accept_terms, :boolean,
+              permit: false,
+              description: "Stamps the moment the seller accepted the marketplace's terms. One-way: sending `false` does not unmake the stamp."
+          end
+
           def show
             render json: serialize_seller
           end
@@ -54,8 +86,6 @@ module Spree
             %w[show]
           end
 
-          # Enumerated rather than borrowing the legacy global list, which
-          # permits :id, :user_id and :deleted_at.
           # Accepting the marketplace's terms is a profile write, not an endpoint
           # of its own: `accept_terms: true` stamps the time, which is what the
           # AcceptTerms requirement reads.
@@ -104,14 +134,7 @@ module Spree
           end
 
           def permitted_params
-            normalize_params(
-              params.permit(:name, :contact_email, :billing_email, :about,
-                            :legal_name, :registration_number,
-                            :logo, :square_logo, :cover_photo,
-                            billing_address: Spree::Api::V3::AddressParams::ADDRESS_KEYS,
-                            custom_fields: [:id, :custom_field_definition_id, :value,
-                                            { value: [] }, { value: {} }])
-            )
+            normalize_params(params.permit(*declared_permitted_attributes))
           end
 
           private

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

@@ -12,6 +12,16 @@ module Spree
         class RequirementSubmissionsController < Seller::BaseController
           scoped_resource :seller_profile
 
+          # `file_signed_id` comes from POST /files, so the bytes are already in
+          # storage by the time this runs.
+          request_params 'RequirementSubmissionParams' do |body|
+            body.attribute :note, :string, description: 'Anything the seller wants to say alongside the submission.'
+            body.attribute :reference, :string,
+              description: 'A reference number or external identifier, for requirements that ask for one.'
+            body.attribute :file_signed_id, :string,
+              description: 'A `signed_id` from `POST /files`, for requirements that ask for a document.'
+          end
+
           before_action :set_requirement, only: [:create]
           before_action :set_submission, only: [:download]
 
@@ -24,7 +34,7 @@ module Spree
               requirement: @requirement,
               note: attributes[:note],
               reference: attributes[:reference],
-              file: attributes[:file],
+              file: attributes[:file_signed_id],
               submitted_by: try_spree_current_user
             )
 
@@ -57,11 +67,8 @@ module Spree
 
           protected
 
-          # What a seller may say about a requirement. `file` is a direct-upload
-          # signed id, so it is a string like the rest — the bytes are already
-          # in storage by the time this runs.
           def permitted_params
-            params.permit(:note, :reference, :file)
+            params.permit(*declared_permitted_attributes)
           end
 
           def read_actions

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

@@ -11,6 +11,7 @@ module Spree
           include Spree::Api::V3::Seller::SellerContext
           include Spree::Api::V3::SellerAuthentication
           include Spree::Api::V3::ScopedAuthorization
+          include Spree::Api::V3::StrictMoneyParams
 
           protected
 
@@ -65,6 +66,17 @@ module Spree
             model_class.table_name.delete_prefix('spree_').to_sym
           end
 
+          # What extensions opened to sellers, never the operator-level list:
+          # an attribute opened to operators must not become seller-writable
+          # by accident.
+          def model_additional_permitted_attributes
+            return [] unless respond_to?(:model_class, true)
+
+            Array(model_class.try(:additional_seller_permitted_attributes))
+          rescue NotImplementedError
+            []
+          end
+
           def authorize_resource!(resource = @resource, action = action_name.to_sym)
             authorize!(action, resource)
           end

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

@@ -24,6 +24,49 @@ module Spree
           # stock.
           scoped_resource :stock
 
+          # The same set the operator's controller permits: a seller runs
+          # their own warehouse, so every field on the shared form is theirs to
+          # set. Anything missing here is dropped by `permit` without a word,
+          # and the form would appear to save while quietly discarding it.
+          request_params :stock_location do |body|
+            body.attribute :name, :string, required: true, on: :create, example: 'Main warehouse'
+            body.attribute :admin_name, :string, nullable: true
+            body.attribute :active, :boolean, description: 'Set `false` to retire a location: there is no delete.'
+            body.attribute :default, :boolean
+            body.attribute :kind, :string,
+              choices: Spree::StockLocation::KINDS,
+              open: true,
+              example: 'warehouse',
+              description: 'Categorizes the location.'
+            body.attribute :propagate_all_variants, :boolean
+            body.attribute :backorderable_default, :boolean
+            body.attribute :address1, :string, nullable: true
+            body.attribute :address2, :string, nullable: true
+            body.attribute :city, :string, nullable: true
+            body.attribute :zipcode, :string, nullable: true
+            body.attribute :phone, :string, nullable: true
+            body.attribute :company, :string, nullable: true
+            body.attribute :country_code, :country,
+              nullable: true,
+              example: 'US',
+              description: 'ISO-3166 alpha-2 country code.'
+            body.attribute :state_code, :string,
+              nullable: true,
+              example: 'OR',
+              description: "State or province abbreviation, resolved against the selected country's states."
+            body.attribute :state_name, :string,
+              nullable: true,
+              description: "Free-text state for countries that don't have a states list."
+            body.attribute :pickup_enabled, :boolean
+            body.attribute :pickup_stock_policy, :string,
+              choices: Spree::StockLocation::PICKUP_STOCK_POLICIES,
+              description: '`local` collects only items at this location; `any` lets items transfer in from other locations (ship-to-store).'
+            body.attribute :pickup_ready_in_minutes, :integer, nullable: true
+            body.attribute :returns_enabled, :boolean,
+              description: 'Whether customers may send returns to this location.'
+            body.attribute :pickup_instructions, :string, nullable: true
+          end
+
           protected
 
           def model_class
@@ -34,20 +77,8 @@ module Spree
             Spree.api.seller_stock_location_serializer
           end
 
-          # The same set the operator's controller permits: a seller runs
-          # their own warehouse, so every field on the shared form is theirs to
-          # set. Anything missing here is dropped by `permit` without a word,
-          # and the form would appear to save while quietly discarding it.
           def permitted_params
-            params.permit(
-              *model_additional_permitted_attributes,
-              :name, :admin_name, :active, :default,
-              :kind, :propagate_all_variants, :backorderable_default,
-              :address1, :address2, :city, :zipcode, :phone, :company,
-              :country_code, :state_code, :state_name,
-              :pickup_enabled, :pickup_stock_policy, :returns_enabled,
-              :pickup_ready_in_minutes, :pickup_instructions
-            )
+            params.permit(*permitted_attributes)
           end
         end
       end

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

@@ -24,6 +24,15 @@ module Spree
           # standard actions have to be listed alongside the custom one.
           before_action :set_resource, only: [:show, :update, :destroy, :validate]
 
+          request_params :seller_tax_identifier do |body|
+            body.attribute :kind, :string, required: true, on: :create,
+              example: 'eu_vat',
+              description: "#{Spree::Api::V3::TaxIdentifierRequestSchema::KIND_DESCRIPTION} One registration per kind."
+            body.attribute :value, :string, required: true, on: :create,
+              example: 'DE100000008',
+              description: 'A number the validator for its kind refuses is rejected rather than stored.'
+          end
+
           protected
 
           def model_class
@@ -39,7 +48,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(:kind, :value)
+            params.permit(*declared_permitted_attributes)
           end
         end
       end

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

@@ -16,6 +16,10 @@ module Spree
 
           before_action :set_member, only: [:destroy]
 
+          request_params :team_member do |body|
+            body.attribute :email, :string, required: true, example: 'colleague@acme.test'
+          end
+
           def index
             render json: { data: members.map { |member| serialize_member(member) } }
           end

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

@@ -16,6 +16,16 @@ module Spree
 
           skip_before_action :authenticate_user, only: [:create, :refresh, :logout]
 
+          request_params 'RefreshTokenParams', action: :refresh do |body|
+            body.attribute :refresh_token, :string,
+              required: true,
+              description: 'The refresh token from the login response.'
+          end
+
+          request_params 'LogoutParams', action: :logout do |body|
+            body.attribute :refresh_token, :string, description: 'The refresh token to revoke.'
+          end
+
           # POST  /api/v3/store/auth/login
           # Supports multiple authentication providers via :provider param
           # Example:

data/app/controllers/spree/api/v3/store/carts/discount_codes_controller.rb

@@ -9,6 +9,13 @@ module Spree
 
             before_action :find_cart!
 
+            request_params 'ApplyDiscountCodeParams', action: :create do |body|
+              body.attribute :code, :string,
+                required: true,
+                example: 'SAVE10',
+                description: 'The promotion code to apply.'
+            end
+
             # POST  /api/v3/store/carts/:cart_id/discount_codes
             # Applies a discount code. A real-but-not-yet-eligible code is
             # accepted and persisted — recalculation activates the discount
@@ -69,7 +76,7 @@ module Spree
             end
 
             def permitted_params
-              params.permit(:code)
+              params.permit(*declared_permitted_attributes)
             end
           end
         end

data/app/controllers/spree/api/v3/store/carts/fulfillments_controller.rb

@@ -9,6 +9,14 @@ module Spree
 
             before_action :find_cart!
 
+            request_params 'UpdateFulfillmentParams', action: :update do |body|
+              body.attribute :selected_delivery_rate_id, :id,
+                example: 'dr_abc123',
+                description: 'The delivery rate to select.'
+              body.attribute :pickup_point_external_id, :string,
+                description: "For a pickup point delivery method: the provider's id of the point to collect from."
+            end
+
             # PATCH /api/v3/store/carts/:cart_id/fulfillments/:id
             # Selects a delivery rate, and for pickup_point methods a concrete
             # pickup point (validated against the provider, then frozen into
@@ -35,7 +43,7 @@ module Spree
             private
 
             def permitted_params
-              params.permit(:selected_delivery_rate_id, :pickup_point_external_id)
+              params.permit(*declared_permitted_attributes)
             end
 
             def recalculate
@@ -55,7 +63,7 @@ module Spree
                 render_error(
                   code: ERROR_CODES[:validation_error],
                   message: I18n.t('spree.errors.messages.no_pickup_point_provider'),
-                  status: :unprocessable_entity
+                  status: :unprocessable_content
                 )
                 return false
               end

data/app/controllers/spree/api/v3/store/carts/gift_cards_controller.rb

@@ -9,6 +9,13 @@ module Spree
 
             before_action :find_cart!
 
+            request_params 'ApplyGiftCardParams', action: :create do |body|
+              body.attribute :code, :string,
+                required: true,
+                example: 'GC-ABCD-1234',
+                description: 'The gift card code to apply.'
+            end
+
             # POST /api/v3/store/carts/:cart_id/gift_cards
             def create
               with_order_lock do
@@ -64,7 +71,7 @@ module Spree
             end
 
             def permitted_params
-              params.permit(:code)
+              params.permit(*declared_permitted_attributes)
             end
           end
         end