Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Fix review findings on the delivery vocabulary rename
Damian Legawiec98807dcf9a35
diff --git a/docs/plans/6.0-fulfillment-and-delivery.md b/docs/plans/6.0-fulfillment-and-delivery.mdindex 96a914497f..2732170493 100644--- a/docs/plans/6.0-fulfillment-and-delivery.md+++ b/docs/plans/6.0-fulfillment-and-delivery.md@@ -27,7 +27,7 @@ Three changes in one:**Ruby-level readers keep working through 6.0**, unlike the CSV column — the break there is justified because a CSV field is data a merchant re-exports, while a model reader is code an extension calls. `Product#shipping_category` and `#shipping_methods` stay as `deprecated: true` associations, and `Variant#shipping_category`/`#shipping_category_id` stay as explicit `Spree::Deprecation.warn` delegates (a plain `delegate` can't warn). `Variant` also gained `product_type`/`product_type_id` delegates alongside them. All four die with the table in 6.1.-**Internal method vocabulary follows the models (2026-08-05).** Core code now calls the delivery/fulfillment names everywhere; the shipping-era names survive one release as `Spree::Deprecation.warn` bridges. Renamed: `Stock::Estimator#shipping_rates` → `#delivery_rates` (and its internals — `calculate_`/`choose_default_`/`sort_`, plus the `shipping_methods` filter seam → `#delivery_methods`, which host apps override), `Stock::Package#shipping_rates`/`#to_shipment` → `#delivery_rates`/`#to_fulfillment`, `Stock::Coordinator#shipments` → `#fulfillments`, `Order#line_items_without_shipping_rates` → `#line_items_without_delivery_rates`, `Order#ensure_available_shipping_rates` → `#ensure_available_delivery_rates` (private — no bridge), and `LineItem#shipping_cost`/`#display_shipping_cost` → `#delivery_cost`/`#display_delivery_cost`. **`Spree::Cart` gets no deprecation bridges at all** — it is new in 6.0, so no legacy caller can exist; its equivalent is simply `#ensure_available_delivery_rates`.+**Internal method vocabulary follows the models (2026-08-05).** Core code now calls the delivery/fulfillment names everywhere; the shipping-era names survive one release as `Spree::Deprecation.warn` bridges. Renamed: `Stock::Estimator#shipping_rates` → `#delivery_rates` (and its internals — `calculate_`/`choose_default_`/`sort_`, plus the `shipping_methods` filter seam → `#delivery_methods`, which host apps override — `#delivery_methods` dispatches through the legacy name when a subclass or decorator has redefined it, so existing overrides keep filtering until 6.1 rather than being silently skipped), `Stock::Package#shipping_rates`/`#to_shipment` → `#delivery_rates`/`#to_fulfillment`, `Stock::Coordinator#shipments` → `#fulfillments`, `Order#line_items_without_shipping_rates` → `#line_items_without_delivery_rates`, `Order#refresh_shipment_rates` → `#refresh_delivery_rates`, `Order#ensure_available_shipping_rates` → `#ensure_available_delivery_rates` (private — no bridge), and `LineItem#shipping_cost`/`#display_shipping_cost` → `#delivery_cost`/`#display_delivery_cost`. **`Spree::Cart` gets no deprecation bridges at all** — it is new in 6.0, so no legacy caller can exist; its equivalent is simply `#ensure_available_delivery_rates`.**Remaining for 6.0:** only the vendor axis (`belongs_to :vendor` replacing the `Spree::VendorConcern` decorator seam, `DeliveryMethodStockLocation` vendor-consistency validation, and refusing `pickup_stock_policy: 'any'` on vendor-owned locations). It is gated on `6.0-multi-vendor-marketplace.md` shipping the `vendor_id` column in its schema wave. Everything else outstanding is Phase 6 (6.1) cleanup.@@ -310,12 +310,13 @@ Batched, idempotent, resumable — same guarantees as the split-adjustments migr- API: switch `FulfillmentSerializer#fulfillment_type` from computed to column-backed; pickup endpoints (`/pickup_locations`, `/pickup_points`); `storefront_visible` exposure; regenerate the type pipeline. (Most serializer/route work already shipped — see "Already shipped".)- **Emails gem** (20 files — never mentioned in the earlier draft): `shipment_mailer`, subscriber, templates → fulfillment vocabulary.-- Dashboard (8 files still on `shipment` vocabulary) + CSV import/export contract (`shipping_category` is a documented public column — importers get a mapping + deprecation window) + user docs. The legacy Rails admin's 26 shipping files are **deleted with `spree/admin` at 6.0**, not renamed — admin fulfillment management lives in the dashboard via Admin API/SDK.+- Dashboard (8 files still on `shipment` vocabulary) + CSV import/export contract + user docs. The legacy Rails admin's 26 shipping files are **deleted with `spree/admin` at 6.0**, not renamed — admin fulfillment management lives in the dashboard via Admin API/SDK.+ - **CSV resolved 2026-08-05: `product_type` is required immediately, no mapping and no deprecation window.** This supersedes the earlier "importers get a mapping + deprecation window" intent — a compatibility mapping would translate onto a model that no longer decides anything (see the CSV note above). `shipping_category` is gone from both import and export.### Phase 6 — cleanup (6.1)- Drop deprecation aliases, `spree_shipping_categories` + `spree_shipping_method_categories`, `products.shipping_category_id`, dual-emitted `shipment.*` events, the dangling `admin_shipping_category_serializer` / v2 platform registrations.-- Also added by the 2026-08-05 work: `DeliveryMethod#display_on` / `#display_on=` / `#available_to_display?` and the `DISPLAY_ON_FRONT_END`/`BACK_END` constants, the `deprecated: true` `shipping_method_categories` / `shipping_categories` associations on DeliveryMethod, the `deprecated: true` `shipping_category` / `shipping_methods` associations on Product, `Variant#shipping_category` / `#shipping_category_id`, and the `spree_delivery_methods.display_on` column. Plus the method bridges listed above: `Estimator#shipping_rates`/`#shipping_methods`, `Package#shipping_rates`/`#to_shipment`, `Coordinator#shipments`, `Order#line_items_without_shipping_rates`, and `LineItem#shipping_cost`/`#display_shipping_cost`. The CSV surface needs no cleanup — it was cut outright in 6.0.+- Also added by the 2026-08-05 work: `DeliveryMethod#display_on` / `#display_on=` / `#available_to_display?`, the `DISPLAY_ON_FRONT_END`/`BACK_END` constants and the `DeliveryMethod.normalize_audience` shim that accepts them, the `deprecated: true` `shipping_method_categories` / `shipping_categories` associations on DeliveryMethod, the `deprecated: true` `shipping_category` / `shipping_methods` associations on Product, `Variant#shipping_category` / `#shipping_category_id`, and the `spree_delivery_methods.display_on` column. Plus the method bridges listed above: `Estimator#shipping_rates`/`#shipping_methods`, `Package#shipping_rates`/`#to_shipment`, `Coordinator#shipments`, `Order#line_items_without_shipping_rates`, `Order#refresh_shipment_rates`, and `LineItem#shipping_cost`/`#display_shipping_cost`. The CSV surface needs no cleanup — it was cut outright in 6.0.- `FulfillmentSerializer#fulfillment_type` can drop its computed fallback once every install has run `spree:migrate_shipping_to_delivery`.## Constraints on Current Workdiff --git a/spree/core/app/models/spree/delivery_method.rb b/spree/core/app/models/spree/delivery_method.rbindex ad7fce8f5d..eafc3c2dfa 100644--- a/spree/core/app/models/spree/delivery_method.rb+++ b/spree/core/app/models/spree/delivery_method.rb@@ -195,13 +195,31 @@ module Spree# An unrecognized audience raises rather than silently quoting storefront# rates — a typo must not narrow the offer set unnoticed.#- # @param audience [Symbol] {STOREFRONT} or {BACKOFFICE}+ # @param audience [Symbol, Integer] {STOREFRONT} or {BACKOFFICE}; the+ # legacy DISPLAY_ON_* integers are accepted until 6.1# @return [Boolean]def available_to?(audience)- case audience+ case self.class.normalize_audience(audience)when BACKOFFICE then true- when STOREFRONT then storefront_visible?- else raise ArgumentError, "unknown delivery audience #{audience.inspect} (expected #{STOREFRONT.inspect} or #{BACKOFFICE.inspect})"+ else storefront_visible?+ end+ end++ # Maps an audience onto {STOREFRONT}/{BACKOFFICE}, accepting the legacy+ # DISPLAY_ON_* integers so callers holding the old constants keep working+ # until 6.1. Anything else raises — a typo must not silently quote+ # storefront-only rates.+ #+ # @param audience [Symbol, Integer]+ # @return [Symbol]+ def self.normalize_audience(audience)+ case audience+ when STOREFRONT, BACKOFFICE then audience+ when DISPLAY_ON_FRONT_END, DISPLAY_ON_BACK_END+ Spree::Deprecation.warn("Spree::DeliveryMethod::DISPLAY_ON_* audience filters are deprecated and will be removed in Spree 6.1. Use #{STOREFRONT.inspect} / #{BACKOFFICE.inspect} instead.")+ audience == DISPLAY_ON_BACK_END ? BACKOFFICE : STOREFRONT+ else+ raise ArgumentError, "unknown delivery audience #{audience.inspect} (expected #{STOREFRONT.inspect} or #{BACKOFFICE.inspect})"endend@@ -209,7 +227,7 @@ module Spree# removed in 6.1.def available_to_display?(display_filter)Spree::Deprecation.warn('Spree::DeliveryMethod#available_to_display? is deprecated and will be removed in Spree 6.1. Use #available_to?(Spree::DeliveryMethod::STOREFRONT / BACKOFFICE) instead.')- available_to?(display_filter == DISPLAY_ON_BACK_END ? BACKOFFICE : STOREFRONT)+ available_to?(display_filter)enddef delivery_rangediff --git a/spree/core/app/models/spree/order.rb b/spree/core/app/models/spree/order.rbindex 4016ebe2e7..9852cb7867 100644--- a/spree/core/app/models/spree/order.rb+++ b/spree/core/app/models/spree/order.rb@@ -814,8 +814,19 @@ module Spreeensure_updated_fulfillmentsend+ # Re-quotes every fulfillment for the given audience.+ #+ # @param audience [Symbol] {Spree::DeliveryMethod::STOREFRONT} (default)+ # or {Spree::DeliveryMethod::BACKOFFICE}+ # @return [Array<Array<Spree::DeliveryRate>>]+ def refresh_delivery_rates(audience = DeliveryMethod::STOREFRONT)+ fulfillments.map { |fulfillment| fulfillment.refresh_rates(audience) }+ end++ # @deprecated Use {#refresh_delivery_rates}; removed in 6.1.def refresh_shipment_rates(audience = DeliveryMethod::STOREFRONT)- fulfillments.map { |s| s.refresh_rates(audience) }+ Spree::Deprecation.warn('Spree::Order#refresh_shipment_rates is deprecated and will be removed in Spree 6.1. Use #refresh_delivery_rates instead.')+ refresh_delivery_rates(audience)enddef set_shipments_costdiff --git a/spree/core/app/models/spree/stock/estimator.rb b/spree/core/app/models/spree/stock/estimator.rbindex 7a1a8fb2b0..07dce36a62 100644--- a/spree/core/app/models/spree/stock/estimator.rb+++ b/spree/core/app/models/spree/stock/estimator.rb@@ -69,8 +69,28 @@ module Spreeend# The eligibility seam: every rate consumer (checkout, routing, cart- # estimates) filters through here.+ # estimates) filters through here, and host apps override it to add+ # their own rules.+ #+ # Dispatches through the legacy +shipping_methods+ name so overrides+ # written against it keep running until 6.1 — without this, a host+ # override would be silently skipped and checkout could quote rates+ # the host meant to filter out.def delivery_methods(package, audience)+ return shipping_methods(package, audience) if overrides_legacy_seam?++ filter_delivery_methods(package, audience)+ end++ # @deprecated Call or override {#delivery_methods}; removed in 6.1.+ # Only reached when a caller uses the old name directly — the override+ # dispatch above goes straight to the override's own definition.+ def shipping_methods(package, audience)+ Spree::Deprecation.warn('Spree::Stock::Estimator#shipping_methods is deprecated and will be removed in Spree 6.1. Use #delivery_methods instead.')+ filter_delivery_methods(package, audience)+ end++ def filter_delivery_methods(package, audience)methods = package.eligible_delivery_methods# Storeless orders exist only in specs; real orders always carry one.methods = methods.merge(order.store.delivery_methods) if order.store@@ -88,10 +108,13 @@ module Spreeendend- # @deprecated Use {#delivery_methods}; removed in 6.1.- def shipping_methods(package, audience)- Spree::Deprecation.warn('Spree::Stock::Estimator#shipping_methods is deprecated and will be removed in Spree 6.1. Use #delivery_methods instead.')- delivery_methods(package, audience)+ # True when a subclass or decorator redefined the legacy seam, so its+ # filtering still applies.+ def overrides_legacy_seam?+ return @overrides_legacy_seam if defined?(@overrides_legacy_seam)++ @overrides_legacy_seam =+ method(:shipping_methods).owner != Spree::Stock::Estimatorendendenddiff --git a/spree/core/lib/spree/testing_support/factories/order_factory.rb b/spree/core/lib/spree/testing_support/factories/order_factory.rbindex 74f44854d3..d7b6715c74 100644--- a/spree/core/lib/spree/testing_support/factories/order_factory.rb+++ b/spree/core/lib/spree/testing_support/factories/order_factory.rb@@ -89,7 +89,7 @@ FactoryBot.define do# Set completed_at before refreshing shipment rates so order.completed? returns true# This prevents the shipping rate selection from recalculating order totalsorder.update_columns(completed_at: order.completed_at || Time.current, status: 'placed')- order.refresh_shipment_rates(evaluator.shipping_method_filter)+ order.refresh_delivery_rates(evaluator.shipping_method_filter)endfactory :completed_order_with_pending_payment dodiff --git a/spree/core/spec/models/spree/delivery_method_spec.rb b/spree/core/spec/models/spree/delivery_method_spec.rbindex acd131dcbb..fac483313b 100644--- a/spree/core/spec/models/spree/delivery_method_spec.rb+++ b/spree/core/spec/models/spree/delivery_method_spec.rb@@ -222,6 +222,13 @@ describe Spree::DeliveryMethod, type: :model doexpect(admin_only_delivery_method.available_to_display?(described_class::DISPLAY_ON_FRONT_END)).to be falseexpect(admin_only_delivery_method.available_to_display?(described_class::DISPLAY_ON_BACK_END)).to be trueend++ # A legacy caller holding the old constants must not crash mid-checkout.+ it 'accepts the legacy integer filters in #available_to? as well' do+ expect(admin_only_delivery_method.available_to?(described_class::DISPLAY_ON_FRONT_END)).to be false+ expect(admin_only_delivery_method.available_to?(described_class::DISPLAY_ON_BACK_END)).to be true+ expect(visible_delivery_method.available_to?(described_class::DISPLAY_ON_FRONT_END)).to be true+ endenddescribe '#delivery_range' dodiff --git a/spree/core/spec/models/spree/stock/estimator_spec.rb b/spree/core/spec/models/spree/stock/estimator_spec.rbindex 529fc164d7..1e1f321709 100644--- a/spree/core/spec/models/spree/stock/estimator_spec.rb+++ b/spree/core/spec/models/spree/stock/estimator_spec.rb@@ -238,6 +238,33 @@ module Spreeendendend++ # Host apps override the eligibility seam to add their own rules. The+ # 6.0 rename must not silently skip overrides written against the old+ # name — that would quote rates the host meant to filter out.+ describe 'eligibility seam overrides' do+ let(:package) { build(:stock_package, contents: inventory_units.map { |_i| ContentItem.new(inventory_unit) }) }++ it 'still invokes a legacy #shipping_methods override' do+ called = false+ estimator = Class.new(Estimator) do+ define_method(:shipping_methods) { |_pkg, _audience| called = true; [] }+ end.new(order)++ estimator.delivery_rates(package)+ expect(called).to be true+ end++ it 'invokes a modern #delivery_methods override' do+ called = false+ estimator = Class.new(Estimator) do+ define_method(:delivery_methods) { |_pkg, _audience| called = true; [] }+ end.new(order)++ estimator.delivery_rates(package)+ expect(called).to be true+ end+ endendendenddiff --git a/spree/core/spec/models/spree/stock/package_spec.rb b/spree/core/spec/models/spree/stock/package_spec.rbindex 82e6c070df..2dde784c51 100644--- a/spree/core/spec/models/spree/stock/package_spec.rb+++ b/spree/core/spec/models/spree/stock/package_spec.rb@@ -93,27 +93,27 @@ module Spreeendend- it 'can convert to a shipment' do+ it 'can convert to a fulfillment' do2.times { subject.add build_inventory_unit }subject.add build_inventory_unit, :backordered- shipping_method = build(:shipping_method)- subject.delivery_rates = [Spree::DeliveryRate.new(delivery_method: shipping_method, cost: 10.00, selected: true)]+ delivery_method = build(:delivery_method)+ subject.delivery_rates = [Spree::DeliveryRate.new(delivery_method: delivery_method, cost: 10.00, selected: true)]- shipment = subject.to_fulfillment- expect(shipment.stock_location).to eq subject.stock_location- expect(shipment.fulfillment_items.size).to eq 3+ fulfillment = subject.to_fulfillment+ expect(fulfillment.stock_location).to eq subject.stock_location+ expect(fulfillment.fulfillment_items.size).to eq 3- first_unit = shipment.fulfillment_items.first+ first_unit = fulfillment.fulfillment_items.firstexpect(first_unit.variant).to eq variantexpect(first_unit.state).to eq 'on_hand'expect(first_unit).to be_pending- last_unit = shipment.fulfillment_items.last+ last_unit = fulfillment.fulfillment_items.lastexpect(last_unit.variant).to eq variantexpect(last_unit.state).to eq 'backordered'- expect(shipment.shipping_method).to eq shipping_method+ expect(fulfillment.delivery_method).to eq delivery_methodenddescribe '#add_multiple' do