spree_api 6.0.0.beta4 → 6.0.0.rc2

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,10 +45,10 @@ 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: Spree.t('shipping_labels.errors.file_required'),
+                  message: I18n.t('spree.shipping_labels.errors.file_required'),
                   status: :unprocessable_content
                 )
               end

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

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

@@ -15,6 +15,8 @@ module Spree
           include Spree::Api::V3::Seller::AuthCookies
           include Spree::Api::V3::JwtAuthentication
 
+          RESET_REQUESTED_EVENT = 'seller_user.password_reset_requested'.freeze
+
           # No `skip_scope_check!`: this extends the plain v3 base, which has
           # no authentication or scope gate to lift. The emailed token is the
           # only credential, exactly as on the admin twin.
@@ -23,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])
@@ -32,12 +44,12 @@ module Spree
             # them a seller reset link would be an invitation to a session they
             # cannot hold.
             if user&.seller_member?
-              user.publish_event('seller_user.password_reset_requested', event_payload(user))
+              user.publish_event(RESET_REQUESTED_EVENT, event_payload(user))
             end
 
             # Always 202, whether or not anything matched — this endpoint must
             # not become a way to discover which addresses exist.
-            render json: { message: Spree.t(:password_reset_requested, scope: :api) }, status: :accepted
+            render json: { message: I18n.t('spree.api.password_reset_requested') }, status: :accepted
           end
 
           # PATCH /api/v3/seller/auth/password_resets/:id
@@ -79,7 +91,7 @@ module Spree
           def render_token_invalid
             render_error(
               code: ErrorHandler::ERROR_CODES[:password_reset_token_invalid],
-              message: Spree.t(:password_reset_token_invalid, scope: :api),
+              message: I18n.t('spree.api.password_reset_token_invalid'),
               status: :unprocessable_content
             )
           end
@@ -88,14 +100,11 @@ module Spree
           # right panel origin and locale without a request to read them from.
           def event_payload(user)
             store = seller_store(user)
-            payload = {
-              reset_token: user.generate_token_for(:password_reset),
-              email: user.email,
-              store_id: store&.prefixed_id
-            }
-            redirect_url = validated_redirect_url(store)
-            payload[:redirect_url] = redirect_url if redirect_url.present?
-            payload
+            user.event_payload_for(
+              RESET_REQUESTED_EVENT,
+              reset_token: user.generate_token_for(:password_reset), store: store,
+              redirect_url: validated_redirect_url(store).presence
+            )
           end
 
           # Which store's panel to send them to.

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]
 
@@ -107,7 +220,7 @@ module Spree
             if resolve_workflow.nil?
               return render_error(
                 code: 'invalid_status',
-                message: Spree.t(:invalid_status, scope: 'errors.messages', default: 'Invalid status'),
+                message: I18n.t('spree.errors.messages.invalid_status'),
                 status: :unprocessable_content
               )
             end
@@ -165,33 +278,7 @@ module Spree
           end
 
           def permitted_params
-            attrs = params.permit(
-              :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