spree_api 6.0.0.rc1 → 6.0.0.rc2

data/app/controllers/spree/api/v3/admin/orders/items_controller.rb

@@ -4,6 +4,16 @@ module Spree
       module Admin
         module Orders
           class ItemsController < BaseController
+            request_params :line_item do |body|
+              body.attribute :variant_id, :id, required: true, only: :create
+              body.attribute :quantity, :integer, example: 1, description: 'Defaults to 1 when adding an item.'
+              body.attribute :price, :decimal,
+                nullable: true,
+                description: "Negotiated unit price. Stamps the line `price_source: 'manual'`, so quantity changes and recalculation never re-price it; an explicit null reverts the line to catalog pricing. Omit to leave pricing alone. Draft (incomplete) orders only."
+              body.attribute :options, :hash, only: :create
+              body.attribute :metadata, :hash, only: :update
+            end
+
             # POST /api/v3/admin/orders/:order_id/items
             def create
               with_order_lock do
@@ -69,7 +79,7 @@ module Spree
             end
 
             def permitted_params
-              params.permit(:variant_id, :quantity, :price, metadata: {}, options: {})
+              params.permit(*permitted_attributes)
             end
 
             private

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

@@ -11,16 +11,39 @@ module Spree
           class LabelsController < BaseController
             include Spree::Api::V3::Orders::ShippingLabelActions
 
+            # The permit list itself lives in ShippingLabelActions, shared with
+            # the seller branch; this declaration documents it.
+            request_params :shipping_label do |body|
+              body.attribute :file_signed_id, :string,
+                description: 'A `signed_id` from `files.upload()`. Its presence records a label bought elsewhere instead of buying one; without it the body is ignored and the label is bought through the carrier.'
+              body.attribute :tracking_number, :string,
+                description: 'The number printed on an uploaded label. Required with `file_signed_id`.'
+              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 merchant 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, :refund, :destroy]
 
             # POST .../labels
             #
-            # Buys the label through the parcel's provider, or — when a `file`
+            # Buys the label through the parcel's provider, or — when a `file_signed_id`
             # is given — records one the merchant bought elsewhere.
             def create
               authorize!(:create, Spree::ShippingLabel)
 
-              return record_uploaded_label if label_params[:file].present?
+              return record_uploaded_label if label_params[:file_signed_id].present?
+              # Buying is the default only when no file is sent at all. A file
+              # under its old name would otherwise fall through to buying a
+              # label on the carrier account.
+              return render_misnamed_label_file if params.key?(:file)
 
               with_order_lock do
                 result = Spree.shipping_label_purchase_workflow.call(owner: @parent)
@@ -59,6 +82,16 @@ module Spree
                           @order.fulfillments.find_by_prefix_id!(params[:fulfillment_id])
                         end
             end
+
+            private
+
+            def render_misnamed_label_file
+              render_error(
+                code: ERROR_CODES[:parameter_invalid],
+                message: I18n.t('spree.shipping_labels.errors.file_renamed'),
+                status: :unprocessable_content
+              )
+            end
           end
         end
       end

data/app/controllers/spree/api/v3/admin/orders/payments_controller.rb

@@ -6,6 +6,18 @@ module Spree
           class PaymentsController < BaseController
             scoped_resource :payments
 
+            request_params :payment do |body|
+              body.attribute :payment_method_id, :id, required: true, on: :create
+              body.attribute :amount, :decimal, description: "Defaults to the order total left after store credit."
+              body.attribute :source_id, :id,
+                description: "A saved payment source of the order's customer (a credit card), for an off-session charge. Used only by payment methods that require a source."
+            end
+
+            request_params 'PaymentCaptureParams', action: :capture do |body|
+              body.attribute :amount, :decimal,
+                description: 'Captures part of the authorized amount. Defaults to all of it.'
+            end
+
             before_action :set_resource, only: [:show, :capture, :void]
 
             # POST /api/v3/admin/orders/:order_id/payments
@@ -52,7 +64,10 @@ module Spree
             # to prevent. Both flows are idempotent on replay — an
             # already-captured or already-void payment returns success.
             def capture
-              amount = params[:amount] ? (params[:amount].to_f * 100).round : nil
+              amount = money_param(:amount, @resource.currency)
+              unless amount.nil? || amount.positive?
+                raise Spree::Money::InvalidFormat.new('must be greater than 0', field: :amount)
+              end
 
               result = Spree.payment_capture_workflow.call(payment: @resource, amount: amount)
 
@@ -76,10 +91,6 @@ module Spree
               Spree.api.admin_payment_serializer
             end
 
-            def permitted_params
-              params.permit(:amount, :payment_method_id, :source_id)
-            end
-
             # Saved-source charges require an order customer — sources are scoped
             # to that customer to prevent attaching customer A's card to
             # customer B's order. Refuse if no customer is assigned.

data/app/controllers/spree/api/v3/admin/orders/refunds_controller.rb

@@ -6,6 +6,12 @@ module Spree
           class RefundsController < BaseController
             scoped_resource :refunds
 
+            request_params :refund do |body|
+              body.attribute :payment_id, :id, required: true, on: :create
+              body.attribute :amount, :decimal, required: true, on: :create
+              body.attribute :refund_reason_id, :id, description: "Defaults to the store's first refund reason."
+            end
+
             # POST /api/v3/admin/orders/:order_id/refunds
             #
             # Deliberately not wrapped in with_order_lock: the workflow calls

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

@@ -19,6 +19,42 @@ module Spree
             # would be wrongly denied.
             scoped_resource :orders
 
+            request_params :return do |body|
+              body.attribute :items, :array,
+                required: true, on: :create,
+                only: :create,
+                description: 'Fulfilled units coming back, and how many of each.' do |item|
+                item.attribute :fulfillment_item_id, :id, required: true
+                item.attribute :quantity, :integer, required: true
+              end
+              body.attribute :stock_location_id, :id,
+                description: 'Where the goods come back to. Defaults to the location that shipped them.'
+              body.attribute :reason_id, :id, description: "One of the store's return reasons."
+              body.attribute :memo, :string
+              body.attribute :metadata, :hash, only: :update
+            end
+
+            request_params 'ReturnReceiveParams', action: :receive do |body|
+              body.attribute :items, :array,
+                description: 'What actually arrived. Omit to receive everything as requested and resellable; send rows for a partial or damaged receipt.' do |item|
+                item.attribute :return_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 'ReturnRefundParams', action: :refund do |body|
+              body.attribute :amount, :decimal, description: 'Defaults to the value of what was actually received.'
+              body.attribute :refund_method, :string,
+                choices: Spree::RefundMethods::METHODS,
+                description: '`store_credit` issues credit immediately; `original_payment` (the default) refunds through the gateway that took the money.'
+            end
+
+            request_params 'ReturnCancelParams', action: :cancel do |body|
+              body.attribute :reason, :string, description: 'A note on why the return was canceled.'
+            end
+
             before_action :set_resource, only: [:show, :update, :approve, :receive, :refund, :cancel]
 
             # PATCH /api/v3/admin/orders/:order_id/returns/:id
@@ -50,7 +86,7 @@ module Spree
             end
 
             def permitted_params
-              params.permit(:memo, :reason_id, :stock_location_id, metadata: {})
+              params.permit(*permitted_attributes)
             end
 
             private

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

@@ -6,17 +6,20 @@ module Spree
           class StoreCreditsController < BaseController
             skip_before_action :set_resource, raise: false
 
+            request_params 'StoreCreditApplyParams' do |body|
+              body.attribute :amount, :decimal,
+                description: "Defaults to the customer's available store credit, up to the order total."
+            end
+
             # POST /api/v3/admin/orders/:order_id/store_credits
             #
-            # Body: { amount: Number (optional) }
-            #
             # When `amount` is omitted, applies the customer's available store
             # credit up to the order total.
             def create
               with_order_lock do
                 result = Spree.store_credit_apply_service.call(
                   order: @parent,
-                  amount: params[:amount].try(:to_f)
+                  amount: money_param(:amount, @parent.currency)
                 )
 
                 if result.success?

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

@@ -7,11 +7,78 @@ module Spree
 
           scoped_resource :orders
 
-          # The order accepts a `po_document` signed blob id and streams it back.
+          # The order accepts a `po_document_signed_id` and streams it back.
           include ActiveStorage::SetCurrent
 
-          # A tampered signed id would otherwise surface as a 500.
-          rescue_from ActiveSupport::MessageVerifier::InvalidSignature, with: :render_invalid_po_document
+          ADDRESS = Spree::Api::V3::RequestSchema.shape('AddressInputParams') do |schema|
+            schema.include_attributes Spree::Api::V3::Admin::AddressRequestSchema
+          end
+
+          request_params :order do |body|
+            body.external_references
+            body.attribute :email, :string, example: 'customer@example.com'
+            body.attribute :customer_id, :id
+            body.attribute :use_customer_default_address, :boolean,
+              only: :create,
+              description: "With `customer_id`, copies the customer's saved billing and shipping addresses onto the order."
+            body.attribute :currency, :currency, example: 'USD'
+            body.attribute :market_id, :id
+            body.attribute :channel_id, :id, description: 'Defaults to the store primary channel when omitted.'
+            body.attribute :locale, :locale, example: 'en-US'
+            body.attribute :customer_note, :string, description: 'Public, customer-visible note.'
+            body.attribute :internal_note, :string,
+              description: 'Staff-only note. Rich text HTML; reads come back as this plus `internal_note_html`.'
+            body.attribute :po_number, :string,
+              description: "The buyer's own purchase-order reference. Searchable alongside the order number, and rendered on every order-facing document."
+            body.attribute :po_document_signed_id, :string,
+              nullable: true,
+              description: "The `signed_id` of the buyer's purchase order, from `files.upload()` with `visibility: 'private'`. Null removes the document the order carries."
+            body.attribute :shipping_address_id, :id,
+              only: :create,
+              description: 'An existing address of the customer.'
+            body.attribute :billing_address_id, :id,
+              only: :create,
+              description: 'An existing address of the customer.'
+            body.attribute :preferred_stock_location_id, :id,
+              description: "Stock location to prefer for fulfillment. Order Routing's built-in preferred-location rule ranks it first; routing falls back to the next rule when the location can't cover the cart."
+            body.attribute :company_id, :id,
+              nullable: true,
+              description: "Makes the order a company purchase, with that company's catalog prices and tax treatment. Null makes a draft a plain customer order again."
+            body.attribute :coupon_code, :string,
+              only: :create,
+              description: 'Applied non-fatally: an invalid code does not block creation.'
+            body.attribute :metadata, :hash
+            body.attribute :tags, :array, of: :string
+            body.attribute :shipping_address, :object, shape: ADDRESS
+            body.attribute :billing_address, :object, shape: ADDRESS
+            body.attribute :items, :array,
+              description: 'Line items to upsert, keyed by variant. An entry sets that variant\'s quantity, creating the line item when the order has none; `quantity: 0` removes it. Variants you do not send are left alone.' do |item|
+              item.attribute :variant_id, :id, required: true
+              item.attribute :quantity, :integer, example: 1
+              item.attribute :price, :decimal,
+                nullable: true,
+                description: "Negotiated unit price; stamps `price_source: 'manual'`. Null reverts the line to catalog pricing. Draft orders only."
+              item.attribute :metadata, :hash
+            end
+          end
+
+          request_params 'OrderCompleteParams', action: :complete do |body|
+            body.attribute :payment_pending, :boolean
+            body.attribute :notify_customer, :boolean,
+              description: 'Send the order confirmation email after completion.'
+          end
+
+          request_params 'OrderCancelParams', action: :cancel do |body|
+            body.attribute :cancel_reason_id, :id,
+              description: "Why the order was canceled: the id of one of the store's cancellation reasons."
+            body.attribute :cancel_note, :string, description: 'Staff-facing note about the cancellation.'
+            body.attribute :refund_payments, :boolean,
+              description: "Whether this order's share of a payment shared across a split checkout is handed back."
+            body.attribute :refund_amount, :decimal,
+              description: 'How much of that share to return. Defaults to all of it; refused on an order whose payment is not shared.'
+            body.attribute :notify_customer, :boolean,
+              description: 'Send the order cancellation email after canceling.'
+          end
 
           skip_before_action :set_resource, only: [:index, :create]
           before_action :set_resource, only: [:show, :update, :destroy, :complete, :cancel, :approve, :resend_confirmation, :resend_digital_links, :po_document]
@@ -244,14 +311,6 @@ module Spree
 
           private
 
-          def render_invalid_po_document
-            render_error(
-              code: ERROR_CODES[:validation_error],
-              message: I18n.t('spree.po_document_invalid_signed_id'),
-              status: :unprocessable_content
-            )
-          end
-
           def resolve_customer
             customer_param = params[:customer_id].presence
             return unless customer_param
@@ -271,44 +330,13 @@ module Spree
           end
 
           def order_create_params
-            permitted = normalize_params(
-              params.permit(
-                :email, :customer_id, :use_customer_default_address,
-                :currency, :market_id, :channel_id, :locale,
-                :customer_note, :internal_note,
-                # The buyer's own purchase-order reference, and the signed blob
-                # id of the document behind it — a PO arriving by email and
-                # keyed in is the draft-order flow plus these two fields.
-                :po_number, :po_document,
-                :shipping_address_id, :billing_address_id,
-                :preferred_stock_location_id, :company_id,
-                :coupon_code,
-                metadata: {},
-                tags: [],
-                shipping_address: address_permitted_keys,
-                billing_address: address_permitted_keys,
-                items: item_permitted_keys
-              )
-            )
-            resolve_company_param(permitted)
+            resolve_company_param(normalize_params(params.permit(*request_params_schema.permit_list(:create))))
           end
 
+          # Named rather than read from the action, since an upsert reaches
+          # update from the create action.
           def order_update_params
-            permitted = normalize_params(
-              params.permit(
-                :email, :customer_id,
-                :customer_note, :internal_note,
-                :po_number, :po_document,
-                :currency, :locale, :market_id, :channel_id,
-                :preferred_stock_location_id, :company_id,
-                metadata: {},
-                tags: [],
-                shipping_address: address_permitted_keys,
-                billing_address: address_permitted_keys,
-                items: item_permitted_keys
-              )
-            )
-            resolve_company_param(permitted)
+            resolve_company_param(normalize_params(params.permit(*request_params_schema.permit_list(:update))))
           end
 
           # An incidental lookup like any other: resolved through the store so
@@ -326,20 +354,6 @@ module Spree
               end
             permitted
           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
-
-          def item_permitted_keys
-            [:variant_id, :quantity, :price, { metadata: {} }]
-          end
         end
       end
     end

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

@@ -14,6 +14,36 @@ module Spree
         class PackageTypesController < ResourceController
           scoped_resource :package_types
 
+          request_params :package_type do |body|
+            body.attribute :name, :string,
+              required: true, on: :create,
+              example: 'Euro pallet',
+              description: 'Unique within the store.'
+            body.attribute :kind, :string,
+              required: true, on: :create,
+              choices: Spree::PackageType::KINDS,
+              example: 'pallet',
+              description: 'What this packaging is: the box parcels ship in, or the carton, pallet or container a wholesale order leaves on.'
+            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,
+              example: 'cm',
+              description: "Unit the three dimensions are in; falls back to the store's unit system."
+            body.attribute :weight, :number,
+              nullable: true,
+              description: "The empty package's own weight, added to content weight on every quote."
+            body.attribute :max_weight, :number,
+              nullable: true,
+              description: 'What the package can hold, not the same as its own weight.'
+            body.attribute :weight_unit, :string, nullable: true, choices: Spree::Variant::WEIGHT_UNITS, example: 'kg'
+            body.attribute :default, :boolean,
+              description: 'The box every parcel quote is built on. Setting this demotes whichever row held it.'
+            body.attribute :metadata, :hash
+          end
+
           protected
 
           def model_class
@@ -27,11 +57,6 @@ module Spree
           def collection_includes
             [:seller]
           end
-
-          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/admin/password_resets_controller.rb

@@ -15,6 +15,23 @@ module Spree
 
           skip_before_action :authenticate_admin!
 
+          request_params 'PasswordResetRequestParams', action: :create do |body|
+            body.attribute :email, :string,
+              required: true,
+              permit: false,
+              format: :email,
+              example: 'admin@example.com'
+            body.attribute :redirect_url, :string,
+              permit: false,
+              example: 'https://admin.your-store.com/reset-password',
+              description: 'The page the emailed reset link points at, with the reset token appended. Honored only on the dashboard origin, for an account that is staff of the store; ignored otherwise.'
+          end
+
+          request_params 'PasswordResetParams', action: :update do |body|
+            body.attribute :password, :string, required: true, permit: false
+            body.attribute :password_confirmation, :string, required: true, permit: false
+          end
+
           # POST /api/v3/admin/password_resets
           def create
             user = Spree.admin_user_class.find_by(email: params[:email])

data/app/controllers/spree/api/v3/admin/payment_methods_controller.rb

@@ -10,27 +10,48 @@ module Spree
           subclassed_via -> { Spree::PaymentMethod.providers },
                          unknown_type_error: 'unknown_payment_method_type'
 
+          request_params :payment_method do |body|
+            body.attribute :type, :string,
+              required: true,
+              only: :create,
+              permit: false,
+              example: 'check',
+              description: 'Wire shorthand from the payment method types endpoint.'
+            body.attribute :name, :string, required: true, on: :create
+            body.attribute :description, :string, nullable: true
+            body.attribute :active, :boolean
+            body.attribute :storefront_visible, :boolean,
+              description: 'False keeps the method to the dashboard; true also offers it on the storefront.'
+            body.attribute :capture_method, :string,
+              nullable: true,
+              choices: Spree::CaptureMethod::CAPTURE_METHODS,
+              description: 'When customers are charged for this method. Null inherits the store setting.'
+            body.attribute :position, :integer
+            body.attribute :metadata, :hash
+            body.attribute :preferences, :hash,
+              description: "Values for the provider's preference schema, from the payment method types endpoint."
+          end
+
           # Lists available payment provider subclasses for the create form.
-          # Returns: { data: [{ type, label, description, preference_schema }] }.
-          # The preference_schema array describes the provider-specific
+          # Returns: { data: [{ type, label, description, schema }] }.
+          # `schema` is the JSON Schema of the provider-specific
           # configuration fields, so admin UIs can render a generic
           # preferences form without hard-coding per-provider knowledge.
-          # Filters out subclasses already installed in the current store —
-          # mirrors the legacy admin's "available_payment_methods" helper, so
-          # admins don't see (and accidentally double-install) the same
-          # provider twice.
+          # Every provider, `installed` when the store already has one: the
+          # create picker leaves those out so a provider is not installed
+          # twice, and the edit form still finds an installed one's schema.
           def types
-            authorize! :create, model_class
+            authorize! :show, model_class
 
             installed_class_names = current_store.payment_methods.pluck(:type)
             installed_shorthands = installed_class_names.filter_map do |name|
               name.safe_constantize&.api_type
             end
-            available = model_class.subclasses_with_preference_schema.reject do |entry|
-              installed_shorthands.include?(entry[:type])
+            entries = model_class.subclasses_with_preference_schema.map do |entry|
+              entry.merge(installed: installed_shorthands.include?(entry[:type]))
             end
 
-            render json: { data: available }
+            render json: { data: entries }
           end
 
           protected
@@ -43,19 +64,14 @@ module Spree
             Spree.api.admin_payment_method_serializer
           end
 
-          # Explicit allowlist per the v3 convention — flat params. `type` and
-          # `preferences` are added by `SubclassedResource` on top.
-          # Deliberately NOT routed through `normalize_params`: gateway
-          # `preferences` are opaque provider values, and prefixed-ID resolution
-          # recurses into nested hashes — a Stripe `webhook_endpoint_id` like
-          # `we_1MqJ8b...` matches the prefixed-ID shape and would be decoded to
-          # an integer. `type` and `preferences` are added by `SubclassedResource`.
+          # `type` is read by `SubclassedResource` from the raw params.
+          # Deliberately NOT routed through `normalize_params`: `metadata` holds
+          # opaque merchant values, and prefixed-ID resolution recurses into
+          # nested hashes — a value like `we_1MqJ8b...` matches the prefixed-ID
+          # shape and would be decoded to an integer. `preferences` decode their
+          # own ids from their schema.
           def permitted_params
-            params.permit(
-              :name, :description, :active, :storefront_visible, :auto_capture, :capture_method, :position,
-              *model_additional_permitted_attributes,
-              metadata: {}, preferences: {}
-            )
+            params.permit(*permitted_attributes)
           end
 
           def scope

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

@@ -8,6 +8,14 @@ module Spree
         class PoliciesController < ResourceController
           scoped_resource :settings
 
+          request_params :policy do |body|
+            body.attribute :name, :string, required: true, on: :create, example: 'Wholesale Policy'
+            body.attribute :slug, :string, example: 'wholesale-policy'
+            body.attribute :body, :string,
+              nullable: true,
+              example: '<p>Trade orders ship within five working days.</p>'
+          end
+
           protected
 
           def model_class
@@ -18,10 +26,6 @@ module Spree
             Spree.api.admin_policy_serializer
           end
 
-          def resource_permitted_attributes
-            [:name, :slug, :body]
-          end
-
           # Accept slug (e.g. returns-policy) or prefixed ID (e.g. pol_abc123),
           # matching the storefront's lookup.
           def find_resource

data/app/controllers/spree/api/v3/admin/price_lists_controller.rb

@@ -26,9 +26,35 @@ module Spree
           # actions. Wrapping it under a different name keeps both.
           before_action :load_member_resource, only: [:activate, :deactivate]
 
+          request_params :price_list do |body|
+            body.attribute :name, :string, required: true, on: :create, example: 'EU wholesale'
+            body.attribute :description, :string, nullable: true
+            body.attribute :position, :integer, example: 1
+            body.attribute :starts_at, :datetime,
+              nullable: true,
+              example: '2026-06-01T00:00:00Z',
+              description: 'Pair with `ends_at` to schedule the list: activating a list whose start is in the future marks it `scheduled`.'
+            body.attribute :ends_at, :datetime, nullable: true, example: '2026-09-01T00:00:00Z'
+            body.attribute :match_policy, :string,
+              choices: Spree::PriceList::MATCH_POLICIES,
+              example: 'all',
+              description: '`all`: every rule must match. `any`: one matching rule is enough.'
+            body.attribute :price_adjustment_percentage, :decimal,
+              nullable: true,
+              example: '-15.0',
+              description: 'Signed: negative discounts off base prices, positive marks up.'
+            body.attribute :adjust_compare_at, :boolean
+            body.attribute :rules, :array, of: Spree::Api::V3::Admin::PriceListRuleRequestSchema,
+              description: 'The complete rule set: rules are matched by `id` and updated, new ones are built, and rules left out are removed.'
+            body.attribute :price_adjustment_tiers, :array, of: Spree::Api::V3::Admin::PriceAdjustmentTierRequestSchema,
+              description: "Quantity bands on the list's percentage. The payload is the whole ladder: a band left out is removed."
+            body.attribute :prices, :array, of: Spree::Api::V3::Admin::PriceListPriceRequestSchema,
+              description: 'Per-variant price overrides. Each row upserts, so the variants it names become part of the list. Curating whole products goes through the nested products endpoint instead.'
+          end
+
           # GET /api/v3/admin/price_lists/price_rule_types
           #
-          # Returns `[{ type, label, description, preference_schema }]`
+          # Returns `[{ type, label, description, schema }]`
           # for every registered subclass in `Spree.pricing.rules`. The
           # SPA uses this to build the "Add rule" picker + render a
           # generic preferences form per subclass. Rules themselves are
@@ -97,20 +123,6 @@ module Spree
             [:price_adjustment_tiers]
           end
 
-          def permitted_params
-            normalize_params(
-              params.permit(
-                *model_additional_permitted_attributes,
-                :name, :description, :position,
-                :starts_at, :ends_at, :match_policy,
-                :price_adjustment_percentage, :adjust_compare_at,
-                rules: [:id, :type, { preferences: {} }],
-                price_adjustment_tiers: [:min_quantity, :percentage],
-                prices: [:id, :variant_id, :currency, :min_quantity, :amount, :compare_at_amount]
-              )
-            )
-          end
-
           private
 
           # Loads the record without the action-derived authorization