spree_core 6.0.0.beta4 → 6.0.0.rc1

data/app/models/concerns/spree/api_typed.rb

@@ -0,0 +1,91 @@
+module Spree
+  # Wire shorthand for the plain-Ruby strategy classes a merchant picks from a
+  # registry (fulfillment, delivery-rate, pickup-point, payout and digital
+  # asset providers, order routing strategies). Records keep storing the class
+  # name; the API reads and writes this shorthand, so the contract never
+  # carries a Ruby constant.
+  #
+  #   class Spree::FulfillmentProvider::Base
+  #     extend Spree::ApiTyped
+  #   end
+  #
+  #   Spree::FulfillmentProvider::Manual.api_type  # => "manual"
+  #   SpreeEasyPost::FulfillmentProvider.api_type  # => "easy_post"
+  module ApiTyped
+    # The demodulized + underscored leaf. A gem names its class after the
+    # family (`SpreeEasyPost::FulfillmentProvider`, `SpreeAcmeOms::Strategy`),
+    # where the leaf would collapse every gem to one value — those derive it
+    # from the gem's module instead, matching {Spree::Integration.api_type}.
+    # Any other class keeps its leaf, so two providers nested in one module
+    # never share a value. Override to keep the value stable across a rename.
+    #
+    # @return [String]
+    def api_type
+      leaf = name.to_s.demodulize
+      outer = name.to_s.deconstantize.demodulize.delete_prefix('Spree')
+      return leaf.underscore unless leaf == api_typed_family && outer.present?
+
+      outer.underscore
+    end
+
+    # The family's own name — the module its base class sits in
+    # (`FulfillmentProvider` for `Spree::FulfillmentProvider::Base`).
+    #
+    # @return [String, nil]
+    def api_typed_family
+      base = ancestors.reverse.find { |ancestor| ancestor.is_a?(Class) && ancestor.singleton_class.include?(Spree::ApiTyped) }
+      base&.name.to_s.deconstantize.demodulize.presence
+    end
+
+    # The registered class answering to a wire shorthand, or nil.
+    #
+    # @param registry [Array<Class, String>]
+    # @param api_type [String, nil]
+    # @return [Class, nil]
+    def self.find(registry, api_type)
+      return nil if api_type.blank?
+
+      Array(registry).map { |entry| entry.is_a?(Class) ? entry : entry.to_s.safe_constantize }.
+        compact.find { |klass| klass.api_type == api_type.to_s }
+    end
+
+    # The registered class a record's stored class name points at, or nil
+    # when it is no longer registered (a typo, an uninstalled gem) — so a
+    # stored string is never constantized outside the registry.
+    #
+    # @param registry [Array<Class>]
+    # @param class_name [String, nil]
+    # @return [Class, nil]
+    def self.registered_class(registry, class_name)
+      return nil if class_name.blank?
+
+      Array(registry).find { |klass| klass.to_s == class_name.to_s }
+    end
+
+    # The class name a record stores for a value arriving from the API. A
+    # registered shorthand becomes its class name; anything else passes through
+    # unchanged so the record's own inclusion validation rejects it.
+    #
+    # @param registry [Array<Class, String>]
+    # @param value [String, nil]
+    # @return [String, nil]
+    def self.class_name_for(registry, value)
+      return value if value.blank?
+
+      find(registry, value)&.to_s || value
+    end
+
+    # The shorthand for a stored class name. A class that is no longer
+    # registered (an uninstalled gem) is shortened the same way rather than
+    # constantized.
+    #
+    # @param class_name [String, nil]
+    # @return [String, nil]
+    def self.api_type_for(class_name)
+      return nil if class_name.blank?
+
+      klass = class_name.to_s.safe_constantize
+      klass.respond_to?(:api_type) ? klass.api_type : class_name.to_s.demodulize.underscore
+    end
+  end
+end

data/app/models/concerns/spree/calculator/tiers.rb

@@ -0,0 +1,76 @@
+module Spree
+  class Calculator < Spree.base_class
+    # A tier ladder for the tiered calculators: a list of
+    # `{ "threshold" => "100.0", "value" => "10.0" }` objects, where the value
+    # is a percentage or an amount depending on the calculator. A list rather
+    # than a hash keyed by threshold, because JSON object keys are always
+    # strings and a number key would not survive storage.
+    module Tiers
+      extend ActiveSupport::Concern
+
+      included do
+        preference :tiers, :array, default: [], parse_on_set: ->(value) { Tiers.normalize(value) }
+
+        validate :preferred_tiers_content
+      end
+
+      # @param value [Object] tiers as an operator or API client sent them
+      # @return [Object] an array of string-keyed hashes with numbers as exact
+      #   decimal strings — the form JSON stores, so a fresh value compares
+      #   equal to one read back — or the value unchanged when it is not a list
+      #   of hashes, so validation can name the problem
+      def self.normalize(value)
+        return value unless value.is_a?(Array) && value.all? { |tier| tier.respond_to?(:to_h) && !tier.is_a?(Array) }
+
+        value.map do |tier|
+          tier.to_h.stringify_keys.to_h { |key, number| [key, decimal(number)&.as_json || number] }
+        end
+      end
+
+      # @return [BigDecimal, nil] nil when the value is not a number
+      def self.decimal(value)
+        BigDecimal(value.to_s, exception: false)
+      end
+
+      # The value of the highest tier whose threshold the amount reaches.
+      #
+      # @param amount [Numeric]
+      # @return [BigDecimal, nil] nil when the amount reaches no tier
+      def tier_value_for(amount)
+        tier_pairs.reverse_each.detect { |threshold, _| amount >= threshold }&.last
+      end
+
+      private
+
+      # Tiers that are not numbers are skipped: validation refuses them on
+      # save, but an unsaved calculator can still be asked to compute. Tiers
+      # still in the pre-6.0 hash keyed by threshold, left by an upgrade that
+      # could not convert them, keep discounting until they are converted.
+      #
+      # @return [Array<Array(BigDecimal, BigDecimal)>] threshold and value, lowest threshold first
+      def tier_pairs
+        tiers = preferred_tiers
+        pairs = case tiers
+                when Hash then tiers.to_a
+                when Array then tiers.grep(Hash).map { |tier| tier.values_at('threshold', 'value') }
+                else []
+                end
+        pairs.map { |threshold, value| [Tiers.decimal(threshold), Tiers.decimal(value)] }.select(&:all?).sort_by(&:first)
+      end
+
+      def preferred_tiers_content
+        tiers = preferred_tiers
+        unless tiers.is_a?(Array) && tiers.all? { |tier| tier.is_a?(Hash) }
+          return errors.add(:preferred_tiers, :should_be_list)
+        end
+
+        thresholds = tiers.map { |tier| Tiers.decimal(tier['threshold']) }
+        values = tiers.map { |tier| Tiers.decimal(tier['value']) }
+
+        errors.add(:preferred_tiers, :thresholds_should_be_positive_number) unless thresholds.all? { |threshold| threshold&.positive? }
+        errors.add(:preferred_tiers, :thresholds_should_be_unique) unless thresholds.uniq.size == thresholds.size
+        validate_tier_values(values)
+      end
+    end
+  end
+end

data/app/models/concerns/spree/customer_methods.rb

@@ -20,8 +20,10 @@ module Spree
       # 2026-03-16 "Consolidate metadata") — no public/private split.
       attribute :metadata, default: -> { {} }
 
-      # Enable lifecycle events for user models
       publishes_lifecycle_events
+      publishes_events 'customer.password_reset', 'customer.anonymized'
+      publishes_event 'customer.password_reset_requested',
+                      serializer: 'Spree::Api::V3::PasswordResetRequestedEventSerializer', credential: 'write_customers'
 
       # Password reset token (Rails 7.1+ signed token, no DB column needed)
       # Token auto-invalidates when password changes (salt changes)
@@ -184,13 +186,10 @@ module Spree
         where(conditions.reduce(:or))
       end
 
-      # Backward compatibility alias — remove in Spree 6.0
-      def self.multi_search(query) = search(query)
-
       self.whitelisted_ransackable_associations = %w[bill_address ship_address addresses tags spree_roles orders customer_groups]
       self.whitelisted_ransackable_attributes = %w[id email first_name last_name phone accepts_email_marketing
                                                     created_at updated_at last_sign_in_at]
-      self.whitelisted_ransackable_scopes = %w[search multi_search with_min_total_spent with_standing_for_company
+      self.whitelisted_ransackable_scopes = %w[search with_min_total_spent with_standing_for_company
                                                anonymized]
 
       # Two-state scope: see Spree::Base.ransack_flag? for why the cast is
@@ -278,6 +277,16 @@ module Spree
       end
     end
 
+    class_methods do
+      # Customer lifecycle events are `user.*`; an installation whose staff
+      # class shares these methods publishes theirs as `admin.*`.
+      #
+      # @return [String]
+      def event_prefix
+        self == Spree.admin_user_class && Spree.admin_user_class != Spree.customer_class ? 'admin' : 'user'
+      end
+    end
+
     # Returns the last incomplete spree order for the current store
     # @deprecated Carts are {Spree::Cart} since 6.0, so an incomplete order is
     #   a backoffice draft rather than the customer's cart. Use
@@ -337,7 +346,7 @@ module Spree
     # @return [Spree::Wishlist]
     def default_wishlist_for_store(current_store)
       wishlists.find_by(is_default: true, store_id: current_store.id) || ActiveRecord::Base.connected_to(role: :writing) do
-        wishlists.create!(store: current_store, is_default: true, name: Spree.t(:default_wishlist_name))
+        wishlists.create!(store: current_store, is_default: true, name: I18n.t('spree.default_wishlist_name'))
       end
     end
 
@@ -368,14 +377,6 @@ module Spree
       'Spree::Api::V3::CustomerSerializer'.safe_constantize
     end
 
-    def event_prefix
-      if self.class == Spree.admin_user_class && Spree.admin_user_class != Spree.customer_class
-        'admin'
-      else
-        'user'
-      end
-    end
-
     # @param store [Spree::Store] store to scope the lookup to; defaults to the current store
     # @return [Spree::NewsletterSubscriber, nil] this user's newsletter subscriber for the given store
     def newsletter_subscriber(store = Spree::Current.store)

data/app/models/concerns/spree/email_template_identity.rb

@@ -0,0 +1,52 @@
+module Spree
+  # What a store's published email template and its draft share: which
+  # editable template they are, in which language, and the default they
+  # started from.
+  module EmailTemplateIdentity
+    extend ActiveSupport::Concern
+
+    # The version every language uses. Never NULL, so the unique index on
+    # store, key and locale holds for it too.
+    ANY_LOCALE = 'any'.freeze
+    LOCALE_FORMAT = /\A(any|[a-z]{2,3}(-[A-Za-z0-9]{2,8})*)\z/
+
+    included do
+      include Spree::SingleStoreResource
+
+      normalizes :locale, with: ->(locale) { locale.to_s.strip.presence || ANY_LOCALE }, apply_to_nil: true
+
+      validates :key, presence: true, uniqueness: { scope: spree_base_uniqueness_scope + [:store_id, :locale] }
+      validates :locale, format: { with: LOCALE_FORMAT }
+      validates :body, :base_body, presence: true
+      validate :key_editable
+      validate :locale_supported
+
+      scope :for_key, ->(key, locale = ANY_LOCALE) { where(key: key, locale: locale) }
+    end
+
+    # @return [Spree::Emails::EditableTemplates::Definition, nil]
+    def definition
+      Spree.editable_email_templates[key]
+    end
+
+    # @return [Boolean] whether Spree's default changed since this version started from it
+    # @param default [Spree::Emails::Template, nil] the current default
+    def default_changed?(default)
+      return false unless default
+
+      default.body != base_body || default.subject.to_s != base_subject.to_s
+    end
+
+    private
+
+    def key_editable
+      errors.add(:key, :invalid) if key.present? && definition.nil?
+    end
+
+    def locale_supported
+      return if locale == ANY_LOCALE || store.nil?
+
+      errors.add(:locale, :inclusion) unless store.supported_locales_list.include?(locale)
+    end
+  end
+end

data/app/models/concerns/spree/parameterizable_name.rb

@@ -20,6 +20,8 @@ module Spree
         end
       end
 
+      scope :with_name, ->(value) { where(name: value.to_s.parameterize) }
+
       def set_name_from_label
         self.name = label
       end

data/app/models/concerns/spree/payment_session_transitions.rb

@@ -24,10 +24,16 @@ module Spree
       pending?
     end
 
-    %w[complete fail cancel expire].each do |transition|
+    %w[complete fail expire].each do |transition|
       define_method(:"can_#{transition}?") { pending? || processing? }
     end
 
+    # A failed confirm can leave the provider intent payable. Cancel is how
+    # placement retires it; the other transitions stay closed.
+    def can_cancel?
+      pending? || processing? || failed?
+    end
+
     def process
       return false unless transition_to('processing', from: %w[pending])
 
@@ -50,7 +56,7 @@ module Spree
     end
 
     def cancel
-      return false unless transition_to('canceled', from: %w[pending processing])
+      return false unless transition_to('canceled', from: %w[pending processing failed])
 
       publish_canceled_event
       true

data/app/models/concerns/spree/post_sale/taxation.rb

@@ -0,0 +1,54 @@
+module Spree
+  module PostSale
+    # Asks the order's tax provider what tax a return, claim or exchange gives
+    # back. Including models name their lines through +taxed_lines+.
+    #
+    # The provider is asked twice: when the record opens, for what was
+    # announced, and again before money moves, for what actually goes back.
+    # Only the first is copied onto the lines' columns — they keep what was
+    # announced, the way a return line's +pre_tax_amount+ does — while the rows
+    # always say what the customer is, or was, refunded.
+    module Taxation
+      extend ActiveSupport::Concern
+
+      # @return [void]
+      # @raise [Spree::Tax::ProviderError]
+      def calculate_tax!
+        lines = taxed_lines.to_a
+        estimate_tax(lines)
+        lines.each(&:fold_tax_lines!)
+      end
+
+      # @param amounts [Hash{Object => BigDecimal}, nil] the money refunded per
+      #   line when it is less than the line is worth
+      # @return [void]
+      # @raise [Spree::Tax::ProviderError]
+      def settle_tax!(amounts: nil)
+        lines = taxed_lines.select(&:settles_tax?)
+        estimate_tax(lines, amounts: amounts) if lines.any?
+      end
+
+      # Drops every row on the record's lines, for a record withdrawn before
+      # anything went back. Nothing is worked out, so the provider is not asked
+      # — a cancellation must not wait on, or fail with, a tax service.
+      #
+      # @return [void]
+      def clear_tax!
+        Spree::TaxLine.post_sale.where(Spree::TaxLine.adjustable_key_for(taxed_lines.klass) => taxed_lines.select(:id)).delete_all
+      end
+
+      # The tax the record's lines give back, as their credit rows stand.
+      #
+      # @return [BigDecimal]
+      def credited_tax_total
+        taxed_lines.sum(0.to_d, &:credited_tax_total)
+      end
+
+      private
+
+      def estimate_tax(lines, amounts: nil)
+        order.tax_provider.estimate_refund(order, lines, amounts: amounts, tax_date: order.completed_at)
+      end
+    end
+  end
+end

data/app/models/concerns/spree/post_sale/taxed_line.rb

@@ -0,0 +1,51 @@
+module Spree
+  module PostSale
+    # The tax side of a line on a return, claim or exchange: the rows the tax
+    # provider writes on it (see Spree::TaxProvider::Base#estimate_refund).
+    #
+    # Including models answer +credited_quantity+ and +credited_worth+, which
+    # the provider reads, and +fold_tax_lines!+, which copies the rows written
+    # at opening onto the line's own columns.
+    module TaxedLine
+      extend ActiveSupport::Concern
+
+      included do
+        has_many :tax_lines, class_name: 'Spree::TaxLine', dependent: :destroy
+      end
+
+      # Whether this line's tax goes through the provider when it is refunded.
+      # A line opened before refunds carried tax recorded none against a taxed
+      # sale line, and is refunded exactly as it was opened.
+      #
+      # Read from the columns, which are written once at opening, rather than
+      # the rows: settling rewrites or deletes the rows, and a settle whose
+      # money step then failed would otherwise leave the line looking like one
+      # that never carried tax.
+      #
+      # @return [Boolean]
+      def settles_tax?
+        recorded_tax_total.positive? || line_item.nil? || !line_item.tax_lines.exists?
+      end
+
+      # The tax this line gives back, as its credit rows stand now.
+      #
+      # @return [BigDecimal]
+      def credited_tax_total
+        tax_lines.credits.sum(:amount)
+      end
+
+      private
+
+      # The tax copied onto the line's columns when it opened.
+      def recorded_tax_total
+        tax_total
+      end
+
+      # @return [Array(BigDecimal, BigDecimal)] included and additional tax
+      def tax_totals_from(rows)
+        included, additional = rows.partition(&:included?)
+        [included.sum(0.to_d, &:amount), additional.sum(0.to_d, &:amount)]
+      end
+    end
+  end
+end

data/app/models/concerns/spree/preference_schema.rb

@@ -93,17 +93,6 @@ module Spree
                                       .freeze
       end
 
-      # Declared order first, so a form reads the way its author grouped the
-      # fields; anything the macro did not record (an association writer that
-      # looks like a preference) keeps its existing place at the end.
-      def ordered_preferences(instance)
-        defined = instance.defined_preferences
-        return defined unless respond_to?(:declared_preference_order)
-
-        declared = declared_preference_order & defined
-        declared + (defined - declared)
-      end
-
       def compute_preference_schema
         # Only instantiation is guarded. `new` touches the database to read
         # the column list, so it fails whenever the schema is asked for before
@@ -121,7 +110,7 @@ module Spree
           return nil
         end
 
-        ordered_preferences(instance).filter_map do |pref|
+        instance.defined_preferences.filter_map do |pref|
           next if instance.preference_deprecated(pref)
           # Written by Spree, not supplied by the operator — a value a
           # provider hands back after we register something with it. Offering
@@ -216,6 +205,9 @@ module Spree
           # their wire shape byte-identical. Pickers stop offering a
           # superseded kind; existing rows still render and match.
           entry[:superseded] = true if klass.respond_to?(:superseded?) && klass.superseded?
+          # Provider families (payment methods) add their gallery logo and
+          # setup guide; other families keep their wire shape unchanged.
+          entry.merge!(klass.provider_listing) if klass.respond_to?(:provider_listing)
           entry
         end.sort_by { |entry| entry[:label] }
       end

data/app/models/concerns/spree/product_scopes.rb

@@ -156,7 +156,8 @@ module Spree
           where(Spree::ProductCategory.table_name => { category_id: taxon_ids }).
           select("#{Product.table_name}.*", "#{min_position_sql} AS min_taxon_position").
           group("#{Product.table_name}.id").
-          order(Arel.sql("#{min_position_sql} ASC"))
+          # Ties fall back to id, so the order holds across queries and pages.
+          order(Arel.sql("#{min_position_sql} ASC"), arel_table[:id].asc)
       }
 
       scope :with_option_value, ->(option, value) {
@@ -218,6 +219,15 @@ module Spree
         channel = Spree::Current.channel
         return where(discontinue_on: [nil, Time.current.beginning_of_minute..]) unless channel
 
+        not_discontinued_on(channel)
+      end
+
+      # Published on the channel and not yet unpublished from it — a channel
+      # publication's end date is the product's discontinuation there.
+      #
+      # @param channel [Spree::Channel]
+      # @return [ActiveRecord::Relation<Spree::Product>]
+      def self.not_discontinued_on(channel)
         for_channel(channel).where(Spree::ProductPublication.table_name => { unpublished_at: [nil, Time.current.beginning_of_minute..] })
       end
 

data/app/models/concerns/spree/provider_listing.rb

@@ -0,0 +1,41 @@
+module Spree
+  # What a provider shows on its gallery card in the dashboard: a logo and a
+  # link to its setup guide. Shared by integrations and payment methods so a
+  # provider gem declares both the same way whichever family it extends.
+  #
+  #   class SpreeStripe::Gateway < Spree::Gateway
+  #     def self.logo_url = 'https://example.com/stripe.png'
+  #     def self.docs_url = 'https://spreecommerce.org/docs/integrations/payments/stripe'
+  #   end
+  module ProviderListing
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # Logo shown on the gallery card: an absolute URL to publicly hosted
+      # brand assets, or a `data:` URI for gems that want to be self-contained
+      # (works air-gapped, no CSP domain to allowlist). Anything an `<img src>`
+      # accepts. Deliberately not an asset-pipeline path — provider gems must
+      # not force an asset pipeline onto headless API hosts. Hosted logos are a
+      # courtesy, not a guarantee: the dashboard falls back to a letter avatar
+      # when unset or unreachable.
+      #
+      # @return [String, nil]
+      def logo_url
+        nil
+      end
+
+      # Absolute URL of the provider's setup guide, linked from its gallery
+      # card. A third-party gem points at its own documentation.
+      #
+      # @return [String, nil]
+      def docs_url
+        nil
+      end
+
+      # @return [Hash] the listing attributes merged into a type-discovery entry
+      def provider_listing
+        { logo_url: logo_url, docs_url: docs_url }
+      end
+    end
+  end
+end

data/app/models/concerns/spree/publishable.rb

@@ -36,9 +36,12 @@ module Spree
   module Publishable
     extend ActiveSupport::Concern
 
+    LIFECYCLE_ACTIONS = { create: :created, update: :updated, delete: :deleted }.freeze
+
     included do
       class_attribute :publish_events, default: true
       class_attribute :lifecycle_events_enabled, default: false
+      class_attribute :lifecycle_event_actions, default: []
 
       after_update :mark_real_update_for_events
     end
@@ -76,6 +79,9 @@ module Spree
         events &= Array(options[:only]) if options[:only]
         events -= Array(options[:except]) if options[:except]
 
+        self.lifecycle_event_actions = events.map { |event| LIFECYCLE_ACTIONS.fetch(event) }
+        lifecycle_event_actions.each { |action| publishes_event(action) }
+
         if events.include?(:create)
           after_commit :publish_create_event, on: :create, if: :should_publish_events?
         end
@@ -90,6 +96,51 @@ module Spree
         end
       end
 
+      # A subclass publishes its lifecycle events under its own prefix, which may
+      # differ from its parent's, so they are declared again for it.
+      def inherited(subclass)
+        super
+        subclass.lifecycle_event_actions.each { |action| subclass.publishes_event(action) }
+      end
+
+      # Declare events this model publishes, each carrying this model's Store
+      # serializer as its payload.
+      #
+      # @param names [Array<Symbol, String>] actions (`:placed`, prefixed with
+      #   {event_prefix}) or full dotted names (`'customer.password_reset'`)
+      # @param options [Hash] see {publishes_event}
+      # @return [void]
+      #
+      # @example
+      #   publishes_events :placed, :paid, :shipped
+      def publishes_events(*names, **options)
+        names.each { |name| publishes_event(name, **options) }
+      end
+
+      # Declare one event this model publishes. Publishing a name no model
+      # declared raises in development and test.
+      #
+      # @param name [Symbol, String] an action or a full dotted name
+      # @param serializer [String, nil] payload serializer class name, when the
+      #   payload is not this model's Store serializer
+      # @param credential [String, nil] for a payload carrying a live credential,
+      #   the permission key needed to point a webhook endpoint at it; such an
+      #   event reaches only endpoints that name it outright
+      # @param deprecated_alias_of [String, nil] the event this one duplicates
+      # @param webhook [Boolean] false for an event no webhook endpoint may
+      #   receive, even one subscribed to `*`
+      # @return [void]
+      #
+      # @example
+      #   publishes_event :canceled, serializer: 'Spree::Api::V3::OrderCanceledEventSerializer'
+      #   publishes_event 'customer.password_reset_requested', serializer: '...', credential: 'write_customers'
+      def publishes_event(name, serializer: nil, credential: nil, deprecated_alias_of: nil, webhook: true)
+        Spree::Events.catalog.declare(
+          self, name,
+          serializer: serializer, credential: credential, deprecated_alias_of: deprecated_alias_of, webhook: webhook
+        )
+      end
+
       # Disable lifecycle events for this model
       #
       # @example
@@ -145,10 +196,13 @@ module Spree
     #   order.publish_event('order.placed', metadata: { user_id: 1 })
     #
     def publish_event(event_name, payload = nil, metadata = {})
+      # Checked even while events are disabled, so every spec that reaches a
+      # publish also proves the event is declared.
+      Spree::Events.catalog.verify_declared!(event_name)
       return unless Spree::Events.enabled?
 
       @_current_event_name = event_name
-      payload ||= event_payload
+      payload ||= event_payload_for(event_name)
       Spree::Events.publish(event_name, payload, metadata)
     ensure
       @_current_event_name = nil
@@ -161,20 +215,19 @@ module Spree
     #
     # @return [Hash]
     def event_payload
-      serializer = event_serializer_class
-
-      unless serializer
-        return {
-          id: respond_to?(:prefixed_id) ? prefixed_id : id,
-          created_at: created_at&.iso8601,
-          updated_at: updated_at&.iso8601
-        }
-      end
+      build_event_payload(event_serializer_class)
+    end
 
-      # Use as_json to ensure all values are JSON-safe primitives.
-      # Alba's to_h can return raw Ruby objects (e.g., Spree::Money) which
-      # ActiveJob cannot serialize for async event subscribers.
-      serializer.new(self, params: event_serializer_params).to_h.as_json
+    # The payload for one event, built with the serializer the catalog declares
+    # for it, falling back to this model's Store serializer.
+    #
+    # @param event_name [String]
+    # @param params [Hash] extra serializer params the event serializer reads,
+    #   e.g. the reset token of a password reset request
+    # @return [Hash]
+    def event_payload_for(event_name, **params)
+      serializer = Spree::Events.catalog.find(event_name)&.serializer_name&.safe_constantize
+      build_event_payload(serializer || event_serializer_class, params)
     end
 
     # Find the event serializer class for this model
@@ -223,6 +276,21 @@ module Spree
 
     private
 
+    def build_event_payload(serializer, params = {})
+      unless serializer
+        return {
+          id: respond_to?(:prefixed_id) ? prefixed_id : id,
+          created_at: created_at&.iso8601,
+          updated_at: updated_at&.iso8601
+        }
+      end
+
+      # Use as_json to ensure all values are JSON-safe primitives.
+      # Alba's to_h can return raw Ruby objects (e.g., Spree::Money) which
+      # ActiveJob cannot serialize for async event subscribers.
+      serializer.new(self, params: event_serializer_params.merge(params)).to_h.as_json
+    end
+
     # Build params for V3 serializers
     #
     # @return [Hash]