solidus_advanced_pricing 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1750fd578f0dd63061c1ad728e7418e11bd128ee4bd18d602b58bdc43d6d84c1
-  data.tar.gz: e56ded8723862a6ac3513dd4ac9df9a5f074a7a5dfcc41664d595a440c67cbf4
+  metadata.gz: 0feded43570200af31d61d2822614677e232d696b480196576c0651edafee278
+  data.tar.gz: 20b1184e197fc387a095d5af68b7936fc894ccd213b6386a259bff8f0e77e6e5
 SHA512:
-  metadata.gz: 158337d85d20a1d2099954234f17a1adf6c3e5eef14369a60379bb690edfd9fd42874dd442a17980a89427f1d2d3cfff14f460350ed173cd3bde65a582954ee3
-  data.tar.gz: ca2d434c231a0e0ea9d9e9bc88730d39b66455a9296cce9809935337ff7d0b5fd7e54eb35471aed2456e3799a1ec4241a4f4d99db2d6fb7f5660d975061bd09d
+  metadata.gz: c2a90ff27650243c41246a0dfa7b9cd1b6a672c73060dcf6abcaf007f101baefdf3d627c28301ac06e576b1a7bb1a4f9602135935a6cbe2327ea62918fa20d20
+  data.tar.gz: 5b57c0ee2ef362b15e377db52ebd80c1624db43c3c94d69846e8e93bfacb7ce17864766f35cb9ee56c8113a424b3afb5a6d550be20b18872eefa6f8bd04ef595

data/.gitignore

@@ -19,3 +19,4 @@ spec/examples.txt
 .rvmrc
 .ruby-version
 .ruby-gemset
+docs/superpowers

data/CHANGELOG.md

@@ -4,6 +4,55 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-09-23
+
+### Added
+
+- **Write endpoints for prices.** `POST`, `PATCH` and `DELETE` on
+  `/api/variants/:variant_id/prices`, so prices can be administered over the API rather
+  than only read. `DELETE` soft-deletes.
+- **`price_type_code` is accepted anywhere `price_type_id` is** on a price payload. Ids
+  are per-database and codes are not, so a payload written against staging works unchanged
+  against production. Sending both is a `422`; an explicit null means the untyped base
+  price.
+- **`GET /api/price_types`**, listing the types a price payload may reference with their
+  ids, codes, names, positions and default roles. Read-only and admin-authorized.
+- **Batch writes: `POST /api/prices/batch`** and the `SolidusAdvancedPricing::PriceBatch`
+  service behind it. Many prices across many variants in one call, matched on the natural
+  key (variant, currency, country, price type, role, `valid_from`) so re-sending a payload
+  is a no-op rather than a pile of duplicates. Always answers `200` with a per-row report.
+  - `dry_run: true` runs the real work in a transaction and rolls it back, so the report
+    reflects what the write would do rather than a guess at it.
+  - A row carrying `id` names that price outright: `variant_id`/`sku` become optional and
+    are checked rather than applied, natural-key fields such as `currency`, `role_id` and
+    `valid_from` become editable, and an unknown or deleted `id` is a row error rather than
+    a new price.
+  - `mode: "replace"` also discards prices the payload left out — scoped to price types and
+    variants the payload actually named.
+  - Rows are applied independently in savepoints, so one bad row does not take the batch
+    down and a row-wise retry is possible.
+  - `SolidusAdvancedPricing.config.batch_row_limit` (default 500) and
+    `config.batch_guard`, a callable invoked with every row written and nothing committed,
+    which may raise to abort. The seam for store policy that does not belong in the gem.
+- `currency` now defaults to `Spree::Config.default_pricing_options.currency` when a
+  created price omits it.
+
+### Fixed
+
+- **`GET /api/variants/:variant_id/prices` listed soft-deleted prices.**
+  `Spree::Variant#prices` is declared `-> { with_discarded }` in core, which the endpoint
+  inherited, so anything an admin had deleted still came back. Deleted prices are now
+  excluded by default; `?show_deleted=true` opts back in.
+
+### Changed
+
+- **`price_type` is now immutable on a persisted price**, raising a validation error
+  instead of silently retyping the row. The admin form has disabled that select since
+  0.2.0; this closes the same gap at the model layer so the API cannot route around it.
+  Re-sending an unchanged `price_type_id` is still fine. Code that deliberately retypes an
+  existing price must now discard it and create a replacement, or use `update_columns` to
+  bypass validation in a data migration.
+
 ## [0.2.0] - 2026-09-23
 
 ### Added
@@ -64,5 +113,6 @@ Initial release.
   bucket. Without the role component a role-targeted price would be cached and served to
   guests.
 
+[0.3.0]: https://github.com/fcpeuro/solidus_advanced_pricing/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/fcpeuro/solidus_advanced_pricing/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/fcpeuro/solidus_advanced_pricing/releases/tag/v0.1.0

data/README.md

@@ -302,15 +302,20 @@ against pre-1.0 `solidus_admin` internals (`SolidusAdmin::UI::Pages::Index::Comp
 ## API
 
 ```
-GET /api/variants/:variant_id/prices
-GET /api/variants/:variant_id/prices/:id
+GET    /api/variants/:variant_id/prices
+GET    /api/variants/:variant_id/prices/:id
+POST   /api/variants/:variant_id/prices
+PATCH  /api/variants/:variant_id/prices/:id
+DELETE /api/variants/:variant_id/prices/:id
+
+GET    /api/price_types
 ```
 
 Each price is serialized with its advanced attributes — `price_type_code`,
 `price_type_name`, `role_id`, `valid_from`, `valid_to` — and `admin_notes` is included
 only for a caller who can update that price.
 
-**This endpoint is admin-facing.** Core's `DefaultCustomer` permission set (what every
+**These endpoints are admin-facing.** Core's `DefaultCustomer` permission set (what every
 non-admin API token gets) grants no rights on `Spree::Price` at all, so a non-admin
 token receives `401 Unauthorized` on the whole endpoint, not a filtered response.
 Headless storefronts do not need this endpoint for normal pricing: core's variants
@@ -318,6 +323,179 @@ endpoint already serializes `price` and `display_price` through this gem's selec
 automatically, because the selector is registered globally via
 `Spree::Config.variant_price_selector_class`.
 
+### Writing prices
+
+```shell
+curl -X POST https://store.example/api/variants/42/prices \
+  -H "Authorization: Bearer $SPREE_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"price": {"amount": "35.00", "price_type_code": "sale",
+                 "valid_from": "2026-11-27T00:00:00Z",
+                 "valid_to": "2026-12-02T00:00:00Z"}}'
+```
+
+- **`price_type_code` is accepted anywhere `price_type_id` is**, and is the better choice
+  for anything scripted: ids differ between your staging and production databases, codes
+  do not. Sending both is a `422`. Sending `price_type_code: null` (or `""`) means the
+  untyped base price, the same as omitting `price_type_id`.
+- **`currency` defaults to `Spree::Config.default_pricing_options.currency`** when the
+  payload omits it.
+- **`price_type` cannot be changed once a price exists.** The admin form has disabled that
+  select on persisted prices since 0.2.0, and the model now enforces it, so the API can't
+  route around it. Retyping a row reinterprets history instead of correcting it; to fix a
+  mistyped price, delete it and create the right one. Re-sending the *same*
+  `price_type_id` on an update is fine, so ordinary read-modify-write clients are
+  unaffected.
+- **`DELETE` soft-deletes** (sets `deleted_at`), so the row stays available to anything
+  reporting on what a variant used to cost. Deleted prices are excluded from the listing;
+  pass `?show_deleted=true` to include them. Writes never reach a deleted price — updating
+  one is a `404`.
+
+Remember that the selector takes the **cheapest** eligible price
+([how a price is chosen](#how-a-price-is-chosen)). A role-targeted price written *above*
+the untargeted price will never apply, and the API will not warn you about it.
+
+Nothing here stops you deleting a variant's only open-ended price, which leaves that
+variant unpriced outside its remaining windows (see
+[Backward compatibility](#backward-compatibility)). If that matters to your store, assert
+it on your side.
+
+### Batch writes
+
+```
+POST /api/prices/batch
+```
+
+One call, many prices, across many variants. Always answers `200` with a per-row report,
+never a partial `4xx` — a caller that sent 500 rows and got a bare `422` has no way to
+know which of them landed.
+
+```shell
+curl -X POST https://store.example/api/prices/batch \
+  -H "Authorization: Bearer $SPREE_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+        "mode": "upsert",
+        "dry_run": true,
+        "prices": [
+          {"sku": "ABC-123", "amount": "35.00", "price_type_code": "sale"},
+          {"sku": "DEF-456", "amount": "45.00", "price_type_code": "sale"},
+          {"id": 907, "amount": "29.99"}
+        ]
+      }'
+```
+
+```json
+{
+  "mode": "upsert",
+  "dry_run": true,
+  "summary": {"created": 1, "updated": 1},
+  "results": [
+    {"index": 0, "status": "created", "variant_id": 42},
+    {"index": 1, "status": "updated", "price_id": 907, "variant_id": 43}
+  ]
+}
+```
+
+Each row takes the same attributes as a single price, plus `id` and `sku`. Per-row
+`status` is `created`, `updated`, `unchanged`, `deleted` or `error`; an `error` row carries
+`errors` and nothing was written for it.
+
+**Send it as JSON.** Form encoding cannot represent an array of hashes whose rows have
+different keys — Rack starts a new hash only when it meets a key it has already seen, so
+`[{"id": 1, "amount": 2}, {"variant_id": 3, "amount": 4}]` arrives as
+`[{"id": 1, "amount": 2, "variant_id": 3}, {"amount": 4}]`. Set
+`Content-Type: application/json`.
+
+#### Naming a row: `id`, or the natural key
+
+**If a row carries `id`, that is the price it changes** — nothing is inferred, nothing can
+be mismatched, and `variant_id`/`sku` become optional (the price already knows its
+variant; supply one and it is checked, not applied). An `id` that does not exist, or that
+has been deleted, is an `error` on that row rather than a new price. This is the right
+shape for read-modify-write: fetch the prices, change what you need, send them back.
+
+**Without an `id`, the row is matched on the natural key** — variant, currency, country,
+price type, role and `valid_from`. Those are the dimensions a price legitimately varies
+on, so an upsert on them is unambiguous, and re-sending the same payload is a no-op rather
+than a pile of duplicates.
+
+That second path is not redundant with the first. A payload authored where Solidus ids are
+unknown — a supplier feed, a merchandiser's spreadsheet, a backfill from another system —
+has no ids to send, and `id`-or-create alone would make every re-run duplicate the whole
+file. The natural key is what makes a nightly feed idempotent.
+
+`valid_to` is deliberately *not* in the key: extending or shortening a window edits the
+price you already have. `valid_from` is matched to the second, because a client that read a
+price back and re-sent its `valid_from` may have dropped the sub-second part in
+serialization, and treating that as a different price would duplicate the row — and under
+`replace`, discard the original. Sending the `id` sidesteps that question entirely.
+
+Two rows in one payload naming the same price — by `id` or by key — are an `error` on the
+second, not a silent last-one-wins.
+
+Fields in the natural key (`currency`, `country_iso`, `role_id`, `valid_from`) can only be
+*changed* by a row that names the price by `id`; on a keyed row they are how the price was
+found. `price_type` cannot be changed either way — see
+[Writing prices](#writing-prices).
+
+#### Modes
+
+- **`upsert`** (default) creates or updates the rows you send and touches nothing else.
+- **`replace`** additionally discards prices the payload *left out* — but only of a price
+  type the payload named, on a variant the payload named. A `replace` that sends one sale
+  price will not reach that variant's base price or its wholesale tier, and will not reach
+  any other variant. Deleted rows appear in the report with `status: "deleted"`.
+
+#### `dry_run`
+
+`dry_run: true` does the real work against the database inside a transaction and rolls it
+back, so the report reflects what the write would actually do — validations, type casting
+and constraints included — rather than a guess at it. Ids are omitted from `created` rows
+on a dry run, since they are about to stop existing.
+
+**Use it.** The failure mode of a bulk price load is a silent one.
+
+#### Atomicity
+
+Rows are applied independently, each in its own savepoint: one bad row does not take the
+batch down, and the successful rows are committed. This is what makes a row-wise retry
+possible. If you need all-or-nothing, run the payload with `dry_run: true` first and only
+send it for real once the report is clean.
+
+#### Limits and store policy
+
+`Spree::Config` is not involved; the extension has its own configuration:
+
+```ruby
+SolidusAdvancedPricing.configure do |config|
+  config.batch_row_limit = 500 # default
+
+  # Called once every row is written and before the transaction commits.
+  # Raise to abort the whole batch.
+  config.batch_guard = ->(batch) do
+    raise TooMuchMovement if batch.summary.fetch(:updated, 0) > 200
+  end
+end
+```
+
+A batch over `batch_row_limit` is refused with a `422` before any row is looked at — a
+synchronous request has to stay inside the web timeout, and anything larger belongs in a
+background job.
+
+`batch_guard` is the seam for store policy — "refuse a batch that moves more than N% of
+prices by more than X%" — which does not belong in a general-purpose extension but does
+need somewhere to stand where it can see the finished picture and still stop it.
+
+### Reading price types
+
+`GET /api/price_types` lists the types a price payload may reference — `id`, `code`,
+`name`, `position` and the type's default `role_id` — in `position` order. Retired
+(discarded) types are omitted, since they are no longer a valid choice; historical prices
+still report their own type's code through the prices endpoints. The endpoint is
+read-only and admin-authorized: creating a pricing dimension is an admin act, not an API
+one.
+
 ## Storefront: compare-at (strikethrough) pricing
 
 `Spree::Variant#price_of_type` and `#base_price` fetch a specific typed price

data/app/decorators/models/solidus_advanced_pricing/spree/price_decorator.rb

@@ -23,6 +23,7 @@ module SolidusAdvancedPricing
           optional: true
 
         base.validate :valid_to_after_valid_from
+        base.validate :price_type_is_immutable
 
         # valid_to is exclusive so a window ending at midnight and the next one starting at midnight do not both match.
         base.scope :valid_at, ->(time) {
@@ -63,6 +64,17 @@ module SolidusAdvancedPricing
 
       private
 
+      # The admin form has disabled this select on persisted records since 0.2.0;
+      # the API would otherwise be a way around that. Retyping an existing row
+      # reinterprets history rather than correcting it -- the fix for a
+      # mistyped price is to discard it and create the right one.
+      def price_type_is_immutable
+        return if new_record?
+        return unless price_type_id_changed?
+
+        errors.add(:price_type_id, :cannot_be_changed)
+      end
+
       def valid_to_after_valid_from
         return if valid_from.blank? || valid_to.blank?
         return if valid_to > valid_from

data/app/models/solidus_advanced_pricing/price_batch.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+module SolidusAdvancedPricing
+  # Applies many price rows in one call, keyed on the dimensions a price
+  # legitimately varies on, so re-sending the same payload is a no-op rather
+  # than a pile of duplicates.
+  #
+  # Deliberately generic: it validates and writes prices and reports what it
+  # did. Store policy -- how large a swing is allowed, what gets reindexed,
+  # what gets published on an event bus -- belongs to the host app, which can
+  # hang it off `SolidusAdvancedPricing.config.batch_guard` or act on the
+  # returned results.
+  class PriceBatch
+    MODES = %w[upsert replace].freeze
+
+    # Two rows agreeing on all of these are the same price. `valid_to` is
+    # deliberately absent: extending or shortening a window is an edit to an
+    # existing price, not a different one.
+    NATURAL_KEY = %i[variant_id currency country_iso price_type_id role_id valid_from].freeze
+
+    # Everything a natural-key row may change. Anything in the key is, by
+    # definition, how the row was found, so changing it there is incoherent.
+    UPDATABLE = %i[amount valid_to admin_notes].freeze
+
+    # An `id` names the row outright, so nothing is off-limits except which
+    # variant it hangs off. `price_type_id` is listed but the model refuses to
+    # change it on a persisted price, which surfaces as an ordinary row error.
+    UPDATABLE_BY_ID = %i[amount currency country_iso price_type_id role_id valid_from valid_to admin_notes].freeze
+
+    class TooManyRows < StandardError; end
+
+    class InvalidMode < StandardError; end
+
+    Result = Struct.new(:index, :status, :price_id, :variant_id, :errors, keyword_init: true) do
+      def to_h
+        {index: index, status: status, price_id: price_id, variant_id: variant_id, errors: errors}.compact
+      end
+    end
+
+    attr_reader :results, :mode
+
+    def initialize(rows:, mode: "upsert", dry_run: false, row_limit: nil)
+      @rows = Array(rows)
+      @mode = mode.to_s
+      @dry_run = ActiveModel::Type::Boolean.new.cast(dry_run) || false
+      @row_limit = row_limit || SolidusAdvancedPricing.config.batch_row_limit
+      @results = []
+      @touched_ids = Hash.new { |hash, key| hash[key] = [] }
+
+      raise InvalidMode, "mode must be one of #{MODES.join(", ")}" unless MODES.include?(@mode)
+      raise TooManyRows, "batch is limited to #{@row_limit} rows, got #{@rows.size}" if @rows.size > @row_limit
+    end
+
+    def dry_run? = @dry_run
+
+    def replace? = @mode == "replace"
+
+    def call
+      # A dry run does the real work against the database and throws it away, so
+      # what it reports is what the write would actually do -- validations, type
+      # casting and constraints included -- rather than a guess at it.
+      ActiveRecord::Base.transaction do
+        seen = {}
+
+        @rows.each_with_index do |row, index|
+          apply_row(row.to_h.symbolize_keys, index, seen)
+        end
+
+        apply_replacements if replace?
+
+        # The host app's veto, with every row already written and nothing
+        # committed. Raising from here aborts the whole batch -- which is the
+        # only place a "this moves too many prices too far" rule can see the
+        # finished picture and still stop it.
+        SolidusAdvancedPricing.config.batch_guard&.call(self)
+
+        raise ActiveRecord::Rollback if dry_run?
+      end
+
+      self
+    end
+
+    def summary
+      results.group_by(&:status).transform_values(&:size)
+    end
+
+    private
+
+    # Resolution happens outside the savepoint -- it touches no state, and a
+    # `return` out of a transaction block is a trap worth not setting.
+    # Two ways to name a row, and `id` wins when it is there: it says exactly
+    # which price to change, with no key to assemble and no precision to lose.
+    #
+    # The natural key is what a payload authored somewhere that does not know
+    # Solidus ids -- a supplier feed, a merchandiser's spreadsheet, a backfill
+    # from another system -- has instead. It is also what makes such a payload
+    # re-runnable: without it, a nightly feed has no ids on its rows and would
+    # create a fresh duplicate of every price on every pass.
+    def apply_row(row, index, seen)
+      located = row[:id].present? ? locate_by_id(row) : locate_by_key(row)
+      return record(index, :error, errors: [located]) if located.is_a?(String)
+
+      price, variant_id, price_type_id, dedup, attributes = located
+
+      if seen.key?(dedup)
+        return record(index, :error, variant_id: variant_id,
+          errors: ["duplicate of row #{seen[dedup]}: #{duplicate_reason(dedup)}"])
+      end
+      seen[dedup] = index
+
+      persist(index, price, variant_id, price_type_id, attributes)
+    end
+
+    def duplicate_reason(dedup)
+      if dedup.first == :id
+        "same price id"
+      else
+        "same variant, currency, country, price type, role and valid_from"
+      end
+    end
+
+    def locate_by_id(row)
+      price = ::Spree::Price.kept.find_by(id: row[:id])
+      return "no price with id #{row[:id]}" if price.nil?
+
+      variant = resolve_variant(row) unless row[:variant_id].blank? && row[:sku].blank?
+      return "variant: #{variant}" if variant.is_a?(String)
+      if variant && variant.id != price.variant_id
+        return "price #{price.id} belongs to variant #{price.variant_id}, not #{variant.id}"
+      end
+
+      price_type_id = resolve_price_type_id(row)
+      return "price_type: #{price_type_id}" if price_type_id.is_a?(String)
+
+      attributes = row.slice(*UPDATABLE_BY_ID)
+      attributes[:price_type_id] = price_type_id if row.key?(:price_type_code)
+
+      [price, price.variant_id, price.price_type_id, [:id, price.id], attributes]
+    end
+
+    def locate_by_key(row)
+      variant = resolve_variant(row)
+      return "variant: #{variant}" if variant.is_a?(String)
+
+      price_type_id = resolve_price_type_id(row)
+      return "price_type: #{price_type_id}" if price_type_id.is_a?(String)
+
+      key = natural_key(row, variant, price_type_id)
+      price = find_existing(key) || ::Spree::Price.new(key)
+
+      [price, variant.id, price_type_id, [:key, key], row.slice(*UPDATABLE)]
+    end
+
+    # Each row gets its own savepoint: one bad row must not poison the batch,
+    # and on PostgreSQL a raised constraint error would otherwise abort every
+    # statement that follows it in the transaction.
+    def persist(index, price, variant_id, price_type_id, attributes)
+      ActiveRecord::Base.transaction(requires_new: true) do
+        existing = price.persisted?
+        price.assign_attributes(attributes)
+
+        if existing && !price.changed?
+          touch(variant_id, price_type_id, price.id)
+          record(index, :unchanged, price_id: price.id, variant_id: variant_id)
+        elsif price.save
+          touch(variant_id, price.price_type_id, price.id)
+          record(index, existing ? :updated : :created, price_id: reportable_id(price), variant_id: variant_id)
+        else
+          # Recorded before the rollback on purpose: @results is a Ruby array,
+          # so the savepoint unwinding the row does not unwind the report of it.
+          record(index, :error, variant_id: variant_id, errors: price.errors.full_messages)
+          raise ActiveRecord::Rollback
+        end
+      end
+    end
+
+    def touch(variant_id, price_type_id, price_id)
+      @touched_ids[[variant_id, price_type_id]] << price_id
+    end
+
+    # Only prices of a type the payload actually spoke about, on a variant the
+    # payload actually named, are in scope. A `replace` that named one sale
+    # price must not reach the variant's base price or its wholesale tier.
+    def apply_replacements
+      @touched_ids.each do |(variant_id, price_type_id), kept_ids|
+        stale = ::Spree::Price.kept.where(variant_id: variant_id, price_type_id: price_type_id).where.not(id: kept_ids)
+
+        stale.each do |price|
+          price.discard
+          @results << Result.new(index: nil, status: :deleted, price_id: price.id, variant_id: variant_id)
+        end
+      end
+    end
+
+    def resolve_variant(row)
+      if row[:variant_id].present? && row[:sku].present?
+        return "give variant_id or sku, not both"
+      end
+
+      if row[:variant_id].present?
+        ::Spree::Variant.find_by(id: row[:variant_id]) || "no variant with id #{row[:variant_id]}"
+      elsif row[:sku].present?
+        ::Spree::Variant.find_by(sku: row[:sku]) || "no variant with sku #{row[:sku].inspect}"
+      else
+        "variant_id or sku is required"
+      end
+    end
+
+    # Mirrors the single-price endpoint: a code is portable between databases
+    # where an id is not. Returns a String to signal failure, since nil is the
+    # legitimate value for the untyped base price.
+    def resolve_price_type_id(row)
+      has_code = row.key?(:price_type_code)
+      return "give price_type_id or price_type_code, not both" if has_code && row[:price_type_id].present?
+      return row[:price_type_id].presence && row[:price_type_id].to_i unless has_code
+
+      code = row[:price_type_code]
+      return nil if code.blank?
+
+      SolidusAdvancedPricing.resolve_price_type_id(code)
+    rescue ArgumentError
+      "no price type with code #{code.inspect}"
+    end
+
+    def natural_key(row, variant, price_type_id)
+      valid_from = ::Spree::Price.type_for_attribute(:valid_from).cast(row[:valid_from].presence)
+
+      {
+        variant_id: variant.id,
+        currency: row[:currency].presence || ::Spree::Config.default_pricing_options.currency,
+        country_iso: row[:country_iso].presence,
+        price_type_id: price_type_id,
+        role_id: row[:role_id].presence && row[:role_id].to_i,
+        # Truncated to the second so the key survives a round trip: a client that
+        # read a price back and re-sent its `valid_from` may have dropped the
+        # sub-second part, and treating that as a different price would duplicate
+        # the row -- and in `replace` mode, discard the original.
+        valid_from: valid_from&.change(usec: 0)
+      }
+    end
+
+    # Matching is a one-second window rather than an equality, so a price that
+    # was stored with sub-second precision by some other writer is still found
+    # by a truncated key.
+    def find_existing(key)
+      scope = ::Spree::Price.kept.where(key.except(:valid_from))
+      from = key[:valid_from]
+
+      return scope.find_by(valid_from: nil) if from.nil?
+
+      scope.where(valid_from: from...(from + 1.second)).first
+    end
+
+    # A dry run rolls back, so any id it allocated is about to stop existing.
+    # Reporting it would invite a client to use it.
+    def reportable_id(price)
+      dry_run? ? nil : price.id
+    end
+
+    def record(index, status, price_id: nil, variant_id: nil, errors: nil)
+      @results << Result.new(index: index, status: status, price_id: price_id, variant_id: variant_id, errors: errors)
+    end
+  end
+end

data/config/locales/en.yml

@@ -41,6 +41,10 @@ en:
               referenced_by_prices: "This price type is still used by one or more prices and cannot be deleted. Retire it instead."
         spree/price:
           attributes:
+            price_type_id:
+              cannot_be_changed: "cannot be changed once the price exists. Discard this price and create a new one with the right type."
+              ambiguous_price_type: "cannot be given as both price_type_id and price_type_code. Send one or the other."
+              unknown_code: "no price type with code %{code}"
             valid_to:
               must_be_after_valid_from: "must be after the valid from date"
         spree/role:

data/config/routes.rb

@@ -3,8 +3,15 @@
 Spree::Core::Engine.routes.draw do
   namespace :api, defaults: {format: "json"} do
     resources :variants, only: [] do
-      resources :prices, only: [:index, :show]
+      resources :prices, only: [:index, :show, :create, :update, :destroy]
     end
+
+    # Not nested under a variant: a batch spans variants, which is the point of it.
+    post "prices/batch", to: "price_batches#create", as: :price_batch
+
+    # Read-only: a client building a price payload needs the codes and ids, but
+    # creating a pricing dimension is an admin act, not an API one.
+    resources :price_types, only: [:index]
   end
 
   namespace :admin do

data/lib/controllers/api/spree/api/price_batches_controller.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    class PriceBatchesController < Spree::Api::BaseController
+      rescue_from SolidusAdvancedPricing::PriceBatch::TooManyRows, with: :batch_too_large
+      rescue_from SolidusAdvancedPricing::PriceBatch::InvalidMode, with: :bad_mode
+
+      # Always 200 with a per-row report, never a partial 4xx: a caller that
+      # sent 500 rows and got a bare 422 has no way to know which of them
+      # landed. The 4xx cases here are the ones where no row was even looked at.
+      def create
+        authorize! :create, Spree::Price
+
+        @batch = SolidusAdvancedPricing::PriceBatch.new(
+          rows: batch_rows,
+          mode: params.fetch(:mode, "upsert"),
+          dry_run: params[:dry_run]
+        ).call
+
+        render :create, status: :ok
+      end
+
+      private
+
+      def batch_rows
+        params.require(:prices).map do |row|
+          row.permit(
+            *Spree::PermittedAttributes.price_attributes,
+            :id,
+            :variant_id,
+            :sku,
+            :price_type_code
+          )
+        end
+      end
+
+      def batch_too_large(exception)
+        render json: {error: exception.message}, status: :unprocessable_entity
+      end
+
+      def bad_mode(exception)
+        render json: {error: exception.message}, status: :unprocessable_entity
+      end
+    end
+  end
+end

data/lib/controllers/api/spree/api/price_types_controller.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    class PriceTypesController < Spree::Api::BaseController
+      # Retired types are excluded: this endpoint exists so a client can build a
+      # valid price payload, and a discarded type is no longer a valid choice.
+      # Historical prices still serialize their own type's code via the prices
+      # endpoint, so nothing is hidden from a reader.
+      def index
+        authorize! :index, SolidusAdvancedPricing::PriceType
+        @price_types = SolidusAdvancedPricing::PriceType.accessible_by(current_ability, :index).ordered
+        respond_with(@price_types)
+      end
+    end
+  end
+end

data/lib/controllers/api/spree/api/prices_controller.rb

@@ -15,18 +15,96 @@ module Spree
         respond_with(@price)
       end
 
+      def create
+        authorize! :create, Spree::Price
+
+        @price = variant.prices.new(currency: Spree::Config.default_pricing_options.currency)
+        assign_price_attributes(@price)
+
+        if @price.errors.empty? && @price.save
+          render :show, status: :created
+        else
+          invalid_resource!(@price)
+        end
+      end
+
+      def update
+        # `find` then `authorize!`, rather than an accessible_by scope, so a
+        # caller without rights gets 401 like every other action here instead of
+        # a 404 that reads as "no such price".
+        @price = live_prices.find(params[:id])
+        authorize! :update, @price
+
+        assign_price_attributes(@price)
+
+        if @price.errors.empty? && @price.save
+          render :show
+        else
+          invalid_resource!(@price)
+        end
+      end
+
+      # Soft delete: `discard`, not `destroy`, so the row stays available to
+      # anything reporting on what a variant used to cost.
+      def destroy
+        @price = live_prices.find(params[:id])
+        authorize! :destroy, @price
+
+        @price.discard
+        render plain: nil, status: :no_content
+      end
+
       private
 
       # Lists what exists for this variant; never routed through
       # current_pricing_options, which would filter by the requesting admin's
       # own roles via current_spree_user.
+      #
+      # `Spree::Variant#prices` is declared `-> { with_discarded }` in core, so
+      # the default here has to put `kept` back -- otherwise every listing
+      # includes prices someone deleted. `?show_deleted=true` opts back in, the
+      # same switch core uses on products.
       def scope
-        variant.prices.accessible_by(current_ability, :index)
+        prices = variant.prices.accessible_by(current_ability, :index)
+        params[:show_deleted] ? prices : prices.kept
+      end
+
+      # Writes never reach a discarded price: undeleting is not an API operation,
+      # and silently editing a deleted row is worse than a 404.
+      def live_prices
+        variant.prices.kept
       end
 
       def variant
         @variant ||= Spree::Variant.find(params[:variant_id])
       end
+
+      # `price_type_code` is accepted as an alternative to `price_type_id` because
+      # ids are per-database and codes are not -- a payload written against staging
+      # has to work unchanged against production. An explicit null means the untyped
+      # base price, so a present-but-empty key is meaningful and not the same as an
+      # absent one.
+      def assign_price_attributes(price)
+        attributes = params.require(:price).permit(*Spree::PermittedAttributes.price_attributes, :price_type_code)
+
+        if attributes.key?("price_type_code")
+          code = attributes.delete("price_type_code")
+
+          if attributes.key?("price_type_id")
+            price.errors.add(:price_type_id, :ambiguous_price_type)
+            return
+          end
+
+          begin
+            attributes["price_type_id"] = code.presence && SolidusAdvancedPricing.resolve_price_type_id(code)
+          rescue ArgumentError
+            price.errors.add(:price_type_id, :unknown_code, code: code)
+            return
+          end
+        end
+
+        price.assign_attributes(attributes)
+      end
     end
   end
 end

data/lib/solidus_advanced_pricing/configuration.rb

@@ -2,9 +2,20 @@
 
 module SolidusAdvancedPricing
   class Configuration
-    # Define here the settings for this extension, e.g.:
-    #
-    # attr_accessor :my_setting
+    # Largest payload PriceBatch will accept in one call. A synchronous request
+    # has to stay inside the web timeout; anything bigger belongs in a job.
+    attr_writer :batch_row_limit
+
+    # Optional callable invoked by PriceBatch once every row is written and
+    # before the transaction commits, receiving the batch. Raise from it to
+    # abort. This is the seam for store policy -- "refuse a batch that moves
+    # more than N% of prices by more than X%" -- which does not belong in a
+    # general-purpose extension but does need somewhere to stand.
+    attr_accessor :batch_guard
+
+    def batch_row_limit
+      @batch_row_limit ||= 500
+    end
   end
 
   class << self

data/lib/solidus_advanced_pricing/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SolidusAdvancedPricing
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/views/api/spree/api/price_batches/create.json.jbuilder

@@ -0,0 +1,6 @@
+json.mode @batch.mode
+json.dry_run @batch.dry_run?
+json.summary @batch.summary
+json.results(@batch.results) do |result|
+  json.merge! result.to_h
+end

data/lib/views/api/spree/api/price_types/_price_type.json.jbuilder

@@ -0,0 +1 @@
+json.call(price_type, :id, :code, :name, :position, :role_id)

data/lib/views/api/spree/api/price_types/index.json.jbuilder

@@ -0,0 +1,3 @@
+json.price_types(@price_types) do |price_type|
+  json.partial!("spree/api/price_types/price_type", price_type: price_type)
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: solidus_advanced_pricing
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Patrick McMorran
@@ -156,6 +156,7 @@ files:
 - app/decorators/models/solidus_advanced_pricing/spree/price_decorator.rb
 - app/decorators/models/solidus_advanced_pricing/spree/role_decorator.rb
 - app/decorators/models/solidus_advanced_pricing/spree/variant_decorator.rb
+- app/models/solidus_advanced_pricing/price_batch.rb
 - app/models/solidus_advanced_pricing/price_selector.rb
 - app/models/solidus_advanced_pricing/price_type.rb
 - app/models/solidus_advanced_pricing/price_type_cache.rb
@@ -179,9 +180,10 @@ files:
 - db/migrate/20260915000002_seed_solidus_advanced_pricing_price_types.rb
 - db/migrate/20260915000003_add_advanced_pricing_to_spree_prices.rb
 - db/migrate/20260923000001_add_role_to_solidus_advanced_pricing_price_types.rb
-- docs/superpowers/specs/2026-09-14-solidus-advanced-pricing-design.md
 - lib/components/admin/solidus_admin/price_types/index/component.rb
 - lib/controllers/admin/solidus_admin/price_types_controller.rb
+- lib/controllers/api/spree/api/price_batches_controller.rb
+- lib/controllers/api/spree/api/price_types_controller.rb
 - lib/controllers/api/spree/api/prices_controller.rb
 - lib/controllers/backend/spree/admin/price_types_controller.rb
 - lib/generators/solidus_advanced_pricing/install/install_generator.rb
@@ -192,6 +194,9 @@ files:
 - lib/solidus_advanced_pricing/testing_support/factories.rb
 - lib/solidus_advanced_pricing/testing_support/factories/price_type_factory.rb
 - lib/solidus_advanced_pricing/version.rb
+- lib/views/api/spree/api/price_batches/create.json.jbuilder
+- lib/views/api/spree/api/price_types/_price_type.json.jbuilder
+- lib/views/api/spree/api/price_types/index.json.jbuilder
 - lib/views/api/spree/api/prices/_price.json.jbuilder
 - lib/views/api/spree/api/prices/index.json.jbuilder
 - lib/views/api/spree/api/prices/show.json.jbuilder

data/docs/superpowers/specs/2026-09-14-solidus-advanced-pricing-design.md

@@ -1,351 +0,0 @@
-# solidus_advanced_pricing — Design
-
-Status: FINAL (approved design, ready for implementation planning)
-Date: 2026-09-14
-
-## Problem
-
-Solidus core models a price as `(variant, currency, country_iso, amount)`. There is no way to
-express that a price is a particular *kind* of price, that it applies only during a window of
-time, or that it applies only to a certain kind of customer.
-
-Stores that need wholesale or dealer pricing, scheduled price-list rollovers, or simply a record
-of why a price exists currently reach for promotions. Promotions are the wrong tool for the
-first two: they *discount* a price rather than replacing it, which leaks the retail price to a
-B2B customer, reads as a discount on invoices, and reports as promotional revenue when it is
-not. See the promotions decision below for the full evaluation.
-
-## Goal
-
-A Solidus extension gem adding three things to `Spree::Price`, plus internal commentary:
-
-1. Configurable, admin-managed **price types**
-2. An optional **validity window** (`valid_from` / `valid_to`)
-3. Optional **role targeting** — one `Spree::Role` a price is visible to
-4. **`admin_notes`** — internal-facing commentary on why a price exists
-
-...delivered through Solidus' existing `Spree::Config.variant_price_selector_class` seam rather
-than by monkey-patching price lookup.
-
-## Non-goals
-
-- **Promotion machinery** — lanes, codes, usage limits, stacking rules, order-level
-  adjustments. A windowed `sale` or `clearance` price *is* supported; anything needing
-  promotional logic belongs in `solidus_promotions`.
-- **Role exclusion.** Only inclusion is expressible. "Everyone except employees" requires one
-  targeted price per included role.
-- **Re-pricing existing line items.** Carts are left alone, matching core.
-- **A prices screen in solidus_admin.** Upstream has not built one; this gem will not guess it.
-- **Display-only / compare-at price types.** Every price is a selection candidate.
-
-## Architecture
-
-Two subclasses registered in one initializer line. Core delegates `pricing_options_class` from
-the selector class, so this wires both:
-
-```ruby
-Spree::Config.variant_price_selector_class = "SolidusAdvancedPricing::PriceSelector"
-```
-
-Everything else is additive columns, one new table, view overrides, and an API controller.
-
-## Data model
-
-```
-solidus_advanced_pricing_price_types
-  id, name, code (unique), position, default (boolean), deleted_at, timestamps
-
-spree_prices                                   (columns added)
-  price_type_id  bigint,   NOT NULL, FK → price_types, indexed
-  role_id        bigint,   NULL,     FK → spree_roles, indexed
-  valid_from     datetime, NULL      (nil = open-ended start)
-  valid_to       datetime, NULL      (nil = never expires)
-  admin_notes    text,     NULL
-  index (variant_id, currency, country_iso, role_id, valid_from, valid_to)
-```
-
-`role_id` is modeled on `country_iso`: nullable, where `nil` means "every customer, including
-guests". There is no join table and no exclusion.
-
-The install migration seeds five price types, keyed by `code` so re-running is idempotent,
-then backfills every existing price into `default` before adding the NOT NULL constraint:
-
-| code | position | default | notes |
-|---|---|---|---|
-| `default` | 1 | yes | backfill target; guarded against discard |
-| `wholesale` | 2 | | |
-| `sale` | 3 | | typically paired with a validity window |
-| `clearance` | 4 | | |
-| `employee` | 5 | | typically paired with `role_id` |
-
-Only `default` is structural. The other four are conveniences — admins may rename, reposition
-or discard them freely, and may add their own.
-
-**A price type grants no access control.** Type and `role_id` are independent columns: naming a
-price `employee` does not hide it from anyone. An employee-only price is
-`price_type: employee` **and** `role_id: <employee role>`. This is the most likely
-misconfiguration in the whole gem and must be called out in both the README and the admin form
-hint text.
-
-## Price selection
-
-`SolidusAdvancedPricing::PricingOptions < Spree::Variant::PricingOptions`
-
-`desired_attributes` gains two real, assignable `Spree::Price` columns:
-
-- `price_type_id` — pinned to the default type in `default_price_attributes`
-- `role_id` — pinned to `nil` in `default_price_attributes`
-
-Both must be assignable columns because core calls `prices.build(default_price_attributes)` in
-`DefaultPrice#default_price_or_build`. They also make core's public `Spree::Price
-.with_default_attributes` scope correct for consumers.
-
-Two contextual readers live *outside* `desired_attributes`, because they are not price columns:
-
-| reader | default | meaning |
-|---|---|---|
-| `at` | `Time.current` | only prices whose window contains this instant |
-| `customer_role_ids` | `[]` | the roles this customer holds; `[]` is a guest |
-
-Built from context as:
-
-- `from_context(ctx)` → `customer_role_ids: ctx.current_spree_user&.spree_role_ids || []`
-- `from_line_item(li)` → `customer_role_ids: li.order&.user&.spree_role_ids || []`
-
-The association is `spree_roles` (see `Spree::UserMethods`), so the reader is `spree_role_ids`,
-not `role_ids`.
-
-**Pricing-relevant narrowing.** Both constructors intersect the customer's roles with the set of
-roles that actually appear on some price — `Spree::Price.distinct.pluck(:role_id).compact`,
-cached and invalidated by a `Spree::Price` `after_commit`. A customer holding
-`[admin, wholesale, newsletter]` narrows to `[wholesale]`. This changes no selection outcome —
-a role no price references can never match — but it collapses cache-key cardinality from
-2^(every role in the store) to 2^(roles used in pricing), which in practice is zero to two.
-
-`SolidusAdvancedPricing::PriceSelector < Spree::Variant::PriceSelector`
-
-`#price_for_options` runs in memory over `variant.prices`, as core does, so unsaved prices and
-preloaded associations keep working. Order of operations:
-
-1. **Filter** — drop discarded (unless the variant itself is discarded, per core); currency must
-   match exactly; the window must contain `at`; and the price must be visible:
-   `price.role_id.nil? || customer_role_ids.include?(price.role_id)`
-2. **Country specificity** — if any survivor matches the desired `country_iso`, keep only those;
-   otherwise keep the `country_iso IS NULL` fallback. This preserves core's behavior exactly:
-   country is specificity, not competition.
-3. **Cheapest wins** — `min_by(&:amount)` across the surviving bucket. Ties break on price type
-   `position`, then `updated_at` desc, then `id` desc, mirroring core's ordering.
-
-Role is **eligibility only** (step 1), never specificity. A wholesale customer sees both the
-wholesale and the untargeted price and gets whichever is cheaper. A wholesale price set *above*
-retail therefore never applies — that is intended and must be documented prominently, since it
-is the one genuinely surprising consequence of this model.
-
-The same predicates exist as AR scopes — `valid_at(time)`, `visible_to_roles(ids)`,
-`for_price_type(x)` — and `Spree::Variant.with_prices` is overridden in a decorator to use them.
-Without that override, a variant whose only price expired yesterday still counts as purchasable
-in product listings, because core's `with_prices` checks only currency and country.
-
-## Backward compatibility
-
-The guarantee: **a store with no typed, windowed or targeted prices behaves identically to
-core.** This gets an explicit spec that fails loudly, because every other compatibility claim
-rests on it.
-
-It holds because the backfill gives every existing price the default type, `role_id` defaults to
-`nil` (visible to all), and both window bounds default to `nil` (always valid). Defaulting `at`
-to `Time.current` changes nothing for a price with no window.
-
-One consequence to document: if a variant's only base prices all have windows and none is
-currently valid, `variant.price` returns `nil`, exactly as core returns `nil` when no price
-matches. Stores should keep one open-ended base price per variant.
-
-## Admin surfaces
-
-**Legacy backend.** `spree/admin/prices/_form` and `_table` both carry `data-hook` attributes, so
-Deface inserts at `admin_product_price_fields`: a price type select, a role select (mirroring the
-existing country select, blank = all customers), `valid_from`/`valid_to` datetime fields, and an
-`admin_notes` textarea. The prices index gains type, role and window columns.
-`Spree::Admin::ResourceController#permitted_resource_params` calls `permit!`, so the new columns
-need no strong-params work.
-
-Plus `Spree::Admin::PriceTypesController` — standard `ResourceController` CRUD.
-
-**solidus_admin.** A price types CRUD only, mirroring the existing `adjustment_reasons` /
-`refund_reasons` resource components. Per-variant price management stays in the legacy backend.
-
-## API
-
-Core's API has no prices resource; variants serialize only `price` / `display_price` via
-`price_for_options(current_pricing_options)`, which the new selector improves for free.
-
-v1 adds `Spree::Api::PricesController` plus jbuilder views exposing price type, role, validity
-window, and `admin_notes`. Two rules:
-
-- **Explicit pricing options, never `current_pricing_options`.** Core builds those
-  `from_context`, which reads `current_spree_user` — on an admin-token request that would
-  silently filter storefront prices by the *admin's* roles.
-- **`admin_notes` is serialized only when `can?(:update, price)`.** It is internal commentary and
-  must never reach a storefront payload.
-
-## Caching
-
-`PricingOptions#cache_key` in core is `desired_attributes.values.select(&:present?).join("/")`.
-Since `customer_role_ids` and `at` deliberately live outside that hash, an unmodified
-`cache_key` would render a wholesale customer's price into a fragment cache and then serve it to
-guests. The subclass **must** override `cache_key` to include sorted `customer_role_ids`.
-
-Note that having `role_id` in `desired_attributes` does *not* solve this. That attribute
-describes the price being sought, not the customer asking: `from_context` leaves it `nil`, so it
-is `nil` for guest and wholesale customer alike — and `select(&:present?)` drops nils regardless.
-Making core's key work unmodified would mean collapsing the customer to a single role, which
-cannot express "visible to any of my roles, cheapest wins".
-
-Time is the harder half: keying on raw `at` gives a 0% hit rate, while omitting it serves prices
-from cache past their window. v1 ships a coarse bucket —
-`Spree::Config.advanced_pricing_cache_granularity`, default 60 seconds — with the trade-off
-documented plainly: a price transition can be up to one granularity window late in cached views.
-Stores that cannot tolerate that set it to `nil` and lose price-dependent fragment caching.
-
-## Validations and edge cases
-
-- `valid_to` must be after `valid_from` when both are present.
-- Price types are soft-deletable. Discarding one removes it from the new-price dropdown but
-  leaves historical prices intact and still selectable, so "Overstock Sale of 2012" keeps its
-  type forever.
-- The `default: true` type is guarded against both discard and having its flag cleared while it
-  is the only default.
-- `role_id` and `price_type_id` integrity is enforced by foreign keys.
-
-## Testing
-
-- Model and scope specs, including the price type default/discard guards.
-- Selector specs driven by `ActiveSupport::Testing::TimeHelpers` across window boundaries.
-- An explicit backward-compatibility spec asserting `default_pricing_options` behavior is
-  unchanged from core.
-- A cache-key spec asserting two different role sets never collide.
-- Request specs for the API, including the `admin_notes` authorization boundary.
-- Feature specs for the legacy backend; component specs for the solidus_admin price types CRUD.
-- Factories under `lib/solidus_advanced_pricing/testing_support/factories.rb`, per contrib
-  convention.
-
-## Packaging
-
-`solidus_dev_support` skeleton: dummy app, RSpec, RuboCop, CI matrix. The engine uses
-`solidus_support`'s `backend_available?` / `admin_available?` / `api_available?` guards to add
-engine paths conditionally, so a headless store without `solidus_backend` does not load Deface
-overrides it cannot use. Solidus floor is 4.0 (`solidus_admin` exists only from 4.3, hence a
-guard rather than a hard dependency).
-
-## Decisions
-
-Every explicit decision from the brainstorm, with rationale.
-
-- **Price types are an admin-managed model**, not a config list or free-form string.
-  Rationale: store admins can add types without a deploy, and `position` gives a deterministic
-  tie-breaker.
-- **v1 ships the full stack**: model + price-selection core, legacy backend admin UI,
-  solidus_admin UI, and REST API exposure. (The solidus_admin half was later scoped down to a
-  price types CRUD — see that decision below.)
-  Rationale: an extension nobody can edit or read over the API isn't usable in a real store.
-- **Role targeting uses `Spree::Role`**, not a gem-owned group model or lambda predicates.
-  Rationale: works out of the box with solidus_auth_devise and any roles a store already
-  defines; keeps targeting queryable in SQL.
-- **Public contrib-style gem**: broad Solidus support, solidus_dev_support dummy app, CI matrix,
-  README, released to RubyGems.
-  Rationale: the feature is generally useful; building to contrib conventions from the start is
-  cheaper than retrofitting them.
-- **No display-only price types.** Every price is a selection candidate; compare-at/MSRP display
-  is the storefront's concern.
-  Rationale: keeps the model small; a `sellable` flag can be added later without breaking
-  anything.
-- **Stale carts are left alone.** A line item keeps its captured price when the source price
-  expires or the customer loses a role; the gem does not hook the order updater.
-  Rationale: matches core, which never re-prices line items on its own.
-- **Additive columns on `spree_prices`** plus a gem-owned price types table, rather than a
-  sidecar `price_details` table or a parallel prices table.
-  Rationale: the selector stays a single joinable query and eligibility becomes composable AR
-  scopes, instead of the LEFT-OUTER-JOIN dance a sidecar would force on every lookup.
-- **`price_type_id` is NOT NULL**; the install migration seeds a `default` type and backfills
-  every existing price into it.
-  Rationale: "every price has a type" is a far easier invariant to hold than "nil is secretly a
-  type", and admins see a real name in the UI.
-- **Filter first, then cheapest wins.** Currency, window and role visibility narrow the
-  candidates; country specificity picks the bucket; the lowest amount wins within it.
-  Rationale: core treats country as specificity, not competition — a `nil`-country fallback must
-  not undercut a deliberate country-specific price.
-- **One `role_id` per price, modeled on `country_iso`** — nullable FK to `spree_roles`, `nil`
-  meaning every customer including guests. No join table, no exclusion.
-  Rationale: matches how country already works, removes a table and with it an N+1 preloading
-  problem, and makes `role_id` a plain indexed column `with_prices` can filter in SQL.
-  Cost: "everyone except role X" is no longer expressible.
-- **Role is eligibility only, not specificity.** A role match qualifies a customer to see a
-  price; among everything visible, cheapest wins after country specificity.
-  Rationale: chosen over "role beats country" and "country beats role". Consequence: a
-  role-targeted price set above the untargeted price never applies.
-- **`price_type_id` and `role_id` are `desired_attributes`; `at` and `customer_role_ids` are
-  not.** Rationale: core calls `prices.build(default_price_attributes)`, so every key in that
-  hash must be an assignable `Spree::Price` column. The first two are columns; the contextual
-  filters are not.
-- **Five price types ship seeded**: `default`, `wholesale`, `sale`, `clearance`, `employee`,
-  seeded idempotently by `code`. Only `default` is structural and guarded; the rest are
-  editable and discardable conveniences.
-  Rationale: a store gets a usable vocabulary on install instead of an empty table, and the
-  names document the intended use cases. Consequence recorded above: a type name conveys no
-  access control — `employee` without `role_id` is visible to everyone.
-- **Customer roles are narrowed to pricing-relevant roles** before they reach the cache key.
-  Rationale: selection is unaffected (a role no price references can never match), but cache
-  cardinality drops from every role combination in the store to just combinations of roles
-  actually used in pricing.
-- **`admin_notes` text column on `spree_prices`** for internal commentary ("Labor Day Sale 2025",
-  "Overstock Sale of 2012"), never rendered to customers.
-  Rationale: makes historical prices legible years after whoever created them left.
-- **solidus_admin scope is price types CRUD only.** Per-variant price management stays in the
-  legacy backend.
-  Rationale: the new admin has no price management at all — `Products::Show` exposes a single
-  `f.text_field(:price)` writing through `DefaultPrice`, with no prices index, form or route.
-  Building that screen is a larger project than this feature and would guess at a design
-  upstream has not landed.
-- **The API passes explicit pricing options** rather than inheriting `current_pricing_options`.
-  Rationale: core builds those `from_context`, which reads `current_spree_user`; on an
-  admin-token request that would silently filter storefront prices by the admin's roles.
-- **Promotions were investigated and set aside.** `solidus_promotions` already ships
-  `Benefits::AdvertisePrice`, price-level conditions (`PriceProduct` / `PriceTaxon` /
-  `PriceOptionValue`), `Conditions::UserRole`, `PricePatch` (`discounts` / `discounted_amount`)
-  and `ProductAdvertiser`. Not adopted because: a promotion *discounts* a price rather than
-  replacing it (wrong semantics for B2B — it leaks retail and reports as promotional revenue);
-  `Conditions::UserRole` implements only `order_eligible?` with `any`/`all` policies, so there
-  is no price-level or exclude form; `ProductAdvertiser` is never invoked by Solidus and needs
-  an order, which is awkward on catalog pages and for guests; and promotions have no concept of
-  a price type at all. Revisit for time-boxed sale pricing, which the promotion engine does
-  better.
-
-### Superseded during the brainstorm
-
-Kept so the reasoning trail survives; do not implement these.
-
-- *Role rules in a join table with a `restrict` / `exclude` mode column.* Superseded by the
-  single `role_id` column. Exclusion went with it.
-- *Contextual filters as tri-state, where `nil` means "ignore this filter".* Superseded once
-  role became eligibility-only: `nil` and `[]` became indistinguishable for
-  `customer_role_ids`, and an `at` of `nil` would have made an admin lookup pick arbitrarily
-  between an expiring price and its replacement. Both now take plain defaults
-  (`[]` and `Time.current`).
-- *A `priority` column on price types driving selection.* Superseded by cheapest-wins;
-  `position` survives as a tie-breaker and admin sort order only.
-
-## Context gathered
-
-- Local Solidus checkout: `4.8.0.dev` (`~/RubymineProjects/solidus`), minimum Rails 7.2.
-- Ruby 3.3.10, Bundler 4.0.16.
-- Relevant core seams:
-  - `Spree::Price` — `core/app/models/spree/price.rb`
-  - `Spree::Variant::PricingOptions` — `desired_attributes`, built `from_line_item`,
-    `from_price`, `from_context`
-  - `Spree::Variant::PriceSelector#price_for_options` — already pluggable
-  - `Spree::Config.variant_price_selector_class`, which core delegates
-    `pricing_options_class` from
-  - `Spree::DefaultPrice` — `default_price` routes through the same selector, and
-    `default_price_or_build` calls `prices.build(default_price_attributes)`
-  - `Spree::Variant.with_prices` — checks only currency and country; needs overriding
-  - `Spree::Role` / `Spree::RoleUser` — `has_many :users, through: :role_users`