spree_api 6.0.0.beta4 → 6.0.0.rc2

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

@@ -12,6 +12,12 @@ module Spree
         class SellerPayoutsController < ResourceController
           scoped_resource :payouts
 
+          request_params 'SellerPayoutCompleteParams', action: :complete do |body|
+            body.attribute :reference, :string,
+              example: 'TRF-8842',
+              description: "The provider's own id for the settlement, when one made it."
+          end
+
           # PATCH /api/v3/admin/seller_payouts/:id/complete
           #
           # What the built-in provider waits for: the operator saying the bank
@@ -30,11 +36,7 @@ module Spree
               reference: params[:reference].to_s.presence
             )
 
-            if result.success?
-              render json: serialize_resource(result.value)
-            else
-              render_result_error(result)
-            end
+            render_result(result)
           end
 
           protected
@@ -47,10 +49,6 @@ module Spree
             Spree.api.admin_seller_payout_serializer
           end
 
-          def scope
-            super.for_store(current_store)
-          end
-
           # Deliberately without `transfers`: the serializer wants their number,
           # not the rows, and a monthly settlement can hold hundreds.
           def collection_includes

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

@@ -12,6 +12,21 @@ module Spree
         class SellerRequirementSubmissionsController < ResourceController
           scoped_resource :sellers
 
+          request_params 'SellerRequirementWaiveParams', action: :create do |body|
+            body.attribute :requirement_id, :id,
+              required: true,
+              example: 'selreq_UkLWZg9DAJ',
+              description: 'The requirement the seller is excused from.'
+            body.attribute :review_note, :string, description: 'Why the seller is excused. Kept with the decision.'
+          end
+
+          %i[accept reject].each do |action|
+            request_params('SellerRequirementReviewParams', action: action) do |body|
+              body.attribute :review_note, :string,
+                description: 'Kept with the decision. On a rejection it is the reason sent back to the seller.'
+            end
+          end
+
           before_action :set_resource, only: [:show, :accept, :reject, :download]
 
           # POST /api/v3/admin/sellers/:seller_id/requirement_submissions
@@ -30,11 +45,7 @@ module Spree
               review_note: params[:review_note]
             )
 
-            if result.success?
-              render json: serialize_resource(result.value), status: :created
-            else
-              render_result_error(result)
-            end
+            render_result(result, status: :created)
           end
 
           # PATCH /api/v3/admin/sellers/:seller_id/requirement_submissions/:id/accept
@@ -126,11 +137,7 @@ module Spree
               review_note: params[:review_note]
             )
 
-            if result.success?
-              render json: serialize_resource(result.value)
-            else
-              render_result_error(result)
-            end
+            render_result(result)
           end
         end
       end

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

@@ -16,6 +16,36 @@ module Spree
           subclassed_via -> { Spree.seller_requirements },
                          unknown_type_error: 'unknown_seller_requirement_type'
 
+          # `type` is stripped before assignment by the subclassed-resource
+          # flow, so a saved row's kind can never change — which matters
+          # because its submissions answered the old one.
+          request_params :seller_requirement do |body|
+            body.attribute :type, :string,
+              required: true,
+              only: :create,
+              example: 'document',
+              description: 'The kind, from the seller requirement types endpoint.'
+            body.attribute :name, :string,
+              example: 'Business registration',
+              description: 'What the seller sees. Required for kinds that can be added more than once, since the wording is the only thing telling them apart. Left blank on the others, the kind names itself.'
+            body.attribute :description, :string,
+              example: 'A copy of your certificate of incorporation.',
+              description: 'Instructions shown to the seller.'
+            body.attribute :position, :integer, example: 1, description: 'Place in the checklist.'
+            body.attribute :active, :boolean, example: true
+            body.attribute :required, :boolean,
+              example: true,
+              description: 'Whether this blocks approval. Off means recommended.'
+            body.attribute :preferences, :hash,
+              example: { accepted_content_types: ['application/pdf'] },
+              description: "Configuration for this kind, per its type's `schema`."
+            body.attribute :metadata, :hash
+            # Permitted per kind, from the kind's own `additional_permitted_attributes`.
+            body.attribute :custom_field_definition_ids, :array, of: :id,
+              permit: false,
+              description: 'Custom field definitions this requirement asks the seller to fill in (`required_custom_fields` kind).'
+          end
+
           # GET /api/v3/admin/seller_requirements/types
           #
           # The kinds an operator can add, with the shape of each one's
@@ -49,7 +79,7 @@ module Spree
                 # Config a kind takes beyond its preferences — a reference
                 # list gets its own picker, not a text box.
                 association_fields: association_fields_for(klass),
-                preference_schema: klass.serialized_preference_schema
+                schema: klass.preference_json_schema
               }
             end
 
@@ -70,12 +100,8 @@ module Spree
             super.ordered
           end
 
-          # `type` is stripped before assignment by the subclassed-resource
-          # flow, so a saved row's kind can never change — which matters
-          # because its submissions answered the old one.
           def permitted_params
-            params.permit(:type, :name, :description, :position, :active, :required,
-                          preferences: {}, metadata: {})
+            params.permit(*declared_permitted_attributes)
           end
 
           # `types` is read-only discovery — maps to the read scope.

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

@@ -20,10 +20,6 @@ module Spree
             Spree.api.admin_seller_transfer_serializer
           end
 
-          def scope
-            super.for_store(current_store)
-          end
-
           # Every association the serializer reads, so a page of rows costs a
           # fixed number of queries rather than one per row.
           def collection_includes

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

@@ -38,7 +38,7 @@ module Spree
               if @invitation.expired?
                 return render_error(
                   code: ErrorHandler::ERROR_CODES[:processing_error],
-                  message: Spree.t(:invitation_expired),
+                  message: I18n.t('spree.invitation_expired'),
                   status: :unprocessable_content
                 )
               end

data/app/controllers/spree/api/v3/admin/sellers/payouts_controller.rb

@@ -47,7 +47,7 @@ module Spree
                 # than a success that produced no payout.
                 render_error(
                   code: ErrorHandler::ERROR_CODES[:validation_error],
-                  message: Spree.t(:seller_payout_nothing_to_settle),
+                  message: I18n.t('spree.seller_payout_nothing_to_settle'),
                   status: :unprocessable_content
                 )
               end

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

@@ -19,6 +19,80 @@ module Spree
           before_action :set_resource, only: [:show, :update, :destroy, :invite, :approve, :suspend, :reject,
                                               :onboarding, :reopen_onboarding]
 
+          # Enumerated rather than borrowing the legacy global list, which
+          # permits :id, :user_id and :deleted_at — the first of which would
+          # reintroduce the address-by-id hole below.
+          # The seller's own profile fields, plus the settlement and tax
+          # configuration only the operator sets. `status` is absent by
+          # design — see the class comment.
+          #
+          # Addresses are written as nested attributes, never as ids: an
+          # address has no store of its own, so accepting `billing_address_id`
+          # would bind an arbitrary row and the serializer would render it
+          # back in full — an enumeration oracle over every customer address
+          # on the installation.
+          request_params :seller do |body|
+            body.external_references
+            body.attribute :name, :string, required: true, on: :create, example: 'Northwind Books'
+            body.attribute :slug, :string,
+              example: 'northwind-books',
+              description: 'URL-safe slug, derived from the name when omitted.'
+            body.attribute :contact_email, :string, nullable: true, example: 'hi@northwind.example'
+            body.attribute :billing_email, :string, nullable: true, example: 'billing@northwind.example'
+            body.attribute :about, :string,
+              nullable: true,
+              example: '<p>Independent bookshop.</p>',
+              description: "Sanitized HTML: the seller's public description."
+            body.attribute :logo_signed_id, :string,
+              nullable: true,
+              description: 'A `signed_id` from the files upload endpoint to set the image, `null` to remove it, or omit the key to leave it untouched. The same applies to `square_logo_signed_id` and `cover_photo_signed_id`.'
+            body.attribute :square_logo_signed_id, :string, nullable: true
+            body.attribute :cover_photo_signed_id, :string, nullable: true
+            body.attribute :tax_remittance, :string, choices: Spree::Seller::TAX_REMITTANCES, example: 'seller'
+            body.attribute :payouts_schedule_interval, :string,
+              nullable: true,
+              choices: Spree::Seller::PAYOUT_INTERVALS
+            body.attribute :minimum_payout_amount, :decimal, nullable: true, example: '25.0'
+            body.attribute :holiday_mode_until, :datetime,
+              nullable: true,
+              description: 'Set while the seller is away: the catalog stays but stops selling.'
+            body.attribute :legal_name, :string, nullable: true
+            body.attribute :registration_number, :string, nullable: true
+            body.attribute :metadata, :hash
+            body.attribute :billing_address, :object,
+              as: 'SellerAddressParams',
+              description: "The seller's own billing address, written inline. There is no `billing_address_id`: an address belongs to whoever it was created for, so it is never referenced by id." do |billing_address|
+              billing_address.include_attributes Spree::Api::V3::AddressRequestSchema
+            end
+            body.attribute :custom_fields, :array, of: Spree::Api::V3::CustomFieldValueRequestSchema,
+              description: 'Custom field values, each validated against its definition.'
+          end
+
+          request_params 'SellerInviteParams', action: :invite do |body|
+            body.attribute :email, :string, required: true, example: 'seller@example.com'
+            body.attribute :role_id, :id,
+              nullable: true,
+              example: 'role_UkLWZg9DAJ',
+              description: "A role this seller owns; defaults to the seller's own admin role."
+          end
+
+          request_params 'SellerApproveParams', action: :approve do |body|
+            body.attribute :override_requirements, :boolean,
+              description: 'Admits a seller whose onboarding checklist is unfinished: the operator\'s deliberate exception, which the `seller.approved` event records along with what was outstanding.'
+          end
+
+          request_params 'SellerReopenOnboardingParams', action: :reopen_onboarding do |body|
+            body.attribute :note, :string, description: 'What the seller has to fix.'
+          end
+
+          request_params 'SellerSuspendParams', action: :suspend do |body|
+            body.attribute :reason, :string, example: 'Counterfeit goods'
+          end
+
+          request_params 'SellerRejectParams', action: :reject do |body|
+            body.attribute :reason, :string, example: 'Incomplete paperwork'
+          end
+
           # POST /api/v3/admin/sellers/:id/invite
           #
           # Opens the seller's team to someone. They become a member when they
@@ -31,11 +105,7 @@ module Spree
               inviter: try_spree_current_user
             )
 
-            if result.success?
-              render json: serialize_resource(result.value), status: :created
-            else
-              render_result_error(result)
-            end
+            render_result(result, status: :created)
           end
 
           # GET /api/v3/admin/sellers/:id/onboarding
@@ -129,29 +199,8 @@ module Spree
              { store: :seller_requirements, logo_attachment: :blob, cover_photo_attachment: :blob }]
           end
 
-          # Enumerated rather than borrowing the legacy global list, which
-          # permits :id, :user_id and :deleted_at — the first of which would
-          # reintroduce the address-by-id hole below.
-          # The seller's own profile fields, plus the settlement and tax
-          # configuration only the operator sets. `status` is absent by
-          # design — see the class comment.
-          #
-          # Addresses are written as nested attributes, never as ids: an
-          # address has no store of its own, so accepting `billing_address_id`
-          # would bind an arbitrary row and the serializer would render it
-          # back in full — an enumeration oracle over every customer address
-          # on the installation.
           def permitted_params
-            normalize_params(
-              params.permit(:name, :slug, :contact_email, :billing_email, :about,
-                            :logo, :square_logo, :cover_photo,
-                            :tax_remittance, :payouts_schedule_interval, :minimum_payout_amount,
-                            :holiday_mode_until,
-                            :legal_name, :registration_number,
-                            metadata: {},
-                            billing_address: Spree::Api::V3::AddressParams::ADDRESS_KEYS,
-                            custom_fields: [:id, :custom_field_definition_id, :value, { value: [] }, { value: {} }])
-            )
+            normalize_params(params.permit(*declared_permitted_attributes))
           end
 
           # Creating a seller provisions their stock location too, so it goes
@@ -176,11 +225,7 @@ module Spree
           def run_workflow(workflow, **arguments)
             result = workflow.call(seller: @resource, **arguments)
 
-            if result.success?
-              render json: serialize_resource(result.value)
-            else
-              render_result_error(result)
-            end
+            render_result(result)
           end
 
           # Read through the seller's own roles: a role id naming somewhere

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

@@ -14,6 +14,35 @@ module Spree
           skip_scope_check!
           skip_before_action :authenticate_admin!, only: [:show, :countries, :create]
 
+          request_params 'SetupParams', action: :create do |body|
+            body.attribute :setup_token, :string,
+              required: true,
+              permit: false,
+              description: 'The one-time token from the install output.'
+            body.attribute :email, :string, required: true, format: :email, example: 'owner@example.com'
+            body.attribute :password, :string, required: true
+            body.attribute :password_confirmation, :string
+            body.attribute :first_name, :string, example: 'Olivia'
+            body.attribute :last_name, :string, example: 'Owner'
+            body.attribute :store_name, :string, permit: false, example: 'My Store'
+            body.attribute :country_code, :country,
+              required: true,
+              permit: false,
+              example: 'US',
+              description: 'ISO 3166-1 alpha-2 country the store sells from. It determines the default market, the warehouse, the delivery zones and the currency.'
+            body.attribute :locale, :locale,
+              permit: false,
+              example: 'en',
+              description: "Storefront locale. Defaults to the country's own language."
+            body.attribute :currency, :currency,
+              permit: false,
+              example: 'USD',
+              description: "ISO 4217 currency. Defaults to the country's own currency: pass one only when the store prices in something else."
+            body.attribute :sample_data, :boolean,
+              permit: false,
+              description: 'Load the demo catalog, customers and orders in the background once the admin account exists. The load takes minutes, so the response does not wait for it.'
+          end
+
           # Only create checks the setup token, so only create needs the strict
           # login budget against guessing. The status and countries reads stay
           # on the general per-caller limit: sharing the login budget with them
@@ -43,15 +72,13 @@ module Spree
           end
 
           # POST /api/v3/admin/auth/setup
-          # Body: { setup_token, email, password, password_confirmation?,
-          #         first_name?, last_name?, store_name, country_code,
-          #         locale?, currency?, sample_data? }
           # Currency defaults to the country's own; an unknown code is refused
           # rather than ignored, since the token is spent in the same request.
           def create
             return render_setup_unavailable unless setup_token_usable?
             return render_missing_country if country.nil?
             return render_unknown_currency if unknown_currency?
+            return render_unknown_locale if unknown_locale?
 
             user = nil
             store = Spree::Store.default
@@ -135,34 +162,38 @@ module Spree
             )
           end
 
+          # Blank means "use the country's own language"; another spelling or a
+          # region Spree does not list moves to the listed locale, but a code
+          # Spree cannot place at all is refused before the token is spent.
+          def unknown_locale?
+            params[:locale].present? && Spree::Locales.listed(params[:locale]).nil?
+          end
+
+          def render_unknown_locale
+            message = "Unknown locale #{params[:locale]}"
+
+            render_error(
+              code: ERROR_CODES[:validation_error],
+              message: message,
+              status: :unprocessable_content,
+              details: { locale: [message] }
+            )
+          end
+
           def country_payload(country)
             {
               code: country.iso,
-              name: country.name,
               currency: country.default_currency,
               locales: offerable_locales(country)
             }
           end
 
-          # A country's official languages, minus any Spree has no translations
-          # for — Switzerland speaks Romansh and Spree does not, so offering it
-          # would point a storefront at a language with nothing behind it.
-          # English closes the gap for countries whose languages all fall
-          # through, and is always offered alongside.
-          #
-          # Installs without spree_i18n only have English, and filtering
-          # against that would leave every country English-only. There the
-          # unfiltered list is the better answer: the merchant's own language
-          # is still the right default for their storefront, whether or not
-          # this install carries a translation bundle for it.
+          # A country's official languages, as the locales Spree lists for them
+          # (Switzerland gives de, fr, it and rm) — content locales, whether
+          # or not Spree ships translations, since the storefront and dashboard
+          # carry their own. English stands in for a country with none listed.
           def offerable_locales(country)
-            return country.official_locales if translated_locales.size <= 1
-
-            (country.official_locales & translated_locales).presence || ['en']
-          end
-
-          def translated_locales
-            @translated_locales ||= Spree.available_locales.map { |locale| locale.to_s.split('-').first }.uniq
+            country.official_locales.filter_map { |language| Spree::Locales.for_language(language) }.uniq.presence || ['en']
           end
 
           # Token mismatch, spent token, and already-set-up all render the
@@ -180,7 +211,7 @@ module Spree
           end
 
           def admin_user_params
-            params.permit(:email, :password, :password_confirmation, :first_name, :last_name)
+            params.permit(*declared_permitted_attributes)
           end
 
           # The seed already created the default store (every downstream seed

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

@@ -10,6 +10,43 @@ module Spree
 
           before_action :require_stock_levels!, only: [:bulk_upsert]
 
+          # Stock levels are auto-created against a (variant, stock_location)
+          # pair and never re-pointed, so update only touches the count and
+          # backorder flag, not the variant or location.
+          request_params :stock_level do |body|
+            body.external_references
+            body.attribute :count_on_hand, :integer,
+              description: 'The count the shelf should end at: a whole number of zero or more. The API records the difference as an `adjusted` movement, so the correction appears in the stock history.'
+            body.attribute :adjustment, :integer,
+              description: 'A signed change to the shelf instead of a target count, applied to the count the API holds at that moment and recorded the same way. Cannot be sent together with `count_on_hand`.'
+            body.attribute :backorderable, :boolean,
+              description: 'Whether this location sells the variant beyond what it holds.'
+            # Optional so an audit requirement never turns an existing
+            # endpoint into a 422.
+            body.attribute :reason, :string,
+              description: 'Labels the correction in the stock history. Defaults to "Manual adjustment".'
+            body.attribute :metadata, :hash
+          end
+
+          request_params 'StockLevelBulkUpsertParams', action: :bulk_upsert do |body|
+            body.attribute :stock_levels, :array,
+              required: true,
+              as: 'StockLevelBulkUpsertRowParams',
+              description: 'Send an empty list to change nothing.' do |stock_level|
+              stock_level.attribute :variant_id, :id, required: true, example: 'variant_xY9'
+              stock_level.attribute :stock_location_id, :id, required: true, example: 'sloc_aBc'
+              stock_level.attribute :count_on_hand, :integer,
+                nullable: true,
+                example: 42,
+                description: 'The absolute level the external system reports.'
+              stock_level.attribute :adjustment, :integer,
+                nullable: true,
+                example: -3,
+                description: 'A relative change, for feeds that report movements rather than levels. Each row needs `count_on_hand` or `adjustment`.'
+              stock_level.attribute :backorderable, :boolean, nullable: true
+            end
+          end
+
           def bulk_upsert
             authorize! :update, Spree::StockLevel
 
@@ -101,16 +138,8 @@ module Spree
             collection.order(Spree::StockLevel.arel_table[:id].asc)
           end
 
-          # Stock levels are auto-created against a (variant, stock_location)
-          # pair and never re-pointed, so update only touches the count and
-          # backorder flag — not the variant or location FKs.
-          #
-          # `reason` labels the correction in the stock history. It stays
-          # optional so an audit requirement never turns an existing endpoint
-          # into a 422; omitting it falls back to a translated default.
           def permitted_params
-            params.permit(*model_additional_permitted_attributes, :count_on_hand, :adjustment, :backorderable, :reason,
-                          metadata: {})
+            params.permit(*permitted_attributes)
           end
 
           private

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

@@ -5,6 +5,46 @@ module Spree
         class StockLocationsController < ResourceController
           scoped_resource :stock
 
+          request_params :stock_location do |body|
+            body.external_references
+            body.attribute :name, :string, required: true, on: :create, example: 'Brooklyn warehouse'
+            body.attribute :admin_name, :string, nullable: true, description: 'Internal name shown only in the admin.'
+            body.attribute :active, :boolean
+            body.attribute :default, :boolean, description: 'Setting to true demotes the previous default.'
+            body.attribute :kind, :string,
+              choices: Spree::StockLocation::KINDS,
+              open: true,
+              example: 'warehouse',
+              description: 'Categorizes the location.'
+            body.attribute :propagate_all_variants, :boolean
+            body.attribute :backorderable_default, :boolean
+            body.attribute :address1, :string, nullable: true
+            body.attribute :address2, :string, nullable: true
+            body.attribute :city, :string, nullable: true
+            body.attribute :zipcode, :string, nullable: true
+            body.attribute :phone, :string, nullable: true
+            body.attribute :company, :string, nullable: true
+            body.attribute :country_code, :country,
+              nullable: true,
+              example: 'US',
+              description: 'ISO-3166 alpha-2 country code.'
+            body.attribute :state_code, :string,
+              nullable: true,
+              example: 'NY',
+              description: "State or province abbreviation, resolved against the selected country's states."
+            body.attribute :state_name, :string,
+              nullable: true,
+              description: "Free-text state for countries that don't have a states list."
+            body.attribute :pickup_enabled, :boolean
+            body.attribute :pickup_stock_policy, :string,
+              choices: Spree::StockLocation::PICKUP_STOCK_POLICIES,
+              description: '`local` collects only items at this location; `any` lets items transfer in from other locations (ship-to-store).'
+            body.attribute :pickup_ready_in_minutes, :integer, nullable: true
+            body.attribute :returns_enabled, :boolean,
+              description: 'Whether customers may send returns to this location.'
+            body.attribute :pickup_instructions, :string, nullable: true
+          end
+
           protected
 
           def model_class
@@ -26,15 +66,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(
-              *model_additional_permitted_attributes,
-              :name, :admin_name, :active, :default,
-              :kind, :propagate_all_variants, :backorderable_default,
-              :address1, :address2, :city, :zipcode, :phone, :company,
-              :country_code, :state_code, :state_name,
-              :pickup_enabled, :pickup_stock_policy, :returns_enabled,
-              :pickup_ready_in_minutes, :pickup_instructions
-            )
+            params.permit(*permitted_attributes)
           end
         end
       end

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

@@ -18,6 +18,47 @@ module Spree
 
           scoped_resource :stock
 
+          # The warehouses and 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 :stock_transfer do |body|
+            body.attribute :source_location_id, :id,
+              required: true, on: :create,
+              permit: false,
+              example: 'sloc_1234567890'
+            body.attribute :destination_location_id, :id,
+              required: true, on: :create,
+              permit: false,
+              example: 'sloc_1234567890'
+            body.attribute :reference, :string,
+              nullable: true,
+              description: "The merchant's own label for the trip. `null` clears it."
+            body.attribute :notes, :string, nullable: true
+            body.attribute :items, :array,
+              permit: false,
+              as: 'StockTransferItemParams',
+              description: 'A draft may open empty and gain lines as the merchant packs. Sending the list replaces whatever the draft currently holds.' do |item|
+              item.attribute :variant_id, :id, required: true, example: 'variant_1234567890'
+              item.attribute :quantity_shipped, :integer, required: true, example: 10
+            end
+            body.attribute :metadata, :hash, nullable: true
+          end
+
+          request_params 'StockTransferMarkInTransitParams', action: :mark_in_transit do |body|
+            body.attribute :force, :boolean, description: 'Ship even if it drives the source below zero.'
+          end
+
+          request_params 'ReceivableCloseParams', action: :close do |body|
+            body.attribute :reason, :string, nullable: true, description: 'Why the balance is not coming.'
+          end
+
+          request_params 'StockTransferCancelParams', action: :cancel do |body|
+            body.attribute :on_in_transit, :string,
+              choices: %w[restock write_off],
+              description: 'Required once the units have left the source: either they come back (`restock`) or they are written off as lost (`write_off`).'
+            body.attribute :reason, :string, nullable: true, description: 'Recorded against the written-off lines.'
+          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.
@@ -38,7 +79,7 @@ module Spree
             unless @resource.draft?
               return render_error(
                 code: 'invalid_status',
-                message: Spree.t('stock_transfer.errors.only_draft_can_be_deleted'),
+                message: I18n.t('spree.stock_transfer.errors.only_draft_can_be_deleted'),
                 status: :unprocessable_content
               )
             end
@@ -129,10 +170,17 @@ module Spree
               items: items_from_params(:quantity_shipped) || [],
               reference: params[:reference],
               notes: params[:notes],
+              metadata: metadata_from_params,
               created_by: try_spree_current_user
             }
           end
 
+          # 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
+
           def update_workflow_arguments
             {
               stock_transfer: @resource,
@@ -141,13 +189,6 @@ module Spree
             }
           end
 
-          # Only what mass assignment may safely carry. The two warehouses are
-          # resolved through the store instead, since an id the payload names
-          # has to be proved to belong here.
-          def resource_permitted_attributes
-            [:reference, :notes, { metadata: {} }]
-          end
-
           # A transfer's status transitions are its own actions, so `update`
           # only ever edits the document — and its two ends are objects the
           # store handed us, never ids the payload asserted.