spree_api 6.0.0.beta4 → 6.0.0.rc2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cbd216e65a6f6ce291a04b750595491f827262d4de353562ac43fa51d69c376e
-  data.tar.gz: ed6181390f17841dc63104e068e6812d936dc29d3896c8366ea27cebc6817274
+  metadata.gz: 06aac9de6a57402c698fb881a27df504047b5a488e9bdc87b472af681115d5f8
+  data.tar.gz: fa3c078090e803d00a5fa1b947b594175d8c5657d90e9490f074a57b814f7dd3
 SHA512:
-  metadata.gz: 50b7fd005e9f4c80d83c1be99a3e4abf9c84a947e5b801fae461a4596b3e5005a376c2fbb1a6e9aeea063492cdc3548116cfdca5621b551598fbcbac1635fb4c
-  data.tar.gz: '00699269b7d5c5c53d2154a32784c48a8e42a9a2759c05e387fb2218a5725249ab52179861f69b0afa217c5fe429a855fcc3077b9d21dce2efcfea6317cad20e'
+  metadata.gz: c3d0ab4516f51aaa3e3c062e35fc1267c2c90191948e5b0d0dc5a7d6fba6b7ce5020cc66ac563ea9ae49c3948d13cf8a2245b655678fb14806612409d3f7cae3
+  data.tar.gz: ac4aae51601b99ab1e4985c521a6edd4dae0613ec68f7950f837cf6fa4181a3c258fd9765206443e1a1b590e2584ce64fb2a93174dd9276a73bc526446a02111

data/Rakefile

@@ -45,61 +45,17 @@ namespace :rswag do
           puts "Reordered paths by tag → #{path}"
         end
       end
-
-      # Keep the CLI's bundled offline spec (@spree/cli's `admin-spec.json` /
-      # `resource-paths.json`) in sync with the freshly generated admin.yaml,
-      # so `spree api endpoints`/`schema` never drift from the published docs.
-      # Best-effort: skipped with a notice when the JS toolchain isn't present
-      # (this is a Ruby/doc task and shouldn't hard-fail on a missing runtime).
-      bundler = File.expand_path('../../packages/cli/scripts/bundle-spec.mjs', __dir__)
-      if File.exist?(bundler) && system('node', '--version', out: File::NULL, err: File::NULL)
-        cli_dir = File.expand_path('../../packages/cli', __dir__)
-        if system('node', bundler, chdir: cli_dir)
-          puts 'Regenerated CLI offline spec → packages/cli/src/generated/'
-        else
-          warn 'WARNING: failed to regenerate CLI offline spec (bundle-spec.mjs); run `pnpm --filter @spree/cli build` to resync.'
-        end
-      else
-        puts 'Skipping CLI offline spec regeneration (node/bundle-spec.mjs unavailable).'
-      end
     end
   end
 end
 
 namespace :typelizer do
-  desc 'Generate TypeScript types for both Store and Admin SDKs'
+  desc 'Generate TypeScript types for every SDK (runs in spree_emails, where all serializers load)'
   task :generate do
-    ENV['RAILS_ENV'] ||= 'test'
-    ENV['DISABLE_TYPELIZER'] = 'false'
-
-    require File.expand_path('spec/dummy/config/environment', __dir__)
-
-    # Eager load serializers so typelizer can find them
-    serializers_path = File.expand_path('app/serializers/spree/api/v3', __dir__)
-    Rails.autoloaders.main.eager_load_dir(serializers_path)
-
-    require 'typelizer/generator'
-
-    # Writer config is in config/initializers/typelizer.rb
-    Typelizer::Generator.call(force: true)
-
-    # Post-process: convert `type Foo = {` to `interface Foo {` for declaration merging support.
-    # This lets SDK consumers extend generated types via `declare module '@spree/sdk' { interface Product { ... } }`.
-    api_root = Spree::Api::Engine.root
-    [
-      api_root.join('../../packages/sdk/src/types/generated'),
-      api_root.join('../../packages/admin-sdk/src/types/generated')
-    ].each do |dir|
-      Dir[File.join(dir, '*.ts')].each do |file|
-        next if File.basename(file) == 'index.ts'
-
-        content = File.read(file)
-        updated = content.gsub(/^type (\w+) = \{/, 'interface \1 {')
-        File.write(file, updated) if updated != content
-      end
+    emails_dir = File.expand_path('../emails', __dir__)
+    Bundler.with_unbundled_env do
+      sh "cd #{emails_dir} && bundle exec rake typelizer:generate"
     end
-
-    puts "Generated types → packages/sdk/src/types/generated/ & packages/admin-sdk/src/types/generated/"
   end
 
   desc 'Clean and regenerate TypeScript types'

data/app/controllers/concerns/spree/api/v3/admin/email_template_lookup.rb

@@ -0,0 +1,139 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Finds the editable email template a request is about, from its
+        # dotted key, for the language the request names.
+        module EmailTemplateLookup
+          extend ActiveSupport::Concern
+
+          included do
+            scoped_resource :email_templates
+
+            before_action :load_email_template
+
+            rescue_from Spree::EmailTemplates::NoSampleRecord, with: :render_no_sample
+            rescue_from Liquid::Error, MRML::Error, with: :render_render_error
+          end
+
+          private
+
+          attr_reader :email_template
+
+          def load_email_template
+            @email_template = Spree::EmailTemplates::Entry.for_id(
+              current_store, params[:email_template_id] || params[:id], locale: language
+            )
+          end
+
+          # A language code, or "any" for the version every language uses. Named
+          # `language` rather than `locale`, which picks the response's language.
+          def language
+            @language ||= params[:language].to_s.strip.presence || Spree::EmailTemplate::ANY_LOCALE
+          end
+
+          def serialize_email_template(reload: false)
+            load_email_template if reload
+            Spree.api.admin_email_template_serializer.new(email_template, params: serializer_params).to_h
+          end
+
+          def serializer_class
+            Spree.api.admin_email_template_serializer
+          end
+
+          # Renders the template as it stands after a workflow ran, or why the
+          # workflow refused.
+          def render_email_template_result(result, status: :ok)
+            return render_stale_draft if result.error&.value == :stale
+            return render_template_problems(result.value) if result.error&.value == :invalid_template
+            return render_result_error(result) unless result.success?
+
+            render json: serialize_email_template(reload: true), status: status
+          end
+
+          # Every published version of the template in the requested language.
+          def email_template_revisions
+            Spree::EmailTemplateRevision.where(
+              email_template: current_store.email_templates.for_key(email_template.key, language)
+            )
+          end
+
+          # An unsaved subject and body are previewed only when sent, so an
+          # empty body still previews as empty. `branding` previews unsaved
+          # colors and font.
+          def preview_arguments
+            arguments = params.permit(:record_id, :subject, :body).to_h.symbolize_keys
+            arguments[:locale] = language
+            arguments[:email_key] = params[:email_key].to_s.tr('.', '/').presence
+            arguments[:branding] = params.fetch(:branding, {}).permit(*Spree::Emails::Branding.attribute_names).to_h
+            arguments
+          end
+
+          # Samples show a real record of the store (the latest order, a
+          # company), so previewing one needs permission to read it.
+          def authorize_sample_data!
+            missing = sample_classes.flat_map { |sample| Array(sample.try(:required_permissions)) }.uniq.
+                      reject { |key| holds_permission?(key) }
+            return if missing.empty?
+
+            render_error(
+              code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:access_denied],
+              message: I18n.t('spree.email_templates.sample_needs_permission', permissions: missing.to_sentence),
+              status: :forbidden,
+              details: { required_scope: missing.first }
+            )
+          end
+
+          # A preview shows one email; publishing the layout or a partial
+          # renders every email, so it needs what all of their samples need.
+          def sample_classes
+            if action_name == 'create' && controller_name == 'publications' && !email_template.definition.email?
+              Spree.editable_email_templates.emails.map(&:sample_class)
+            else
+              [build_preview.email.sample_class]
+            end
+          end
+
+          def build_preview
+            Spree::EmailTemplates::Preview.new(store: current_store, key: email_template.key, strict: true, **preview_arguments)
+          end
+
+          def render_template_problems(problems)
+            problems = problems.map { |problem| problem.merge(email: problem[:email].tr('/', '.')) }
+
+            render_error(
+              code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:email_template_invalid],
+              message: problems.map { |problem| problem[:message] }.uniq.to_sentence,
+              status: :unprocessable_content,
+              details: { problems: problems }
+            )
+          end
+
+          # Attributed to the template being edited, whose lines the editor marks.
+          def render_render_error(error)
+            render_template_problems([{ email: email_template.id, message: error.message, line: error.try(:line_number) }])
+          end
+
+          def render_no_sample(error)
+            render_error(
+              code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:email_template_no_sample],
+              message: error.message,
+              status: :unprocessable_content
+            )
+          end
+
+          def render_stale_draft
+            saved_by = email_template.draft&.updated_by&.actor_label
+
+            render_error(
+              code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:email_template_stale],
+              message: I18n.t('spree.email_templates.stale_draft', name: saved_by || I18n.t('spree.email_templates.another_admin')),
+              status: :conflict,
+              details: { updated_by: saved_by }
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/concerns/spree/api/v3/admin/product_membership.rb

@@ -32,6 +32,16 @@ module Spree
             # Membership actions resolve products themselves; the base
             # single-resource load has nothing to look up.
             skip_before_action :set_resource
+
+            # Adding (create) and removing (destroy) take the same body.
+            [nil, :destroy].each do |action|
+              request_params 'ProductMembershipParams', action: action do |body|
+                body.attribute :product_ids, :array, of: :id,
+                  required: true,
+                  example: %w[prod_abc123],
+                  description: 'Products from other stores, or ones the caller cannot see, are ignored.'
+              end
+            end
           end
 
           # POST /{parents}/:parent_id/products

data/app/controllers/concerns/spree/api/v3/admin/stock_receipt_actions.rb

@@ -15,6 +15,32 @@ module Spree
 
           included do
             before_action :authorize_parent_access!
+
+            # Read from the raw params by `create_workflow_arguments`, with
+            # every line resolved through the document.
+            request_params :stock_receipt do |body|
+              body.attribute :reference, :string,
+                nullable: true,
+                example: 'DN-4471',
+                description: "The supplier's delivery note, or the carrier's reference."
+              body.attribute :received_at, :datetime,
+                nullable: true,
+                description: 'When the goods were counted in. Defaults to now.'
+              body.attribute :notes, :string, nullable: true
+              body.attribute :items, :array,
+                permit: false,
+                as: 'StockReceiptItemParams',
+                description: 'Omit to book in everything still outstanding, intact. Naming lines, even none, records exactly what the dock counted: `quantity_accepted` reaches the shelf; `quantity_rejected` is refused, recorded with a `rejection_reason` and never stocked.' do |item|
+                item.attribute :id, :id, required: true, description: 'The purchase order or transfer line.'
+                item.attribute :quantity_accepted, :integer, example: 58
+                item.attribute :quantity_rejected, :integer, example: 2
+                item.attribute :rejection_reason, :string,
+                  nullable: true,
+                  choices: Spree::StockReceiptItem::REJECTION_REASONS,
+                  example: 'damaged'
+                item.attribute :notes, :string, nullable: true
+              end
+            end
           end
 
           protected
@@ -39,10 +65,6 @@ module Spree
             [items: :line]
           end
 
-          def resource_permitted_attributes
-            [:received_at, :reference, :notes]
-          end
-
           def create_workflow_arguments
             {
               receivable_keyword => @parent,

data/app/controllers/concerns/spree/api/v3/admin/store_context.rb

@@ -44,7 +44,7 @@ module Spree
             if secret_api_key && store_id_header && secret_api_key.store&.prefixed_id != store_id_header
               render_error(
                 code: ErrorHandler::ERROR_CODES[:access_denied],
-                message: Spree.t('api.errors.store_mismatch', default: 'The requested store does not match the store this API key belongs to.'),
+                message: I18n.t('spree.api.errors.store_mismatch'),
                 status: :forbidden
               )
               return

data/app/controllers/concerns/spree/api/v3/admin/subclassed_resource.rb

@@ -13,11 +13,10 @@ module Spree
         #
         # The body picks the subclass against the registry (returns 422 with
         # the configured error code on miss), strips `type`/`preferences`
-        # from the permitted attrs, builds/assigns the rest, and routes
-        # preference values through the typed `preferred_<name>=` setters
-        # so booleans/decimals/etc. get coerced. Unknown preference keys
-        # are silently dropped — the schema endpoint is the source of truth
-        # for what's settable.
+        # from the permitted attrs, builds/assigns the rest, and writes the
+        # preferences after checking them against the subclass's schema —
+        # an unknown key or a value of the wrong type is a 422
+        # `invalid_preferences`.
         module SubclassedResource
           extend ActiveSupport::Concern
 
@@ -45,9 +44,9 @@ module Spree
             attrs, preferences, calculator = extract_subclass_params(permitted)
 
             @resource = build_subclassed_resource(klass, attrs)
+            authorize_resource!(@resource, :create)
             apply_preferences(@resource, preferences) if preferences.present?
             apply_calculator(@resource, calculator) if calculator.present?
-            authorize_resource!(@resource, :create)
 
             if @resource.save
               render json: serialize_resource(@resource), status: :created
@@ -63,11 +62,13 @@ module Spree
             permitted = permitted_params_for(@resource.class)
             attrs, preferences, calculator = extract_subclass_params(permitted)
 
-            @resource.assign_attributes(attrs)
-            apply_preferences(@resource, preferences) if preferences.present?
-            apply_calculator(@resource, calculator) if calculator.present?
+            saved = save_atomically do
+              @resource.assign_attributes(attrs)
+              apply_preferences(@resource, preferences) if preferences.present?
+              apply_calculator(@resource, calculator) if calculator.present?
+            end
 
-            if @resource.save
+            if saved
               render json: serialize_resource(@resource)
             else
               render_validation_error(@resource.errors)
@@ -103,31 +104,16 @@ module Spree
           def render_unknown_type
             render_error(
               code: self.class.unknown_type_error_code,
-              message: Spree.t("api.#{self.class.unknown_type_error_code}",
+              message: I18n.t("spree.api.#{self.class.unknown_type_error_code}",
                                default: 'Unknown type'),
               status: :unprocessable_content
             )
           end
 
+          # Validated against the subclass's schema before anything is written
+          # (see `Spree::Preferences::Preferable#assign_preferences`).
           def apply_preferences(resource, preferences)
-            password_keys = resource.password_preference_keys
-
-            preferences.each do |key, value|
-              pref_name = key.to_sym
-              next unless resource.has_preference?(pref_name)
-              # Internal preferences are Spree's to write — a secret a
-              # provider issued, an id it gave back. They are absent from the
-              # schema, so no form offers them; ignoring them here is what
-              # stops a client writing one anyway and breaking the signature
-              # check that depends on it.
-              next if resource.preference_internal(pref_name)
-              # Round-trip guard: clients fetching a record see masked
-              # `:password` values. Submitting the mask back unchanged
-              # must NOT overwrite the real secret with `••••cret`.
-              next if password_keys.include?(pref_name) && Spree::Preferences::Masking.masked?(value)
-
-              resource.set_preference(pref_name, value)
-            end
+            resource.assign_preferences(preferences)
           end
 
           # Pulls `preferences` and `calculator` out of the permitted

data/app/controllers/concerns/spree/api/v3/admin/validation_details.rb

@@ -26,7 +26,7 @@ module Spree
               # nil code, which the dashboard reads as "render the message".
               details = errors.details[attribute] || []
 
-              result[attribute] = messages.each_with_index.map do |message, index|
+              result[wire_error_attribute(errors, attribute)] = messages.each_with_index.map do |message, index|
                 detail = details[index] || {}
                 code = detail[:error].is_a?(Symbol) ? detail[:error] : nil
 

data/app/controllers/concerns/spree/api/v3/cart_resolvable.rb

@@ -4,6 +4,8 @@ module Spree
       module CartResolvable
         extend ActiveSupport::Concern
 
+        include Spree::Api::V3::PurchaseSerialization
+
         protected
 
         # Find cart by prefixed ID and authorize read access (owner or guest
@@ -57,6 +59,13 @@ module Spree
           @cart = @cart.remove_out_of_stock_items!
         end
 
+        # Drops a batch coupon code the cart no longer holds. Unlike the line
+        # sweep this runs after writes too, since an API client may rely on
+        # write responses alone to learn why its discount went.
+        def sweep_unavailable_coupon_code!
+          @cart = @cart.remove_unavailable_coupon_code!
+        end
+
         # Render what the checkout produced (for the complete action).
         #
         # A checkout spanning several sellers produced a group of orders rather
@@ -66,9 +75,8 @@ module Spree
         # needs there.
         def render_order(status: :ok)
           record = @cart.reload
-          serializer = record.is_a?(Spree::OrderGroup) ? Spree.api.order_group_serializer : Spree.api.order_serializer
 
-          render json: serializer.new(record, params: serializer_params).to_h, status: status
+          render json: purchase_serializer_for(record).new(record, params: serializer_params).to_h, status: status
         end
 
         # Return the cart token from the request headers.

data/app/controllers/concerns/spree/api/v3/channel_resolution.rb

@@ -59,8 +59,8 @@ module Spree
             if header && header.id != bound.id
               render_error(
                 code: ErrorHandler::ERROR_CODES[:channel_mismatch],
-                message: Spree.t('api.errors.channel_mismatch', default: 'The requested channel does not match the channel this API key is bound to'),
-                status: :unprocessable_entity
+                message: I18n.t('spree.api.errors.channel_mismatch'),
+                status: :unprocessable_content
               )
               return
             end
@@ -68,7 +68,7 @@ module Spree
             unless bound.active?
               render_error(
                 code: ErrorHandler::ERROR_CODES[:channel_inactive],
-                message: Spree.t('api.errors.channel_inactive', default: 'The channel this API key is bound to is not active'),
+                message: I18n.t('spree.api.errors.channel_inactive'),
                 status: :forbidden
               )
               return

data/app/controllers/concerns/spree/api/v3/company_address_writes.rb

@@ -13,8 +13,10 @@ module Spree
 
         protected
 
+        # Each including controller declares the address it takes with
+        # `request_params`.
         def permitted_params
-          params.permit(:label, *Spree::Api::V3::AddressParams::ADDRESS_KEYS)
+          params.permit(*declared_permitted_attributes)
         end
 
         # @return [Hash] default keywords for Spree::Addresses::Create / Update

data/app/controllers/concerns/spree/api/v3/current_password_confirmation.rb

@@ -39,7 +39,7 @@ module Spree
         def render_current_password_invalid
           render_error(
             code: ErrorHandler::ERROR_CODES[:current_password_invalid],
-            message: Spree.t(:current_password_invalid, scope: :api),
+            message: I18n.t('spree.api.current_password_invalid'),
             status: :unprocessable_content
           )
         end

data/app/controllers/concerns/spree/api/v3/error_handler.rb

@@ -48,10 +48,12 @@ module Spree
           insufficient_stock: 'insufficient_stock',
           invalid_quantity: 'invalid_quantity',
           invalid_price: 'invalid_price',
+          invalid_money_format: 'invalid_money_format',
           price_override_not_allowed: 'price_override_not_allowed',
 
           # Validation errors
           validation_error: 'validation_error',
+          invalid_preferences: 'invalid_preferences',
           parameter_missing: 'parameter_missing',
           parameter_invalid: 'parameter_invalid',
 
@@ -74,6 +76,11 @@ module Spree
           # Export errors
           export_not_ready: 'export_not_ready',
 
+          # Email template errors
+          email_template_stale: 'email_template_stale',
+          email_template_invalid: 'email_template_invalid',
+          email_template_no_sample: 'email_template_no_sample',
+
           # Rate limiting errors
           rate_limit_exceeded: 'rate_limit_exceeded',
 
@@ -96,8 +103,11 @@ module Spree
           rescue_from Spree::Core::GatewayError, with: :handle_gateway_error
           rescue_from ActionController::ParameterMissing, with: :handle_parameter_missing
           rescue_from ActiveRecord::RecordInvalid, with: :handle_record_invalid
+          rescue_from Spree::Preferences::InvalidPreferences, with: :handle_invalid_preferences
+          rescue_from ActiveRecord::RecordNotSaved, with: :handle_record_not_saved
           rescue_from ArgumentError, with: :handle_argument_error
           rescue_from ActionDispatch::Http::Parameters::ParseError, with: :handle_parse_error
+          rescue_from ActiveSupport::MessageVerifier::InvalidSignature, with: :handle_invalid_signature
         end
 
         protected
@@ -155,7 +165,7 @@ module Spree
             # Workflows reject with a symbol naming the reason. Translate it,
             # falling back to the symbol so a missing key is visible rather
             # than silently blank.
-            render_error(code: code, message: Spree.t(error, default: error.to_s.humanize), status: status)
+            render_error(code: code, message: I18n.t("spree.#{error}", default: error.to_s.humanize), status: status)
           else
             render_error(code: code, message: error.to_s, status: status)
           end
@@ -239,6 +249,26 @@ module Spree
           render_validation_error(exception.record.errors)
         end
 
+        # Each failing value is keyed by its JSON pointer into the request,
+        # e.g. `/preferences/channel_ids/1`.
+        def handle_invalid_preferences(exception)
+          render_error(
+            code: ERROR_CODES[:invalid_preferences],
+            message: exception.message,
+            status: :unprocessable_content,
+            details: exception.failures.group_by { |failure| failure[:pointer] }.transform_values { |failures| failures.pluck(:message) }
+          )
+        end
+
+        # Replacing a has_one on a saved record saves the new one at once, and
+        # raises when that one fails its own validations.
+        def handle_record_not_saved(exception)
+          errors = exception.record&.errors
+          return render_validation_error(errors) if errors.present?
+
+          render_error(code: ERROR_CODES[:validation_error], message: exception.message, status: :unprocessable_content)
+        end
+
         def handle_argument_error(exception)
           Rails.error.report(exception, context: error_context, source: 'spree.api.v3')
           render_error(
@@ -248,6 +278,16 @@ module Spree
           )
         end
 
+        # A `signed_id` that was tampered with, or has expired (they last a
+        # day), is a bad parameter rather than a server fault.
+        def handle_invalid_signature(_exception)
+          render_error(
+            code: ERROR_CODES[:parameter_invalid],
+            message: I18n.t('spree.upload_reference_invalid'),
+            status: :unprocessable_content
+          )
+        end
+
         def handle_parse_error(exception)
           Rails.error.report(exception, context: error_context, source: 'spree.api.v3')
           message = exception.respond_to?(:original_message) ? exception.original_message : exception.message
@@ -263,11 +303,22 @@ module Spree
 
         # Format validation errors for details field
         def format_validation_details(errors)
-          errors.messages.transform_values do |messages|
-            messages.map { |msg| msg }
+          errors.messages.to_h do |attribute, messages|
+            [wire_error_attribute(errors, attribute), messages.map { |msg| msg }]
           end
         end
 
+        # A setting the API reads and writes under its plain name reports its
+        # errors under that name too, never the `preferred_` one the model uses;
+        # an attachment slot reports them under the `<slot>_signed_id` it is
+        # written with.
+        def wire_error_attribute(errors, attribute)
+          record_class = errors.objects.first&.base&.class
+          (record_class.exposed_preference_name(attribute) if record_class.respond_to?(:exposed_preference_name)) ||
+            (record_class.signed_id_attribute_for(attribute) if record_class.respond_to?(:signed_id_attribute_for)) ||
+            attribute
+        end
+
         # Infer error code from context
         def infer_error_code(errors, status)
           case status
@@ -311,7 +362,7 @@ module Spree
                     model_name&.humanize || 'record'
                   end
 
-          Spree.t(:record_not_found, scope: 'api', model: label)
+          I18n.t('spree.api.record_not_found', model: label)
         end
 
         # Extract clean model name from exception

data/app/controllers/concerns/spree/api/v3/file_uploads.rb

@@ -0,0 +1,35 @@
+module Spree
+  module Api
+    module V3
+      # `POST /files`: accepts a file for the current store and returns the
+      # opaque, expiring `signed_id` an endpoint that uses the file takes
+      # (docs/plans/6.0-uploads-and-file-ownership.md).
+      #
+      # A JSON request carries the file's metadata and gets back a storage
+      # target to send the bytes to; a multipart request carries the bytes in
+      # its `file` part. Shared by the admin and seller branches: a file
+      # stored here is attached to nothing, so what differs is only the gate
+      # each branch puts in front of it, which stays on the including
+      # controller as its `scoped_resource`.
+      module FileUploads
+        extend ActiveSupport::Concern
+
+        def create
+          file_upload = Spree::FileUpload.new(store: current_store, **file_upload_params)
+
+          if file_upload.save
+            render json: file_upload_serializer.new(file_upload, params: serializer_params).to_h, status: :created
+          else
+            render_validation_error(file_upload.errors)
+          end
+        end
+
+        private
+
+        def file_upload_params
+          params.permit(*declared_permitted_attributes).to_h.symbolize_keys
+        end
+      end
+    end
+  end
+end