spree_api 6.0.0.rc1 → 6.0.0.rc2

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

@@ -13,6 +13,47 @@ module Spree
           before_action :require_ids!, only: [:bulk_destroy]
           before_action :require_prices!, only: [:bulk_upsert]
 
+          # variant_id and price_list_id resolve through the current store's
+          # scopes (+permitted_params+), so a foreign or unknown id 404s.
+          request_params :price do |body|
+            body.attribute :variant_id, :id, required: true, on: :create, example: 'variant_xY9'
+            body.attribute :currency, :currency, required: true, on: :create, example: 'USD'
+            body.attribute :min_quantity, :integer,
+              description: 'The quantity a line must reach for this price to apply. Omit for the bottom rung of the ladder. Anything above 1 requires a `price_list_id`.'
+            body.attribute :amount, :decimal, nullable: true, example: '19.99'
+            body.attribute :compare_at_amount, :decimal, nullable: true, example: '19.99'
+            body.attribute :price_list_id, :id,
+              nullable: true,
+              example: 'pl_aBc123',
+              description: 'Omit or null for a base price; a price list for a list override.'
+          end
+
+          request_params 'PriceBulkUpsertParams', action: :bulk_upsert do |body|
+            body.attribute :prices, :array,
+              required: true,
+              as: 'PriceBulkUpsertRowParams',
+              description: 'Send an empty list to change nothing.' do |price|
+              price.attribute :id, :id,
+                nullable: true,
+                example: 'price_aBc123',
+                description: 'Present: updates that row. Absent: upserts on `(variant_id, currency, price_list_id, min_quantity)`.'
+              price.attribute :variant_id, :id, required: true, example: 'variant_xY9'
+              price.attribute :currency, :currency, required: true, example: 'USD'
+              price.attribute :price_list_id, :id,
+                nullable: true,
+                example: 'pl_aBc123',
+                description: 'Omit or null for a base price.'
+              price.attribute :min_quantity, :integer,
+                description: "The rung of the variant's ladder. Omit for the bottom rung; anything above 1 requires a `price_list_id`. A variant carries at most ten rungs on one list per currency."
+              price.attribute :amount, :decimal, nullable: true, example: '19.99'
+              price.attribute :compare_at_amount, :decimal, nullable: true, example: '19.99'
+            end
+          end
+
+          request_params 'PriceBulkDestroyParams', action: :bulk_destroy do |body|
+            body.attribute :ids, :array, of: :id, required: true, example: %w[price_aBc123]
+          end
+
           # Bulk-upserts prices on the unique key
           # `(variant_id, currency, price_list_id, min_quantity)` — one row per
           # rung of a variant's ladder (docs/plans/6.0-volume-pricing.md).
@@ -67,6 +108,15 @@ module Spree
               )
             end
 
+            if (malformed = result.error&.value.try(:[], :malformed_amounts))
+              return render_error(
+                code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:invalid_money_format],
+                message: I18n.t('activerecord.errors.models.spree/price_list.attributes.base.malformed_price').upcase_first,
+                status: :unprocessable_content,
+                details: { rows: malformed }
+              )
+            end
+
             if (negative = result.error&.value.try(:[], :invalid_amounts))
               return render_error(
                 code: 'invalid_amount',
@@ -160,11 +210,8 @@ module Spree
             false
           end
 
-          # Resolves variant_id / price_list_id through the current store's
-          # scopes so a foreign or unknown id 404s instead of binding the
-          # price to another store's record.
           def permitted_params
-            permitted = params.permit(*model_additional_permitted_attributes, :variant_id, :currency, :min_quantity, :amount, :compare_at_amount, :price_list_id)
+            permitted = params.permit(*permitted_attributes)
             permitted[:variant_id] = store_variants.find_by_prefix_id!(permitted[:variant_id]).id if permitted[:variant_id].present?
             permitted[:price_list_id] = store_price_lists.find_by_prefix_id!(permitted[:price_list_id]).id if permitted[:price_list_id].present?
             permitted

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

@@ -11,6 +11,30 @@ module Spree
         class ProductTypesController < ResourceController
           scoped_resource :product_types
 
+          # The associations are a template for products created with this type:
+          # replace-sets that never change the products already carrying it.
+          request_params :product_type do |body|
+            body.attribute :name, :string, required: true, on: :create, example: 'Hoodie'
+            body.attribute :delivery_profile_id, :id,
+              nullable: true,
+              example: 'fp_86Rf07xd4z',
+              description: 'Delivery profile stamped onto products created with this type. Null leaves new products on the store default profile.'
+            body.attribute :option_type_ids, :array, of: :id,
+              description: 'Option types seeded onto products that get this type. Use apply to products to backfill existing ones.'
+            body.attribute :category_ids, :array, of: :id,
+              description: 'Categories seeded onto products that get this type. Categories from other stores are ignored.'
+            body.attribute :custom_field_definitions, :array,
+              as: 'ProductTypeCustomFieldDefinitionParams',
+              description: 'The custom field definitions the product form shows. Definitions not listed are removed from the type.' do |custom_field_definition|
+              custom_field_definition.attribute :id, :id,
+                required: true,
+                example: 'cfdef_abc123',
+                description: 'The custom field definition.'
+              custom_field_definition.attribute :required, :boolean
+              custom_field_definition.attribute :sort_order, :integer
+            end
+          end
+
           # Backfills this type's option types and categories onto the products
           # that already carry it. Additive and idempotent — nothing is removed.
           def apply_to_products
@@ -50,14 +74,7 @@ module Spree
           end
 
           def permitted_params
-            attrs = params.permit(
-              *model_additional_permitted_attributes,
-              :name,
-              :delivery_profile_id,
-              option_type_ids: [],
-              category_ids: [],
-              custom_field_definitions: [:id, :required, :sort_order]
-            )
+            attrs = params.permit(*permitted_attributes)
             attrs = scope_delivery_profile(attrs)
             scope_category_ids(attrs)
           end

data/app/controllers/spree/api/v3/admin/products/digital_assets_controller.rb

@@ -6,6 +6,32 @@ module Spree
           class DigitalAssetsController < ResourceController
             scoped_resource :products
 
+            request_params :digital_asset do |body|
+              # Names a blob rather than a column, so it is attached
+              # separately (+attach_uploaded_file+).
+              body.attribute :signed_id, :string,
+                permit: false,
+                description: "A `signed_id` from `files.upload()` with `visibility: 'private'`. Required for an uploaded file, omitted for a provider-backed asset. On update it replaces the file for everyone who already bought it."
+              # Resolved through the parent rather than assigned, so an asset
+              # can't be pointed at a variant of another product or store.
+              body.attribute :variant_id, :id,
+                permit: false,
+                description: "Defaults to the product's default variant when omitted."
+              # The model validates it names a registered provider.
+              body.attribute :provider_type, :string,
+                description: 'A provider shorthand from the providers endpoint. Omit for an uploaded file.'
+              # Its keys are declared by the provider, so it lands verbatim
+              # under one key in the asset's metadata.
+              body.attribute :provider_settings, :hash,
+                description: "Values for the provider's settings schema, keyed by field name."
+              body.attribute :authorized_clicks, :integer,
+                nullable: true,
+                description: "Null means the store's download settings apply."
+              body.attribute :authorized_days, :integer,
+                nullable: true,
+                description: "Null means the store's download settings apply."
+            end
+
             # PATCH /api/v3/admin/products/:product_id/digital_assets/:id
             #
             # Replacing the file keeps every already-issued link working, since
@@ -84,17 +110,8 @@ module Spree
               [:variant, { attachment_attachment: :blob }]
             end
 
-            # variant_id is resolved through the parent rather than assigned:
-            # mass-assigning it would let a caller point an asset at a variant
-            # of any product, in any store. signed_id likewise names a blob
-            # rather than a column, so it is attached separately.
-            # provider_type is mass-assignable: the model validates it names a
-            # registered provider, so an unknown value is a 422, not a hazard.
-            # provider_settings is an open hash — its keys are declared by the
-            # provider, not fixed here — so it is permitted as arbitrary scalars
-            # and lands verbatim under one key in the asset's metadata.
             def permitted_params
-              params.permit(:authorized_clicks, :authorized_days, :provider_type, provider_settings: {})
+              params.permit(*declared_permitted_attributes)
             end
 
             private

data/app/controllers/spree/api/v3/admin/products/variants_controller.rb

@@ -6,6 +6,14 @@ module Spree
           class VariantsController < ResourceController
             scoped_resource :products
 
+            request_params :variant do |body|
+              body.external_references
+              body.include_attributes Spree::Api::V3::VariantRequestSchema
+              body.attribute :options, :array, of: Spree::Api::V3::VariantOptionRequestSchema,
+                required: true, on: :create,
+                description: 'One pair per option type the variant takes part in (size, color). Option types and values are created when missing. On update, omit to leave the option values untouched.'
+            end
+
             protected
 
             def model_class
@@ -42,20 +50,7 @@ module Spree
             end
 
             def permitted_params
-              params.permit(
-                *model_additional_permitted_attributes,
-                :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: [:stock_location_id, :count_on_hand, :backorderable]
-              )
+              params.permit(*permitted_attributes)
             end
           end
         end

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
@@ -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.

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.

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.
@@ -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.