spree_api 6.0.0.beta4 → 6.0.0.rc2

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

@@ -8,6 +8,82 @@ module Spree
 
           scoped_resource :products
 
+          # Product is purely a catalog grouping in API v3: every purchasable
+          # attribute lives on variants (docs/plans/6.0-remove-master-variant.md).
+          request_params :product do |body|
+            body.external_references
+            body.attribute :name, :string, required: true, on: :create, example: 'Premium T-Shirt'
+            body.attribute :description, :string,
+              description: 'Rich text HTML. Reads come back as this (plain text) plus `description_html`.'
+            body.attribute :slug, :string
+            body.attribute :status, :string, choices: Spree::Product::STATUSES, open: true
+            body.attribute :meta_title, :string
+            body.attribute :meta_description, :string
+            body.attribute :meta_keywords, :string
+            body.attribute :tax_category_id, :id
+            body.attribute :product_type_id, :id,
+              nullable: true,
+              description: 'The product type this product is created from (`pt_...`). Its option types and categories seed onto the product and its custom field definitions drive the product form. Editing the type later never rewrites existing products.'
+            body.attribute :delivery_profile_id, :id,
+              nullable: true,
+              description: 'The delivery profile deciding how this product ships (`fp_...`); null falls back to the store default.'
+            body.attribute :promotionable, :boolean
+            body.attribute :tags, :array, of: :string, example: %w[eco sale]
+            body.attribute :category_ids, :array, of: :id
+            # Reachable with `write_products` rather than `write_collections`:
+            # filing a product into its groupings is part of maintaining it.
+            body.attribute :collection_ids, :array, of: :id,
+              description: 'Manual collections this product belongs to. Automatic collections are kept as they are, since their rules decide membership.'
+            body.attribute :metadata, :hash
+            body.attribute :prices, :array, of: Spree::Api::V3::PriceRequestSchema,
+              description: "Shorthand for a simple (no-options) product: per-currency prices that forward to the product's sole variant. For products with options, set prices per variant under `variants` instead. Don't pass both."
+            body.attribute :custom_fields, :array, of: Spree::Api::V3::CustomFieldValueRequestSchema,
+              description: 'Custom field values, each validated against its definition.'
+            # `external_url` is left out on purpose: it makes the server fetch
+            # a URL the caller chose, so it belongs to trusted importers.
+            body.attribute :media, :array,
+              as: 'ProductMediaParams',
+              description: 'Media written with the product. Entries with `id` update an existing asset; entries with `signed_id` attach a fresh upload; an external video needs only its URL.' do |media_item|
+              media_item.attribute :id, :id
+              media_item.attribute :signed_id, :string, description: 'A `signed_id` from `files.upload()`.'
+              media_item.attribute :source_media_id, :id, description: 'Copies an asset from the media library.'
+              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
+            body.attribute :digital_assets, :array,
+              as: 'ProductDigitalAssetParams',
+              description: 'Downloadable files written with the product. Each entry carries a `signed_id` (an upload to private storage) or a `provider_type` (a provider-backed asset), and attaches to the default variant unless `variant_id` is given. An `id` updates that asset in place, so replaying the list does not duplicate it; removal uses the nested digital assets endpoint.' do |digital_asset|
+              digital_asset.attribute :id, :id
+              digital_asset.attribute :signed_id, :string
+              digital_asset.attribute :variant_id, :id
+              digital_asset.attribute :provider_type, :string,
+                description: 'A provider shorthand from the digital asset providers endpoint.'
+              digital_asset.attribute :provider_settings, :hash,
+                description: "Values for the provider's settings schema, keyed by field name."
+              digital_asset.attribute :authorized_clicks, :integer,
+                nullable: true,
+                description: "Null means the store's download settings apply."
+              digital_asset.attribute :authorized_days, :integer,
+                nullable: true,
+                description: "Null means the store's download settings apply."
+            end
+            body.attribute :product_publications, :array, as: 'ProductPublicationParams' do |product_publication|
+              product_publication.attribute :id, :id
+              product_publication.attribute :channel_id, :id
+              product_publication.attribute :published_at, :datetime, nullable: true
+              product_publication.attribute :unpublished_at, :datetime, nullable: true
+            end
+            body.attribute :variants, :array,
+              as: 'ProductVariantParams',
+              description: 'Every purchasable attribute (sku, prices, stock, weight, dimensions) lives on variants. An entry without `options` upserts onto the default variant of a simple product; pass `id` to update an existing variant.' do |variant|
+              variant.attribute :id, :id
+              variant.include_attributes Spree::Api::V3::VariantRequestSchema
+              variant.attribute :options, :array, of: Spree::Api::V3::VariantOptionRequestSchema,
+                description: 'One pair per option type the variant takes part in (size, color). Option types and values are created when missing.'
+            end
+          end
+
           before_action :require_ids!, only: [
             :bulk_status_update,
             :bulk_add_to_categories,
@@ -19,6 +95,42 @@ module Spree
             :bulk_destroy
           ]
 
+          request_params 'ProductRejectParams', action: :reject do |body|
+            body.attribute :reason, :string,
+              description: 'Why the submission was turned down. Sent back to the seller.'
+          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: Spree::Product::STATUSES,
+              description: 'Products in review are skipped and counted in `skipped_in_review_count`.'
+          end
+
+          {
+            'ProductBulkCategoriesParams' => [:category_ids, %i[bulk_add_to_categories bulk_remove_from_categories]],
+            'ProductBulkCollectionsParams' => [:collection_ids, %i[bulk_add_to_collections bulk_remove_from_collections]],
+            'ProductBulkChannelsParams' => [:channel_ids, %i[bulk_add_to_channels bulk_remove_from_channels]]
+          }.each do |name, (field, actions)|
+            actions.each do |action|
+              request_params(name, action: action) do |body|
+                body.attribute :ids, :array, of: :id, required: true
+                body.attribute field, :array, of: :id, required: true
+              end
+            end
+          end
+
+          %i[bulk_add_tags bulk_remove_tags].each do |action|
+            request_params('BulkTagsParams', action: action) { |body| body.include_attributes Spree::Api::V3::Admin::BulkTagsRequestSchema }
+          end
+
+          request_params 'ProductBulkDestroyParams', action: :bulk_destroy do |body|
+            body.attribute :ids, :array, of: :id,
+              required: true,
+              description: 'Products the caller cannot delete are skipped.'
+          end
+
           # POST /api/v3/admin/products/:id/clone
           def clone
             @resource = find_resource
@@ -54,7 +166,7 @@ module Spree
             unless Spree::Product::STATUSES.include?(params[:status].to_s)
               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
@@ -155,6 +267,14 @@ module Spree
 
           protected
 
+          def additional_sort_fields
+            Spree::SearchProvider::Base::SORT_FIELDS
+          end
+
+          def custom_field_filters?
+            true
+          end
+
           def model_class
             Spree::Product
           end
@@ -201,76 +321,7 @@ module Spree
           end
 
           def permitted_params
-            # Product is purely a catalog grouping in API v3. All purchasable
-            # attributes (sku, barcode, price, weight, dimensions, stock,
-            # track_inventory) live on variants. See
-            # docs/plans/6.0-remove-master-variant.md.
-            #
-            # Top-level `prices` is a convenience for simple (no-options)
-            # products: the merchant doesn't need to know about the default
-            # variant, so they ship prices alongside name/status and the
-            # `Spree::Product#prices=` setter forwards them to it.
-            params.permit(
-              *model_additional_permitted_attributes,
-              :name, :description, :slug, :status,
-              :meta_title, :meta_description, :meta_keywords,
-              :tax_category_id, :product_type_id, :delivery_profile_id,
-              :promotionable,
-              tags: [],
-              category_ids: [],
-              # Manual collection membership only — the model setter ignores
-              # incoming automatic collections and preserves the product's
-              # existing ones, since those are materialized from their rules.
-              #
-              # Deliberately reachable with `write_products` rather than
-              # `write_collections`: filing a product into its groupings is part
-              # of maintaining the product, which is why `category_ids` and the
-              # bulk membership endpoints have always worked this way too.
-              # Creating or configuring a collection still needs
-              # `write_collections`.
-              collection_ids: [],
-              metadata: {},
-              prices: [:amount, :compare_at_amount, :currency],
-              # Inline custom field values keyed by definition id. The model
-              # setter (`Spree::HasCustomFields#custom_fields=`) validates each
-              # entry against its definition. We permit `value` as a scalar AND
-              # as `value: []` / `value: {}` so JSON custom_fields round-trip
-              # whether the parsed payload is an array or an object, while
-              # text/number/boolean ship scalars.
-              custom_fields: [:id, :custom_field_definition_id, :value, { value: [] }, { value: {} }],
-              # Inline media. Entries with `id` patch an existing asset.
-              # Entries with `signed_id` create + attach a fresh upload; an
-              # external video creates with a URL and no file. Lets the
-              # dashboard ship media changes alongside the rest of the product
-              # form. See `Spree::Products::NestedAttributes`.
-              #
-              # `external_url` is deliberately not permitted here: it makes the
-              # server fetch a URL the caller chose, so it belongs to trusted
-              # importers rather than to a request body.
-              media: [*Spree::Media::WRITABLE_ATTRIBUTES, :id, :signed_id, :source_media_id, { variant_ids: [] }],
-              # Inline digital files, so a new product ships its downloadable
-              # files in the same request. Additive: an entry carries a
-              # `signed_id` (uploaded file) or a `provider_type` (provider-backed
-              # asset), and an `id` patches that asset in place rather than
-              # building a duplicate — so replaying a product's list on update
-              # does not accumulate copies. Removal uses the nested
-              # digital_assets endpoint. See `Spree::Product#digital_assets=`.
-              digital_assets: [:id, :signed_id, :variant_id, :provider_type, :authorized_clicks, :authorized_days, provider_settings: {}],
-              product_publications: [:id, :channel_id, :published_at, :unpublished_at],
-              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,
-                :seller_id, :delivery_profile_id,
-                :track_inventory, :preorderable, :preorder_ships_at, :backorder_limit, :tax_category_id, :position,
-                options: [:name, :value],
-                prices: [:amount, :compare_at_amount, :currency],
-                stock_levels: [:id, :stock_location_id, :count_on_hand, :backorderable]
-              ]
-            ).tap { |attrs| attrs.delete(:status) if review_status?(attrs[:status]) }
+            params.permit(*permitted_attributes).tap { |attrs| attrs.delete(:status) if review_status?(attrs[:status]) }
           end
 
           # A review status is an outcome, not a value to assign: `proposed`

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

@@ -13,6 +13,15 @@ module Spree
           subclassed_via -> { Spree.promotions.actions },
                          unknown_type_error: 'unknown_promotion_action_type'
 
+          request_params :promotion_action do |body|
+            body.attribute :type, :string,
+              required: true, on: :create,
+              only: :create,
+              example: 'free_shipping',
+              description: 'The action kind, from `GET /promotion_actions/types`.'
+            body.include_attributes Spree::Api::V3::Admin::PromotionActionRequestSchema
+          end
+
           def types
             authorize! :read, model_class
 
@@ -38,7 +47,7 @@ module Spree
               {
                 type: calc.api_type,
                 label: calc.respond_to?(:description) ? calc.description : calc.to_s.demodulize.titleize,
-                preference_schema: calc.respond_to?(:serialized_preference_schema) ? calc.serialized_preference_schema : []
+                schema: calc.preference_json_schema
               }
             end.sort_by { |entry| entry[:label].to_s }
 
@@ -56,7 +65,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(*model_additional_permitted_attributes, :type, preferences: {})
+            params.permit(*permitted_attributes)
           end
 
           # `types`/`calculators` are read-only discovery — read scope + :show ability.
@@ -71,10 +80,6 @@ module Spree
                                    .find_by_prefix_id!(params[:promotion_id])
           end
 
-          def parent_association
-            :promotion_actions
-          end
-
           private
 
           def build_subclassed_resource(klass, attrs)

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

@@ -13,6 +13,15 @@ module Spree
           subclassed_via -> { Spree.promotions.rules },
                          unknown_type_error: 'unknown_promotion_rule_type'
 
+          request_params :promotion_rule do |body|
+            body.attribute :type, :string,
+              required: true, on: :create,
+              only: :create,
+              example: 'currency',
+              description: 'The rule kind, from `GET /promotion_rules/types`.'
+            body.include_attributes Spree::Api::V3::Admin::PromotionRuleRequestSchema
+          end
+
           def types
             authorize! :read, model_class
 
@@ -30,7 +39,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(*model_additional_permitted_attributes, :type, preferences: {})
+            params.permit(*permitted_attributes)
           end
 
           # `types` is read-only discovery — maps to the read scope + :show ability.
@@ -45,10 +54,6 @@ module Spree
                                    .find_by_prefix_id!(params[:promotion_id])
           end
 
-          def parent_association
-            :promotion_rules
-          end
-
           private
 
           def build_subclassed_resource(klass, attrs)

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

@@ -5,6 +5,51 @@ module Spree
         class PromotionsController < ResourceController
           scoped_resource :promotions
 
+          request_params :promotion do |body|
+            body.attribute :name, :string, required: true, on: :create
+            body.attribute :description, :string, nullable: true
+            body.attribute :code, :string,
+              nullable: true,
+              description: 'Required for single-code coupon promotions. Ignored when `multi_codes` is true.'
+            body.attribute :path, :string, nullable: true
+            body.attribute :starts_at, :datetime, nullable: true
+            body.attribute :expires_at, :datetime, nullable: true
+            body.attribute :usage_limit, :integer, nullable: true
+            body.attribute :match_policy, :string, choices: Spree::Promotion::MATCH_POLICIES
+            body.attribute :kind, :string,
+              choices: Spree::Promotion.kinds.keys,
+              description: '`coupon_code` needs a code (or `multi_codes`); `automatic` applies without one.'
+            body.attribute :multi_codes, :boolean,
+              description: 'Generates `number_of_codes` codes starting with `code_prefix`.'
+            body.attribute :number_of_codes, :integer, nullable: true
+            body.attribute :code_prefix, :string, nullable: true
+            body.attribute :promotion_category_id, :id, nullable: true
+            # Rules and actions are permitted below, with the keys each
+            # registered kind adds.
+            body.attribute :rules, :array,
+              permit: false,
+              as: 'PromotionRuleDraftParams',
+              description: 'The rules the promotion should have: entries with `id` update, entries without are created, and rules left out are removed.' do |rule|
+              rule.attribute :id, :id
+              rule.attribute :type, :string,
+                required: true,
+                example: 'currency',
+                description: 'The rule kind, from `GET /promotion_rules/types`.'
+              rule.include_attributes Spree::Api::V3::Admin::PromotionRuleRequestSchema
+            end
+            body.attribute :actions, :array,
+              permit: false,
+              as: 'PromotionActionDraftParams',
+              description: 'The actions the promotion should have, matched the same way as `rules`.' do |action|
+              action.attribute :id, :id
+              action.attribute :type, :string,
+                required: true,
+                example: 'free_shipping',
+                description: 'The action kind, from `GET /promotion_actions/types`.'
+              action.include_attributes Spree::Api::V3::Admin::PromotionActionRequestSchema
+            end
+          end
+
           protected
 
           def model_class
@@ -23,21 +68,12 @@ module Spree
             promotion_includes
           end
 
-          # A single POST/PATCH /promotions can ship rules and actions
-          # alongside the basics; `Promotion#rules=` / `actions=` reconcile
-          # to the desired set. The nested allowlist below is the union of
-          # every built-in rule/action's expected keys. Plugin-defined
-          # subclasses can add to it — see `additional_permitted_attributes`
-          # below.
+          # `Promotion#rules=` / `actions=` reconcile to the desired set. The
+          # nested allowlists are the union of every registered rule/action
+          # kind's keys, so plugin-defined kinds add to them through
+          # `additional_permitted_attributes`.
           def resource_permitted_attributes
-            [
-              :name, :description, :code, :path,
-              :starts_at, :expires_at, :usage_limit, :match_policy,
-              :kind, :multi_codes, :number_of_codes, :code_prefix,
-              :promotion_category_id,
-              rules: rule_attributes,
-              actions: action_attributes
-            ]
+            [*super, { rules: rule_attributes, actions: action_attributes }]
           end
 
           def rule_attributes

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

@@ -16,6 +16,53 @@ module Spree
 
           scoped_resource :purchasing
 
+          # The supplier, the warehouse and the lines are read from the raw
+          # params and resolved through the store (see ReceivableActions), so
+          # only the document's own fields are permitted.
+          request_params :purchase_order do |body|
+            body.attribute :supplier_id, :id, required: true, on: :create, permit: false, example: 'sup_1234567890'
+            body.attribute :destination_location_id, :id,
+              required: true, on: :create,
+              permit: false,
+              example: 'sloc_1234567890'
+            body.attribute :currency, :currency,
+              nullable: true,
+              example: 'USD',
+              description: "Defaults to the store's currency; set it for a foreign-currency order."
+            body.attribute :expected_at, :date,
+              nullable: true,
+              example: '2026-10-01',
+              description: 'The day the supplier promised. `null` clears it.'
+            body.attribute :cancel_by, :date,
+              nullable: true,
+              description: 'The day after which the goods are no longer wanted. `null` clears it.'
+            body.attribute :reference, :string,
+              nullable: true,
+              description: "The supplier's own order number. `null` clears it."
+            body.attribute :notes, :string, nullable: true
+            body.attribute :items, :array,
+              permit: false,
+              as: 'PurchaseOrderItemParams',
+              description: 'Sending the list replaces whatever the order currently holds.' do |item|
+              item.attribute :variant_id, :id, required: true, example: 'variant_1234567890'
+              item.attribute :quantity_ordered, :integer, required: true, example: 100
+              item.attribute :unit_cost, :decimal,
+                example: '12.50',
+                description: 'What the merchant agreed to pay per unit.'
+            end
+            body.attribute :metadata, :hash, nullable: true
+          end
+
+          request_params 'ReceivableCloseParams', action: :close do |body|
+            body.attribute :reason, :string, nullable: true, description: 'Why the balance is not coming.'
+          end
+
+          request_params 'PurchaseOrderCancelParams', action: :cancel do |body|
+            body.attribute :reason, :string,
+              example: 'Supplier went under',
+              description: "Appended to the order's notes."
+          end
+
           # The base registers this for show/update/destroy; a second
           # `before_action :set_resource` replaces that registration rather than
           # adding to it, so those three are listed again here.
@@ -31,7 +78,7 @@ module Spree
 
             render_error(
               code: 'invalid_status',
-              message: Spree.t('purchase_order.errors.only_draft_can_be_deleted'),
+              message: I18n.t('spree.purchase_order.errors.only_draft_can_be_deleted'),
               status: :unprocessable_content
             )
           end
@@ -109,6 +156,7 @@ module Spree
               cancel_by: params[:cancel_by],
               reference: params[:reference],
               notes: params[:notes],
+              metadata: metadata_from_params,
               created_by: try_spree_current_user
             }
           end
@@ -121,13 +169,6 @@ module Spree
             }
           end
 
-          # The supplier and the warehouse are resolved through the store
-          # instead, since an id the payload names has to be proved to belong
-          # here.
-          def resource_permitted_attributes
-            [:currency, :expected_at, :cancel_by, :reference, :notes, { metadata: {} }]
-          end
-
           def editable_attributes
             attributes = permitted_params.to_h.symbolize_keys
             attributes[:supplier] = supplier_from_params if params.key?(:supplier_id)
@@ -143,6 +184,12 @@ module Spree
 
           private
 
+          # Merchant data, stored as sent: never through the prefixed-id decoding
+          # `permitted_params` applies.
+          def metadata_from_params
+            params.permit(*declared_permitted_attributes)[:metadata]&.to_h
+          end
+
           # Read through `current_store` rather than the model constant: a
           # supplier id belonging to another store must 404, which no ability
           # check would catch.

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

@@ -5,6 +5,10 @@ module Spree
         class RefundReasonsController < ResourceController
           scoped_resource :settings
 
+          request_params :reason do |body|
+            body.include_attributes Spree::Api::V3::Admin::ReasonRequestSchema
+          end
+
           protected
 
           def model_class
@@ -16,7 +20,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(*model_additional_permitted_attributes, :name, :active)
+            params.permit(*permitted_attributes)
           end
         end
       end

data/app/controllers/spree/api/v3/admin/reporting/saved_reports_controller.rb

@@ -11,6 +11,14 @@ module Spree
           class SavedReportsController < ResourceController
             scoped_resource :reports
 
+            request_params :saved_report do |body|
+              body.attribute :name, :string, required: true, on: :create
+              body.attribute :description, :string, nullable: true
+              body.attribute :query, :hash,
+                required: true, on: :create,
+                description: 'A reporting query, validated against the reporting registry on save.'
+            end
+
             protected
 
             def model_class
@@ -31,7 +39,7 @@ module Spree
             # nested hashes — they would be decoded to integers on save and
             # never resolve again. Extension attributes are splatted in.
             def permitted_params
-              params.permit(:name, :description, *model_additional_permitted_attributes, query: {})
+              params.permit(*permitted_attributes)
             end
 
             def build_resource

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

@@ -14,6 +14,40 @@ module Spree
 
           QUERY_KEYS = %w[metrics dimensions filters metric_filters time_range compare sort limit currency].freeze
 
+          request_params 'ReportingQueryParams', action: :query do |body|
+            body.attribute :metrics, :array, of: :string,
+              required: true,
+              description: 'Registered metric names, from the reporting schema endpoint.'
+            body.attribute :dimensions, :array, of: :any, permit: false, description: <<~TEXT.squish
+              Up to #{Spree::Reporting::Query::MAX_DIMENSIONS} dimensions to break the metrics down by. Each is a dimension
+              name, or `{ name, grain, include_empty }`: `grain` (`hour`, `day`, `week`, `month`) buckets a time
+              dimension, and `include_empty` lists members with no matching rows where the schema entry supports it.
+            TEXT
+            body.attribute :filters, :array, description: 'Narrows the rows by dimension value.' do |filter|
+              filter.attribute :dimension, :string, required: true
+              filter.attribute :op, :string, required: true, choices: Spree::Reporting::Query::FILTER_OPS
+              filter.attribute :value, :any, required: true, description: 'One value for `eq`, a list for `in`.'
+            end
+            body.attribute :metric_filters, :array,
+              description: "Filters on an aggregate, such as `units_sold = 0`. Narrows the rows only; the totals stay the period's real figure. The metric must also appear in `metrics`, and cannot be a derived one." do |metric_filter|
+              metric_filter.attribute :metric, :string, required: true
+              metric_filter.attribute :op, :string,
+                required: true,
+                choices: Spree::Reporting::Query::METRIC_FILTER_OPS
+              metric_filter.attribute :value, :number, required: true
+            end
+            body.attribute :time_range, :object,
+              description: "A named preset (`last_month`, `week_to_date`, any `last_<n>_<days|weeks|months>`), or ISO 8601 dates or times in `since` and `until` (a bare date covers the store's whole day). Defaults to the last 30 days, in the store's time zone." do |time_range|
+              time_range.attribute :preset, :string
+              time_range.attribute :since, :string
+              time_range.attribute :until, :string
+            end
+            body.attribute :compare, :string, choices: Spree::Reporting::Query::COMPARE_MODES
+            body.attribute :sort, :string, description: 'A metric name; prefix it with `-` to sort descending.'
+            body.attribute :limit, :integer, description: "At most #{Spree::Reporting::Query::MAX_LIMIT}."
+            body.attribute :currency, :currency
+          end
+
           # POST /api/v3/admin/reporting/query
           def query
             reporting_query = Spree::Reporting::Query.new(store: current_store, params: query_params)

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

@@ -9,6 +9,7 @@ module Spree
           include Spree::Api::V3::Admin::StoreContext
           include Spree::Api::V3::AdminAuthentication
           include Spree::Api::V3::ScopedAuthorization
+          include Spree::Api::V3::StrictMoneyParams
           # External-identity addressing for every admin resource whose model
           # opts in via Spree::HasExternalReferences — the concern's guards
           # no-op for everything else. Sitting here rather than per controller
@@ -84,7 +85,7 @@ module Spree
           def render_invalid_position
             render_error(
               code: ERROR_CODES[:validation_error],
-              message: Spree.t('api.errors.invalid_position', default: 'new_position must be an integer'),
+              message: I18n.t('spree.api.errors.invalid_position'),
               status: :unprocessable_content
             )
           end

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

@@ -5,6 +5,10 @@ module Spree
         class ReturnReasonsController < ResourceController
           scoped_resource :settings
 
+          request_params :reason do |body|
+            body.include_attributes Spree::Api::V3::Admin::ReasonRequestSchema
+          end
+
           protected
 
           def model_class
@@ -16,7 +20,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(*model_additional_permitted_attributes, :name, :active)
+            params.permit(*permitted_attributes)
           end
         end
       end

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

@@ -13,6 +13,18 @@ module Spree
 
           scoped_resource :staff
 
+          request_params :role do |body|
+            body.attribute :name, :string,
+              required: true, on: :create,
+              example: 'order_manager',
+              description: 'Unique role name, the machine identifier shown capitalized in the dashboard.'
+            body.attribute :description, :string, nullable: true, example: 'Handles daily orders'
+            # A caller may only grant permissions they hold themselves.
+            body.attribute :permissions, :array, of: :string,
+              example: %w[write_orders read_customers],
+              description: 'Permission keys (`read_orders`, `write_products`, ...) from the permissions endpoint. You can only grant keys you hold yourself.'
+          end
+
           # POST /api/v3/admin/roles
           # A caller may only grant permissions they effectively hold — the
           # same anti-amplification rule as role grants and API-key minting.
@@ -58,7 +70,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(*model_additional_permitted_attributes, :name, :description, permissions: [])
+            params.permit(*permitted_attributes)
           end
 
           private