spree_core 5.4.3 → 5.5.0.rc1

data/app/models/spree/base.rb

@@ -1,10 +1,12 @@
 class Spree::Base < ApplicationRecord
   include Spree::Preferences::Preferable
+  include Spree::PreferenceSchema
   include Spree::RansackableAttributes
   include Spree::TranslatableResourceScopes
   include Spree::IntegrationsConcern
   include Spree::Publishable
   include Spree::PrefixedId
+  include Spree::TypedAssociations
 
   after_initialize do
     if has_attribute?(:preferences) && !preferences.nil?
@@ -57,6 +59,10 @@ class Spree::Base < ApplicationRecord
     true
   end
 
+  def mysql_adapter?
+    ActiveRecord::Base.connection.adapter_name.downcase.include?('mysql')
+  end
+
   def self.json_api_columns
     column_names.reject { |c| c.match(/_id$|id|preferences|(.*)password|(.*)token|(.*)api_key|^original_(.*)/) }
   end
@@ -71,10 +77,21 @@ class Spree::Base < ApplicationRecord
     column_names.reject { |c| skipped_attributes.include?(c.to_s) }
   end
 
-  def self.json_api_type
+  # Public-API shorthand for this class, used as the `type` value on the
+  # wire (e.g. `"currency"` for `Spree::Promotion::Rules::Currency`,
+  # `"flat_rate"` for `Spree::Calculator::FlatRate`). Defaults to the
+  # demodulized + underscored leaf; override on a subclass when the wire
+  # format should stay stable across class renames.
+  def self.api_type
     to_s.demodulize.underscore
   end
 
+  # Backwards-compatible alias for `.api_type`. Delegates so subclass
+  # overrides of `api_type` are honored.
+  def self.json_api_type
+    api_type
+  end
+
   def self.to_tom_select_json
     pluck(:name, :id).map do |name, id|
       {

data/app/models/spree/channel.rb

@@ -0,0 +1,159 @@
+module Spree
+  # Lightweight distribution surface within a Store: online storefront, POS,
+  # marketplace integration, wholesale portal. Channels carry order
+  # attribution and the routing-strategy override.
+  class Channel < Spree.base_class
+    DEFAULT_CODE = 'online'.freeze
+
+    has_prefix_id :ch
+
+    include Spree::SingleStoreResource
+    include Spree::Metafields
+    include Spree::Metadata
+    include Spree::OrderRouting::HasStrategyPreference
+
+    # Empty -> falls back to the Store-level preference.
+    preference :order_routing_strategy, :string, default: nil
+
+    belongs_to :store, class_name: 'Spree::Store'
+
+    has_many :orders, class_name: 'Spree::Order', inverse_of: :channel, dependent: :nullify
+    has_many :order_routing_rules, class_name: 'Spree::OrderRoutingRule', dependent: :destroy
+    has_many :publications, class_name: 'Spree::ProductPublication', dependent: :destroy
+    has_many :products, through: :publications, class_name: 'Spree::Product'
+
+    attribute :active, :boolean, default: true
+
+    # HTTP headers arrive as ASCII-8BIT; +parameterize+ raises on those.
+    normalizes :code, with: ->(value) { value.to_s.dup.force_encoding(Encoding::UTF_8).parameterize.presence }
+
+    before_validation :backfill_code_from_name, if: -> { code.blank? && name.present? }
+    before_validation :promote_first_channel_to_default
+
+    validates :name, :store, presence: true
+    validates :code, presence: true, uniqueness: { scope: spree_base_uniqueness_scope + [:store_id] }
+
+    # Demote any prior default in the same transaction so the partial unique
+    # index ("only one default per store") never sees two TRUE rows. Runs
+    # before save so MySQL — which can't enforce a partial unique index — also
+    # arrives at a single default without relying on DB constraints.
+    before_save :demote_other_defaults, if: -> { default? && will_save_change_to_default? }
+    before_destroy :ensure_not_default
+    after_create :ensure_default_order_routing_rules
+
+    scope :active, -> { where(active: true) }
+    scope :default, -> { where(default: true) }
+
+    self.whitelisted_ransackable_attributes = %w[name code active default store_id]
+
+    # Publishes the given products on this channel by creating/upserting ProductPublications.
+    # Optionally sets the publication window; if not given, the products will be published immediately
+    # with no end date.
+    # @param product_ids [Array<Integer>, Integer] the IDs of the products to publish on this channel
+    # @param published_at [Time, nil] when the publications go live; nil means immediately
+    # @param unpublished_at [Time, nil] when the publications come down; nil means never
+    # @return [Integer] the number of ProductPublications created or updated
+    def add_products(product_ids, published_at: nil, unpublished_at: nil)
+      product_ids = Array(product_ids).map(&:to_s).uniq
+      return 0 if product_ids.empty?
+
+      now = Time.current
+      # Only include window columns in the upsert payload when the caller
+      # explicitly passed a value. Leaving them out keeps existing
+      # publication schedules intact on re-publish — otherwise +on_duplicate:
+      # :update+ + +update_only+ would rewrite scheduled +published_at+ /
+      # +unpublished_at+ to NULL whenever the bulk action re-runs without
+      # dates.
+      base = { channel_id: id, created_at: now, updated_at: now }
+      base[:published_at] = published_at unless published_at.nil?
+      base[:unpublished_at] = unpublished_at unless unpublished_at.nil?
+
+      records_to_upsert = product_ids.map { |product_id| base.merge(product_id: product_id) }
+
+      # Only update the window columns the caller passed. When neither was
+      # passed, treat re-publish as a no-op (+on_duplicate: :skip+ → MySQL
+      # +INSERT IGNORE+, PG/SQLite +ON CONFLICT DO NOTHING+).
+      update_columns = []
+      update_columns << :published_at unless published_at.nil?
+      update_columns << :unpublished_at unless unpublished_at.nil?
+      opts = if update_columns.empty?
+               { on_duplicate: :skip }
+             else
+               { record_timestamps: false, update_only: update_columns, on_duplicate: :update }
+             end
+      # MySQL infers the conflict target from the table's unique constraints
+      # and rejects an explicit +unique_by+; PostgreSQL/SQLite require it.
+      opts[:unique_by] = %i[product_id channel_id] unless mysql_adapter?
+
+      Spree::ProductPublication.upsert_all(records_to_upsert, **opts)
+
+      products = Spree::Product.where(id: product_ids)
+      products.touch_all
+      products.each(&:enqueue_search_index)
+      touch
+
+      records_to_upsert.size
+    end
+
+    # Unpublishes the given products from this channel.
+    # @param product_ids [Array<Integer>, Integer] the IDs of the products to unpublish
+    # @return [Integer] the number of ProductPublications destroyed
+    def remove_products(product_ids)
+      product_ids = Array(product_ids).map(&:to_s).uniq
+      return 0 if product_ids.empty?
+
+      count = publications.where(product_id: product_ids).destroy_all.size
+
+      products = Spree::Product.where(id: product_ids)
+      products.touch_all
+      products.each(&:enqueue_search_index)
+
+      touch if count.positive?
+      count
+    end
+
+    # @return [Boolean]
+    def can_be_deleted?
+      !default?
+    end
+
+    private
+
+    def ensure_not_default
+      return if can_be_deleted?
+      return if destroyed_by_association.present?
+
+      errors.add(:base, Spree.t('errors.messages.cannot_delete_default_channel'))
+      throw :abort
+    end
+
+    def backfill_code_from_name
+      self.code = name
+    end
+
+    # First channel on a store becomes the default. Lets the
+    # +Stores::Channels#ensure_default_channel+ seed path and the legacy
+    # admin "create channel" form both produce a sensible default without
+    # the caller having to know.
+    def promote_first_channel_to_default
+      return if default
+      return unless new_record? && store_id.present?
+
+      self.default = true unless Spree::Channel.where(store_id: store_id).exists?
+    end
+
+    def demote_other_defaults
+      Spree::Channel.where(store_id: store_id, default: true).where.not(id: id).update_all(default: false)
+    end
+
+    # Default ordering: preferred location wins, then minimize splits, then
+    # fall back to StockLocation.default. See docs/plans/6.0-order-routing.md.
+    def ensure_default_order_routing_rules
+      return if order_routing_rules.any?
+
+      Spree::OrderRouting::Rules::PreferredLocation.create!(store: store, channel: self, position: 1)
+      Spree::OrderRouting::Rules::MinimizeSplits.create!(store: store , channel: self, position: 2)
+      Spree::OrderRouting::Rules::DefaultLocation.create!(store: store, channel: self, position: 3)
+    end
+  end
+end

data/app/models/spree/country.rb

@@ -1,5 +1,7 @@
 module Spree
   class Country < Spree.base_class
+    self.whitelisted_ransackable_attributes = %w[iso iso3 iso_name name]
+
     has_many :addresses, dependent: :restrict_with_error
     has_many :states,
              -> { order name: :asc },

data/app/models/spree/current.rb

@@ -4,7 +4,7 @@ module Spree
   # All attributes are automatically reset between requests by Rails.
   # Fallback chains ensure sensible defaults when attributes are not explicitly set.
   class Current < ::ActiveSupport::CurrentAttributes
-    attribute :store, :market, :currency, :locale, :zone, :default_tax_zone, :price_lists, :global_pricing_context
+    attribute :store, :channel, :market, :currency, :locale, :zone, :default_tax_zone, :price_lists, :global_pricing_context
 
     resets { @default_tax_zone_loaded = false }
 
@@ -14,6 +14,10 @@ module Spree
       super || Spree::Store.default
     end
 
+    def channel
+      super || (self.channel = store&.default_channel)
+    end
+
     # Returns the current market, falling back to the store's default market.
     # @return [Spree::Market, nil]
     def market

data/app/models/spree/custom_field.rb

@@ -0,0 +1,9 @@
+module Spree
+  # Constant alias for the legacy Spree::Metafield class. Lets controllers,
+  # serializers, and 5.5+ extensions reference the model by its 6.0-bound name
+  # without the actual class rename (which lands with the table rename in 6.0).
+  #
+  # This is a true constant alias — the underlying class, table, STI subclasses,
+  # and `model_name` are all `Spree::Metafield`. Only the constant name differs.
+  CustomField = Metafield
+end

data/app/models/spree/custom_field_definition.rb

@@ -0,0 +1,7 @@
+module Spree
+  # Constant alias for the legacy Spree::MetafieldDefinition class. Lets
+  # controllers, serializers, and 5.5+ extensions reference the model by its
+  # 6.0-bound name without the actual class rename (which lands with the table
+  # rename in 6.0).
+  CustomFieldDefinition = MetafieldDefinition
+end

data/app/models/spree/customer_group.rb

@@ -10,6 +10,11 @@ module Spree
     belongs_to :store, class_name: 'Spree::Store', inverse_of: :customer_groups
     has_many :customer_group_users, class_name: 'Spree::CustomerGroupUser', dependent: :destroy
     has_many :users, through: :customer_group_users, source: :user, source_type: Spree.user_class.to_s
+    # `customers` is the public name across the v3 API; declaring it as its
+    # own association (rather than `alias_method`) is what lets `customer_ids=`
+    # exist and what makes the `PrefixedId` auto-decoder in `assign_attributes`
+    # recognise the key — that lookup keys off `reflect_on_association(:customers)`.
+    has_many :customers, through: :customer_group_users, source: :user, source_type: Spree.user_class.to_s
 
     #
     # Validations
@@ -25,9 +30,10 @@ module Spree
     #
     # Instance Methods
     #
-    def users_count
-      customer_group_users.count
+    def customers_count
+      customer_group_users.size
     end
+    alias_method :users_count, :customers_count
 
     # Bulk add customers to the group
     # @param user_ids [Array] array of user IDs to add

data/app/models/spree/export.rb

@@ -22,13 +22,16 @@ module Spree
     # Associations
     #
     belongs_to :store, class_name: 'Spree::Store'
-    belongs_to :user, class_name: Spree.admin_user_class.to_s
+    # Optional so secret-API-key callers (apps / server-to-server) can create
+    # exports without a human user attached. The email notification is
+    # skipped for these — apps poll instead.
+    belongs_to :user, class_name: Spree.admin_user_class.to_s, optional: true
     belongs_to :vendor, -> { with_deleted }, class_name: 'Spree::Vendor', optional: true
 
     #
     # Validations
     #
-    validates :format, :store, :user, :type, presence: true
+    validates :format, :store, :type, presence: true
 
     #
     # Enums
@@ -127,12 +130,34 @@ module Spree
 
     def records_to_export
       if search_params.present?
-        scope.ransack(search_params.is_a?(String) ? JSON.parse(search_params.to_s).to_h : search_params)
+        params = search_params.is_a?(String) ? JSON.parse(search_params.to_s).to_h : search_params
+        scope.ransack(decode_prefixed_id_filters(params))
       else
         scope.ransack
       end.result
     end
 
+    # Replace any prefixed IDs in `search_params` with their raw DB IDs so
+    # Ransack can match them. Without this, an admin filtering an export by
+    # a foreign key (`promotion_id_eq: 'promo_xxx'`, `vendor_id_in: [...]`)
+    # would always get zero rows. We only touch values that look like
+    # prefixed IDs — anything else (numeric IDs, code strings, ranges,
+    # state names) passes through untouched.
+    def decode_prefixed_id_filters(params)
+      params.transform_values { |value| decode_search_value(value) }
+    end
+
+    def decode_search_value(value)
+      case value
+      when String
+        Spree::PrefixedId.prefixed_id?(value) ? (Spree::PrefixedId.decode_prefixed_id(value) || value) : value
+      when Array
+        value.map { |v| decode_search_value(v) }
+      else
+        value
+      end
+    end
+
     def scope_includes
       []
     end
@@ -181,6 +206,8 @@ module Spree
     end
 
     def send_export_done_email
+      return if user.blank? # App-created exports (secret API key) have no user to email.
+
       Spree::ExportMailer.export_done(self).deliver_later
     end
 

data/app/models/spree/gateway.rb

@@ -6,6 +6,31 @@ module Spree
 
     validates :type, presence: true, inclusion: { in: :valid_providers_list }
 
+    # Payment provider gems conventionally ship a top-level `Gateway`
+    # class — `SpreeStripe::Gateway`, `SpreeAdyen::Gateway`,
+    # `SpreePaypalCheckout::Gateway`. The default demodulized
+    # `api_type` collapses every provider to `"gateway"`, which
+    # collides in the registry and produces duplicate keys in admin
+    # UIs. For gateway subclasses, use the outer module instead (with
+    # a leading `Spree` namespace stripped), matching the labelling
+    # convention in `PreferenceSchema#subclass_label`:
+    #
+    #   SpreeStripe::Gateway          → "stripe"
+    #   SpreeAdyen::Gateway           → "adyen"
+    #   SpreePaypalCheckout::Gateway  → "paypal_checkout"
+    #   MyShop::Gateway               → "my_shop"
+    #
+    # Subclasses nested under a Gateway module (e.g.
+    # `Spree::Gateway::Bogus`) demodulize to their own leaf and
+    # bypass this fallback.
+    def self.api_type
+      leaf = super
+      return leaf unless leaf == 'gateway'
+
+      outer = to_s.deconstantize.delete_prefix('Spree::').delete_prefix('Spree').presence
+      outer ? outer.underscore : leaf
+    end
+
     def payment_source_class
       CreditCard
     end

data/app/models/spree/gift_card.rb

@@ -62,7 +62,7 @@ module Spree
     #
     # Ransack
     #
-    self.whitelisted_ransackable_attributes = %w[code user_id state]
+    self.whitelisted_ransackable_attributes = %w[code user_id state gift_card_batch_id created_by_id]
     self.whitelisted_ransackable_associations = %w[users orders batch]
     self.whitelisted_ransackable_scopes = %w[active expired redeemed partially_redeemed]
 

data/app/models/spree/gift_card_batch.rb

@@ -18,7 +18,10 @@ module Spree
     # Validations
     #
     validates :codes_count, :amount, :prefix, presence: true
-    validates :codes_count, numericality: { greater_than: 0, less_than_or_equal_to: Spree::Config[:gift_card_batch_limit].to_i }
+    validates :codes_count, numericality: {
+      greater_than: 0,
+      less_than_or_equal_to: ->(_record) { Spree::Config[:gift_card_batch_limit].to_i }
+    }
     validates :store, :currency, presence: true
     validates :amount, numericality: { greater_than: 0 }
 

data/app/models/spree/import.rb

@@ -62,6 +62,7 @@ module Spree
       event :complete do
         transition from: :processing, to: :completed
       end
+      after_transition to: :completed, do: :touch_store
       after_transition to: :completed, do: :publish_import_completed_event
       # NOTE: send_import_completed_email and update_loader_in_import_view
       # are now handled by Spree::Admin::ImportSubscriber listening to 'import.completed' event
@@ -181,6 +182,10 @@ module Spree
       "#{Spree.t(type.demodulize.pluralize.downcase)} #{number}"
     end
 
+    def touch_store
+      store.touch
+    end
+
     def publish_import_completed_event
       publish_event('import.completed')
     end

data/app/models/spree/import_row.rb

@@ -41,6 +41,11 @@ module Spree
       # are now handled by Spree::Admin::ImportRowSubscriber
     end
 
+    # How long a row may sit in `processing` before we consider its owning worker dead
+    # (OOM, SIGKILL, deploy without graceful drain — none of these trigger a Sidekiq
+    # retry). After this window, stalled rows no longer block the import from completing.
+    STALLED_PROCESSING_AFTER = 1.hour
+
     #
     # Scopes
     #
@@ -48,6 +53,13 @@ module Spree
     scope :completed, -> { where(status: :completed) }
     scope :failed, -> { where(status: :failed) }
     scope :processed, -> { where(status: %i[completed failed]) }
+    # Rows still legitimately blocking import completion: `pending` (not started) or
+    # `processing` with a recent updated_at (worker still alive). Orphaned `processing`
+    # rows past the stall window are excluded so a dead worker can't permanently block
+    # completion — operators can clean those up separately.
+    scope :in_flight, -> {
+      where(status: :pending).or(where(status: :processing).where(updated_at: STALLED_PROCESSING_AFTER.ago..))
+    }
 
     def data_json
       @data_json ||= JSON.parse(data)

data/app/models/spree/line_item.rb

@@ -24,6 +24,7 @@ module Spree
     has_many :inventory_units, class_name: 'Spree::InventoryUnit', inverse_of: :line_item, dependent: :destroy
     has_many :shipments, through: :inventory_units, source: :shipment
     has_many :digital_links, dependent: :destroy
+    has_many :stock_reservations, class_name: 'Spree::StockReservation', inverse_of: :line_item, dependent: :destroy
 
     before_validation :copy_price
     before_validation :copy_tax_category
@@ -164,9 +165,13 @@ module Spree
 
     # Returns true if the line item has sufficient stock
     #
+    # The order's own active stock reservations are excluded from the
+    # availability check — a customer's own checkout hold must not make
+    # their own line item look out of stock.
+    #
     # @return [Boolean]
     def sufficient_stock?
-      can_supply? quantity
+      Spree::Stock::Quantifier.new(variant, excluded_order: order).can_supply?(quantity)
     end
 
     # Returns true if the line item has insufficient stock

data/app/models/spree/market.rb

@@ -10,7 +10,7 @@ module Spree
     #
     # Associations
     #
-    belongs_to :store, class_name: 'Spree::Store', touch: true
+    belongs_to :store, class_name: 'Spree::Store', touch: true, inverse_of: :markets
     has_many :market_countries, class_name: 'Spree::MarketCountry', dependent: :destroy
     has_many :countries, through: :market_countries, class_name: 'Spree::Country'
     has_many :orders, class_name: 'Spree::Order', dependent: :nullify
@@ -81,6 +81,37 @@ module Spree
       @supported_locales_list ||= (supported_locales.to_s.split(',').map(&:strip) << default_locale).compact.uniq.sort
     end
 
+    # Accepts an Array of locale codes and persists them as a comma-separated
+    # string on the `supported_locales` column. Strings are still accepted
+    # verbatim so legacy callers (the Rails admin form, raw seed scripts)
+    # keep working.
+    #
+    # @param value [Array<String>, String, nil]
+    def supported_locales=(value)
+      @supported_locales_list = nil
+      normalized = value.is_a?(Array) ? value.compact.uniq.reject(&:blank?).join(',') : value
+      super(normalized)
+    end
+
+    # Read companion for `country_isos=`. Returns the sorted list of ISO codes
+    # currently assigned to the market.
+    #
+    # @return [Array<String>]
+    def country_isos
+      countries.map(&:iso).compact.sort
+    end
+
+    # Accepts an Array of 2-letter ISO codes and resolves them to the matching
+    # `Spree::Country` records, replacing the market's countries. Unknown codes
+    # are silently dropped — the `validates :countries, presence: true` covers
+    # the "every ISO was bogus" case.
+    #
+    # @param values [Array<String>]
+    def country_isos=(values)
+      isos = Array(values).compact.map { |v| v.to_s.upcase }.reject(&:blank?)
+      self.countries = isos.any? ? Spree::Country.where(iso: isos) : []
+    end
+
     # Returns true when the market is safe to delete. A market cannot be deleted
     # if it is the default market or the only market in the store, since
     # Spree::Current.currency would have no fallback.

data/app/models/spree/metafield.rb

@@ -1,5 +1,26 @@
 module Spree
   class Metafield < Spree.base_class
+    # Map of API-facing tokens to Ruby STI class names. The wire format is the
+    # token (`short_text`); the database column stores the class name. Reads
+    # translate to the token via `field_type`; writes accept either form.
+    # Plugin-defined types fall through to the raw class name until 6.0 when a
+    # registration API lands.
+    TYPE_TOKENS = {
+      'short_text' => 'Spree::Metafields::ShortText',
+      'long_text'  => 'Spree::Metafields::LongText',
+      'rich_text'  => 'Spree::Metafields::RichText',
+      'number'     => 'Spree::Metafields::Number',
+      'boolean'    => 'Spree::Metafields::Boolean',
+      'json'       => 'Spree::Metafields::Json'
+    }.freeze
+    TYPE_CLASS_TO_TOKEN = TYPE_TOKENS.invert.freeze
+
+    # Array form consumed by serializers via
+    # `typelize field_type: Spree::Metafield::FIELD_TYPE_TOKENS`. Typelizer
+    # emits a string-literal union in TypeScript and `{type: string, enum: […]}`
+    # in OpenAPI (string-array form was added in typelizer 0.10.0).
+    FIELD_TYPE_TOKENS = TYPE_TOKENS.keys.freeze
+
     has_prefix_id :cf
 
     #
@@ -8,6 +29,21 @@ module Spree
     belongs_to :resource, polymorphic: true, touch: true
     belongs_to :metafield_definition, class_name: 'Spree::MetafieldDefinition'
 
+    #
+    # API naming bridge — internal column rename lands in 6.0
+    #
+    alias_attribute :custom_field_definition_id, :metafield_definition_id
+
+    # API-facing form of the STI `type` column. Returns the token
+    # (`short_text`) when the row's type is a registered built-in; falls
+    # through to the raw class name for plugin types.
+    #
+    # `self[:type]` reads the raw column to bypass AR's STI reader (which
+    # returns the resolved class constant, not a string).
+    def field_type
+      TYPE_CLASS_TO_TOKEN[self[:type]] || self[:type]
+    end
+
     #
     # Delegations
     #
@@ -43,6 +79,8 @@ module Spree
     private
 
     def set_type_from_metafield_definition
+      return if metafield_definition.blank?
+
       self.type ||= metafield_definition.metafield_type
     end
 

data/app/models/spree/metafield_definition.rb

@@ -18,6 +18,7 @@ module Spree
     validates :metafield_type, presence: true, inclusion: { in: :valid_available_types }
     validates :resource_type, presence: true, inclusion: { in: :valid_available_resources }
     validates :key, uniqueness: { scope: spree_base_uniqueness_scope + [:resource_type, :namespace] }
+    validate :field_type_input_must_be_recognized
 
     #
     # Scopes
@@ -51,14 +52,29 @@ module Spree
     self.whitelisted_ransackable_attributes = %w[key namespace name resource_type display_on]
     self.whitelisted_ransackable_scopes = %w[search multi_search]
 
-    # 5.5 API naming bridge (DB column rename in 6.0)
-    # Aligns with OptionType/OptionValue which also expose `label` for the display name.
-    def label
-      name
+    # API naming bridge — internal columns rename in 6.0. `label` matches
+    # OptionType/OptionValue conventions. (`storefront_visible` lives on
+    # the `Spree::DisplayOn` concern, shared with PaymentMethod + ShippingMethod —
+    # see docs/plans/5.5-6.0-display-on-to-boolean.md.)
+    alias_attribute :label, :name
+
+    # API-facing token for the STI subclass name stored in `metafield_type`.
+    # Reader returns the registered token (`short_text`); writer accepts either
+    # the token or the legacy class-name form for back-compat.
+    def field_type
+      Spree::Metafield::TYPE_CLASS_TO_TOKEN[metafield_type] || metafield_type
     end
 
-    def label=(value)
-      self.name = value
+    def field_type=(value)
+      v = value.to_s
+      mapped = Spree::Metafield::TYPE_TOKENS[v]
+      # An input is "recognized" when it's either a known token (mapped to a
+      # class) or already a known class name. Anything else gets surfaced as
+      # an error on `field_type` so API clients get a token-vocabulary
+      # message instead of the raw class-name inclusion error on
+      # `metafield_type`.
+      @field_type_input_recognized = !mapped.nil? || Spree::Metafield::TYPE_CLASS_TO_TOKEN.key?(v)
+      self.metafield_type = mapped || value
     end
 
     # Returns the full key with namespace
@@ -91,6 +107,13 @@ module Spree
       self.class.available_types.map(&:to_s)
     end
 
+    def field_type_input_must_be_recognized
+      return if @field_type_input_recognized.nil? || @field_type_input_recognized
+
+      tokens = Spree::Metafield::TYPE_TOKENS.keys.join(', ')
+      errors.add(:field_type, "is not a known custom field type (expected one of: #{tokens})")
+    end
+
     def valid_available_resources
       self.class.available_resources.map(&:to_s)
     end

data/app/models/spree/metafields/json.rb

@@ -3,6 +3,16 @@ module Spree
     class Json < Spree::Metafield
       validate :value_must_be_valid_json
 
+      # Accept either a JSON-serialized String (from CSV / Admin UI text
+      # input) or a raw Hash / Array (from API callers that ship parsed
+      # objects). Non-String inputs get JSON-serialized so the underlying
+      # text column always holds canonical JSON.
+      #
+      # @param raw [String, Hash, Array, nil]
+      def value=(raw)
+        super(raw.is_a?(Hash) || raw.is_a?(Array) ? raw.to_json : raw)
+      end
+
       def serialize_value
         JSON.parse(value)
       rescue JSON::ParserError