spree_api 6.0.0.beta4 → 6.0.0.rc2

data/app/controllers/spree/api/v3/admin/customers/store_credits_controller.rb

@@ -9,9 +9,15 @@ module Spree
             # broad customer access.
             scoped_resource :store_credits
 
+            request_params :customer_store_credit do |body|
+              body.attribute :amount, :decimal, required: true, on: :create, example: '50.00'
+              body.attribute :currency, :currency, required: true, on: :create, only: :create, example: 'USD'
+              body.attribute :memo, :string
+            end
+
             # POST /api/v3/admin/customers/:customer_id/store_credits
             def create
-              @resource = @parent.store_credits.new(create_attrs)
+              @resource = @parent.store_credits.new(store_credit_attributes)
               @resource.created_by = try_spree_current_user
               @resource.store ||= current_store
               authorize_resource!(@resource, :create)
@@ -27,7 +33,7 @@ module Spree
             def update
               authorize_resource!(@resource)
 
-              if @resource.amount_used.positive? && update_attrs.key?(:amount)
+              if @resource.amount_used.positive? && store_credit_attributes.key?(:amount)
                 render_error(
                   code: 'store_credit_in_use',
                   message: 'Cannot change amount on a store credit that has already been used',
@@ -36,7 +42,7 @@ module Spree
                 return
               end
 
-              if @resource.update(update_attrs)
+              if @resource.update(store_credit_attributes)
                 render json: serialize_resource(@resource.reload)
               else
                 render_validation_error(@resource.errors)
@@ -62,10 +68,6 @@ module Spree
 
             protected
 
-            def parent_association
-              :store_credits
-            end
-
             # Customers are global; store credits belong to a store, so the
             # nested collection is bound to the current store.
             def scope
@@ -82,12 +84,8 @@ module Spree
 
             private
 
-            def create_attrs
-              params.permit(:amount, :currency, :memo).to_h
-            end
-
-            def update_attrs
-              params.permit(:memo, :amount).to_h
+            def store_credit_attributes
+              params.permit(*declared_permitted_attributes).to_h
             end
           end
         end

data/app/controllers/spree/api/v3/admin/customers/tax_identifiers_controller.rb

@@ -8,6 +8,11 @@ module Spree
 
             include Spree::Api::V3::TaxIdentifierValidation
 
+            request_params :tax_identifier do |body|
+              body.include_attributes Spree::Api::V3::Admin::TaxIdentifierRequestSchema
+              body.require_attributes :kind, :value, on: :create
+            end
+
             # Re-declaring the filter replaces the inherited options, so the
             # standard actions have to be listed alongside the custom one.
             before_action :set_resource, only: [:show, :update, :destroy, :validate]
@@ -33,7 +38,7 @@ module Spree
             end
 
             def permitted_params
-              params.permit(:kind, :value)
+              params.permit(*declared_permitted_attributes)
             end
           end
         end

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

@@ -7,6 +7,40 @@ module Spree
 
           scoped_resource :customers
 
+          request_params :customer do |body|
+            body.attribute :email, :string, required: true, on: :create, example: 'new@example.com'
+            body.attribute :first_name, :string
+            body.attribute :last_name, :string
+            body.attribute :phone, :string
+            body.attribute :password, :string,
+              description: 'Optional: a customer created without one claims the account through a password reset.'
+            body.attribute :password_confirmation, :string,
+              description: 'Optional: a customer created without one claims the account through a password reset.'
+            body.attribute :selected_locale, :string
+            body.attribute :avatar_signed_id, :string, description: 'A `signed_id` from `files.upload()`.'
+            body.attribute :accepts_email_marketing, :boolean
+            body.attribute :internal_note, :string,
+              description: 'Rich text HTML. Reads come back as this plus `internal_note_html`.'
+            body.attribute :metadata, :hash
+            body.attribute :tags, :array, of: :string
+            body.attribute :customer_group_ids, :array, of: :id,
+              description: "Replaces the customer's group membership."
+          end
+
+          %i[bulk_add_to_groups bulk_remove_from_groups].each do |action|
+            request_params 'CustomerBulkGroupsParams', action: action do |body|
+              body.attribute :ids, :array, of: :id, required: true, example: %w[cus_UkLWZg9DAJ cus_QrLWXg9CAJ]
+              body.attribute :customer_group_ids, :array, of: :id,
+                required: true,
+                example: %w[cg_UkLWZg9DAJ],
+                description: 'Groups from other stores are ignored.'
+            end
+          end
+
+          %i[bulk_add_tags bulk_remove_tags].each do |action|
+            request_params('BulkTagsParams', action: action) { |body| body.include_attributes Spree::Api::V3::Admin::BulkTagsRequestSchema }
+          end
+
           # Re-declaring a `before_action` for the same method REPLACES the
           # inherited registration rather than adding to it, so the inherited
           # actions have to be repeated here or show/update/destroy silently
@@ -51,7 +85,7 @@ module Spree
           rescue Spree::Core::DestroyWithOrdersError => e
             render_error(
               code: 'customer_has_orders',
-              message: e.message.presence || Spree.t(:error_user_destroy_with_orders),
+              message: e.message.presence || I18n.t('spree.error_user_destroy_with_orders'),
               status: :unprocessable_content
             )
           end
@@ -108,7 +142,7 @@ module Spree
             if @resource.anonymized?
               return render_error(
                 code: ERROR_CODES[:validation_error],
-                message: Spree.t('data_request_errors.already_anonymized'),
+                message: I18n.t('spree.data_request_errors.already_anonymized'),
                 status: :unprocessable_content
               )
             end
@@ -258,13 +292,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(
-              *model_additional_permitted_attributes,
-              :email, :first_name, :last_name, :phone,
-              :password, :password_confirmation, :selected_locale,
-              :avatar, :accepts_email_marketing, :internal_note,
-              metadata: {}, tags: [], customer_group_ids: []
-            )
+            params.permit(*permitted_attributes)
           end
 
           # Authorises bulk group mutation, decodes prefixed IDs, then dispatches

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

@@ -11,6 +11,14 @@ module Spree
         class DataRequestsController < ResourceController
           scoped_resource :customers
 
+          request_params 'DataRequestCreateParams', action: :create do |body|
+            body.attribute :customer_id, :id, required: true
+            body.attribute :kind, :string,
+              required: true,
+              choices: Spree::DataRequest::KINDS,
+              description: "`access` asks for a copy of the customer's personal data; `erasure` asks for it to be erased."
+          end
+
           def create
             authorize! :create, Spree::DataRequest
 

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

@@ -15,7 +15,7 @@ module Spree
                 type: klass.api_type,
                 name: klass.human_name,
                 description: klass.human_description,
-                preference_schema: klass.serialized_preference_schema,
+                schema: klass.preference_json_schema,
                 # Association-backed config (e.g. `product_ids`) a rule accepts
                 # beyond its preferences, so admin UIs can render the right
                 # editor without hardcoding rule types.

data/app/controllers/spree/api/v3/admin/delivery_methods/rules_controller.rb

@@ -8,6 +8,18 @@ module Spree
           class RulesController < ResourceController
             scoped_resource :delivery_methods
 
+            request_params :delivery_method_rule do |body|
+              body.attribute :type, :string,
+                required: true,
+                only: :create,
+                example: 'excluded_products_rule',
+                description: 'A rule kind from the delivery method rule types endpoint.'
+              body.attribute :active, :boolean, description: 'Defaults to true on create.'
+              body.attribute :preferences, :hash, description: "Values for the rule kind's preference schema."
+              body.attribute :product_ids, :array, of: :id,
+                description: 'Products an association-backed rule (`excluded_products_rule`) applies to. An empty list clears them.'
+            end
+
             def create
               rule_class = Spree.delivery_method_rules.detect do |klass|
                 klass.api_type == params[:type].to_s
@@ -16,8 +28,8 @@ module Spree
               if rule_class.nil?
                 return render_error(
                   code: ERROR_CODES[:validation_error],
-                  message: Spree.t('errors.messages.invalid_delivery_method_rule'),
-                  status: :unprocessable_entity
+                  message: I18n.t('spree.errors.messages.invalid_delivery_method_rule'),
+                  status: :unprocessable_content
                 )
               end
 
@@ -62,7 +74,7 @@ module Spree
             end
 
             def permitted_params
-              params.permit(*model_additional_permitted_attributes, :type, :active, preferences: {}, product_ids: [])
+              params.permit(*permitted_attributes)
             end
 
             private
@@ -86,11 +98,7 @@ module Spree
             end
 
             def assign_rule_preferences(rule)
-              (permitted_params[:preferences] || {}).each do |key, value|
-                next unless rule.has_preference?(key)
-
-                rule.set_preference(key, value)
-              end
+              rule.assign_preferences(permitted_params[:preferences]) if permitted_params[:preferences]
             end
 
             # Association-backed rule config (ExcludedProductsRule). Products are

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

@@ -5,6 +5,88 @@ module Spree
         class DeliveryMethodsController < ResourceController
           scoped_resource :delivery_methods
 
+          # A single POST/PATCH can ship eligibility rules and carrier service
+          # rows alongside the basics; `DeliveryMethod#rules=` / `#services=`
+          # reconcile to the desired set, so the dashboard saves the whole
+          # sheet in one round-trip.
+          request_params :delivery_method do |body|
+            body.attribute :name, :string, required: true, on: :create, example: 'Express'
+            body.attribute :admin_name, :string, nullable: true
+            body.attribute :code, :string, nullable: true
+            body.attribute :fulfillment_provider, :string,
+              example: 'manual',
+              description: 'Fulfillment provider shorthand (see the fulfillment providers endpoint), e.g. `manual`.'
+            body.attribute :pickup_point_provider, :string, nullable: true
+            body.attribute :rate_provider, :string,
+              nullable: true,
+              description: 'Rate provider shorthand (see the rate providers endpoint), e.g. `easy_post`. Omit or send null for the built-in provider, which prices through the method\'s calculator.'
+            body.attribute :storefront_visible, :boolean
+            body.attribute :available_to_sellers, :boolean,
+              description: "Marketplace only: whether a seller's packages may be quoted by this method. Off by default, and refused on a method that belongs to a seller."
+            body.attribute :tracking_url, :string, nullable: true
+            body.attribute :estimated_transit_business_days_min, :integer, nullable: true
+            body.attribute :estimated_transit_business_days_max, :integer, nullable: true
+            body.attribute :tax_category_id, :id,
+              nullable: true,
+              description: 'Prefixed tax category ID (`taxcat_...`), or null to clear.'
+            body.attribute :markup_flat, :decimal,
+              nullable: true,
+              description: 'Method-level flat handling fee added on top of provider-quoted rates.'
+            body.attribute :markup_percent, :decimal,
+              nullable: true,
+              description: 'Method-level percentage handling fee added on top of provider-quoted rates. Ignored for calculator-priced methods.'
+            body.attribute :delivery_profile_id, :id,
+              example: 'fp_86Rf07xd4z',
+              description: 'Delivery profile this method belongs to (`fp_...`); defaults to the store default profile.'
+            body.attribute :delivery_origin_group_id, :id,
+              description: "Origin group offering this method (`og_...`); defaults to the zone's group, else the profile's default group."
+            body.attribute :delivery_zone_id, :id,
+              nullable: true,
+              description: "Delivery zone narrowing destinations (`dz_...`), or null for no restriction. Must belong to the method's profile."
+            body.attribute :stock_location_ids, :array, of: :id,
+              description: 'Pickup locations (`sloc_...`); replaces the full set.'
+            body.attribute :calculator, :object,
+              description: "How the method prices a shipment: a type from the calculators endpoint and its preferences, matching that type's `schema`." do |calculator|
+              calculator.attribute :type, :string, example: 'flat_rate'
+              calculator.attribute :preferences, :hash, example: { amount: '12.5' }
+            end
+            # Permitted by `rule_attributes`, which adds the association-backed
+            # config each registered rule kind declares.
+            body.attribute :rules, :array,
+              permit: false,
+              description: 'Eligibility rules. Replaces the full set: omitted rules are removed.' do |rule|
+              rule.attribute :id, :id
+              rule.attribute :type, :string, description: 'A rule kind from the delivery method rule types endpoint.'
+              rule.attribute :active, :boolean
+              rule.attribute :preferences, :hash
+              rule.attribute :product_ids, :array, of: :id,
+                description: 'Products an association-backed rule (`excluded_products_rule`) applies to.'
+            end
+            body.attribute :services, :array,
+              as: 'DeliveryMethodServiceParams',
+              description: 'Carrier service rows: which provider services this method offers. Replaces the full set: omitted rows are removed; no rows means every service the provider returns is offered.' do |service|
+              service.attribute :id, :id, description: 'Prefixed row ID (`dms_...`) when updating an existing row.'
+              service.attribute :carrier, :string,
+                required: true,
+                example: 'UPS',
+                description: "Carrier identifier as the provider's API knows it."
+              service.attribute :service, :string,
+                required: true,
+                example: 'Ground',
+                description: "Service identifier as the provider's API knows it."
+              service.attribute :label, :string,
+                nullable: true,
+                description: 'Display label shown to customers instead of the carrier-derived name.'
+              service.attribute :markup_flat, :decimal,
+                nullable: true,
+                description: 'Overrides the method-level flat markup for this service.'
+              service.attribute :markup_percent, :decimal,
+                nullable: true,
+                description: 'Overrides the method-level percentage markup for this service.'
+              service.attribute :position, :integer
+            end
+          end
+
           # GET /api/v3/admin/delivery_methods/calculators
           # Registered delivery calculator classes with their preference
           # schemas, so admin UIs can render configuration forms.
@@ -15,7 +97,7 @@ module Spree
               {
                 type: calculator_class.api_type,
                 name: calculator_class.description,
-                preference_schema: calculator_class.respond_to?(:serialized_preference_schema) ? calculator_class.serialized_preference_schema : []
+                schema: calculator_class.preference_json_schema
               }
             end
 
@@ -31,9 +113,8 @@ module Spree
 
             data = Spree.fulfillment_providers.map do |provider_class|
               {
-                type: provider_class.to_s,
+                type: provider_class.api_type,
                 name: provider_class.provider_name,
-                integration_class: provider_class.integration_class,
                 integration_type: integration_api_type(provider_class),
                 available: provider_class.available_for_store?(current_store),
                 digital: provider_class.digital?,
@@ -61,9 +142,8 @@ module Spree
               catalog = provider_class.service_catalog(integration)
 
               {
-                type: provider_class.to_s,
+                type: provider_class.api_type,
                 name: provider_class.provider_name,
-                integration_class: provider_class.integration_class,
                 integration_type: integration_api_type(provider_class),
                 available: provider_class.available_for_store?(current_store),
                 requires_address: provider_class.requires_address?,
@@ -76,15 +156,15 @@ module Spree
               }
             end
 
-            render json: { data: data, default: Spree::DeliveryMethod::DEFAULT_RATE_PROVIDER }
+            render json: { data: data, default: Spree::ApiTyped.api_type_for(Spree::DeliveryMethod::DEFAULT_RATE_PROVIDER) }
           end
 
           def create
             @resource = model_class.new(assignable_params)
             authorize_resource!(@resource, :create)
-            assign_calculator(@resource)
+            @resource.assign_calculator_attributes(permitted_params[:calculator])
 
-            if @resource.errors.empty? && @resource.save
+            if @resource.save
               render json: serialize_resource(@resource), status: :created
             else
               render_validation_error(@resource.errors)
@@ -92,10 +172,12 @@ module Spree
           end
 
           def update
-            @resource.assign_attributes(assignable_params)
-            assign_calculator(@resource)
+            saved = save_atomically do
+              @resource.assign_attributes(assignable_params)
+              @resource.assign_calculator_attributes(permitted_params[:calculator])
+            end
 
-            if @resource.errors.empty? && @resource.save
+            if saved
               render json: serialize_resource(@resource)
             else
               render_validation_error(@resource.errors)
@@ -120,23 +202,8 @@ module Spree
             Spree.api.admin_delivery_method_serializer
           end
 
-          # A single POST/PATCH can ship eligibility rules and carrier service
-          # rows alongside the basics; `DeliveryMethod#rules=` / `#services=`
-          # reconcile to the desired set, so the dashboard saves the whole
-          # sheet in one round-trip.
           def permitted_params
-            params.permit(
-              *model_additional_permitted_attributes,
-              :name, :admin_name, :code, :fulfillment_provider,
-              :pickup_point_provider, :rate_provider, :storefront_visible, :tracking_url,
-              :available_to_sellers,
-              :estimated_transit_business_days_min, :estimated_transit_business_days_max,
-              :tax_category_id, :calculator_type, :markup_flat, :markup_percent,
-              :delivery_profile_id, :delivery_origin_group_id, :delivery_zone_id,
-              stock_location_ids: [], calculator_preferences: {},
-              rules: rule_attributes,
-              services: [:id, :carrier, :service, :label, :markup_flat, :markup_percent, :position]
-            )
+            params.permit(*permitted_attributes, rules: rule_attributes)
           end
 
           def rule_attributes
@@ -160,7 +227,7 @@ module Spree
 
           # Resolves prefixed-ID params to records; calculator handled separately.
           def assignable_params
-            attributes = permitted_params.except(:tax_category_id, :delivery_profile_id, :delivery_origin_group_id, :delivery_zone_id, :stock_location_ids, :calculator_type, :calculator_preferences)
+            attributes = permitted_params.except(:tax_category_id, :delivery_profile_id, :delivery_origin_group_id, :delivery_zone_id, :stock_location_ids, :calculator)
             if params.key?(:tax_category_id)
               attributes[:tax_category] = params[:tax_category_id].present? ? Spree::TaxCategory.accessible_by(current_ability, :show).find_by_prefix_id!(params[:tax_category_id]) : nil
             end
@@ -202,40 +269,6 @@ module Spree
               where(id: decode_prefixed_ids(ids)).
               pluck(:id)
           end
-
-          def assign_calculator(delivery_method)
-            calculator_type = permitted_params[:calculator_type]
-            preferences = permitted_params[:calculator_preferences]
-
-            if calculator_type.present? && delivery_method.calculator&.class&.api_type != calculator_type
-              selected_calculator_class = Spree::DeliveryMethod.calculators.find do |klass|
-                klass.api_type == calculator_type
-              end
-              unless selected_calculator_class
-                delivery_method.errors.add(:calculator_type, :invalid)
-                return
-              end
-
-              delivery_method.calculator = selected_calculator_class.new
-            end
-
-            return if preferences.blank?
-
-            # A payload may carry preferences without naming a calculator —
-            # editing the amount on a method that already has one, or creating
-            # with the default. The model only builds the default calculator
-            # at validation, so without this the preferences land on nothing
-            # and the amount the merchant typed is silently replaced by a free
-            # rate.
-            delivery_method.ensure_calculator
-            return if delivery_method.calculator.nil?
-
-            preferences.each do |key, value|
-              next unless delivery_method.calculator.has_preference?(key)
-
-              delivery_method.calculator.set_preference(key, value)
-            end
-          end
         end
       end
     end

data/app/controllers/spree/api/v3/admin/delivery_profiles/origin_groups_controller.rb

@@ -10,6 +10,13 @@ module Spree
           class OriginGroupsController < ResourceController
             scoped_resource :settings
 
+            request_params 'DeliveryOriginGroupParams' do |body|
+              body.attribute :name, :string, nullable: true, example: 'EU warehouse'
+              body.attribute :position, :integer
+              body.attribute :stock_location_ids, :array, of: :id,
+                description: 'Prefixed stock location IDs (`sloc_...`); replaces the full set. Empty means every store location.'
+            end
+
             def create
               @resource = scope.new(assignable_params)
               authorize_resource!(@resource, :create)
@@ -46,7 +53,7 @@ module Spree
             end
 
             def permitted_params
-              params.permit(*model_additional_permitted_attributes, :name, :position, stock_location_ids: [])
+              params.permit(*permitted_attributes)
             end
 
             def collection_includes

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

@@ -9,18 +9,25 @@ module Spree
         class DeliveryProfilesController < ResourceController
           scoped_resource :settings
 
+          request_params :delivery_profile do |body|
+            body.attribute :name, :string, required: true, on: :create, example: 'Oversized'
+            body.attribute :kind, :string,
+              example: 'shipping',
+              description: 'Registered profile kind (`shipping`, `digital`, extension kinds) from the kinds endpoint. Read on create only; defaults to shipping.'
+            body.attribute :default, :boolean,
+              description: 'Promotes this profile to the store default; the previous default is demoted.'
+            body.attribute :position, :integer
+            body.attribute :stock_location_ids, :array, of: :id,
+              description: 'Prefixed stock location IDs (`sloc_...`); replaces the full set. Empty means every store location.'
+          end
+
           # GET /api/v3/admin/delivery_profiles/kinds
           # Registered profile kinds, so admin UIs offer extension-added
           # kinds without hardcoding the built-ins.
           def kinds
             authorize! :create, model_class
 
-            data = Spree.delivery_profile_types.map do |profile_class|
-              {
-                type: profile_class.to_s,
-                kind: profile_class.api_type
-              }
-            end
+            data = Spree.delivery_profile_types.map { |profile_class| { kind: profile_class.api_type } }
 
             render json: { data: data }
           end
@@ -63,7 +70,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(*model_additional_permitted_attributes, :name, :default, :position, :kind, stock_location_ids: [])
+            params.permit(*permitted_attributes)
           end
 
           def collection_includes

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

@@ -8,6 +8,26 @@ module Spree
         class DeliveryZonesController < ResourceController
           scoped_resource :settings
 
+          request_params :delivery_zone do |body|
+            body.attribute :name, :string, required: true, on: :create, example: 'US North-East'
+            body.attribute :description, :string, nullable: true
+            body.attribute :delivery_profile_id, :id,
+              description: 'Delivery profile this zone belongs to (`fp_...`); defaults to the store default profile.'
+            body.attribute :delivery_origin_group_id, :id,
+              description: 'Origin group this zone belongs to (`og_...`).'
+            body.attribute :members, :array,
+              as: 'DeliveryZoneMemberParams',
+              description: "Replaces the zone's full member set atomically." do |member|
+              member.attribute :member_type, :string, required: true, choices: Spree::DeliveryZoneMember::MEMBER_TYPES
+              member.attribute :country_code, :country, example: 'US'
+              member.attribute :state_code, :string,
+                description: 'A subdivision code or name. Without `country_code` the country is inferred when only one country matches.'
+              member.attribute :postal_code_prefix, :string
+              member.attribute :postal_code_from, :string
+              member.attribute :postal_code_to, :string
+            end
+          end
+
           def create
             @resource = model_class.new(zone_params)
             authorize_resource!(@resource, :create)
@@ -50,11 +70,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(
-              *model_additional_permitted_attributes,
-              :name, :description, :delivery_profile_id, :delivery_origin_group_id,
-              members: [:member_type, :country_code, :state_code, :postal_code_prefix, :postal_code_from, :postal_code_to]
-            )
+            params.permit(*permitted_attributes)
           end
 
           def collection_includes

data/app/controllers/spree/api/v3/admin/email_templates/drafts_controller.rb

@@ -0,0 +1,53 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module EmailTemplates
+          # The draft of an editable email template: saved in any state, while
+          # customers keep receiving the published version.
+          class DraftsController < Admin::BaseController
+            include Spree::Api::V3::Admin::EmailTemplateLookup
+
+            request_params 'EmailTemplateDraftParams' do |body|
+              body.include_attributes Spree::Api::V3::Admin::EmailTemplateLanguageRequestSchema
+              body.attribute :subject, :string, nullable: true, example: 'Your order {{ order.number }} is confirmed'
+              body.attribute :body, :string,
+                example: '<mj-section><mj-column><mj-text>Thanks, {{ order.customer_name }}!</mj-text></mj-column></mj-section>'
+              body.attribute :lock_version, :integer,
+                nullable: true,
+                example: 0,
+                description: 'The `lock_version` the draft was loaded with, or null when there was no draft; a save from an older copy is refused with 409. Omit it to save without checking.'
+              body.attribute :rebase, :boolean,
+                description: "Marks the draft as based on Spree's current default, after reviewing what changed in it."
+            end
+
+            # PUT /api/v3/admin/email_templates/:email_template_id/draft
+            #
+            # Send the `lock_version` the draft was loaded with: a save made from
+            # an older copy is refused with 409, naming who saved last. `rebase`
+            # marks the draft as based on Spree's current default.
+            def update
+              authorize! :update, Spree::EmailTemplate
+
+              result = Spree.email_template_save_draft_workflow.call(
+                store: current_store, key: email_template.key, locale: language, actor: current_actor,
+                attributes: params.permit(*declared_permitted_attributes).to_h.symbolize_keys
+              )
+              render_email_template_result(result)
+            end
+
+            # DELETE /api/v3/admin/email_templates/:email_template_id/draft
+            def destroy
+              authorize! :update, Spree::EmailTemplate
+
+              result = Spree.email_template_discard_draft_workflow.call(
+                store: current_store, key: email_template.key, locale: language, lock_version: params[:lock_version].presence
+              )
+              render_email_template_result(result)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/email_templates/previews_controller.rb

@@ -0,0 +1,34 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module EmailTemplates
+          class PreviewsController < Admin::BaseController
+            include Spree::Api::V3::Admin::EmailTemplateLookup
+
+            request_params 'EmailTemplatePreviewParams' do |body|
+              body.include_attributes Spree::Api::V3::Admin::EmailTemplatePreviewRequestSchema
+            end
+
+            before_action :authorize_sample_data!
+
+            # POST /api/v3/admin/email_templates/:email_template_id/preview
+            #
+            # Renders the template with sample data built from the store's latest
+            # matching record, or the one `record_id` names. An unsaved `subject`
+            # and `body` take the place of the current version. Returns the
+            # rendered email and the variables it was rendered with.
+            def create
+              authorize! :update, Spree::EmailTemplate
+
+              preview = build_preview
+              preview.call
+
+              render json: Spree.api.admin_email_template_preview_serializer.new(preview, params: serializer_params).to_h
+            end
+          end
+        end
+      end
+    end
+  end
+end