spree_core 5.6.1 → 6.0.0.beta2

data/app/models/spree/seller.rb

@@ -0,0 +1,475 @@
+# frozen_string_literal: true
+
+module Spree
+  # A selling party on a marketplace: the store is the tenant, the seller is a
+  # seller within it (docs/plans/6.0-multi-vendor-marketplace.md).
+  #
+  # A seller owns roles, so its team is the people holding them — the same
+  # machinery the store's own back office uses, pointed at the seller.
+  class Seller < Spree.base_class
+    has_prefix_id :sel
+
+    acts_as_paranoid
+
+    include Spree::SingleStoreResource
+    include Spree::UserManagement
+    include Spree::TranslatableResource
+    include Spree::HasCustomFields
+    include Spree::Metadata
+    include Spree::MemoizedData
+    include Spree::SanitizableRichText
+    # The seller's account with whichever provider pays them — see
+    # #payout_account_reference.
+    include Spree::HasExternalReferences
+
+    MEMOIZED_METHODS = %w[onboarding_requirements onboarding_progress products_count returns_location].freeze
+
+    publishes_lifecycle_events
+
+    # Where a seller is in its life on the marketplace. Transitions belong to
+    # workflows (Spree::Sellers::Approve and friends) rather than a state
+    # machine: approving sends mail and provisions payouts, which is exactly
+    # the work that must not run inside a save callback.
+    #
+    #   pending → invited → onboarding → ready_for_review → approved
+    #
+    # `approve` also lifts a suspension, and a rejected seller can be revived,
+    # so the reachable set is deliberately wider than that line suggests.
+    include Spree::HasStatus
+    has_status :pending, :invited, :canceled, :onboarding, :ready_for_review,
+               :approved, :rejected, :suspended, default: :pending
+
+    # Who remits consumer tax on this seller's sales. `seller` means they are
+    # merchant of record; `platform` is the marketplace-facilitator case, and
+    # only Enterprise decides a seller belongs there — core just reads it.
+    TAX_REMITTANCES = %w[seller platform].freeze
+    PAYOUT_INTERVALS = %w[daily weekly biweekly monthly manual].freeze
+
+    TRANSLATABLE_FIELDS = %i[name about].freeze
+    RICH_TEXT_TRANSLATABLE_FIELDS = %i[about].freeze
+    translates(*TRANSLATABLE_FIELDS, column_fallback: Spree.mobility_column_fallback)
+
+    self::Translation.class_eval do
+      include Spree::SanitizableRichText
+      sanitizes_rich_text :about
+
+      acts_as_paranoid
+      # A deleted seller's translations still have to render — its storefront
+      # profile outlives the row for as long as anything links to it.
+      default_scope { unscope(where: :deleted_at) }
+    end
+
+    #
+    # Associations
+    #
+    belongs_to :store, class_name: 'Spree::Store'
+    # The address knows it is a seller's from its owner, so it is read back
+    # with the business rules — no personal name insisted on, the company line
+    # required. Not `dependent: :destroy`: a seller is paranoid, so destroy is
+    # a soft delete, and taking the address with it would hard-delete a row
+    # historical commission invoices still point at.
+    belongs_to :billing_address, class_name: 'Spree::Address', optional: true
+
+    # `update_only` edits the existing row rather than building a replacement
+    # and orphaning it; the association carries the saving and validation that
+    # go with it.
+    accepts_nested_attributes_for :billing_address, update_only: true
+
+    # The API reads and writes this under one name, so the writer takes the
+    # attributes a client sends as well as a record. Never an id: an address
+    # carries no store of its own, so binding one by id would reach another
+    # store's rows.
+    def billing_address=(value)
+      case value
+      when Hash, ActionController::Parameters
+        self.billing_address_attributes = value
+      when Spree::Address
+        super(value.tap { |address| address.owner = self })
+      else
+        super
+      end
+    end
+
+    # The seller holds the foreign key, so nothing on the address side says
+    # whose it is — an association cannot declare that for us. This is the one
+    # path Rails builds the row on, so it is where the row is told, and what
+    # it asks for follows: no personal name, the company line required.
+    def billing_address_attributes=(attributes)
+      super
+      billing_address&.owner = self
+    end
+
+    # Where this seller keeps stock, and so where their returns land. Released
+    # rather than destroyed for the same reason products are: the operator
+    # decides what becomes of a departed seller's inventory.
+    has_many :stock_locations, class_name: 'Spree::StockLocation', dependent: :nullify,
+                               inverse_of: :seller
+
+    # How this seller ships: their own methods, priced and retired by them,
+    # against the marketplace's profiles and zones
+    # (docs/plans/6.0-multi-vendor-marketplace.md, Decision 13).
+    #
+    # Deliberately NOT `dependent: :nullify`, unlike stock locations: a nil
+    # `seller_id` IS the marketplace's own method, so releasing a departed
+    # seller's rows would hand the operator their pricing and start quoting it
+    # on first-party packages. The seller is paranoid, so the rows keep
+    # pointing at a record that still resolves; retiring them is the
+    # operator's call.
+    has_many :delivery_methods, class_name: 'Spree::DeliveryMethod', dependent: nil,
+                                inverse_of: :seller
+
+    # What this seller packs their goods into: their own boxes, cartons and
+    # pallets, beside the marketplace's shared vocabulary they may also use
+    # (docs/plans/6.0-seller-package-types.md).
+    #
+    # `dependent: nil` for the same reason as delivery methods above: a nil
+    # `seller_id` IS the marketplace's row, so nullifying a departed seller's
+    # rows would give the operator a second default box and start quoting this
+    # seller's tare on first-party parcels.
+    has_many :package_types, class_name: 'Spree::PackageType', dependent: nil,
+                             inverse_of: :seller
+
+    # The box this seller's parcels are quoted with. Nil until they record
+    # one, and `Stock::Package` then falls back to the marketplace's.
+    has_one :default_package_type, -> { where(default: true) }, class_name: 'Spree::PackageType',
+            dependent: nil, inverse_of: :seller
+
+    # The seller's tax registrations — the VAT number the commission invoice
+    # needs, with the validation verdict and evidence the model carries.
+    #
+    # Deliberately not `dependent: :destroy`, for the same reason as the
+    # billing address above: a seller is paranoid, so destroy is a soft
+    # delete, while a TaxIdentifier is not — cascading would permanently
+    # erase the evidence behind commission invoices already issued, which is
+    # exactly what it exists to preserve.
+    has_many :tax_identifiers, class_name: 'Spree::TaxIdentifier', as: :owner,
+                               dependent: nil, inverse_of: :owner
+
+    # Products and stock survive the seller leaving: the operator decides what
+    # happens to a departed seller's catalog, so it is never cascade-deleted.
+    # Both levels are released — a variant can carry the seller on its own
+    # (the shared catalog), and one left pointing at a departed seller would
+    # read as first-party to the buy box while its id still said otherwise.
+    has_many :products, class_name: 'Spree::Product', dependent: :nullify
+    has_many :variants, class_name: 'Spree::Variant', dependent: :nullify
+
+    # What this seller has been charged. Deliberately neither destroyed nor
+    # nullified when the seller goes: a seller is paranoid, so it is still
+    # there to be read, and a settlement record that forgot who owed it would
+    # be worse than no record at all.
+    has_many :commission_lines, class_name: 'Spree::CommissionLine', dependent: nil
+
+    # This seller's own orders — the child orders a split checkout produced,
+    # and whole orders on a single-seller checkout. Left alone when the seller
+    # goes, for the same reason as commission lines: a completed sale outlives
+    # the party that made it.
+    has_many :orders, class_name: 'Spree::Order', dependent: nil
+    has_many :payment_splits, through: :orders, class_name: 'Spree::PaymentSplit', source: :payment_splits
+
+    # The two levels of the fund ledger: what this seller has earned, and what
+    # has been settled to them. Left alone when the seller goes, for the same
+    # reason as their orders and commission — money that moved is a fact about
+    # the past.
+    has_many :seller_transfers, class_name: 'Spree::SellerTransfer', dependent: nil
+    has_many :seller_payouts, class_name: 'Spree::SellerPayout', dependent: nil
+    # CSV files this seller asked for. Destroyed with the seller: an export is
+    # a copy of records held elsewhere, so nothing is lost by dropping it, and
+    # a file of one seller's orders should not outlive them.
+    has_many :exports, class_name: 'Spree::Export', dependent: :destroy_async, inverse_of: :seller
+
+    # What this seller has done about the marketplace's requirements — their
+    # attestations, the documents they uploaded, what the operator made of
+    # them. Goes with the seller, since it means nothing without them.
+    has_many :requirement_submissions, class_name: 'Spree::SellerRequirementSubmission',
+                                       dependent: :destroy, inverse_of: :seller
+
+    # This seller's own legal documents — shipping, returns, whatever the
+    # marketplace asks of them. Unlike a store, a seller is born with none:
+    # what they must publish is a `SellerRequirements::Policy` decision, not
+    # a set of empty rows every seller carries whether or not it applies.
+    has_many :policies, class_name: 'Spree::Policy', dependent: :destroy, as: :owner
+
+    #
+    # Attachments
+    #
+    has_one_attached :logo, service: Spree.public_storage_service_name
+    has_one_attached :square_logo, service: Spree.public_storage_service_name
+    has_one_attached :cover_photo, service: Spree.public_storage_service_name
+
+    #
+    # Validations
+    #
+    validates :name, presence: true
+    # Scoped to the store, not global: two marketplaces on one installation
+    # may each have a "sparks". Backed by the unique index on the pair.
+    validates :slug, presence: true,
+                     uniqueness: { scope: [*spree_base_uniqueness_scope, :store_id], case_sensitive: false }
+    validates :tax_remittance, inclusion: { in: TAX_REMITTANCES }
+    validates :payouts_schedule_interval, inclusion: { in: PAYOUT_INTERVALS }, allow_nil: true
+    validates :minimum_payout_amount, numericality: { greater_than_or_equal_to: 0 }, allow_nil: true
+
+    has_spree_rich_text :about
+
+    #
+    # Scopes
+    #
+    scope :sellable, -> { approved.where(holiday_mode_until: [nil, ..Time.current]) }
+
+    #
+    # Callbacks
+    #
+    before_validation :normalize_slug
+    # Roles refuse to be destroyed while anyone still holds them, which is
+    # right when a role is deleted on its own and wrong when the whole seller
+    # goes: its roles govern nothing else. Dissolving the team first lets the
+    # cascade through, so an invited seller stays deletable.
+    before_destroy :dissolve_team, prepend: true
+
+    # Which audience of the permission catalog this seller's own super-role is
+    # born holding. A seller's role cannot take the store super-role's
+    # short-circuit (`Role#admin?` requires `staff?`), so without these keys
+    # whoever runs the seller would hold nothing and every endpoint on their
+    # own panel would refuse them.
+    #
+    # @return [Symbol]
+    def role_audience
+      :seller
+    end
+
+    # Whether the seller is currently away. The catalog stays visible; what
+    # stops is selling.
+    #
+    # @return [Boolean]
+    def on_holiday?
+      holiday_mode_until.present? && holiday_mode_until > Time.current
+    end
+
+    # Whether customers may buy from this seller right now.
+    #
+    # @return [Boolean]
+    def sellable?
+      approved? && !on_holiday?
+    end
+
+    # @return [Boolean]
+    def terms_accepted?
+      terms_accepted_at.present?
+    end
+
+    # What the marketplace still owes this seller in one currency.
+    #
+    # Derived rather than stored: it is the whole point of keeping both ledger
+    # levels, and a column would be a second answer that could disagree with
+    # the rows. Per currency because nothing is ever converted — a seller
+    # trading in two currencies accrues two balances and is paid twice.
+    #
+    # Only settlements known to have completed count against it, so one whose
+    # outcome was never established still reads as owed. That is the honest
+    # answer while nobody knows, and it cannot be paid twice by mistake: those
+    # earnings stay claimed by the settlement holding them until it resolves.
+    #
+    # Answered in the currency the money can actually be sent in: a seller whose
+    # account settles in another currency is owed what their account holds, not
+    # what the sale was priced in.
+    #
+    # @param currency [String] a settlement currency
+    # @return [BigDecimal]
+    def balance(currency)
+      earnings = seller_transfers.completed.settling_in(currency)
+
+      earnings.settlement_total -
+        earnings.joins(:payout).merge(Spree::SellerPayout.completed).settlement_total
+    end
+
+    # The currencies this seller can actually be paid in — the ones their
+    # account settles in, which is not the same as the ones they sold in.
+    #
+    # @return [Array<String>]
+    def payable_currencies
+      seller_transfers.unsettled.settlement_currencies
+    end
+
+    # The seller's position in every currency they have earned or been paid
+    # in, for the ledger screens. Empty before their first fulfilled sale.
+    #
+    # Only rows that contribute a figure decide the list: a currency whose
+    # every transfer failed would otherwise show a row of zeros on a money
+    # screen, which reads as a balance rather than as nothing having happened.
+    #
+    # One position per (sale currency, settlement currency) pair, so a seller
+    # who sells in dollars and banks in pounds sees both sides of the one
+    # relationship rather than two unrelated ledgers.
+    #
+    # @return [Array<Spree::SellerBalance>]
+    def balances
+      pairs = seller_transfers.where.not(status: 'failed').
+              distinct.pluck(:currency, :settled_currency)
+
+      pairs.sort.map { |currency, settlement| Spree::SellerBalance.for(self, currency, settlement) }
+    end
+
+    # The seller's account with whichever provider pays them — a Stripe Connect
+    # `acct_…`, or whatever a SEPA or PayPal provider issues.
+    #
+    # Kept as an external reference rather than a column because that is
+    # exactly what it is: this seller's identity in somebody else's system.
+    # Keying it by the provider means a marketplace that migrates keeps the old
+    # account on the record instead of overwriting it, and the reverse lookup a
+    # webhook needs — "which seller is acct_123?" — is a uniquely indexed read
+    # rather than a scan.
+    #
+    # @param provider [Class] the payout provider whose account is wanted;
+    #   defaults to the one the store is configured to pay through
+    # @return [String, nil]
+    def payout_account_reference(provider = store.payout_provider_class)
+      external_id_for(provider.reference_system)
+    end
+
+    # Records the account a provider issued this seller.
+    #
+    # @param provider [Class] the provider that issued it — stated by the
+    #   caller rather than read from the store, since a gem writes the account
+    #   it minted whatever the store is currently configured to pay through
+    # @param account_reference [String, nil] blank forgets the account
+    # @return [void]
+    def set_payout_account_reference(provider, account_reference)
+      set_external_id(provider.reference_system, account_reference)
+    end
+
+    # A seller keeps no clock of their own: a date means whatever the
+    # marketplace says it means, so their panel reads timestamps in the
+    # store's zone rather than in whichever one their browser sits in.
+    delegate :preferred_timezone, to: :store, allow_nil: true
+
+    # Sellers holding an account with one provider, for the reverse lookup a
+    # provider webhook does — it knows the account, not the seller.
+    #
+    # @param store [Spree::Store]
+    # @param provider [Class]
+    # @param account_reference [String]
+    # @return [ActiveRecord::Relation]
+    def self.with_payout_account(store, provider, account_reference)
+      store.sellers.with_external_id(provider.reference_system, account_reference)
+    end
+
+    # Whether a provider says this seller may be sent money yet.
+    #
+    # A marketplace settling offline never asks, so a seller with no account
+    # reference is payable by definition — it is only a provider that executes
+    # transfers which can refuse one.
+    #
+    # @return [Boolean]
+    def payouts_enabled?
+      return true unless store.payout_provider_class.requires_payout_account?
+
+      payouts_enabled_at.present?
+    end
+
+    # What this seller's settlement schedule is, falling back to the store's.
+    #
+    # @return [String]
+    def resolved_payouts_schedule_interval
+      payouts_schedule_interval.presence || store.preferred_default_payouts_schedule_interval
+    end
+
+    # The balance a settlement must reach before it is worth sending, falling
+    # back to the store's. Below it, the balance simply carries to next time.
+    #
+    # @return [BigDecimal]
+    def resolved_minimum_payout_amount
+      (minimum_payout_amount || store.preferred_default_minimum_payout_amount).to_d
+    end
+
+    # Where customers send returns — this seller's default stock location.
+    #
+    # A location rather than a loose address because a received return has to
+    # restock somewhere the catalog believes in: stock movements anchor to a
+    # location, so an address alone would leave the goods arriving nowhere.
+    #
+    # @return [Spree::StockLocation, nil]
+    # Where this seller's goods come back to. Prefers a location that accepts
+    # returns; falls back to any active one, since a seller with none marked
+    # still has to receive what customers send back.
+    def returns_location
+      @returns_location ||= stock_locations.active.returns_enabled.order_default.first ||
+                            stock_locations.active.order_default.first
+    end
+
+    # The postal address a shopper is given for returns.
+    #
+    # Nil until the location is postable: it builds an address from its own
+    # columns on demand, so an incomplete one would otherwise answer with a
+    # blank address that reads as configured.
+    #
+    # @return [Spree::Address, nil]
+    def returns_address
+      location = returns_location
+      return unless location&.postable?
+
+      location.address
+    end
+
+    # @return [Integer] how many products this seller lists
+    def products_count
+      @products_count ||= products.count
+    end
+
+    # Where this seller stands against the marketplace's checklist
+    # (docs/plans/6.0-seller-onboarding-requirements.md), for the operator's
+    # views of them. Computed on read, never stored: a column would be wrong
+    # the moment a product was deleted or a document sent back.
+    #
+    # Reads the store's checklist off its loaded association when the store
+    # was eager-loaded with it (the admin list and profile do), so a page of
+    # sellers loads the rows once; a seller reached any other way queries.
+    #
+    # @return [Array<Spree::SellerRequirementStatus>]
+    def onboarding_requirements
+      @onboarding_requirements ||= Spree::Sellers::Requirements.new(
+        self,
+        preloaded: store&.association(:seller_requirements)&.loaded? || false,
+        cached: onboarding_requirements_cached
+      ).statuses
+    end
+
+    # Whether this seller's checklist may answer from what Spree already knows
+    # rather than asking a payment provider. Set by a caller rendering many
+    # sellers at once, where one network call per row is the difference
+    # between a list that loads and one that does not.
+    #
+    # Deliberately not inferred from the checklist being eager-loaded: a
+    # single-seller read shares that preload, and there the operator is
+    # looking at exactly this seller and wants the current answer.
+    attr_writer :onboarding_requirements_cached
+
+    def onboarding_requirements_cached
+      @onboarding_requirements_cached || false
+    end
+
+    # @return [Hash{Symbol => Integer}] done and total over the whole
+    #   checklist, optional requirements included
+    def onboarding_progress
+      @onboarding_progress ||= Spree::Sellers::Requirements.progress_of(onboarding_requirements)
+    end
+
+    # @return [Boolean] whether nothing required is outstanding
+    def onboarding_complete?
+      onboarding_requirements.none?(&:blocking?)
+    end
+
+    private
+
+
+    def normalize_slug
+      self.slug = (slug.presence || name).to_s.parameterize.presence
+    end
+
+    # Memberships and outstanding invitations are what make a role undeletable.
+    # They mean nothing once the seller is gone, so they go first.
+    def dissolve_team
+      Spree::RoleUser.where(role_id: roles.ids).delete_all
+      invitations.destroy_all
+      roles.each { |role| role.update_columns(mutable: true) unless role.mutable? }
+    end
+  end
+end

data/app/models/spree/seller_balance.rb

@@ -0,0 +1,86 @@
+module Spree
+  # One seller's position in one currency, read off the fund ledger.
+  #
+  # Never persisted: every figure is a sum over {Spree::SellerTransfer} and
+  # {Spree::SellerPayout} rows, so the ledger stays the only record and this
+  # only presents it. One per currency — a marketplace paying a seller in two
+  # currencies has two ledgers, and adding them would answer a question nobody
+  # asked.
+  #
+  # A position has two sides when the seller's account settles in a currency
+  # other than the one they sold in: what the sale was worth, and what their
+  # account received once the provider converted it. Both are recorded figures.
+  # They are never added together, and Spree converts nothing itself.
+  class SellerBalance
+    include ActiveModel::Model
+    include ActiveModel::Attributes
+
+    attribute :seller
+    # What the sales were priced in.
+    attribute :currency, :string
+    # What the seller's account holds, and is paid in. The same as `currency`
+    # unless the provider converted on the way in.
+    attribute :settlement_currency, :string
+    # What the seller has earned: completed transfers, reversals included.
+    attribute :earned, :decimal, default: 0
+    # Earnings still with the provider — a transfer not yet confirmed, or one
+    # whose outcome is unknown. Shown so a shipped order does not read as
+    # unpaid while the money is in flight.
+    attribute :pending, :decimal, default: 0
+    # The same completed earnings, as their account received them.
+    attribute :payable, :decimal, default: 0
+    # How much of that has reached them, through settlements that completed.
+    attribute :paid, :decimal, default: 0
+
+    extend Spree::DisplayMoney
+    money_methods :earned, :pending
+
+    # @param seller [Spree::Seller]
+    # @param currency [String] what the sales were priced in
+    # @param settlement_currency [String] what the account settles in
+    # @return [Spree::SellerBalance]
+    def self.for(seller, currency, settlement_currency = currency)
+      transfers = seller.seller_transfers.where(currency: currency).settling_in(settlement_currency)
+
+      new(
+        seller: seller,
+        currency: currency,
+        settlement_currency: settlement_currency,
+        earned: transfers.completed.sum(:amount),
+        pending: transfers.with_status('pending', 'processing', 'unresolved').sum(:amount),
+        payable: transfers.completed.settlement_total,
+        # Read through the transfers a settlement claimed rather than off the
+        # settlement's own total: two sale currencies can settle into one, and
+        # the payout's figure would then count against both of them.
+        paid: transfers.completed.joins(:payout).
+              merge(Spree::SellerPayout.completed).settlement_total
+      )
+    end
+
+    # What the marketplace still owes, in the currency it can actually be sent
+    # in.
+    #
+    # A payout settles every position sharing that currency, so a seller who
+    # sells in two currencies that settle into one is paid the sum of both
+    # rather than either. The figures reconcile — both sides read the same
+    # transfer rows — but one position is not one deposit.
+    #
+    # @return [BigDecimal]
+    def balance
+      payable - paid
+    end
+
+    # @return [Boolean] whether the provider converted this seller's earnings
+    def converted?
+      settlement_currency != currency
+    end
+
+    # Formatted in the settlement currency rather than the sale's, since these
+    # are what the account holds.
+    %i[payable paid balance].each do |figure|
+      define_method(:"display_#{figure}") do
+        Spree::Money.new(public_send(figure), currency: settlement_currency)
+      end
+    end
+  end
+end

data/app/models/spree/seller_payout.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Spree
+  # One settlement to one seller: the earnings they had accrued, batched and
+  # sent on their own schedule.
+  #
+  # The second of the ledger's two levels. Transfers credit a seller as each
+  # order ships; a payout is the money actually leaving — daily, weekly,
+  # monthly, or whenever an operator says so. It names exactly which transfers
+  # it settled, so a seller asking "what is this deposit for" has an answer,
+  # and so a reversal arriving after a payout closed lands in the next period
+  # rather than rewriting a settlement that already happened.
+  #
+  # Core records both levels for every marketplace. Whether money actually
+  # moves is the {Spree::PayoutProvider}'s business: the built-in one records
+  # and leaves the operator to pay by bank, while a provider like Stripe
+  # Connect performs the transfer itself.
+  class SellerPayout < Spree.base_class
+    has_prefix_id :vpo
+
+    include Spree::Metadata
+    # Denormalized from the seller, which never changes store — so the copy
+    # cannot drift, and tenancy is structural rather than a subquery every
+    # consumer must remember. Always set explicitly from the seller: ledger
+    # rows are written by jobs and subscribers, where the request-scoped
+    # default store is absent or wrong.
+    include Spree::SingleStoreResource
+
+    #
+    # Associations
+    #
+    belongs_to :seller, class_name: 'Spree::Seller'
+    # What this payout settles. Deliberately nullify rather than destroy: a
+    # transfer is the record of an earning and outlives the settlement that
+    # paid it, so a deleted payout releases its transfers back to the next
+    # sweep instead of erasing what the seller earned.
+    has_many :transfers, class_name: 'Spree::SellerTransfer', foreign_key: :payout_id,
+                         inverse_of: :payout, dependent: :nullify
+
+    #
+    # Validations
+    #
+    validates :amount, numericality: true
+    validates :currency, presence: true
+    validates :provider, presence: true
+
+    #
+    # Statuses. As with transfers, movement is through workflows rather than a
+    # transition graph.
+    #
+    include Spree::HasStatus
+    has_status :pending, :processing, :completed, :failed, :unresolved, default: :pending
+
+    #
+    # Scopes
+    #
+    # Money promised but not yet gone — what an operator's queue is for.
+    scope :owed, -> { where(status: %w[pending processing]) }
+
+    self.whitelisted_ransackable_attributes = %w[amount currency status provider reference period_start period_end created_at seller_id]
+    self.whitelisted_ransackable_associations = %w[seller transfers]
+
+    extend Spree::DisplayMoney
+    money_methods :amount
+
+    # @return [BigDecimal] what the transfers this payout holds actually come
+    #   to, for checking a stored amount against its parts
+    # Summed on what the seller's account actually received, since that is
+    # what this payout moves.
+    def transfers_total
+      transfers.settlement_total
+    end
+
+    # Gives up on this settlement and puts its earnings back.
+    #
+    # Releasing them is what makes a failure recoverable, and it is the one
+    # thing a caller must not forget: a sweep only ever collects unstamped
+    # rows, so earnings left stamped to a failed payout are invisible to every
+    # later sweep while the balance still reports the seller as owed them.
+    # Released, they simply fall into the next one.
+    #
+    # Lives here rather than in the flows that call it — core's sweep and any
+    # provider's failure webhook — because the association and the status both
+    # belong to the payout, and a provider gem should not have to know the
+    # invariant to honour it.
+    def fail!
+      transaction do
+        release_transfers
+        # The amount stays: an operator investigating a failed settlement has
+        # to see what was attempted, and the `owed` scope already excludes it
+        # from what is still to be sent.
+        update!(status: 'failed')
+      end
+    end
+
+    # Records that nobody knows whether this settlement happened, and
+    # deliberately keeps its earnings claimed.
+    #
+    # The opposite of {#fail!} in the one way that matters. Releasing here
+    # would let the next sweep assemble the same earnings into a second
+    # payout, and a provider's idempotency key only protects a retry for as
+    # long as the provider keeps the record — Stripe prunes after a day, so a
+    # monthly sweep is well past it. Held instead, the earnings stay out of
+    # every later sweep until a person or a webhook settles what actually
+    # happened.
+    def unresolve!
+      update!(status: 'unresolved')
+    end
+
+    # Hands the earnings back to the next sweep without recording a failure —
+    # for a settlement that never had anything to send.
+    def release_transfers
+      transfers.update_all(payout_id: nil, updated_at: Time.current)
+    end
+  end
+end