@spree/docs 0.1.47 → 0.1.49

package/dist/developer/core-concepts/media.md

@@ -12,17 +12,74 @@ Spree handles uploads, processing, and delivery for product media. Images are au
 
 ## Product Media
 
-Product media uses the `Spree::Asset` model, which provides:
+A media record carries:
 
-- **Multiple media per product** with ordering
-- **Media types** — `image`, `video`, `external_video`
+- **Position** for ordering within the gallery
+- **Media type** — `image`, `video`, or `external_video` (defaults to `image`)
 - **Alt text** for accessibility and SEO
 - **Focal point** coordinates for smart cropping
 - **Preprocessed named variants** for fast delivery
+- **`variant_ids`** — which product variants the media represents. An empty array means it represents the product as a whole.
 
-Each media item has a `media_type` field that defaults to `image`. The `variant_ids` field indicates which product variants the media is associated with — an empty array means the media belongs to the product as a whole.
+### Product-level Gallery 
 
-> **NOTE:** `Spree::Image` is a backward-compatible subclass of `Spree::Asset` that sets `media_type` to `image`. New code should use `Spree::Asset` directly.
+In Spree 5.5 the **product** is the default owner of media. Before 5.5, every image was pinned to a specific variant (usually the master), and sharing the same image across variants meant re-uploading the file. From 5.5 onward, an image lives on the product, and any subset of variants can reference it through `variant_ids` — without duplicating the underlying file.
+
+#### Uploading a product-level image
+
+
+```typescript Admin SDK
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({ baseUrl, secretKey })
+
+// `signed_id` comes from a direct upload; see the Active Storage docs for
+// generating one client-side.
+const media = await client.products.media.create('prod_86Rf07xd4z', {
+  signed_id: signedBlobId,
+  alt: 'Front view',
+  position: 1,
+})
+```
+
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/admin/products/prod_86Rf07xd4z/media' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "signed_id": "<signed-blob-id>",
+    "alt": "Front view",
+    "position": 1
+  }'
+```
+
+
+#### Sharing a single image across variants
+
+Pass a `variant_ids` array on the same media endpoint to link/unlink variants. The server replaces the asset's link set on every call — empty array clears all links, omitting the field leaves them untouched.
+
+
+```typescript Admin SDK
+await client.products.media.update('prod_86Rf07xd4z', 'media_k5nR8xLq', {
+  variant_ids: ['variant_redM', 'variant_redL'],
+})
+```
+
+```bash cURL
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/products/prod_86Rf07xd4z/media/media_k5nR8xLq' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{ "variant_ids": ["variant_redM", "variant_redL"] }'
+```
+
+
+Variants belonging to a different product are silently dropped — the API rejects cross-product tampering at the model layer. Reordering happens once on the product gallery; every linked variant inherits the new order.
+
+#### Storefront gallery resolution
+
+The Store API's `media` field on a product returns its gallery — product-level media when present, falling back to legacy variant-pinned images during the transition. On a variant, `media` returns the assets linked to that variant via `variant_ids`, falling back to direct variant uploads.
+
+This dual rendering means existing storefronts keep working during the upgrade; new uploads attach to the product, and you opt into a [one-shot migration](../upgrades/5.4-to-5.5.md) to re-home legacy variant-pinned data when convenient.
 
 ### Named Variant Sizes 
 
@@ -134,8 +191,9 @@ curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=media,vari
 | `focal_point_x` | number \| null | Horizontal focal point (0.0–1.0) |
 | `focal_point_y` | number \| null | Vertical focal point (0.0–1.0) |
 | `external_video_url` | string \| null | External video URL (YouTube/Vimeo) |
-| `original_url` | string \| null | Full-size image URL |
+| `original_url` | string \| null | Full-size image URL (inline disposition) |
 | `mini_url` ... `xlarge_url` | string \| null | Named variant URLs |
+| `download_url` | string \| null | Same blob as `original_url` but with `Content-Disposition: attachment`. Admin API only.  |
 
 ## Image Processing
 

package/dist/developer/core-concepts/shipments.md

@@ -3,6 +3,8 @@ title: Shipments
 description: Shipping methods, rates, split shipments, and fulfillment
 ---
 
+import { Since } from '/snippets/since.mdx';
+
 ## Overview
 
 A shipment represents a package being sent to a customer from a [Stock Location](inventory.md#stock-locations). Each order can have one or more shipments — Spree automatically splits orders into multiple shipments when items need to ship from different locations or require different shipping methods.
@@ -156,31 +158,115 @@ Each shipping method uses a [Calculator](calculators.md) to determine the cost.
 
 You can create custom calculators for more complex pricing. See the [Calculators guide](calculators.md).
 
+## Order Routing 
+
+When an order moves from cart to checkout, Spree decides which [Stock Location](inventory.md#stock-locations) fulfills it. **Order Routing** is the system that makes that decision — driven by configurable rules so merchants can express preferences like "fulfill from the customer's preferred warehouse first," "minimize the number of split shipments," or "always pick the closest location."
+
+```mermaid
+flowchart LR
+    Order[Order entering checkout] --> Strategy
+    Strategy[Routing strategy] --> Rules[(Rules,<br/>per channel)]
+    Strategy --> Locations[(Eligible<br/>stock locations)]
+    Rules --> Reducer
+    Locations --> Reducer
+    Reducer[Reducer:<br/>full ranking,<br/>best-first] --> Ordered[Locations<br/>in rank order]
+    Ordered --> Shipments[Shipments created<br/>top location first]
+```
+
+### How the decision is made
+
+Each Channel (the distribution surface — online storefront, POS, wholesale portal) has an ordered list of **routing rules**. When the customer enters checkout, Spree walks the rules from highest priority to lowest and asks each rule to rank the candidate locations. The result is a full best-to-worst ordering of every eligible location. The top-ranked location packs as much of the cart as it can; anything it can't cover spills over to the next-ranked location, and so on.
+
+The default rules every channel ships with:
+
+| Order | Rule | What it does |
+|---|---|---|
+| 1 | **Preferred Location** | If the order has a preferred location set (e.g. by an admin staff member), that location ranks first. Otherwise abstains. |
+| 2 | **Minimize Splits** | Prefers locations that can fulfill the most line items single-handedly. The location that covers the most cart on its own ranks higher. |
+| 3 | **Default Location** | Tie-breaker: ranks the store default first, then other active locations. Always ranks every candidate so there's always a complete order. |
+
+Reorder them, deactivate them, or add new rules without touching code — they're just rows in `spree_order_routing_rules`.
+
+### Channels
+
+Every order belongs to a Channel. Routing rules are scoped to the channel, so the wholesale channel can have completely different fulfillment logic from the online storefront. New channels seed their own three default rules automatically.
+
+A channel can also override the routing **strategy** entirely — useful when one channel needs an algorithmic shape that's different from rules-walking, e.g. a POS channel that always picks the brick-and-mortar location, or a wholesale channel that delegates routing to an external warehouse management system.
+
+### When it fires
+
+Routing fires once, when the order transitions from `cart` to `address` (the start of checkout). It produces one or more `Shipment`s, each tied to a chosen stock location. The decision is sticky — once the shipments are created, their locations stay fixed unless the merchant edits them in the admin or the cart is cleared and re-routed.
+
+Routing happens **after** stock reservations: by the time routing runs, the cart has already reserved the units it needs. Reservations and routing make their decisions at different layers — reservations protect the variant's total inventory across all locations, routing picks which location ships. They coexist correctly today, with a small inefficiency around location-pinning that's planned to be tightened in 6.0.
+
+### Extending routing
+
+For business-specific logic — proximity to the shipping address, customer-tier-aware fulfillment, refrigerated SKUs, day-of-week dispatch — you write a custom **rule** that plugs into the existing pipeline. For replacing the algorithm entirely (OMS delegation, ML-based routing, multi-order optimization solvers), you write a custom **strategy**.
+
+See the [Build Custom Order Routing](../how-to/custom-order-routing.md) guide for both.
+
 ## Split Shipments
 
-When items in an order ship from different stock locations or have different shipping categories, Spree automatically splits the order into multiple shipments.
+An order's allocation can split along two independent axes:
+
+| Axis | Decided by | Question it answers |
+|---|---|---|
+| **Across stock locations** | [Order Routing](#order-routing) | _Which_ locations fulfill this order? |
+| **Within a stock location** | [Stock Splitters](#stock-splitters) | _How_ do we break each location's allocation into separate packages? |
+
+The two layers compose cleanly — routing picks and ranks the locations, then each chosen location is independently broken down by the splitter chain. The Prioritizer then walks all the resulting packages in rank order and decides which package fulfills each inventory unit.
 
 ```mermaid
 flowchart TB
-    A[Order with 3 items] --> B{Stock check}
-    B --> C["Item A & B: NYC Warehouse"]
-    B --> D["Item C: LA Warehouse"]
-    C --> E["Shipment 1: UPS Ground"]
-    D --> F["Shipment 2: FedEx 2Day"]
+    A[Order with 3 items] --> R[Routing strategy]
+    R --> NYC[NYC Warehouse<br/>covers 2 items]
+    R --> LA[LA Warehouse<br/>covers 1 item]
+    NYC --> P1[Packer + splitters]
+    LA --> P2[Packer + splitters]
+    P1 --> S1["Shipment 1: Light items<br/>UPS Ground from NYC"]
+    P1 --> S2["Shipment 2: Heavy items<br/>FedEx Freight from NYC"]
+    P2 --> S3["Shipment 3: Backup item<br/>UPS Ground from LA"]
 ```
 
 ### How Splitting Works
 
-1. When an order reaches the delivery step, Spree evaluates where each item is in stock
-2. Items are grouped by stock location and shipping category
-3. Each group becomes a separate shipment with its own shipping rates
-4. The customer selects a shipping rate for each shipment independently
+1. **Order Routing** produces a ranked list of stock locations (best first).
+2. **Per-location packing**: each location's units pass through `Spree::Stock::Packer` plus the configured splitter chain (`Spree.stock_splitters`), producing one or more packages per location — broken out by shipping category, on-hand vs backorder, digital vs physical, and so on.
+3. **Prioritizer**: walks all resulting packages in rank order and assigns each inventory unit to the first package that has it on hand. Units the top-ranked location can't cover spill into lower-ranked location packages; unfilled units are flagged backordered.
+4. **Shipment creation**: each remaining package becomes a `Shipment`. The customer selects a shipping rate for each shipment independently.
+
+## Stock Splitters
+
+Splitters are the per-location half of the split-shipment story. Each splitter takes the packages produced so far for one location and decides whether to break them further along its own axis. Splitters are chained — every splitter's output feeds into the next.
+
+Splitters never see more than one location's allocation at a time, so they cannot overlap with routing's location decision. Routing answers "which locations?"; splitters answer "how do we slice each location's packages?"
+
+### Built-in Splitters
+
+| Splitter | Default? | What it does |
+|---|---|---|
+| `Spree::Stock::Splitter::ShippingCategory` | Yes | Groups items in each package by their product's [Shipping Category](#shipping-categories), so each package has only one category. Ensures shipping methods scoped to specific categories receive the right items. |
+| `Spree::Stock::Splitter::Backordered` | Yes | Splits each package into an on-hand part and a backordered part. The two halves can ship at different times with different ETAs. |
+| `Spree::Stock::Splitter::Digital` | Yes | Separates digital items from physical items so digital deliveries don't get bundled with a physical package. |
+| `Spree::Stock::Splitter::Weight` | Opt-in | Caps each package at a weight threshold (default `150`). Splits heavy packages until each is under the limit. Used by carriers with per-package weight limits. |
+
+The default chain is set in `Spree::Core::Engine` and can be overridden:
+
+```ruby
+# config/initializers/spree.rb
+Rails.application.config.spree.stock_splitters = [
+  Spree::Stock::Splitter::ShippingCategory,
+  Spree::Stock::Splitter::Backordered,
+  Spree::Stock::Splitter::Digital,
+  Spree::Stock::Splitter::Weight  # add the opt-in weight cap
+]
+```
 
-### Weight Splitting
+The order matters — each splitter's output is the next one's input.
 
-By default, Spree also splits shipments when a package exceeds a weight threshold (default: 150 units). This prevents individual packages from being too heavy.
+### Extending Splitters
 
-> **INFO:** Split shipment behavior is customizable. See the [Customization Quickstart](../customization/quickstart.md) for details on creating custom splitting rules.
+To add custom splitting logic — refrigerated SKUs, gift wrap separation, bulky-vs-small bin separation, anything that needs to fan one location's allocation into multiple shipments — write a new subclass of `Spree::Stock::Splitter::Base`. See the [Build Custom Stock Splitter](../how-to/custom-stock-splitter.md) guide.
 
 ## Examples
 
@@ -214,4 +300,5 @@ A store shipping from 2 locations (New York, Los Angeles) with 3 carriers and 3
 - [Inventory](inventory.md) — Stock locations and inventory management
 - [Calculators](calculators.md) — Shipping rate calculators
 - [Addresses](addresses.md) — Shipping address and zones
+- [Build Custom Order Routing](../how-to/custom-order-routing.md) — Custom rules and strategies for choosing the fulfillment location
 - [Events](events.md) — Subscribe to shipment events (e.g., `shipment.shipped`)

package/dist/developer/how-to/custom-order-routing.md

@@ -0,0 +1,308 @@
+---
+title: Build Custom Order Routing
+description: Step-by-step guide to extending Spree's order routing — write custom rules to add new signals, or a custom strategy to replace the algorithm entirely.
+---
+
+import { Since } from '/snippets/since.mdx';
+
+
+## Overview
+
+Order routing decides which [Stock Location](../core-concepts/inventory.md#stock-locations) fulfills an order at checkout. Spree gives you two extension points:
+
+- **Rules** — add a new signal to the existing rules-walking algorithm (proximity, customer tier, refrigerated SKUs, day-of-week dispatch).
+- **Strategies** — replace the algorithm entirely (delegate to a warehouse management system, run an ML model, call an optimization solver).
+
+This guide covers both. Most extensions are rules — they compose with the built-ins and don't require rewriting the pipeline.
+
+Before starting, make sure you understand [how order routing works in Spree](../core-concepts/shipments.md#order-routing).
+
+| If the answer is "yes" | Pick |
+|---|---|
+| Could this work just by reordering or adding signals to the existing algorithm? | A **rule** |
+| Does the data live in another system you have to call? | A **strategy** |
+| Will the algorithm need access to multiple orders simultaneously (batching, capacity-aware)? | A **strategy** |
+| Are you replacing the entire decision (no rules at all)? | A **strategy** |
+
+## Custom Routing Rules
+
+A rule is one input to the rules-walking algorithm. Each rule subclasses `Spree::OrderRoutingRule` and implements `#rank`, returning an array of `LocationRanking` — one per candidate location.
+
+### Step 1: Create the Rule Class
+
+```ruby app/models/spree/order_routing/rules/closest_location.rb
+module Spree
+  module OrderRouting
+    module Rules
+      class ClosestLocation < Spree::OrderRoutingRule
+        preference :max_distance_km, :integer, default: 1000
+
+        def rank(order, locations)
+          target = order.ship_address&.coordinates
+          return locations.map { |l| LocationRanking.new(location: l, rank: nil) } if target.nil?
+
+          locations.map do |loc|
+            distance = loc.distance_from(target)
+            ranked = distance && distance <= preferred_max_distance_km ? distance.to_i : nil
+            LocationRanking.new(location: loc, rank: ranked)
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+#### Key Method to Implement
+
+| Method | Required | Description |
+|--------|----------|-------------|
+| `rank(order, locations)` | Yes | Returns one `LocationRanking` per input location. Lower rank wins (`0` is best); `nil` means abstain (the rule has no opinion about that location and is skipped for that pass). |
+
+#### Using Preferences
+
+Rules use Spree's preference system for configuration, the same way [Promotion Rules](custom-promotion.md#using-preferences) do. Each preference creates getter/setter methods automatically:
+
+```ruby
+preference :max_distance_km, :integer, default: 1000
+
+# Creates:
+# preferred_max_distance_km / preferred_max_distance_km=
+```
+
+Available types: `:string`, `:integer`, `:decimal`, `:boolean`, `:array`.
+
+### Step 2: Activate the Rule on a Channel
+
+Every routing rule belongs to a Channel. Pick the channel(s) you want it active on and insert a row:
+
+```ruby
+store   = Spree::Store.default
+channel = store.default_channel
+
+Spree::OrderRouting::Rules::ClosestLocation.create!(
+  store: store,
+  channel: channel,
+  position: 0,                    # before the seeded preferred_location rule
+  preferred_max_distance_km: 500
+)
+```
+
+Spree's autoloader picks up models under `app/models/` automatically — no separate registration step.
+
+To activate the rule across multiple channels, create one row per channel. That keeps each channel's rule list explicit and lets you tune per-channel preferences independently.
+
+### Rank Semantics
+
+The reducer composes rules using "first non-tie wins":
+
+| Situation | What the reducer does |
+|---|---|
+| All rules abstain (`nil`) for a location | Falls back to `StockLocation.default`, then by `id` |
+| One rule returns a unique minimum rank | That location wins; remaining rules skipped |
+| One rule returns a tied minimum | The tied locations carry forward; the next rule weighs in *only on those* |
+| All rules tie through the whole chain | Final tiebreak: default location, then by `id` |
+
+Practical implications:
+
+- **Returning `0` for everything is a reset.** If every location ties at `0`, all locations carry forward — the reducer treats it as "no signal" and moves on.
+- **Coverage-style metrics negate.** When higher-is-better, return `-coverage` so lower wins. See `Spree::OrderRouting::Rules::MinimizeSplits` for the canonical example.
+- **Abstaining yields to other rules.** `nil` is the right answer when your rule has no opinion — it lets later rules decide.
+
+### Step 3: Test the Rule
+
+```ruby spec/models/spree/order_routing/rules/closest_location_spec.rb
+require 'rails_helper'
+
+RSpec.describe Spree::OrderRouting::Rules::ClosestLocation, type: :model do
+  let(:store) { @default_store }
+  let(:channel) { store.default_channel }
+  let(:near)  { create(:stock_location, latitude: 40.71, longitude: -74.00) }   # NYC
+  let(:far)   { create(:stock_location, latitude: 34.05, longitude: -118.24) }  # LA
+  let(:order) { build(:order, store: store, ship_address: build(:address, latitude: 40.75, longitude: -73.99)) }
+
+  subject(:rule) do
+    described_class.new(store: store, channel: channel, position: 99, preferred_max_distance_km: 5000)
+  end
+
+  it 'ranks the closer location lower' do
+    rankings = rule.rank(order, [near, far])
+    expect(rankings.find { |r| r.location == near }.rank).to be < rankings.find { |r| r.location == far }.rank
+  end
+
+  it 'abstains for every location when the order has no shippable address' do
+    addressless_order = build(:order, store: store, ship_address: nil)
+    rankings = rule.rank(addressless_order, [near, far])
+    expect(rankings.map(&:rank)).to all(be_nil)
+  end
+end
+```
+
+### Common Pitfalls
+
+- **Forgetting `position`.** `position` is required and `acts_as_list`-scoped per channel. Use a number that doesn't collide with the seeded `1` / `2` / `3` (low for "before the defaults", `100+` for "after the defaults").
+- **Returning fewer rankings than locations.** Always return one entry per input location, including abstains (`nil` rank). The reducer needs to see every location.
+- **Trying to "block" a location.** Rules rank, they don't filter. To exclude a location, lower its rank to a value worse than every other rule produces, or abstain everywhere except the locations you want and rely on a later rule to cover the rest.
+
+## Custom Routing Strategies
+
+A strategy is a complete algorithm — when rules-walking doesn't fit your problem, you write a strategy that owns the entire allocation pipeline.
+
+### Step 1: Create the Strategy Class
+
+The contract is `Spree::OrderRouting::Strategy::Base`. There are no defaults — you implement all four methods:
+
+| Method | When it fires | Returns |
+|---|---|---|
+| `#for_allocation` | Cart → checkout transition (`Order#create_proposed_shipments`) | `Array<Spree::Stock::Package>` |
+| `#for_sale(fulfillment:)` | A shipment ships | (side effect) |
+| `#for_release` | An in-flight order is canceled before shipping | (side effect) |
+| `#for_cancellation` | A shipped order is canceled (return) | (side effect) |
+
+The four methods bracket the lifecycle: allocation → sale, allocation → release, or allocation → cancellation. Whatever your algorithm does at allocation time, the other three are where you reverse or settle it.
+
+```ruby app/models/acme/oms/strategy.rb
+module Acme
+  module Oms
+    class Strategy < Spree::OrderRouting::Strategy::Base
+      def for_allocation
+        decision = client.allocate(order_payload)
+        return [] if decision.assignments.empty?
+
+        decision.assignments.map { |assignment| build_package(assignment) }
+      end
+
+      def for_sale(fulfillment:)
+        client.notify_shipped(fulfillment_payload(fulfillment))
+      end
+
+      def for_release
+        client.release(order.number)
+      end
+
+      def for_cancellation
+        client.cancel_and_restock(order.number)
+      end
+
+      private
+
+      def client
+        @client ||= Acme::Oms::Client.new(api_key: ENV.fetch('ACME_OMS_API_KEY'))
+      end
+
+      def order_payload
+        {
+          order_number: order.number,
+          line_items: order.line_items.map { |li| { sku: li.variant.sku, qty: li.quantity } },
+          ship_to: order.ship_address&.country&.iso
+        }
+      end
+
+      def build_package(assignment)
+        location = Spree::StockLocation.find_by!(code: assignment.location_code)
+        units = order.inventory_units.where(variant_id: assignment.variant_ids).to_a
+
+        package = Spree::Stock::Packer.new(location, units, Spree.stock_splitters).packages.first
+        package.shipping_rates = Spree::Stock::Estimator.new(order).shipping_rates(package)
+        package
+      end
+
+      def fulfillment_payload(fulfillment)
+        # ...
+      end
+    end
+  end
+end
+```
+
+Notes:
+
+- **Strategies are plain Ruby classes**, not ActiveRecord models. Live under `app/models/` so the autoloader picks them up; or anywhere on the load path if you'd rather organize them as services.
+- **`for_allocation` returns `Spree::Stock::Package` objects.** The order's `create_proposed_shipments` turns those into `Shipment`s by calling `package.to_shipment`. Returning shipments directly will break the call site.
+- **Reuse the existing primitives.** `Spree::Stock::Packer`, `Spree::Stock::Estimator`, and `Spree::Stock::InventoryUnitBuilder` handle packing, rate estimation, and inventory unit construction. Custom strategies are about the location decision, not re-implementing the packing pipeline.
+
+### Step 2: Register the Strategy
+
+Strategies are selected by class name string — set on `Spree::Store` (default) or `Spree::Channel` (override).
+
+Activate on the whole store:
+
+```ruby
+Spree::Store.default.update!(
+  preferred_order_routing_strategy: 'Acme::Oms::Strategy'
+)
+```
+
+Override on one channel only:
+
+```ruby
+store = Spree::Store.default
+store.channels.find_by(code: 'pos').update!(
+  preferred_order_routing_strategy: 'Acme::Oms::Strategy'
+)
+```
+
+Resolution order: `channel.preferred_order_routing_strategy` → `store.preferred_order_routing_strategy`. The class is `safe_constantize`-d and rejected if it doesn't subclass `Strategy::Base`.
+
+### Step 3: Test the Strategy
+
+Strategy tests are integration tests — build an order, instantiate the strategy, exercise the four methods, assert on the resulting shipments and mocked side effects.
+
+```ruby spec/models/acme/oms/strategy_spec.rb
+require 'rails_helper'
+
+RSpec.describe Acme::Oms::Strategy, type: :model do
+  let(:store)    { @default_store }
+  let(:variant)  { create(:variant) }
+  let(:location) { create(:stock_location, code: 'NYC') }
+  let(:order)    { create(:order_with_line_items, store: store, line_items_attributes: [{ variant: variant, quantity: 1 }]) }
+
+  before { location.stock_item_or_create(variant).update!(count_on_hand: 10) }
+
+  subject(:strategy) { described_class.new(order: order) }
+
+  describe '#for_allocation' do
+    it 'returns packages from the OMS-chosen locations' do
+      stub_oms_decision(assignments: [{ location_code: 'NYC', variant_ids: [variant.id] }])
+
+      packages = strategy.for_allocation
+      expect(packages.map(&:stock_location)).to all(eq(location))
+    end
+
+    it 'returns no packages when the OMS has nothing to assign' do
+      stub_oms_decision(assignments: [])
+      expect(strategy.for_allocation).to eq([])
+    end
+  end
+end
+```
+
+### Common Pitfalls
+
+- **Forgetting the lifecycle hooks.** `for_release` and `for_cancellation` raise `NotImplementedError` by default. If your algorithm doesn't need post-allocation hooks, override them as no-ops explicitly.
+- **Ignoring inventory.** Even custom strategies should query `Spree::StockLocation.active` and respect the order's reserved units. Hardcoding `Spree::StockLocation.first` will work in tests and break in production.
+- **Side effects in `for_sale` / `for_release`.** These fire from state-machine callbacks where the order may already be partially mutated. Treat the methods as side-effect endpoints; pull what you need from the `order` and `fulfillment` arguments — don't reload state mid-call.
+
+## Coexistence with Stock Reservations
+
+Stock reservations and order routing are independent systems in 5.5 — they make decisions at different times and protect different invariants.
+
+| Concern | Reservation system | Order routing |
+|---|---|---|
+| **When it fires** | Cart mutation (add item, change qty, enter checkout) | Cart → checkout transition |
+| **What it decides** | How many units of a variant are held for this cart | Which `StockLocation` fulfills the order |
+| **Granularity** | Per-variant | Per-order |
+
+`Spree::Stock::Quantifier` already subtracts active reservations from `count_on_hand` per-variant across all locations, so global "can we sell this variant?" math is correct even when the reservation and the routing decision land on different locations.
+
+What this means for you when writing custom rules and strategies:
+
+- **Don't read `StockReservation` from inside a routing rule's `#rank`.** The reservations were created against arbitrary stock_items at cart time and don't reflect the routing decision.
+- **Don't relocate reservations from a custom strategy's `for_allocation`.** That's the path 6.0 codifies; doing it ad-hoc in 5.5 races against the cart services that own reservation lifecycle.
+- **`AvailabilityValidator` is the safety net.** If a routing decision picks a location that's actually short on stock, the validator catches it before the order completes.
+
+## Next Steps
+
+- [How orders work](../core-concepts/orders.md) — Order lifecycle and the routing context
+- [Inventory & Stock Locations](../core-concepts/inventory.md) — Where the locations live
+- [Build Custom Promotion Rules & Actions](custom-promotion.md) — A similar STI-based extension pattern

package/dist/developer/how-to/custom-stock-splitter.md

@@ -0,0 +1,213 @@
+---
+title: Build a Custom Stock Splitter
+description: Step-by-step guide to extending Spree's stock splitter chain — break a location's allocation into multiple shipments along your own axis (refrigeration, gift wrap, bin size, hazmat, anything you need to physically separate).
+---
+
+## Overview
+
+When [Order Routing](../core-concepts/shipments.md#order-routing) picks one or more stock locations to fulfill an order, each location's allocation is then run through a chain of **splitters**. Each splitter looks at the packages produced so far and decides whether to break them further along its own axis.
+
+Spree ships with four splitters out of the box (`ShippingCategory`, `Backordered`, `Digital`, `Weight`). You add your own when you need a *physical* separation that isn't expressed by any of the existing ones — refrigerated SKUs that can't share a box with ambient ones, hazmat goods that need their own carrier label, gift-wrap items that ship from a separate processing room, and so on.
+
+Before starting, make sure you understand [how splitting works in Spree](../core-concepts/shipments.md#stock-splitters) and the [order routing](../core-concepts/shipments.md#order-routing) layer that runs before splitters.
+
+| If the answer is "yes" | Pick |
+|---|---|
+| Should this affect _which_ locations fulfill the order? | A [routing rule](custom-order-routing.md#custom-routing-rules), not a splitter |
+| Does it just need to break one location's allocation into multiple physical packages? | A **splitter** |
+| Should it apply to every location, every order? | A **splitter** registered globally |
+| Should it apply only on certain channels or stores? | A **splitter** plus a guard inside `#split` |
+
+### Splitters vs Order Routing — quick recap
+
+Routing picks _which_ locations ship; splitters decide _how_ each location's packages are broken up. They live at different layers and never overlap:
+
+| Layer | Decides | Sees | Output |
+|---|---|---|---|
+| Routing | Location order | All eligible locations + the whole order | Ranked location list |
+| Splitter | Intra-location packaging | One location's packages so far | More (or fewer) packages |
+
+A plugin can absolutely ship both — for example, a refrigerated-goods plugin might add a `RefrigeratedRouting::Rule` (prefer locations with cold storage) **and** a `RefrigeratedSplitter` (separate cold items from ambient items within each location). The two extension points are independent.
+
+## Custom Stock Splitters
+
+A splitter subclasses `Spree::Stock::Splitter::Base` and implements `#split(packages)`. The method receives an array of packages produced by the previous splitter (or the initial single-package output of `Packer#default_package`), returns an array of packages, and *must* call `return_next` so the chain continues.
+
+### Step 1: Create the Splitter Class
+
+```ruby app/models/spree/stock/splitter/refrigerated.rb
+module Spree
+  module Stock
+    module Splitter
+      class Refrigerated < Spree::Stock::Splitter::Base
+        def split(packages)
+          split_packages = packages.flat_map { |pkg| split_by_temperature(pkg) }
+          return_next(split_packages)
+        end
+
+        private
+
+        def split_by_temperature(package)
+          grouped = package.contents.group_by { |item| item.variant.refrigerated? }
+          grouped.values.map { |contents| build_package(contents) }
+        end
+      end
+    end
+  end
+end
+```
+
+#### Key Method to Implement
+
+| Method | Required | Description |
+|--------|----------|-------------|
+| `#split(packages)` | Yes | Receives the packages produced by the previous splitter, returns the new (possibly larger or smaller) array of packages. **Must call `return_next(packages)`** so the next splitter in the chain runs. |
+
+#### Helpers Inherited from `Splitter::Base`
+
+| Helper | Returns | When to use |
+|---|---|---|
+| `build_package(contents = [])` | A new `Spree::Stock::Package` for the splitter's `stock_location` | When you create a new package out of contents you've separated from an input package |
+| `return_next(packages)` | The result of the next splitter, or `packages` if this is the last splitter | Always — at the end of `#split` |
+| `stock_location` | The location the parent `Packer` is packing for | When you need to inspect or compare against the location |
+| `packer` | The `Packer` instance | Rarely needed; available for advanced cases |
+
+#### What `package.contents` Looks Like
+
+Each `package.contents` is an array of `Spree::Stock::ContentItem` — wrappers around `InventoryUnit`. The two attributes you'll use most:
+
+```ruby
+content.variant         # The Spree::Variant being shipped
+content.inventory_unit  # The Spree::InventoryUnit (gives access to line_item, order, etc.)
+content.weight          # Convenience: variant.weight × inventory_unit.quantity
+content.state           # :on_hand or :backordered
+```
+
+So the splitter's job is "look at each package's contents, decide which contents stay together, build new packages, return the chained result."
+
+### Step 2: Register the Splitter
+
+Splitters are registered globally on `Rails.application.config.spree.stock_splitters` — every order runs through the full chain. Add yours via an initializer:
+
+```ruby config/initializers/spree.rb
+Rails.application.config.to_prepare do
+  Rails.application.config.spree.stock_splitters << Spree::Stock::Splitter::Refrigerated
+end
+```
+
+The `to_prepare` block re-runs on Zeitwerk code reloads in development, so the splitter survives reloads correctly. Putting the line at the top of the initializer (outside `to_prepare`) works too in production but can leave a stale registry in development.
+
+#### Replacing the Whole Chain
+
+If you'd rather control the full chain (uncommon — the defaults are well-chosen), assign instead of append:
+
+```ruby
+Rails.application.config.spree.stock_splitters = [
+  Spree::Stock::Splitter::ShippingCategory,
+  Spree::Stock::Splitter::Refrigerated,        # custom one slotted in
+  Spree::Stock::Splitter::Backordered,
+  Spree::Stock::Splitter::Digital
+]
+```
+
+#### Ordering Matters
+
+Splitters run in array order, each feeding the next. Two practical rules:
+
+1. **Coarse before fine.** `ShippingCategory` runs first by default because it groups packages by carrier-relevant category before any other axis cuts in. Your custom splitter usually wants to run after it, unless you're separating items that should *never* share a package even within a category (e.g. hazmat).
+2. **`Backordered` should usually be last among the "type" splitters.** It splits on-hand from backordered items, which is a state-axis split rather than a packaging-axis split. Splitting before `Backordered` gives you finer category buckets; splitting after does too — pick based on whether your axis applies to backorders. Refrigerated items have the same handling whether on-hand or backordered, so running before `Backordered` is fine. Hazmat shipping rules might differ between on-hand (real package) and backorder (paperwork only), so running after might be cleaner.
+
+### Step 3: Test the Splitter
+
+Splitter tests are unit tests — instantiate a fake `Packer`, hand the splitter a hand-built package, assert on the output. There's no factory required.
+
+```ruby spec/models/spree/stock/splitter/refrigerated_spec.rb
+require 'rails_helper'
+
+RSpec.describe Spree::Stock::Splitter::Refrigerated, type: :model do
+  let(:stock_location) { build_stubbed(:stock_location) }
+  let(:packer)         { instance_double(Spree::Stock::Packer, stock_location: stock_location) }
+  let(:cold_variant)   { build_stubbed(:variant).tap { |v| allow(v).to receive(:refrigerated?).and_return(true) } }
+  let(:warm_variant)   { build_stubbed(:variant).tap { |v| allow(v).to receive(:refrigerated?).and_return(false) } }
+
+  let(:cold_item) { content_item_for(cold_variant) }
+  let(:warm_item) { content_item_for(warm_variant) }
+
+  subject(:splitter) { described_class.new(packer) }
+
+  it 'splits a mixed package into a refrigerated package and an ambient package' do
+    package = Spree::Stock::Package.new(stock_location, [cold_item, warm_item])
+
+    result = splitter.split([package])
+
+    expect(result.size).to eq(2)
+    expect(result.flat_map { |p| p.contents.map(&:variant) }).to contain_exactly(cold_variant, warm_variant)
+  end
+
+  it 'leaves an all-cold package as a single package' do
+    package = Spree::Stock::Package.new(stock_location, [cold_item])
+
+    result = splitter.split([package])
+
+    expect(result.size).to eq(1)
+    expect(result.first.contents.map(&:variant)).to eq([cold_variant])
+  end
+
+  it 'returns chained packages unchanged when there is a next_splitter' do
+    next_splitter = instance_double(Spree::Stock::Splitter::Base, split: [:done])
+    splitter      = described_class.new(packer, next_splitter)
+    package       = Spree::Stock::Package.new(stock_location, [cold_item, warm_item])
+
+    expect(splitter.split([package])).to eq([:done])
+  end
+
+  def content_item_for(variant)
+    inventory_unit = build_stubbed(:inventory_unit, variant: variant)
+    Spree::Stock::ContentItem.new(inventory_unit, :on_hand)
+  end
+end
+```
+
+### Step 4 (optional): Add a Variant-side Predicate
+
+The example above relies on `variant.refrigerated?`. In a real plugin you'd back that with a [Custom Field](../core-concepts/custom-fields.md) on `Spree::Variant` — say a boolean metafield with key `refrigerated` — and define the predicate as a thin reader:
+
+```ruby app/models/spree/variant_decorator.rb
+Spree::Variant.class_eval do
+  def refrigerated?
+    metafields.find_by(namespace: 'logistics', key: 'refrigerated')&.value == 'true'
+  end
+end
+```
+
+This keeps the splitter pure and lets merchants flag SKUs from the admin UI without touching code.
+
+### Common Pitfalls
+
+- **Forgetting to call `return_next`.** If you return raw packages instead of `return_next(packages)`, every splitter after yours in the chain is silently skipped. The integration test will catch it; the unit test usually won't.
+- **Building empty packages.** If you `group_by` and the group has no contents, `build_package([])` produces a package with no contents that downstream code may treat as a real package. Skip empty groups: `grouped.values.reject(&:empty?).map { |c| build_package(c) }`.
+- **Mutating input packages in place.** A splitter should return new packages built from the contents of the inputs, not edit the originals — `Packer` and other splitters keep references. Use `build_package(contents)`, not `package.contents = ...`.
+- **Doing routing-style work.** A splitter only sees one location's contents. If your logic needs to compare across locations ("ship the cheapest one first"), that's a routing rule or strategy, not a splitter.
+
+## Coexistence with Order Routing
+
+Splitters and routing run in series, not in parallel — every package a splitter sees comes from a single location that routing already chose. The interaction is purely top-down:
+
+| Step | Layer | What runs |
+|---|---|---|
+| 1 | Routing | `Strategy::Rules#for_allocation` ranks all eligible locations |
+| 2 | Per-location packing | One `Packer` per location runs the full splitter chain |
+| 3 | Cross-location dedup | `Prioritizer.Adjuster` walks packages in rank order, assigns each inventory unit to the first package with on-hand stock |
+| 4 | Rate estimation | `Estimator` attaches shipping rates |
+
+Practical implications:
+
+- **Splitter output feeds the Prioritizer.** A splitter that produces 3 packages from one location adds 3 candidates to the Prioritizer's pool. The Prioritizer keeps each unit in the highest-ranked package that still has it on hand and prunes empties.
+- **Splitters can produce backordered-only packages.** That's fine — the `Backordered` splitter is the canonical example. The Prioritizer treats backordered packages as a fallback after exhausting on-hand options across all higher-ranked locations.
+- **A splitter can't see which location ranked higher.** It runs per-location with no awareness of the rank. If you need rank-aware splitting (rare), do it in a custom strategy's `build_packages`, not a splitter.
+
+## Next Steps
+
+- [Shipments — Stock Splitters](../core-concepts/shipments.md#stock-splitters) — Concept overview and built-in splitter list
+- [Build Custom Order Routing](custom-order-routing.md) — The other layer of split-shipment customization
+- [Custom Fields](../core-concepts/custom-fields.md) — Tag variants with the data your splitter reads

package/dist/developer/upgrades/5.4-to-5.5.md

@@ -19,6 +19,49 @@ description: This guide covers upgrading a Spree 5.4 application to Spree 5.5.
   bin/rake spree:install:migrations && bin/rails db:migrate
   ```
 
+### Migrate legacy variant-pinned media
+
+In 5.5 the [product is the default owner of media](../core-concepts/media.md#product-level-gallery). Existing variant-pinned images keep rendering, but new admin uploads attach to the product. To consolidate both into a single gallery, run:
+
+```bash
+bin/rails spree:media:migrate_master_images_to_product_media
+```
+
+The task enqueues one `Spree::Media::MigrateProductAssetsJob` per product onto the `images` queue — make sure your job runner is processing that queue. Each job is idempotent, so re-running the task is safe; it skips products that no longer have variant-pinned assets.
+
+For larger catalogs, tune the batching with `BATCH_SIZE`:
+
+```bash
+bin/rails spree:media:migrate_master_images_to_product_media BATCH_SIZE=1000
+```
+
+> **WARNING:** Run the task locally and on production. It does not block storefront rendering — new uploads attach to the product immediately — but until the enqueued jobs finish, old assets remain pinned to variants.
+
+### Run the channels upgrade
+
+Spree 5.5 promotes `Order#channel` from a free-text string column to a real `Spree::Channel` FK. **Run this rake task immediately after `db:migrate`** — it seeds the channel rows your existing stores need and backfills `spree_orders.channel_id` from the legacy string column:
+
+```bash
+bin/rake spree:channels:upgrade
+```
+
+The task is idempotent — safe to re-run if it fails partway, and a no-op on stores/orders that have already been upgraded. It runs two sub-tasks in order:
+
+1. **`spree:channels:create_defaults`** — creates a default `online` channel for every store that doesn't already have one. New 5.5+ stores get this automatically via the `Store` after_create callback; this sub-task only matters for stores that already exist when you upgrade. The channel's after_create hook seeds the three default routing rules (Preferred Location → Minimize Splits → Default Location).
+
+2. **`spree:channels:backfill_order_channel_ids`** — scans each store's orders, creates one `Spree::Channel` per distinct legacy `channel` value (claiming `NULL`/blank rows under the `online` default channel), and writes `channel_id`.
+
+You can also run the two steps individually if you'd rather pace the upgrade:
+
+```bash
+bin/rake spree:channels:create_defaults
+bin/rake spree:channels:backfill_order_channel_ids
+```
+
+Orders modified after the upgrade auto-set `channel_id` via the model's `before_validation` callback, so the backfill is only strictly required for orders that aren't touched again post-upgrade — but running it once at upgrade time avoids surprises later.
+
+The legacy `channel` string column is **kept** on `spree_orders` and ignored by ActiveRecord (`Spree::Order` declares it in `ignored_columns`). It will be dropped in a later Spree release once enough time has passed for everyone to have run the backfill — until then it's harmless DB ballast that lets the rake task be re-run if you need to.
+
 ### Schedule the Stock Reservations expiry job
 
 Spree 5.5 introduces time-limited stock reservations during checkout to prevent two customers from buying the same last unit at the same time. Abandoned checkouts leave behind expired reservation rows, and Spree does **not** auto-schedule the cleanup — your application's job runner must run `Spree::StockReservations::ExpireJob` periodically (every minute is the recommended cadence).
@@ -86,6 +129,20 @@ Spree::Config[:stock_reservations_enabled] = false
 
 The Quantifier short-circuits before any reservation query when this is `false`, so there's no runtime cost and no table growth.
 
+### (Optional) Opt out of rules-based Order Routing
+
+Spree 5.5 introduces [Order Routing](../core-concepts/shipments.md#order-routing) — a configurable, per-channel pipeline that decides which stock locations fulfill an order. Every store and every channel ships with three default rules (Preferred Location → Minimize Splits → Default Location) that produce sensible behavior out of the box, with no migration work required.
+
+If you've heavily customized fulfillment in Spree 5.4 and aren't ready to adopt the new rules engine, you can keep the legacy pre-5.5 routing by switching the store's strategy to `Spree::OrderRouting::Strategy::Legacy`:
+
+```ruby
+store.update!(preferred_order_routing_strategy: 'Spree::OrderRouting::Strategy::Legacy')
+```
+
+The Legacy strategy delegates to `Spree::Stock::Coordinator`, which is the exact pre-5.5 packing pipeline — every active stock location is packed, the Prioritizer distributes inventory units across the resulting packages, and no merchant routing rules are consulted. Your existing customizations on `Coordinator`, `Packer`, `Prioritizer`, and the splitters keep working unchanged.
+
+> **WARNING:** `Spree::OrderRouting::Strategy::Legacy` and `Spree::Stock::Coordinator` are slated for removal in Spree 6.0. Use this only as a temporary escape hatch while you evaluate the new Rules strategy. New 5.5+ installations should stay on the default Rules strategy.
+
 ## Behavior changes worth knowing
 
 ### Cart changes during checkout can now fail with insufficient stock
@@ -97,3 +154,11 @@ Storefronts and custom integrations that act on the cart should expect this new
 ### Storefront availability drops faster under contention
 
 Other customers now see availability reduced by all active reservations, not just by completed orders. This is the intended fix to overselling — but if you have a real-time inventory dashboard that reads `count_on_hand` directly (rather than going through Spree's availability checks), you'll want to expose a "Reserved" axis to merchants so they can see in-checkout demand.
+
+### Order Routing chooses location order via merchant rules instead of database order
+
+The default routing strategy (`Spree::OrderRouting::Strategy::Rules`) packs the same set of stock locations as before, but the **order** in which locations are tried is now determined by the routing rules — Preferred Location → Minimize Splits → Default Location — rather than by raw database row order. The unit distribution (Prioritizer + Adjuster) is unchanged: top-ranked location's packages get first pick of on-hand inventory, the rest spills over.
+
+For most stores this is invisible: when one location can fulfill the entire cart, that location now wins consistently (instead of depending on database iteration order). When the cart needs to split across locations, the same multi-location split happens — just with the location order driven by rules.
+
+If you rely on the legacy "every location packed in iteration order, no rule consulted" behavior, see [Opt out of rules-based Order Routing](#optional-opt-out-of-rules-based-order-routing) above.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spree/docs",
-  "version": "0.1.47",
+  "version": "0.1.49",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",