spree_api 6.0.0.beta4 → 6.0.0.rc2

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

@@ -5,6 +5,125 @@ module Spree
         class StoreController < Admin::BaseController
           scoped_resource :settings
 
+          request_params :store do |body|
+            body.attribute :name, :string, example: 'My Store'
+            body.attribute :admin_locale, :string, example: 'en'
+            body.attribute :timezone, :string, example: 'Europe/Berlin'
+            body.attribute :weight_unit, :string, choices: Spree::Variant::WEIGHT_UNITS
+            body.attribute :unit_system, :string, choices: Spree::Store::UNIT_SYSTEMS
+            body.attribute :storefront_access, :string,
+              choices: Spree::Channel::Gating::STOREFRONT_ACCESS,
+              description: "The store-wide default for what anonymous visitors can see. Channels fall back to it when they don't set their own."
+            body.attribute :storefront_url, :string,
+              nullable: true,
+              description: "The storefront's public URL, the base for links in customer emails. Saving it also completes the storefront setup task."
+            body.attribute :guest_checkout, :boolean,
+              description: 'The store-wide default for guest checkout. Channels fall back to it.'
+            body.attribute :always_include_confirm_step, :boolean,
+              description: 'Always show a confirmation step in checkout, even when no payment method requires one.'
+            body.attribute :company_field_enabled, :boolean, description: 'Shows a company field on address forms.'
+            body.attribute :address_requires_company, :boolean,
+              description: 'Makes a company name mandatory on addresses.'
+            body.attribute :address_requires_phone, :boolean,
+              description: 'Makes a phone number mandatory on customer addresses.'
+            body.attribute :capture_method, :string,
+              choices: Spree::CaptureMethod::CAPTURE_METHODS,
+              description: "The store-wide default for when a customer is charged rather than only authorized. A payment method's own setting wins when set."
+            body.attribute :track_inventory_levels, :boolean,
+              description: 'Counts on-hand quantities. Off means everything is treated as always available.'
+            body.attribute :stock_reservations_enabled, :boolean,
+              description: "Holds stock for shoppers while they check out, so the same item can't be sold twice."
+            body.attribute :low_stock_threshold, :integer,
+              description: 'On-hand units at or below which a tracked variant counts as low stock on the home screen; 0 turns the warning off.'
+            body.attribute :tax_using_ship_address, :boolean,
+              description: 'Calculates tax from the shipping address. When false, tax is calculated from the billing address.'
+            body.attribute :track_price_history, :boolean,
+              description: 'Records price changes for the EU Omnibus lowest-price-in-30-days display.'
+            body.attribute :show_products_without_price, :boolean,
+              description: "Whether products with no price in the shopper's currency still appear in listings."
+            body.attribute :disable_sku_validation, :boolean,
+              description: 'Lets more than one variant share the same SKU.'
+            body.attribute :order_routing_strategy, :string,
+              description: 'The store-wide order routing strategy shorthand. Channels fall back to it.'
+            body.attribute :pricing_provider, :string,
+              description: 'Where prices come from: a registered provider key, or `internal`.'
+            body.attribute :inventory_provider, :string,
+              description: 'Where stock levels come from: a registered provider key, or `internal`.'
+            body.attribute :pricing_provider_failure_policy, :string,
+              choices: Spree::ProviderFailurePolicy::VALUES,
+              description: '`strict` refuses to price when the provider cannot answer; `fallback` uses the catalog.'
+            body.attribute :inventory_provider_failure_policy, :string,
+              choices: Spree::ProviderFailurePolicy::VALUES,
+              description: '`fallback` sells on the local stock snapshot when the provider cannot answer; `strict` refuses.'
+            body.attribute :payout_provider, :string,
+              description: 'Blank means the built-in provider: the marketplace settles by hand.'
+            body.attribute :default_payouts_schedule_interval, :string, choices: Spree::Seller::PAYOUT_INTERVALS
+            body.attribute :default_minimum_payout_amount, :decimal,
+              example: '50.00',
+              description: "In the store's currency."
+            body.attribute :auto_approve_sellers, :boolean,
+              description: 'Admits a seller as soon as they finish onboarding, with no operator review.'
+            body.attribute :auto_approve_seller_products, :boolean,
+              description: 'Puts a seller product on sale the moment it is submitted, with no review.'
+            body.attribute :send_seller_transactional_emails, :boolean,
+              description: 'When false, transactional seller emails (approval, payouts and so on) are not sent.'
+            body.attribute :default_commission_tax_rate, :decimal,
+              example: '0.23',
+              description: 'Tax charged on commission as a fraction (`"0.23"` is 23%), when neither the commission rate nor the tax provider names one.'
+            body.attribute :document_number_format, :string,
+              example: 'sequential',
+              description: 'How document numbers are produced: `sequential` or `random`. Applies to every numbered document.'
+            body.attribute :order_number_prefix, :string,
+              example: 'R',
+              description: 'Leads every order number. Uppercase letters, digits, dashes and # only.'
+            body.attribute :order_number_suffix, :string,
+              description: 'Ends every order number. Uppercase letters, digits, dashes and # only.'
+            body.attribute :order_number_sequence_start, :integer,
+              description: "The first sequential order number. Only applies before the store's first order."
+            body.attribute :limit_digital_download_count, :boolean,
+              description: 'Whether a digital download link stops working after a number of clicks.'
+            body.attribute :digital_asset_authorized_clicks, :integer,
+              description: 'How many clicks a download link allows, unless the file sets its own.'
+            body.attribute :limit_digital_download_days, :boolean,
+              description: 'Whether a digital download link expires after a number of days.'
+            body.attribute :digital_asset_authorized_days, :integer,
+              description: 'How many days a download link stays valid, unless the file sets its own.'
+            body.attribute :mail_from_address, :string, description: 'Sender address of every transactional email.'
+            body.attribute :customer_support_email, :string,
+              nullable: true,
+              description: 'Customer-facing reply-to address shown in the storefront and email footers.'
+            body.attribute :new_order_notifications_email, :string,
+              nullable: true,
+              description: 'Recipient of "new order placed" staff notifications.'
+            body.attribute :send_consumer_transactional_emails, :boolean,
+              description: 'When false, transactional customer emails (order confirmation and so on) are not sent.'
+            body.attribute :email_accent_color, :string,
+              nullable: true,
+              description: 'Customer email buttons and links, as `#RRGGBB`. Blank keeps the outlined buttons emails ship with.'
+            body.attribute :email_background_color, :string,
+              nullable: true,
+              description: 'Customer email page background, as `#RRGGBB`.'
+            body.attribute :email_card_color, :string,
+              nullable: true,
+              description: 'Customer email card behind the content, as `#RRGGBB`.'
+            body.attribute :email_text_color, :string,
+              nullable: true,
+              description: 'Customer email body text, as `#RRGGBB`.'
+            body.attribute :email_heading_color, :string,
+              nullable: true,
+              description: 'Customer email headings and emphasized text, as `#RRGGBB`.'
+            body.attribute :email_font, :string,
+              nullable: true,
+              example: 'inter',
+              description: 'Customer email font: `inter`, `system`, `helvetica`, `georgia`, `roboto`, `lato` or `merriweather`.'
+            body.attribute :logo_signed_id, :string,
+              nullable: true,
+              description: 'A `signed_id` from `files.upload()` for the store logo, or null to remove it.'
+            body.attribute :mailer_logo_signed_id, :string,
+              nullable: true,
+              description: 'A `signed_id` from `files.upload()` for the logo in transactional emails, or null to remove it.'
+          end
+
           # Reading the current store is shell data — the dashboard needs the
           # name, logo, timezone, currency and locales to render anything at
           # all, so every signed-in staff member can read it regardless of
@@ -56,7 +175,6 @@ module Spree
               {
                 key: provider_class.key,
                 name: provider_class.provider_name,
-                integration_class: provider_class.integration_class,
                 integration_type: provider_class.integration_class.presence&.safe_constantize&.api_type,
                 available: provider_class.available_for_store?(current_store)
               }
@@ -71,54 +189,10 @@ module Spree
             Spree.api.admin_store_serializer
           end
 
+          # Extensions' fields too: the store settings page saves the fields
+          # plugins add to it with the rest of the form.
           def permitted_params
-            params.permit(
-              :name,
-              :preferred_admin_locale,
-              :preferred_timezone,
-              :preferred_weight_unit,
-              :preferred_unit_system,
-              :preferred_storefront_access,
-              :preferred_storefront_url,
-              :preferred_guest_checkout,
-              :preferred_always_include_confirm_step,
-              :preferred_company_field_enabled,
-              :preferred_address_requires_company,
-              :preferred_address_requires_phone,
-              :preferred_capture_method,
-              # @deprecated Superseded by preferred_capture_method; the model
-              #   maps them onto it. Removed in 6.1.
-              :preferred_auto_capture,
-              :preferred_auto_capture_on_dispatch,
-              :preferred_track_inventory_levels,
-              :preferred_stock_reservations_enabled,
-              :preferred_low_stock_threshold,
-              :preferred_tax_using_ship_address,
-              :preferred_track_price_history,
-              :preferred_show_products_without_price,
-              :preferred_disable_sku_validation,
-              :preferred_order_routing_strategy,
-              :preferred_pricing_provider,
-              :preferred_inventory_provider,
-              :preferred_pricing_provider_failure_policy,
-              :preferred_inventory_provider_failure_policy,
-              :preferred_payout_provider,
-              :preferred_default_payouts_schedule_interval,
-              :preferred_default_minimum_payout_amount,
-              :preferred_auto_approve_sellers,
-              :preferred_auto_approve_seller_products,
-              :preferred_send_seller_transactional_emails,
-              :preferred_default_commission_tax_rate,
-              :preferred_document_number_format,
-              :preferred_order_number_prefix,
-              :preferred_order_number_suffix,
-              :preferred_order_number_sequence_start,
-              :mail_from_address,
-              :customer_support_email,
-              :new_order_notifications_email,
-              :preferred_send_consumer_transactional_emails,
-              :mailer_logo
-            )
+            params.permit(*declared_permitted_attributes, *Array(Spree::Store.additional_permitted_attributes))
           end
         end
       end

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

@@ -63,9 +63,6 @@ module Spree
                    )
 
             rows.map do |currency, amount, used, authorized|
-              # `SUM` answers an Integer on a whole-number total, and these
-              # totals render beside rows that serialize decimal strings — so
-              # "50" must not appear against their "50.0".
               figures = {
                 amount: amount.to_d,
                 amount_used: used.to_d,
@@ -74,10 +71,7 @@ module Spree
               figures[:amount_remaining] =
                 figures[:amount] - figures[:amount_used] - figures[:amount_authorized]
 
-              displays = figures.transform_keys { |name| :"display_#{name}" }.
-                         transform_values { |value| Spree::Money.new(value, currency: currency).to_s }
-
-              { currency: currency }.merge(figures.transform_values(&:to_s)).merge(displays)
+              { currency: currency }.merge(figures.transform_values { |value| Spree::Money::Rounding.format(value, currency) })
             end
           end
         end

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

@@ -8,6 +8,22 @@ module Spree
         class SuppliersController < ResourceController
           scoped_resource :purchasing
 
+          request_params :supplier do |body|
+            body.attribute :name, :string, required: true, on: :create, example: 'Northwind Trading'
+            body.attribute :contact_name, :string, nullable: true, example: 'Dana Okafor'
+            body.attribute :email, :string, nullable: true, example: 'sales@northwind.test'
+            body.attribute :phone, :string, nullable: true, example: '555-0100'
+            body.attribute :notes, :string, nullable: true
+            body.attribute :address1, :string, nullable: true, example: '1 Warehouse Way'
+            body.attribute :address2, :string, nullable: true
+            body.attribute :city, :string, nullable: true, example: 'Brooklyn'
+            body.attribute :state_name, :string, nullable: true
+            body.attribute :state_code, :string, nullable: true, example: 'NY'
+            body.attribute :country_code, :country, nullable: true, example: 'US'
+            body.attribute :postal_code, :string, nullable: true, example: '11201'
+            body.attribute :metadata, :hash, nullable: true
+          end
+
           protected
 
           def model_class
@@ -17,12 +33,6 @@ module Spree
           def serializer_class
             Spree.api.admin_supplier_serializer
           end
-
-          def resource_permitted_attributes
-            [:name, :contact_name, :email, :phone, :notes,
-             :address1, :address2, :city, :state_name, :state_code,
-             :country_code, :postal_code, { metadata: {} }]
-          end
         end
       end
     end

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

@@ -45,16 +45,19 @@ module Spree
 
           private
 
+          # The class name taggings store for the requested shorthand
+          # (`product` → `Spree::Product`), or nil when it is not taggable.
           def taggable_type
-            params[:taggable_type].to_s
+            @taggable_type ||= Spree::Base.polymorphic_type_for(params[:taggable_type], allowed_taggable_types)
           end
 
           def valid_taggable_type?
-            return true if allowed_taggable_types.include?(taggable_type)
+            return true if taggable_type
 
+            allowed = allowed_taggable_types.map { |type| Spree::Base.polymorphic_api_type(type) }
             render_error(
               code: 'invalid_taggable_type',
-              message: "taggable_type must be one of #{allowed_taggable_types.join(', ')}",
+              message: "taggable_type must be one of #{allowed.join(', ')}",
               status: :unprocessable_content
             )
             false
@@ -83,7 +86,7 @@ module Spree
           # admins are gated by store membership + CanCanCan, not scopes.
           def authorize_taggable_scope!
             return unless current_api_key
-            return unless allowed_taggable_types.include?(taggable_type)
+            return unless taggable_type
 
             required = self.class.scope_for_taggable_type.fetch(taggable_type, 'read_all')
             return if current_api_key.has_scope?(required)
@@ -101,7 +104,7 @@ module Spree
           # list in an initializer without overriding this controller:
           #   Spree.taggable_types << 'MyApp::Seller'
           def allowed_taggable_types
-            Spree.taggable_types
+            Spree.taggable_types.map(&:to_s)
           end
         end
       end

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

@@ -5,6 +5,13 @@ module Spree
         class TaxCategoriesController < ResourceController
           scoped_resource :settings
 
+          request_params :tax_category do |body|
+            body.attribute :name, :string, required: true, on: :create
+            body.attribute :tax_code, :string, nullable: true
+            body.attribute :description, :string, nullable: true
+            body.attribute :is_default, :boolean
+          end
+
           protected
 
           def model_class
@@ -14,10 +21,6 @@ module Spree
           def serializer_class
             Spree.api.admin_tax_category_serializer
           end
-
-          def resource_permitted_attributes
-            [:name, :tax_code, :description, :is_default]
-          end
         end
       end
     end

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

@@ -7,6 +7,26 @@ module Spree
         class TaxRatesController < ResourceController
           scoped_resource :settings
 
+          request_params :tax_rate do |body|
+            body.attribute :name, :string, required: true, on: :create, example: 'VAT', description: 'Customer-facing rate name.'
+            body.attribute :rate, :decimal,
+              example: '0.19',
+              description: 'The rate as a fraction. Send this or `rate_percent`.'
+            body.attribute :rate_percent, :decimal, example: '19', description: 'The rate as a percentage.'
+            body.attribute :included_in_price, :boolean
+            body.attribute :show_rate_in_label, :boolean
+            body.attribute :tax_category_id, :id, required: true, on: :create
+            body.attribute :country_code, :country,
+              nullable: true,
+              example: 'DE',
+              description: 'ISO country code. A rate naming no country taxes everywhere.'
+            body.attribute :state_code, :string,
+              nullable: true,
+              example: 'CA',
+              description: 'State abbreviation within that country.'
+            body.attribute :metadata, :hash
+          end
+
           protected
 
           def model_class
@@ -22,9 +42,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(*model_additional_permitted_attributes, :name, :amount, :amount_percentage, :included_in_price,
-                          :show_rate_in_label, :tax_category_id,
-                          :country_code, :state_code, metadata: {})
+            params.permit(*permitted_attributes)
           end
         end
       end

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

@@ -23,6 +23,10 @@ module Spree
 
           protected
 
+          def filterable?
+            false
+          end
+
           def model_class
             Spree::Fulfillment
           end

data/app/controllers/spree/api/v3/admin/translations/batches_controller.rb

@@ -13,15 +13,6 @@ module Spree
           # resource_type + resource_id, so the controller stays free of
           # per-model branching.
           #
-          # POST /api/v3/admin/translations/batch
-          # Body:
-          #   { "translations": [
-          #       { "resource_type": "option_type",  "resource_id": "opt_…",
-          #         "values": { "de": { "label": "Größe" } } },
-          #       { "resource_type": "option_value", "resource_id": "optval_…",
-          #         "values": { "de": { "label": "Klein" } } }
-          #   ] }
-          #
           # All entries succeed or none do — a validation failure on any entry
           # rolls back the whole transaction and returns per-entry detail.
           # The orchestration (resolve → upsert → rollback) lives in
@@ -34,6 +25,23 @@ module Spree
             # which is stricter than the static check and keeps the audit model.
             skip_scope_check!
 
+            request_params 'TranslationBatchParams' do |body|
+              body.attribute :translations, :array,
+                required: true,
+                as: 'TranslationBatchEntryParams',
+                description: 'At least one entry. All entries are saved, or none are.' do |translation|
+                translation.attribute :resource_type, :string,
+                  required: true,
+                  example: 'option_type',
+                  description: 'Translatable resource type token, e.g. `option_type`.'
+                translation.attribute :resource_id, :id, required: true, example: 'opt_abc123'
+                translation.attribute :values, :hash,
+                  required: true,
+                  example: { de: { label: 'Größe' } },
+                  description: 'Translated fields keyed by locale code, then by field name.'
+              end
+            end
+
             # POST /api/v3/admin/translations/batch
             def create
               raw = params[:translations]

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

@@ -29,6 +29,10 @@ module Spree
 
           protected
 
+          def filterable?
+            false
+          end
+
           def set_parent
             raise ActiveRecord::RecordNotFound, 'Parent resource not found' unless parent_lookup
 

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

@@ -31,6 +31,11 @@ module Spree
 
           protected
 
+          # The model, and so the filters, follow `resource_type`.
+          def filterable?
+            false
+          end
+
           # Resolved from the required `resource_type` param. An unknown or
           # untranslatable type is a 404 rather than a 500 from a nil class.
           def model_class

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

@@ -0,0 +1,39 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Whether a newer Spree release exists, for the dashboard's update
+        # notice. Asks spreecloud.io at most once a day (see Spree::UpdateCheck).
+        #
+        # The only place the Admin API reveals the running Spree version, so it
+        # answers signed-in staff who can manage the store and nobody else. A
+        # secret API key gets a 404, like GET /me: an integration key would
+        # otherwise fingerprint the deployment for anyone matching CVEs.
+        class UpdatesController < Admin::BaseController
+          skip_scope_check!
+
+          before_action :require_current_user!
+
+          # GET /api/v3/admin/updates
+          def show
+            authorize! :manage, current_store
+
+            render json: Spree.api.admin_update_status_serializer.new(Spree::UpdateCheck.status).to_h
+          end
+
+          private
+
+          def require_current_user!
+            return if current_user
+
+            render_error(
+              code: ERROR_CODES[:record_not_found],
+              message: I18n.t('spree.me_no_current_user'),
+              status: :not_found
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -8,6 +8,28 @@ module Spree
         class WebhookEndpointsController < ResourceController
           scoped_resource :webhooks
 
+          request_params :webhook_endpoint do |body|
+            body.attribute :name, :string,
+              nullable: true,
+              example: 'Order pipeline',
+              description: 'A label shown in the dashboard list.'
+            body.attribute :url, :string,
+              required: true, on: :create,
+              example: 'https://example.com/webhooks/orders',
+              description: 'HTTPS destination URL. It cannot resolve to a private IP address outside development.'
+            body.attribute :active, :boolean,
+              description: 'Defaults to true on create. Prefer the disable and enable endpoints to pause one.'
+            body.attribute :subscriptions, :array, of: :string,
+              example: %w[order.placed order.canceled],
+              description: 'Event names this endpoint receives. An empty list or `["*"]` subscribes to every event; otherwise list exact names (`order.completed`) or patterns (`order.*`).'
+          end
+
+          request_params 'WebhookEndpointDisableParams', action: :disable do |body|
+            body.attribute :reason, :string,
+              example: 'Investigating elevated 5xx rate',
+              description: 'Shown next to the disabled indicator. Defaults to "Manually disabled".'
+          end
+
           before_action :reject_unauthorized_credential_subscription!, only: [:create, :update]
 
           # POST /api/v3/admin/webhook_endpoints/:id/send_test
@@ -68,32 +90,37 @@ module Spree
           end
 
           def permitted_params
-            params.permit(*model_additional_permitted_attributes, :name, :url, :active, subscriptions: [])
+            params.permit(*permitted_attributes)
           end
 
           private
 
-          # Customer password reset tokens are account credentials, so the
-          # webhooks permission alone cannot subscribe an endpoint to them, or
-          # repoint an endpoint that already receives them.
+          # A customer's password reset token is an account credential, so the
+          # webhooks permission alone cannot subscribe an endpoint to it, or
+          # repoint an endpoint that already receives it: that needs the
+          # permission the event catalog names for it (`write_customers`).
           def reject_unauthorized_credential_subscription!
-            return if holds_permission?('write_customers')
-
-            requested = Array(permitted_params[:subscriptions]) & Spree::WebhookEndpoint::CREDENTIAL_EVENTS
-            return if requested.empty? && !repoints_credential_endpoint?
+            events = requested_credential_events | repointed_credential_events
+            missing = events.reject { |entry| holds_permission?(entry.credential_permission) }
+            return if missing.empty?
 
             render_error(
               code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:access_denied],
-              message: "Receiving #{Spree::WebhookEndpoint::CREDENTIAL_EVENTS.to_sentence} requires permission to manage customers",
+              message: "Receiving #{missing.map(&:name).to_sentence} requires the " \
+                       "#{missing.map(&:credential_permission).uniq.to_sentence} permission",
               status: :forbidden
             )
           end
 
-          def repoints_credential_endpoint?
-            return false unless action_name == 'update'
-            return false unless permitted_params.key?(:url) || permitted_params.key?(:subscriptions)
+          def requested_credential_events
+            Spree::Events.catalog.credential_events(Array(permitted_params[:subscriptions]))
+          end
+
+          def repointed_credential_events
+            return [] unless action_name == 'update'
+            return [] unless permitted_params.key?(:url) || permitted_params.key?(:subscriptions)
 
-            current_store.webhook_endpoints.find_by_prefix_id(params[:id])&.receives_credentials?
+            current_store.webhook_endpoints.find_by_prefix_id(params[:id])&.credential_subscriptions || []
           end
         end
       end

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

@@ -0,0 +1,25 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # The events a webhook endpoint can subscribe to — every event Spree
+        # and the installed extensions declare, so the endpoint picker never
+        # drifts from what the server really publishes.
+        class WebhookEventsController < Admin::BaseController
+          scoped_resource :webhooks
+
+          # GET /api/v3/admin/webhook_events
+          def index
+            authorize!(:show, Spree::WebhookEndpoint)
+            entries = Spree::Events.catalog.webhook_events
+
+            render json: {
+              data: entries.map { |entry| Spree.api.admin_webhook_event_serializer.new(entry).to_h },
+              meta: { count: entries.size }
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/base_controller.rb

@@ -12,6 +12,8 @@ module Spree
         include Spree::Api::V3::JwtAuthentication
         include Spree::Api::V3::ApiKeyAuthentication
         include Spree::Api::V3::ErrorHandler
+        include Spree::Api::V3::MoneyParams
+        include Spree::Api::V3::RequestParams
         include Spree::Api::V3::SecurityHeaders
         include Spree::Api::V3::ResourceSerializer
         include Spree::Api::V3::RateLimitHeaders
@@ -70,6 +72,16 @@ module Spree
           request.headers['x-spree-token']
         end
 
+        # Renders a workflow's result: the serialized record on success, its
+        # errors otherwise.
+        def render_result(result, status: :ok)
+          if result.success?
+            render json: serialize_resource(result.value), status: status
+          else
+            render_result_error(result)
+          end
+        end
+
         # Renders a failed service/workflow Result: validation errors become a
         # 422 field-error payload, anything else a plain service error. Shared
         # by both APIs — Store endpoints surface workflow failures (a rejected