spree_core 6.0.0.beta4 → 6.0.0.rc2

data/app/models/spree/store.rb

@@ -13,6 +13,7 @@ module Spree
     include Spree::Stores::Setup
     include Spree::Stores::Markets
     include Spree::Stores::Channels
+    include Spree::Stores::EmailBranding
     include Spree::StoreDataSources
     include Spree::Security::Stores if defined?(Spree::Security::Stores)
     include Spree::UserManagement
@@ -40,11 +41,16 @@ module Spree
     #
     # Preferences
     #
+    UNIT_SYSTEMS = %w[metric imperial].freeze
+
     # general preferences
-    preference :admin_locale, :string
-    preference :timezone, :string, default: Time.zone.name
-    preference :weight_unit, :string, default: 'lb'
-    preference :unit_system, :string, default: 'imperial'
+    preference :admin_locale, :string, format: :locale
+    preference :timezone, :string, format: :timezone, default: Time.zone.name
+    preference :weight_unit, :string, default: 'lb', choices: -> { Spree::Variant::WEIGHT_UNITS }
+    preference :unit_system, :string, default: 'imperial', choices: -> { UNIT_SYSTEMS }
+    # Anonymous identifier of this installation, kept on the default store
+    # (see Spree.install_id). Written by Spree, never by the operator.
+    preference :install_id, :string, internal: true, nullable: true
     # email preferences
     preference :send_consumer_transactional_emails, :boolean, default: true
     # Sellers are a different audience from shoppers, with their own reasons to
@@ -69,7 +75,8 @@ module Spree
     # Who pays this store's sellers. Blank means core's record-only provider,
     # so a marketplace that has connected nothing still keeps a correct ledger
     # and settles by hand.
-    preference :payout_provider, :string, default: nil
+    preference :payout_provider, :string, default: nil,
+                                          parse_on_set: ->(value) { Spree::ApiTyped.class_name_for(Spree.payout_providers, value) }
     # Refused at write time rather than silently falling back at read time: an
     # operator who mistypes a provider would otherwise get a bookkeeping-only
     # ledger and no indication anywhere that their choice was ignored.
@@ -78,22 +85,22 @@ module Spree
     # How often sellers are settled, unless one carries its own schedule.
     # Monthly by default because it is the interval that needs least of an
     # operator paying by hand, which is what the built-in provider expects.
-    preference :default_payouts_schedule_interval, :string, default: 'monthly'
+    preference :default_payouts_schedule_interval, :string, default: 'monthly', choices: -> { Spree::Seller::PAYOUT_INTERVALS }
     validates :preferred_default_payouts_schedule_interval,
               inclusion: { in: Spree::Seller::PAYOUT_INTERVALS }, allow_blank: true
     # What a seller's balance must reach before a settlement is worth sending;
     # below it the balance carries to the next period. Zero pays whatever is
     # owed, which is right for a provider that moves money for free.
-    preference :default_minimum_payout_amount, :decimal, default: 0
+    preference :default_minimum_payout_amount, :money, default: 0
     # Checkout preferences
     # Store-level fallback for the channel-owned `guest_checkout` preference
     # (see Spree::Channel::Gating). Retained so existing accessors keep working.
     preference :guest_checkout, :boolean, default: true
     # Store-level fallback for the channel-owned `storefront_access` posture.
-    preference :storefront_access, :string, default: 'public'
+    preference :storefront_access, :string, default: 'public', choices: -> { Spree::Channel::Gating::STOREFRONT_ACCESS }
     # Canonical storefront origin used in customer-facing emails and links,
     # e.g. "https://myshop.com" — see #storefront_url for the fallback chain.
-    preference :storefront_url, :string
+    preference :storefront_url, :string, format: :url
     preference :special_instructions_enabled, :boolean, default: false
     # Advertises a confirm/review step for every checkout, even when no
     # payment method asks for one. Payment methods that require confirmation
@@ -103,7 +110,8 @@ module Spree
     # Store-wide default for when a customer is charged rather than only
     # authorized. A payment method's own capture_method wins when set.
     # See Spree::CaptureMethod.
-    preference :capture_method, :string, default: Spree::CaptureMethod::DEFAULT_CAPTURE_METHOD
+    preference :capture_method, :string, default: Spree::CaptureMethod::DEFAULT_CAPTURE_METHOD,
+                                       choices: -> { Spree::CaptureMethod::CAPTURE_METHODS }
     preference :stock_reservations_enabled, :boolean, default: true
     # Which address a sale's tax is computed against. Stores selling where tax
     # follows the destination keep this on; billing-address jurisdictions turn
@@ -115,9 +123,9 @@ module Spree
     preference :inventory_provider, :string, default: 'internal'
     # What happens when an external source cannot be reached.
     preference :pricing_provider_failure_policy, :string,
-               default: Spree::ProviderFailurePolicy::DEFAULT_PRICING_POLICY
+               default: Spree::ProviderFailurePolicy::DEFAULT_PRICING_POLICY, choices: -> { Spree::ProviderFailurePolicy::VALUES }
     preference :inventory_provider_failure_policy, :string,
-               default: Spree::ProviderFailurePolicy::DEFAULT_INVENTORY_POLICY
+               default: Spree::ProviderFailurePolicy::DEFAULT_INVENTORY_POLICY, choices: -> { Spree::ProviderFailurePolicy::VALUES }
     # Catalog preferences
     preference :track_inventory_levels, :boolean, default: true
     # On-hand quantity at or below which a tracked variant counts as running
@@ -151,17 +159,34 @@ module Spree
     preference :digital_asset_link_expire_time, :integer, default: 300
     # Class name of the Spree::OrderRouting::Strategy::Base subclass that
     # decides which StockLocation fulfills which items.
-    preference :order_routing_strategy, :string, default: 'Spree::OrderRouting::Strategy::Rules'
+    preference :order_routing_strategy, :string, default: 'Spree::OrderRouting::Strategy::Rules',
+                                                 parse_on_set: ->(value) { Spree::ApiTyped.class_name_for(Spree.order_routing.strategies, value) }
 
     # Document numbering (docs/plans/6.0-document-numbers.md). The format
     # applies to every numbered document; prefix, suffix and starting value
     # are order-only — other document types keep their code-level prefixes.
     # Changes affect future numbers only; existing numbers are permanent.
-    preference :document_number_format, :string, default: 'sequential'
+    preference :document_number_format, :string, default: 'sequential', choices: -> { Spree::NumberGenerators::Registry::FORMATS.keys }
     preference :order_number_prefix, :string, default: 'R'
     preference :order_number_suffix, :string, default: ''
     preference :order_number_sequence_start, :integer, default: 1001
 
+    # The settings the API reads and writes under their plain names.
+    exposes_preferences :admin_locale, :timezone, :storefront_url, :weight_unit, :unit_system, :storefront_access, :guest_checkout,
+                        :always_include_confirm_step, :company_field_enabled, :address_requires_company,
+                        :address_requires_phone, :capture_method, :track_inventory_levels, :stock_reservations_enabled,
+                        :low_stock_threshold, :tax_using_ship_address, :track_price_history,
+                        :show_products_without_price, :disable_sku_validation, :order_routing_strategy,
+                        :pricing_provider, :inventory_provider, :pricing_provider_failure_policy,
+                        :inventory_provider_failure_policy, :payout_provider, :default_payouts_schedule_interval,
+                        :default_minimum_payout_amount, :auto_approve_sellers, :auto_approve_seller_products,
+                        :send_seller_transactional_emails, :default_commission_tax_rate, :document_number_format,
+                        :order_number_prefix, :order_number_suffix, :order_number_sequence_start,
+                        :limit_digital_download_count, :digital_asset_authorized_clicks,
+                        :limit_digital_download_days, :digital_asset_authorized_days,
+                        :send_consumer_transactional_emails, :email_accent_color, :email_background_color,
+                        :email_card_color, :email_text_color, :email_heading_color, :email_font
+
     #
     # Associations
     #
@@ -300,6 +325,8 @@ module Spree
     has_many :policies, class_name: 'Spree::Policy', dependent: :destroy, as: :owner
 
     has_many :webhook_endpoints, class_name: 'Spree::WebhookEndpoint', dependent: :destroy, inverse_of: :store
+    has_many :email_templates, class_name: 'Spree::EmailTemplate', dependent: :destroy, inverse_of: :store
+    has_many :email_template_drafts, class_name: 'Spree::EmailTemplateDraft', dependent: :destroy, inverse_of: :store
     has_many :webhook_deliveries, through: :webhook_endpoints, class_name: 'Spree::WebhookDelivery'
 
     has_many :channels, class_name: 'Spree::Channel', dependent: :destroy
@@ -335,6 +362,10 @@ module Spree
     validates :preferred_default_commission_tax_rate,
               numericality: { greater_than_or_equal_to: 0, less_than_or_equal_to: 1 }
     validates :preferred_storefront_access, inclusion: { in: Spree::Channel::Gating::STOREFRONT_ACCESS }
+    # Blank falls back to the defaults where they are read, so a store saved
+    # with one before these checks existed stays savable.
+    validates :preferred_unit_system, inclusion: { in: UNIT_SYSTEMS }, allow_blank: true
+    validates :preferred_weight_unit, inclusion: { in: Spree::Variant::WEIGHT_UNITS }, allow_blank: true
     validates :preferred_document_number_format,
               inclusion: { in: Spree::NumberGenerators::Registry::FORMATS.keys }
     validates :preferred_order_number_sequence_start,
@@ -362,6 +393,7 @@ module Spree
     #
     has_one_attached :logo, service: Spree.public_storage_service_name
     has_one_attached :mailer_logo, service: Spree.public_storage_service_name
+    signed_id_attachments :logo, :mailer_logo
 
     # First-run setup credential (docs/plans/6.0-store-context-and-first-run-setup.md):
     # printed by the installer, only consulted by the setup endpoint while no
@@ -384,6 +416,7 @@ module Spree
     before_validation :set_default_code, on: :create
     before_validation :normalize_preferred_storefront_url
     before_save :ensure_default_exists_and_is_unique
+    before_save :set_install_id
     after_create :create_default_policies
     after_create :create_default_delivery_profile
 
@@ -475,14 +508,12 @@ module Spree
     #
     # @return [Class]
     def payout_provider_class
-      configured = preferred_payout_provider.presence
       # A name no longer in the registry — a typo, or a gem since removed —
       # would otherwise raise inside a subscriber on every fulfillment and stop
       # the ledger recording anything. The built-in provider keeps the books
       # until an operator fixes the setting.
-      configured = nil unless Spree.payout_providers.any? { |provider| provider.to_s == configured }
-
-      (configured || Spree.default_payout_provider.to_s).constantize
+      Spree::ApiTyped.registered_class(Spree.payout_providers, preferred_payout_provider) ||
+        Spree.default_payout_provider.to_s.constantize
     end
 
     def formatted_url
@@ -521,6 +552,7 @@ module Spree
     end
 
     # Returns the storefront origin URL for use in customer-facing emails and links.
+    # Replaces the plain `storefront_url` reader `exposes_preferences` defines.
     # Uses the `storefront_url` preference when set, then the oldest non-loopback
     # allowed origin (the `http://localhost` origin seeded on install must never
     # leak into customer emails), otherwise falls back to formatted_url.
@@ -543,6 +575,21 @@ module Spree
       allowed_origins.any? { |allowed_origin| allowed_origin.matches?(url) }
     end
 
+    # The logo emails show: the dedicated mailer logo, else the store logo.
+    #
+    # @return [ActiveStorage::Attached::One, nil] nil when neither is an image
+    def email_logo
+      logo = mailer_logo.attached? ? mailer_logo : self.logo
+      logo if logo.attached? && logo.variable?
+    end
+
+    # The address customers are told to write to: the support address, else the sender address.
+    #
+    # @return [String, nil]
+    def support_email_address
+      customer_support_email.presence || mail_from_address
+    end
+
     # Returns the states available for checkout for the store
     # @param country [Spree::Country] the country to get the states for
     # @return [Array<Spree::State>]
@@ -613,7 +660,7 @@ module Spree
       @default_stock_location ||= begin
         stock_location_scope = stock_locations.first_party.where(default: true)
         stock_location_scope.first || ActiveRecord::Base.connected_to(role: :writing) do
-          stock_location_scope.create(default: true, name: Spree.t(:default_stock_location_name),
+          stock_location_scope.create(default: true, name: I18n.t('spree.default_stock_location_name'),
                                       country_code: default_country&.iso)
         end
       end
@@ -699,6 +746,10 @@ module Spree
       I18n.t(key, locale: locale, default: I18n.t(key, locale: :en))
     end
 
+    def set_install_id
+      self.preferred_install_id = SecureRandom.uuid if preferred_install_id.blank?
+    end
+
     def ensure_default_exists_and_is_unique
       if default
         Spree::Store.where.not(id: id).update_all(default: false)

data/app/models/spree/store_credit.rb

@@ -5,6 +5,9 @@ module Spree
     include Spree::SingleStoreResource
     include Spree::HasCustomFields
     include Spree::Metadata
+    include Spree::CanonicalDecimals
+
+    canonical_decimals :amount
 
     publishes_lifecycle_events
 
@@ -18,7 +21,6 @@ module Spree
     AUTHORIZE_ACTION  = 'authorize'.freeze
     ALLOCATION_ACTION = 'allocation'.freeze
 
-    belongs_to :store, class_name: 'Spree::Store'
     # A gift card applied to a guest cart issues store credit with no customer
     # to attach it to.
     belongs_to :customer, class_name: "::#{Spree.customer_class}", optional: true
@@ -106,13 +108,11 @@ module Spree
     extend Spree::DisplayMoney
     money_methods :amount, :amount_used, :amount_remaining, :amount_authorized
 
-    def amount=(amount)
-      self[:amount] = Spree::LocalizedNumber.parse(amount)
-    end
-
     self.whitelisted_ransackable_attributes = %w[customer_id created_by_id amount currency memo]
+    search_by :memo
     self.whitelisted_ransackable_associations = %w[customer created_by]
     self.whitelisted_ransackable_scopes = %w[outstanding from_gift_card]
+    self.ransackable_scope_types = %w[outstanding from_gift_card].index_with('boolean')
     # Staff notes and who issued the credit are back-office data.
     self.private_ransackable_attributes = { store: %w[memo created_by_id] }
 
@@ -146,16 +146,16 @@ module Spree
         )
         authorization_code
       else
-        errors.add(:base, :insufficient_authorized_amount, message: Spree.t('store_credit_payment_method.insufficient_authorized_amount'))
+        errors.add(:base, :insufficient_authorized_amount, message: I18n.t('spree.store_credit_payment_method.insufficient_authorized_amount'))
         false
       end
     end
 
     def validate_authorization(amount, order_currency)
       if BigDecimal(amount_remaining, 3) < BigDecimal(amount, 3)
-        errors.add(:base, :insufficient_funds, message: Spree.t('store_credit_payment_method.insufficient_funds'))
+        errors.add(:base, :insufficient_funds, message: I18n.t('spree.store_credit_payment_method.insufficient_funds'))
       elsif currency != order_currency
-        errors.add(:base, :currency_mismatch, message: Spree.t('store_credit_payment_method.currency_mismatch'))
+        errors.add(:base, :currency_mismatch, message: I18n.t('spree.store_credit_payment_method.currency_mismatch'))
       end
       errors.blank?
     end
@@ -165,7 +165,7 @@ module Spree
 
       if amount <= amount_authorized
         if currency != order_currency
-          errors.add(:base, :currency_mismatch, message: Spree.t('store_credit_payment_method.currency_mismatch'))
+          errors.add(:base, :currency_mismatch, message: I18n.t('spree.store_credit_payment_method.currency_mismatch'))
           false
         else
           update!(
@@ -179,7 +179,7 @@ module Spree
           authorization_code
         end
       else
-        errors.add(:base, :insufficient_authorized_amount, message: Spree.t('store_credit_payment_method.insufficient_authorized_amount'))
+        errors.add(:base, :insufficient_authorized_amount, message: I18n.t('spree.store_credit_payment_method.insufficient_authorized_amount'))
         false
       end
     end
@@ -196,7 +196,7 @@ module Spree
         true
       else
         errors.add(:base, :unable_to_void, auth_code: authorization_code,
-                   message: Spree.t('store_credit_payment_method.unable_to_void', auth_code: authorization_code))
+                   message: I18n.t('spree.store_credit_payment_method.unable_to_void', auth_code: authorization_code))
         false
       end
     end
@@ -206,7 +206,7 @@ module Spree
       capture_event = store_credit_events.find_by(action: CAPTURE_ACTION, authorization_code: authorization_code)
 
       if currency != order_currency # sanity check to make sure the order currency hasn't changed since the auth
-        errors.add(:base, :currency_mismatch, message: Spree.t('store_credit_payment_method.currency_mismatch'))
+        errors.add(:base, :currency_mismatch, message: I18n.t('spree.store_credit_payment_method.currency_mismatch'))
         false
       elsif capture_event && amount <= capture_event.amount
         action_attributes = {
@@ -219,7 +219,7 @@ module Spree
         true
       else
         errors.add(:base, :unable_to_credit, auth_code: authorization_code,
-                   message: Spree.t('store_credit_payment_method.unable_to_credit', auth_code: authorization_code))
+                   message: I18n.t('spree.store_credit_payment_method.unable_to_credit', auth_code: authorization_code))
         false
       end
     end

data/app/models/spree/store_credit_event.rb

@@ -24,15 +24,15 @@ module Spree
     def display_action
       case action
       when Spree::StoreCredit::CAPTURE_ACTION
-        Spree.t('store_credit.captured')
+        I18n.t('spree.store_credit.captured')
       when Spree::StoreCredit::AUTHORIZE_ACTION
-        Spree.t('store_credit.authorized')
+        I18n.t('spree.store_credit.authorized')
       when Spree::StoreCredit::ALLOCATION_ACTION
-        Spree.t('store_credit.allocated')
+        I18n.t('spree.store_credit.allocated')
       when Spree::StoreCredit::ELIGIBLE_ACTION
-        Spree.t('store_credit.eligible')
+        I18n.t('spree.store_credit.eligible')
       when Spree::StoreCredit::VOID_ACTION, Spree::StoreCredit::CREDIT_ACTION
-        Spree.t('store_credit.credit')
+        I18n.t('spree.store_credit.credit')
       end
     end
 

data/app/models/spree/supplier.rb

@@ -32,6 +32,7 @@ module Spree
     normalizes :name, :contact_name, :phone, with: ->(value) { value.strip }
 
     self.whitelisted_ransackable_attributes = %w[name contact_name email phone city country_code created_at]
+    search_by :name, :contact_name, :email
 
     # The postal address, built from this row's own columns the way
     # {Spree::StockLocation#address} does. Unsaved, and blank when nothing has

data/app/models/spree/tax_category.rb

@@ -16,6 +16,7 @@ module Spree
     before_save :set_default_category
 
     self.whitelisted_ransackable_attributes = %w[name is_default tax_code]
+    search_by :name
 
     # The category applied to taxable records that carry none of their own.
     #

data/app/models/spree/tax_exemption_certificate.rb

@@ -9,6 +9,8 @@ module Spree
   # valid in one state and not the next is the ordinary case, and the country
   # and state columns say exactly where it holds.
   class TaxExemptionCertificate < Spree.base_class
+    publishes_event :verified
+
     has_prefix_id :cert
 
     include Spree::HasStatus
@@ -25,6 +27,7 @@ module Spree
     # Confidential, so the private service rather than the public one that
     # serves product images.
     has_one_attached :document, service: Spree.private_storage_service_name
+    signed_id_attachments :document
 
     validates :certificate_number, :reason_code, presence: true
     # Certificates exist only on legal-entity nodes — a division's purchases

data/app/models/spree/tax_identifier.rb

@@ -36,6 +36,8 @@ module Spree
   # directly. It is a habit of the gems that use it, not a rule this model
   # applies.
   class TaxIdentifier < Spree.base_class
+    publishes_event :number_changed
+
     has_prefix_id :txi
 
     # Statuses the platform records rather than the buyer chooses: nil means
@@ -150,7 +152,7 @@ module Spree
     # The kind as the dashboard shows it, falling back to the raw key so an
     # extension's kind reads as itself rather than blank.
     def kind_label
-      Spree.t("tax_identifier_kinds.#{kind}", default: kind.to_s.humanize)
+      I18n.t("spree.tax_identifier_kinds.#{kind}", default: kind.to_s.humanize)
     end
 
     # The class registered for this kind, or nil when nothing is registered and

data/app/models/spree/tax_line.rb

@@ -4,6 +4,11 @@ module Spree
   # per estimate. Snapshot columns (+rate+, +label+, +provider_id+) keep rows
   # self-describing after a TaxRate is deleted or when an external provider
   # computed them.
+  #
+  # Rows on a return, claim or exchange line are post-sale: the tax given back
+  # (+credit+), or the tax on an exchange's replacement. They are owned by the
+  # order like every other row but never count towards its totals — the order
+  # reads only {.sale} rows.
   class TaxLine < Spree.base_class
     include Spree::TypedAdjustmentLine
 
@@ -35,6 +40,13 @@ module Spree
     belongs_to :line_item, class_name: 'Spree::LineItem', optional: true
     belongs_to :fulfillment, class_name: 'Spree::Fulfillment', optional: true
     belongs_to :fee, class_name: 'Spree::Fee', optional: true
+    belongs_to :return_line_item, class_name: 'Spree::ReturnLineItem', optional: true
+    belongs_to :claim_line_item, class_name: 'Spree::ClaimLineItem', optional: true
+    belongs_to :exchange_line_item, class_name: 'Spree::ExchangeLineItem', optional: true
+
+    # The sale row a credit gives back — what caps repeated credits against one
+    # line, and the original a credit note refers to.
+    belongs_to :original_tax_line, class_name: 'Spree::TaxLine', optional: true
 
     # Tax included in price vs additional. Per-row (mixed regimes on one order).
     attribute :included, :boolean, default: false
@@ -46,20 +58,50 @@ module Spree
               inclusion: { in: ->(tax_line) { tax_line.class.taxability_reasons } },
               allow_nil: true
     validate :exactly_one_adjustable
+    validate :post_sale_owned_by_order
 
     # Tax reporting is the reason the treatment columns exist — "which country's
     # tax was this, and which sales were reverse-charged" has to be answerable.
     self.whitelisted_ransackable_attributes = %w[taxability_reason country_code state_code included provider_id]
 
+    POST_SALE_KEYS = %i[return_line_item_id claim_line_item_id exchange_line_item_id].freeze
+
+    ADJUSTABLE_KEYS = {
+      'Spree::LineItem' => :line_item_id,
+      'Spree::Fulfillment' => :fulfillment_id,
+      'Spree::Fee' => :fee_id,
+      'Spree::ReturnLineItem' => :return_line_item_id,
+      'Spree::ClaimLineItem' => :claim_line_item_id,
+      'Spree::ExchangeLineItem' => :exchange_line_item_id
+    }.freeze
+
     scope :included_in_price, -> { where(included: true) }
     scope :additional, -> { where(included: false) }
     scope :for_line_items, -> { where.not(line_item_id: nil) }
     scope :for_fulfillments, -> { where.not(fulfillment_id: nil) }
     scope :for_fees, -> { where.not(fee_id: nil) }
+    scope :sale, -> { where(POST_SALE_KEYS.index_with(nil)) }
+    scope :post_sale, -> { where.not(POST_SALE_KEYS.index_with(nil)) }
+    scope :credits, -> { where(credit: true) }
+    scope :charges, -> { where(credit: false) }
+
+    # The foreign key a row uses to point at an item of this class.
+    #
+    # @param klass [Class]
+    # @return [Symbol]
+    # @raise [ArgumentError] for a class that is not taxed
+    def self.adjustable_key_for(klass)
+      ADJUSTABLE_KEYS.fetch(klass.name) { raise ArgumentError, "#{klass} is not taxable" }
+    end
 
-    # @return [Spree::LineItem, Spree::Fulfillment, Spree::Fee, nil]
+    # @return [Spree::LineItem, Spree::Fulfillment, Spree::Fee, Spree::ReturnLineItem,
+    #   Spree::ClaimLineItem, Spree::ExchangeLineItem, nil]
     def adjustable
-      line_item || fulfillment || fee
+      line_item || fulfillment || fee || return_line_item || claim_line_item || exchange_line_item
+    end
+
+    def post_sale?
+      POST_SALE_KEYS.any? { |key| self[key].present? }
     end
 
     def included?
@@ -73,7 +115,15 @@ module Spree
     private
 
     def exactly_one_adjustable
-      errors.add(:base, :exactly_one_adjustable, message: Spree.t('errors.messages.exactly_one_adjustable')) unless [line_item, fulfillment, fee].compact.one?
+      adjustables = [line_item, fulfillment, fee, return_line_item, claim_line_item, exchange_line_item]
+      errors.add(:base, :exactly_one_adjustable, message: I18n.t('spree.errors.messages.exactly_one_adjustable')) unless adjustables.compact.one?
+    end
+
+    # Returns, claims and exchanges only exist on placed orders.
+    def post_sale_owned_by_order
+      return unless post_sale? && order.nil?
+
+      errors.add(:base, :exactly_one_of_cart_or_order, message: I18n.t('spree.errors.messages.exactly_one_of_cart_or_order'))
     end
   end
 end

data/app/models/spree/tax_provider/base.rb

@@ -3,12 +3,16 @@ module Spree
     # Contract for tax providers — the only sanctioned writers of
     # {Spree::TaxLine} rows. +estimate+ must use replace-all set semantics per
     # target item (delete the item's stale lines, insert fresh ones); that is
-    # what keeps tax correct after address or item changes. Commit/void/refund
-    # are lifecycle no-ops for providers without a remote ledger.
+    # what keeps tax correct after address or item changes, and the post-sale
+    # +estimate_refund+ / +estimate_replacement+ follow the same rule.
+    # Commit/void/refund/commit_replacement are lifecycle no-ops for providers
+    # without a remote ledger.
     #
     # Providers are stateless and constructed without arguments, so anything
     # request-specific arrives as an argument rather than through the instance.
     class Base
+      extend Spree::ApiTyped
+
       # Domains this provider cannot handle, so a merchant is warned when
       # pairing it with a market instead of silently under-collecting. Declared
       # on the class because core reads it while presenting the choice, before
@@ -47,8 +51,8 @@ module Spree
         unsupported_capabilities.map do |capability|
           {
             key: capability.to_s,
-            label: Spree.t("tax_capabilities.#{capability}.label", default: capability.to_s.humanize),
-            description: Spree.t("tax_capabilities.#{capability}.description", default: nil)
+            label: I18n.t("spree.tax_capabilities.#{capability}.label", default: capability.to_s.humanize),
+            description: I18n.t("spree.tax_capabilities.#{capability}.description", default: nil)
           }.compact
         end
       end
@@ -61,7 +65,7 @@ module Spree
       # @return [Hash]
       def self.to_api_hash(store)
         {
-          id: name,
+          id: api_type,
           name: display_name,
           available: available_for_store?(store),
           unsupported_capabilities: unsupported_capability_details,
@@ -128,19 +132,72 @@ module Spree
         nil
       end
 
+      # Works out the tax given back on lines of a return, claim or exchange,
+      # and writes it as credit TaxLine rows on them. The customer is refunded
+      # exactly what these rows hold, so this — not +refund+ — decides the
+      # figure.
+      #
+      # Each item credits its +credited_quantity+, and zero means no rows.
+      # Replace-all per item, as +estimate+: the rows are rewritten when the
+      # warehouse counts what arrived and again when the money goes back.
+      #
+      # A provider may quote the credit, for example at the original
+      # +tax_date+, or give back the recorded share of what the sale charged —
+      # {Spree::TaxProvider::RecordedShare}, which Internal uses. Either way
+      # it answers in the same rows.
+      #
+      # @param order [Spree::Order] a placed order
+      # @param items [Array<Spree::ReturnLineItem, Spree::ClaimLineItem, Spree::ExchangeLineItem>]
+      # @param amounts [Hash{Object => BigDecimal}, nil] the money refunded per
+      #   item when it is less than the item's worth — a restocking fee, a
+      #   part refund. Tax is then credited in the same proportion. Nil
+      #   credits every item's full worth.
+      # @param tax_date [Time, nil] the date whose rates apply; nil = order.completed_at
+      # @return [void]
+      # @raise [Spree::Tax::ProviderError] when the credit could not be worked out
+      def estimate_refund(order, items, amounts: nil, tax_date: nil)
+        raise NotImplementedError, "Please implement 'estimate_refund' in your tax provider: #{self.class.name}"
+      end
+
+      # Taxes the replacement an exchange sends out, as a new sale, and writes
+      # it as charge TaxLine rows on the exchange lines. Never touches the
+      # order's own rows, which stay as the sale was placed. Replace-all per
+      # item; each item is taxed on its +taxable_basis+ under its
+      # +tax_category_id+, and one whose +credited_quantity+ is zero ships
+      # nothing and ends with no rows.
+      #
+      # @param order [Spree::Order] a placed order
+      # @param items [Array<Spree::ExchangeLineItem>]
+      # @param tax_date [Time, nil] date whose rates apply; nil = now
+      # @param tax_identifier [Spree::TaxIdentifier, nil] the order's frozen registration
+      # @param exemptions [Array] exemption evidence to apply
+      # @return [void]
+      # @raise [Spree::Tax::ProviderError] when the tax could not be worked out
+      def estimate_replacement(order, items, tax_date: nil, tax_identifier: nil, exemptions: [])
+        raise NotImplementedError, "Please implement 'estimate_replacement' in your tax provider: #{self.class.name}"
+      end
+
+      # Files an exchange's replacement as a sale. Called once the exchange is
+      # fulfilled; must be idempotent, keyed on the exchange. No-op for a
+      # provider without a remote ledger.
+      #
+      # @param order [Spree::Order]
+      # @param items [Array<Spree::ExchangeLineItem>]
+      # @return [void]
+      def commit_replacement(order, items); end
+
       # Reports a partial credit against the committed document, keyed to the
-      # original transaction rather than voiding and re-committing it.
+      # original transaction rather than voiding and re-committing it. Called
+      # after the money has moved.
       #
-      # +amount+ is what the customer was actually refunded, which is not always
-      # the returned lines' worth: an admin may keep a restocking fee or refund
-      # a goodwill figure of their own. A provider must credit no more tax than
-      # that refund carries — crediting every returned line when only part of
-      # their value went back would reclaim tax the merchant never repaid, and a
-      # return is marked refunded once, so nothing later corrects it. Where the
-      # amount is short, allocate proportionally.
+      # By then each item's credit rows hold what went back (see
+      # +estimate_refund+), and a provider must credit no more than they do:
+      # the customer was repaid that tax and no more. +amount+ is the money
+      # refunded, which may be less than the items are worth when an admin kept
+      # a restocking fee or refunded a goodwill figure of their own.
       #
       # @param order [Spree::Order]
-      # @param return_items [Array<Spree::ReturnLineItem>] the returned lines
+      # @param return_items [Array<Spree::ReturnLineItem, Spree::ClaimLineItem, Spree::ExchangeLineItem>]
       # @param amount [BigDecimal, nil] the refund issued; nil = the lines' full worth
       # @param tax_date [Time, nil] the original supply date; nil = order.completed_at
       # @return [void]