spree_api 6.0.0.rc1 → 6.0.0.rc3

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

@@ -13,6 +13,13 @@ module Spree
           # grantable separately from store configuration (6.0-admin-rbac.md).
           scoped_resource :staff
 
+          request_params :invitation do |body|
+            body.attribute :email, :string, required: true, on: :create
+            body.attribute :role_id, :id,
+              required: true, on: :create,
+              description: 'The role (`role_...`) the invitee gets on accepting.'
+          end
+
           # POST /api/v3/admin/invitations
           # Guards against inviting a new staff member straight into the admin
           # super-role unless the inviter already holds it.
@@ -65,7 +72,7 @@ module Spree
           # No extension union: an invitation carries only the role grant, which is
           # the authorization surface itself, not extensible resource data.
           def permitted_params
-            attrs = params.permit(:email, :role_id)
+            attrs = params.permit(*declared_permitted_attributes)
             if attrs[:role_id].present? && Spree::PrefixedId.prefixed_id?(attrs[:role_id])
               attrs[:role_id] = Spree::PrefixedId.decode_prefixed_id(attrs[:role_id])
             end

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

@@ -14,7 +14,7 @@ module Spree
           def index
             render json: {
               data: current_store.supported_locales.map do |locale|
-                Spree.api.locale_serializer.new(locale).to_h
+                Spree.api.admin_locale_serializer.new(locale).to_h
               end
             }
           end

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

@@ -13,6 +13,36 @@ module Spree
         class MarketsController < ResourceController
           scoped_resource :settings
 
+          request_params :market do |body|
+            body.attribute :name, :string,
+              required: true, on: :create,
+              example: 'Europe',
+              description: 'Display name, unique within the store.'
+            body.attribute :currency, :currency,
+              required: true, on: :create,
+              example: 'EUR',
+              description: 'ISO 4217 currency code.'
+            body.attribute :default_locale, :locale,
+              required: true, on: :create,
+              example: 'de',
+              description: 'Locale used as the market default. Always part of `supported_locales`.'
+            body.attribute :tax_inclusive, :boolean, description: 'Display prices with tax included.'
+            body.attribute :tax_provider, :string,
+              nullable: true,
+              example: 'internal',
+              description: 'Shorthand of the tax engine that prices this market, from the tax providers endpoint. Null uses the installation default.'
+            body.attribute :default, :boolean,
+              description: 'Setting true demotes the previous default market of the store.'
+            body.attribute :position, :integer, description: 'Sort order within the store; lower comes first.'
+            body.attribute :supported_locales, :array, of: :locale,
+              example: %w[de en],
+              description: 'Locales available in this market. The default locale is always included.'
+            body.attribute :country_codes, :array, of: :country,
+              required: true, on: :create,
+              example: %w[DE FR],
+              description: 'ISO 3166-1 alpha-2 codes of the countries in this market. At least one is required.'
+          end
+
           protected
 
           def model_class
@@ -30,15 +60,6 @@ module Spree
           def scope
             super.ordered
           end
-
-          def permitted_params
-            normalize_params(
-              params.permit(
-                :name, :currency, :default_locale, :tax_inclusive, :tax_provider,
-                :default, :position, supported_locales: [], country_codes: []
-              )
-            )
-          end
         end
       end
     end

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

@@ -7,6 +7,15 @@ module Spree
 
           skip_scope_check!
 
+          request_params :me do |body|
+            body.attribute :selected_locale, :string, example: 'de', description: 'The dashboard display language.'
+            body.attribute :first_name, :string
+            body.attribute :last_name, :string
+            body.attribute :avatar_signed_id, :string,
+              nullable: true,
+              description: 'A `signed_id` from `files.upload()` to set the avatar, or null to remove it. Omit it to keep the current photo.'
+          end
+
           before_action :require_current_user!
 
           # GET /api/v3/admin/me
@@ -33,8 +42,8 @@ module Spree
           # name, admin UI language, and avatar) — it operates on `current_user`
           # directly, so it needs no per-record authorization. Distinct from
           # PATCH /admin_users/:id, which is store-scoped staff management of
-          # *other* users. `avatar` accepts an ActiveStorage direct-upload
-          # signed id to set the photo, or `null` to remove it.
+          # *other* users. `avatar_signed_id` takes a signed id from
+          # POST /files to set the photo, or `null` to remove it.
           def update
             if current_user.update(permitted_params)
               render json: me_response
@@ -70,7 +79,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(:selected_locale, :first_name, :last_name, :avatar)
+            params.permit(*declared_permitted_attributes)
           end
 
           def me_response

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

@@ -5,6 +5,27 @@ module Spree
         class MediaController < ResourceController
           scoped_resource :products
 
+          # The media file, a URL to fetch one from, and the library row to copy
+          # are transport, not attributes (+media_attributes+ drops them).
+          request_params :media do |body|
+            body.external_references
+            body.include_attributes Spree::Api::V3::MediaRequestSchema
+            body.attribute :attachment, :string,
+              description: 'The file itself, sent as multipart form data. JSON clients upload first and send `signed_id`.'
+            # How the file arrives, so creating only: an update keeps its file.
+            body.attribute :url, :string,
+              only: :create,
+              description: 'Fetch an image from this URL, in the background. Images only: an external video uses `external_video_url`.'
+            body.attribute :signed_id, :string,
+              only: :create,
+              description: 'A `signed_id` from `files.upload()` for the media file itself.'
+            body.attribute :source_media_id, :id,
+              only: :create,
+              description: 'Place a file that is already in the library. The new row shares the source file rather than copying it, and takes its own alt, position and variant links from here.'
+            body.attribute :variant_ids, :array, of: :id,
+              description: 'Variants to link this product-level media to. Variants of other products are dropped.'
+          end
+
           def create
             # An external video has no file, so it takes the plain create path
             # even though a URL is present — `url` means "fetch this image from
@@ -91,16 +112,8 @@ module Spree
             permitted_params.except(:attachment, :url, :signed_id, :source_media_id)
           end
 
-          # The media file, a URL to fetch one from, and the library row to copy
-          # are transport, not attributes — everything a client can set lives on
-          # the model.
           def permitted_params
-            params.permit(
-              *model_additional_permitted_attributes,
-              *Spree::Media::WRITABLE_ATTRIBUTES,
-              :attachment, :url, :signed_id, :source_media_id,
-              variant_ids: []
-            )
+            params.permit(*permitted_attributes)
           end
 
           def external_video_request?

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

@@ -19,6 +19,10 @@ module Spree
           # `products` — those are one product's own media, reached through a
           # product the caller can already see.
           scoped_resource :media
+
+          request_params :media_library do |body|
+            body.include_attributes MediaController.request_params_schema
+          end
           # Restates the base class's member actions with `usage` added — a
           # second `before_action :set_resource` would replace that filter
           # rather than extend it, leaving show/update/destroy without a record.

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

@@ -5,6 +5,29 @@ module Spree
         class OptionTypesController < ResourceController
           scoped_resource :products
 
+          request_params :option_type do |body|
+            body.attribute :name, :string, required: true, on: :create, example: 'color'
+            body.attribute :label, :string, required: true, on: :create, example: 'Color'
+            body.attribute :position, :integer
+            body.attribute :filterable, :boolean
+            body.attribute :kind, :string, choices: Spree::OptionType::KINDS
+            body.attribute :option_values, :array,
+              as: 'OptionValueParams',
+              description: 'Inline option values. Values left out of the list on update are destroyed, so send the full set every time.' do |option_value|
+              option_value.attribute :id, :id, description: 'Present for existing values. Omit to create a new one.'
+              option_value.attribute :name, :string, example: 'red'
+              option_value.attribute :label, :string, example: 'Red'
+              option_value.attribute :position, :integer
+              option_value.attribute :color_code, :string,
+                nullable: true,
+                example: '#FF0000',
+                description: "Hex color. Only meaningful when the option type's `kind` is `color_swatch`."
+              option_value.attribute :image_signed_id, :string,
+                nullable: true,
+                description: 'A `signed_id` from `files.upload()`, or null to remove the image.'
+            end
+          end
+
           protected
 
           def model_class
@@ -20,13 +43,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(
-              *model_additional_permitted_attributes,
-              :name, :label, :position, :filterable, :kind,
-              option_values: [
-                :id, :name, :label, :position, :color_code, :image
-              ]
-            )
+            params.permit(*permitted_attributes)
           end
         end
       end

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

@@ -5,6 +5,10 @@ module Spree
         class OrderCancellationReasonsController < 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/order_routing_rules_controller.rb

@@ -13,6 +13,18 @@ module Spree
           subclassed_via -> { Spree.order_routing.rules },
                          unknown_type_error: 'unknown_order_routing_rule_type'
 
+          request_params :order_routing_rule do |body|
+            body.attribute :type, :string,
+              required: true,
+              only: :create,
+              example: 'preferred_location',
+              description: 'Wire shorthand for the rule kind, from the order routing rule types endpoint.'
+            body.attribute :active, :boolean
+            body.attribute :position, :integer,
+              description: "1-based priority in the channel's rule list. Omitted on create, the rule goes last; a new position reorders the rest of the list around it."
+            body.attribute :preferences, :hash, description: "Values for the rule kind's preference schema."
+          end
+
           def types
             authorize! :read, model_class
 
@@ -30,7 +42,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(*model_additional_permitted_attributes, :type, :active, :position, 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/orders/claims_controller.rb

@@ -12,6 +12,44 @@ module Spree
             # would name a key no catalog knows.
             scoped_resource :orders
 
+            request_params :claim do |body|
+              body.attribute :items, :array,
+                required: true, on: :create,
+                only: :create,
+                description: 'Affected items, and how each should be made right.' do |item|
+                item.attribute :line_item_id, :id, required: true
+                item.attribute :quantity, :integer, required: true
+                item.attribute :description, :string
+                item.attribute :send_replacement, :boolean
+                item.attribute :replacement_variant_id, :id, description: 'Defaults to the variant that was bought.'
+                item.attribute :refund_amount, :decimal
+              end
+              body.attribute :reason_id, :id, description: "One of the store's claim reasons."
+              body.attribute :memo, :string
+              body.attribute :metadata, :hash, only: :update
+            end
+
+            request_params 'ClaimResolveParams', action: :resolve do |body|
+              body.attribute :resolution, :string,
+                required: true,
+                choices: Spree::Claim::RESOLUTIONS,
+                description: 'Money back, a replacement shipment, or both.'
+              body.attribute :refund_method, :string,
+                choices: Spree::RefundMethods::METHODS,
+                description: 'Defaults to `store_credit`.'
+              body.attribute :amount, :decimal, description: 'Defaults to the claim total.'
+              body.attribute :replacement_line_item_ids, :array, of: :id,
+                description: 'Which claim lines to send a replacement for. Omit to keep what the claim was opened with.'
+            end
+
+            request_params 'ClaimDenyParams', action: :deny do |body|
+              body.attribute :reason, :string, description: 'Recorded on the claim for the customer.'
+            end
+
+            request_params 'ClaimCancelParams', action: :cancel do |body|
+              body.attribute :reason, :string, description: 'A note on why the claim was canceled.'
+            end
+
             before_action :set_resource, only: [:show, :update, :approve, :resolve, :deny, :cancel]
 
             # PATCH /api/v3/admin/orders/:order_id/claims/:id
@@ -36,7 +74,7 @@ module Spree
             end
 
             def permitted_params
-              params.permit(:memo, :reason_id, metadata: {})
+              params.permit(*permitted_attributes)
             end
 
             private

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

@@ -13,6 +13,24 @@ module Spree
           class DeliveriesController < BaseController
             include Spree::Api::V3::Orders::DeliveryActions
 
+            # The permit list itself lives in DeliveryActions, shared with the
+            # seller branch; this declaration documents it.
+            request_params :delivery do |body|
+              body.attribute :tracking_number, :string,
+                required: true, on: :create,
+                description: 'A carrier tracking number, a freight PRO or container number, or a full tracking link. A corrected number resets the carrier status to `pending`.'
+              body.attribute :carrier, :string,
+                description: "Free text; detected from the number's format when omitted."
+              body.attribute :service, :string
+              body.attribute :tracking_url, :string
+            end
+
+            request_params 'DeliveryMarkDeliveredParams', action: :mark_delivered do |body|
+              body.attribute :delivered_at, :datetime, description: 'When it arrived. Defaults to now.'
+              body.attribute :notify_customer, :boolean,
+                description: 'Whether the customer gets a delivery notification once the parcel completes. Defaults to true.'
+            end
+
             before_action :set_resource, only: [:show, :update, :destroy, :mark_delivered]
 
             # PATCH .../deliveries/:id/mark_delivered — staff saying this one
@@ -47,7 +65,7 @@ module Spree
             private
 
             def mark_delivered_params
-              @mark_delivered_params ||= params.permit(:delivered_at, :notify_customer)
+              @mark_delivered_params ||= params.permit(*declared_permitted_attributes)
             end
 
             # Only an explicit false suppresses the email.

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

@@ -10,6 +10,10 @@ module Spree
           # orders are frozen; their discounts change only through manual rows
           # (see DiscountsController).
           class DiscountCodesController < BaseController
+            request_params 'DiscountCodeApplyParams' do |body|
+              body.attribute :code, :string, required: true
+            end
+
             skip_before_action :set_resource, raise: false
 
             # POST /api/v3/admin/orders/:order_id/discount_codes
@@ -76,7 +80,7 @@ module Spree
             end
 
             def permitted_params
-              params.permit(:code)
+              params.permit(*declared_permitted_attributes)
             end
           end
         end

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

@@ -11,23 +11,47 @@ module Spree
           class DiscountsController < BaseController
             scoped_resource :orders
 
+            request_params :discount do |body|
+              body.attribute :label, :string, required: true, on: :create, example: 'Customer appeasement'
+              body.attribute :value, :decimal,
+                required: true, on: :create,
+                only: :create,
+                example: '10.00',
+                description: 'An amount in the order currency for a `flat` discount, or a percentage for a `percent` one.'
+              body.attribute :amount, :decimal,
+                only: :update,
+                description: 'The new amount of the row, in the order currency.'
+              body.attribute :value_type, :string,
+                only: :create,
+                choices: %w[flat percent],
+                description: 'Defaults to `flat`.'
+              body.attribute :line_item_id, :id,
+                only: :create,
+                nullable: true,
+                description: 'The line item the discount applies to. Omitted, the value is distributed across the line items.'
+            end
+
             # POST /api/v3/admin/orders/:order_id/discounts
             def create
               with_order_lock do
                 line_item = @parent.line_items.find_by_prefix_id!(params[:line_item_id]) if params[:line_item_id].present?
 
+                value_type = params[:value_type].presence || 'flat'
+                # A flat discount is money in the order's currency; a percentage is a rate.
+                value = value_type == 'percent' ? decimal_param(:value) : money_param(:value, @parent.currency)
+
                 result = Spree.order_discount_create_service.call(
                   order: @parent,
                   label: params[:label],
-                  value: params[:value].presence || params[:amount],
-                  value_type: params[:value_type].presence || 'flat',
+                  value: value,
+                  value_type: value_type,
                   line_item: line_item
                 )
 
                 if result.success?
                   render json: { data: serialize_collection(result.value) }, status: :created
                 else
-                  render_error(code: ERROR_CODES[:validation_error], message: result.error.to_s, status: :unprocessable_entity)
+                  render_error(code: ERROR_CODES[:validation_error], message: result.error.to_s, status: :unprocessable_content)
                 end
               end
             end
@@ -75,7 +99,7 @@ module Spree
             end
 
             def permitted_params
-              params.permit(:label, :amount)
+              params.permit(*permitted_attributes)
             end
 
             def collection_includes
@@ -88,7 +112,7 @@ module Spree
               render_error(
                 code: ERROR_CODES[:discount_not_editable],
                 message: I18n.t('spree.errors.messages.promotion_discount_not_editable'),
-                status: :unprocessable_entity
+                status: :unprocessable_content
               )
             end
           end

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

@@ -13,6 +13,41 @@ module Spree
             # would name a key no catalog knows.
             scoped_resource :orders
 
+            request_params :exchange do |body|
+              body.attribute :items, :array,
+                required: true, on: :create,
+                only: :create,
+                description: 'Items coming back, and what goes out in their place.' do |item|
+                item.attribute :fulfillment_item_id, :id, required: true
+                item.attribute :new_variant_id, :id, required: true
+                item.attribute :quantity, :integer, required: true
+              end
+              body.attribute :stock_location_id, :id, description: 'Where the goods come back to.'
+              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 'ExchangeReceiveParams', action: :receive do |body|
+              body.attribute :items, :array,
+                description: 'What actually arrived. Omit to receive everything as requested and resellable.' do |item|
+                item.attribute :exchange_line_item_id, :id, required: true
+                item.attribute :quantity, :integer, required: true
+                item.attribute :resellable, :boolean,
+                  description: 'Goods that cannot be resold are received but never restocked. Defaults to true.'
+              end
+            end
+
+            request_params 'ExchangeFulfillParams', action: :fulfill do |body|
+              body.attribute :refund_method, :string,
+                choices: Spree::RefundMethods::METHODS,
+                description: 'How a credit is returned when the replacements cost less than what came back. Defaults to `store_credit`. A balance the customer owes is left for the merchant to collect.'
+            end
+
+            request_params 'ExchangeCancelParams', action: :cancel do |body|
+              body.attribute :reason, :string, description: 'A note on why the exchange was canceled.'
+            end
+
             before_action :set_resource, only: [:show, :update, :approve, :receive, :fulfill, :cancel]
 
             # PATCH /api/v3/admin/orders/:order_id/exchanges/:id
@@ -37,7 +72,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/fees_controller.rb

@@ -11,6 +11,27 @@ module Spree
           class FeesController < BaseController
             scoped_resource :orders
 
+            request_params :fee do |body|
+              body.attribute :label, :string, required: true, on: :create, example: 'Gift wrap'
+              body.attribute :amount, :decimal, required: true, on: :create, example: '4.00'
+              body.attribute :kind, :string,
+                choices: Spree::Fee::KINDS,
+                open: true,
+                example: 'gift_wrap',
+                description: 'Defaults to `surcharge`.'
+              # Resolved through the order by the controller, never assigned.
+              body.attribute :line_item_id, :id,
+                only: :create,
+                nullable: true,
+                permit: false,
+                description: 'The line item or fulfillment the fee belongs to. Omitted, the fee is order-level.'
+              body.attribute :fulfillment_id, :id,
+                only: :create,
+                nullable: true,
+                permit: false,
+                description: 'The line item or fulfillment the fee belongs to. Omitted, the fee is order-level.'
+            end
+
             # POST /api/v3/admin/orders/:order_id/fees
             def create
               with_order_lock do
@@ -60,7 +81,7 @@ module Spree
             end
 
             def permitted_params
-              params.permit(:label, :amount, :kind)
+              params.permit(*permitted_attributes)
             end
 
             def collection_includes

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

@@ -14,6 +14,69 @@ module Spree
 
             scoped_resource :fulfillments
 
+            request_params :fulfillment do |body|
+              body.attribute :stock_location_id, :id,
+                required: true, on: :create,
+                description: "The location the fulfillment ships from. On update, moving it re-prices the fulfillment against that location's rates."
+              body.attribute :source_fulfillment_id, :id,
+                only: :create,
+                description: "The only fulfillment of this order to move units from, its exchange and claim replacements included: how a canceled replacement is sent again. Omitted, the customer's bought units are taken from every unshipped fulfillment."
+              body.attribute :tracking, :string,
+                description: 'Carrier tracking number, or a full `https://` tracking link, which is served back as `tracking_url` unchanged.'
+              body.attribute :tracking_carrier, :string,
+                only: :update,
+                description: "Which carrier the tracking number belongs to: a slug from the tracking carriers endpoint. Left blank, it is detected from the number's format where possible."
+              body.attribute :selected_delivery_rate_id, :id, only: :update
+              body.attribute :delivery_method_id, :id,
+                only: :create,
+                description: 'Delivery method attached as the selected rate. Defaults to the delivery method of the fully drained source fulfillments.'
+              body.attribute :cost, :decimal,
+                only: :create,
+                example: '7.42',
+                description: 'Explicit shipping cost, such as the 3PL price. Defaults to the summed cost of the fully drained source fulfillments, which keeps the order total unchanged. Persists only with `status: shipped`; pending fulfillments are re-priced by the rate engine.'
+              body.attribute :status, :string,
+                only: :create,
+                choices: %w[shipped],
+                description: 'Pass `shipped` to register an already-shipped external fulfillment.'
+              body.attribute :metadata, :hash, only: :create
+              body.attribute :items, :array,
+                only: :create,
+                description: 'Line item quantities to fulfill. Omit to fulfill every unit not yet shipped.' do |item|
+                item.attribute :item_id, :id, required: true
+                item.attribute :quantity, :integer, required: true
+              end
+            end
+
+            request_params 'FulfillmentFulfillParams', action: :fulfill do |body|
+              body.attribute :items, :array,
+                description: 'Line item quantities to ship. Omit to ship everything the fulfillment holds; a subset is split onto a new fulfillment, which is the one that ships.' do |item|
+                item.attribute :item_id, :id, required: true
+                item.attribute :quantity, :integer, required: true
+              end
+              body.attribute :tracking, :string,
+                description: 'Carrier tracking number or a full `https://` tracking link, stored on the fulfillment that ships.'
+              body.attribute :tracking_carrier, :string,
+                description: 'Which carrier the number belongs to; detected from the number when omitted.'
+              body.attribute :notify_customer, :boolean,
+                description: 'Whether the customer gets the shipment email. Defaults to true; pass false to suppress it for this dispatch only.'
+              body.attribute :force, :boolean,
+                description: 'Hand the goods over even though the order is unpaid or holds backordered units.'
+            end
+
+            request_params 'FulfillmentMarkDeliveredParams', action: :mark_delivered do |body|
+              body.attribute :delivered_at, :datetime,
+                description: 'When it arrived. Defaults to now; return windows run from this time.'
+              body.attribute :notify_customer, :boolean,
+                description: 'Whether the customer gets a delivery notification. Defaults to true.'
+            end
+
+            request_params 'FulfillmentSplitParams', action: :split do |body|
+              body.attribute :variant_id, :id, required: true, description: 'The variant being moved out.'
+              body.attribute :quantity, :integer, required: true
+              body.attribute :stock_location_id, :id,
+                description: "Origin of the new fulfillment. Defaults to the source fulfillment's location."
+            end
+
             before_action :set_resource, only: [:show, :update, :fulfill, :mark_delivered, :cancel, :split]
 
             # POST /api/v3/admin/orders/:order_id/fulfillments
@@ -74,16 +137,12 @@ module Spree
             end
 
             def permitted_params
-              params.permit(:tracking, :tracking_carrier, :selected_delivery_rate_id, :stock_location_id)
+              params.permit(*permitted_attributes)
             end
 
             private
 
             # Forcing past a stock or payment guard is the operator's call.
-            def fulfill_permitted_keys
-              super + [:force]
-            end
-
             def fulfill_workflow_options
               { force: fulfill_params[:force].to_b }
             end
@@ -101,11 +160,11 @@ module Spree
             end
 
             def create_params
-              @create_params ||= params.permit(:stock_location_id, :source_fulfillment_id, :tracking, :delivery_method_id, :cost, :status, metadata: {}, items: [:item_id, :quantity])
+              @create_params ||= params.permit(*declared_permitted_attributes)
             end
 
             def mark_delivered_params
-              @mark_delivered_params ||= params.permit(:delivered_at, :notify_customer)
+              @mark_delivered_params ||= params.permit(*declared_permitted_attributes)
             end
 
             def find_stock_location!(id)

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

@@ -6,9 +6,13 @@ module Spree
           class GiftCardsController < BaseController
             skip_before_action :set_resource, raise: false
 
+            request_params 'GiftCardApplyParams' do |body|
+              body.attribute :code, :string,
+                required: true,
+                description: 'The gift card code; matched case-insensitively.'
+            end
+
             # POST /api/v3/admin/orders/:order_id/gift_cards
-            #
-            # Body: { code: String }
             def create
               with_order_lock do
                 gift_card = find_gift_card!