@spree/docs 0.1.248 → 0.1.249

package/dist/developer/dashboard/recipes/attribute-end-to-end.md

@@ -33,7 +33,7 @@ Four small pieces — each one unlocks a specific frontend capability. In a host
 **The column** (with an index — you're adding it *because* it will be queried):
 
 ```ruby
-class AddLeadTimeDaysToSpreeProducts < ActiveRecord::Migration[7.2]
+class AddLeadTimeDaysToSpreeProducts < ActiveRecord::Migration[8.1]
   def change
     add_column :spree_products, :lead_time_days, :integer
     add_index :spree_products, :lead_time_days
@@ -58,22 +58,8 @@ Spree.api.admin_product_serializer = 'Admin::ProductSerializer'
 **The permitted param** — makes it *writable* (the form's Save ships it in the same PATCH as core fields). The read and write names must match:
 
 ```ruby
-# app/controllers/spree/api/v3/admin/products_controller_decorator.rb
-module Spree
-  module Api
-    module V3
-      module Admin
-        module ProductsControllerDecorator
-          def permitted_params
-            super.merge(params.permit(:lead_time_days))
-          end
-        end
-
-        ProductsController.prepend(ProductsControllerDecorator)
-      end
-    end
-  end
-end
+# config/initializers/spree.rb
+Spree::Product.additional_permitted_attributes += [:lead_time_days]
 ```
 
 **The Ransack allowlist** — makes it *filterable and sortable*. Both the list's sort param and every filter predicate go through Ransack, and Ransack refuses attributes that aren't allowlisted:
@@ -208,4 +194,3 @@ Two `ColumnDef` extras worth knowing: `ransackAttribute` points the predicate so
 - [Custom form field recipe](custom-form-field.md) — the form layer in isolation, and the custom-field-definition path
 - [Tables](../customization/tables.md) — the full `ColumnDef` and table registry API
 - [Backend integration](../customization/backend.md) — serializers, permitted params, error mapping
-- [Decorators](../../customization/decorators.md) — the `prepend` pattern used for the controller

package/dist/developer/deployment/aws.md

@@ -80,7 +80,7 @@ volumes:
 docker compose up -d
 ```
 
-The database is migrated automatically on boot. Once DNS resolves, your store is live at `https://store.example.com` — admin at `/admin`, background jobs running inside the web container ([combined mode](quickstart.md#web-and-worker)).
+The database is migrated automatically on boot. Once DNS resolves, your store is live at `https://store.example.com` — admin dashboard at `/dashboard`, background jobs running inside the web container ([combined mode](quickstart.md#web-and-worker)).
 
 ## Updating
 

package/dist/developer/deployment/aws_ecs.md

@@ -419,13 +419,13 @@ aws application-autoscaling put-scaling-policy \
 
 ### Admin
 
-Access your admin panel at:
+Access the admin dashboard at:
 
 ```
-https://<your-domain>/admin
+https://<your-domain>/dashboard
 ```
 
-Default credentials are created during `db:seed`. Change them immediately after first login.
+No default admin account is created. Seeding prints a one-time setup link where you create the first admin account — print it again with `bin/rails spree:setup:token`. For scripted installs, set `ADMIN_EMAIL` and `ADMIN_PASSWORD` before seeding to create the account directly.
 
 ### Database Migrations
 

package/dist/developer/deployment/background_jobs.md

@@ -82,22 +82,28 @@ Configure the queues with weights — Sidekiq's equivalent of Solid Queue's poll
   - [spree_events, 3]
   - [spree_exports, 3]
   - [spree_images, 3]
+  - [spree_stock_reservations, 5]
   - [spree_products, 3]
-  - [spree_reports, 3]
   - [spree_variants, 3]
-  - [spree_taxons, 3]
-  - [spree_stock_location_stock_items, 3]
+  - [spree_categories, 3]
+  - [spree_collections, 3]
+  - [spree_stock_location_stock_levels, 3]
   - [spree_coupon_codes, 3]
   - [spree_addresses, 3]
   - [spree_gift_cards, 3]
   - [spree_webhooks, 3]
   - [spree_api_keys, 3]
   - [spree_search, 3]
+  - [spree_tax_identifiers, 3]
+  - [spree_payouts, 3]
+  - [spree_data_requests, 1]
   - [active_storage_transform, 3]
   - [active_storage_analysis, 1]
   - [active_storage_purge, 1]
 ```
 
+Unlike Solid Queue, Sidekiq has no catch-all queue: a job on a queue missing from this list never runs. Every queue name you assign with `Spree.queues` in `config/initializers/spree.rb` must appear here. Any `Spree.queues` entry you don't assign uses `default`.
+
 Move the `config/recurring.yml` schedules to sidekiq-cron (it auto-loads `config/schedule.yml`):
 
 ```yaml config/schedule.yml

package/dist/developer/deployment/docker.md

@@ -119,7 +119,6 @@ docker pull ghcr.io/spree/spree:latest
 | Tag | Description |
 |-----|-------------|
 | `latest` | Latest stable release |
-| `5.4.0` | Specific version |
-| `5.4` | Latest patch for a minor version |
+| `6.0.0` | Specific version |
 
 Browse all tags on the [GitHub Packages page](https://github.com/spree/spree/pkgs/container/spree). The image drops into the compose file above in place of your custom tag.

package/dist/developer/deployment/emails.md

@@ -28,7 +28,7 @@ Spree Backend → Webhook POST → Storefront → render email → send via Rese
 
 #### Setup
 
-1. **Create a webhook endpoint** in Spree Admin → Settings → Developers → Webhooks:
+1. **Create a webhook endpoint** in Spree Admin → Settings → Developer → Webhooks:
    - **URL:** `https://your-storefront.com/api/webhooks/spree`
    - **Events:** `order.completed`, `order.canceled`, `order.shipped`, `customer.password_reset_requested`, `newsletter_subscriber.subscription_requested`
 
@@ -55,6 +55,8 @@ Spree Backend → Webhook POST → Storefront → render email → send via Rese
 | `customer.password_reset_requested` | Password reset link |
 | `newsletter_subscriber.subscription_requested` | Newsletter double opt-in confirmation link |
 
+> **NOTE:** The storefront listens for `order.completed` and `order.shipped`, the names these events had before Spree 6.0. Spree 6.0 still sends them alongside the new names, `order.placed` and `order.fulfilled`, but stops in Spree 6.1. Before upgrading to 6.1, switch the storefront handlers and your webhook endpoint subscriptions to the new names.
+
 #### Custom Frameworks
 
 If you're not using the Next.js storefront, you can build your own webhook handler with any framework. Use `@spree/sdk/webhooks` for signature verification:

package/dist/developer/deployment/environment_variables.md

@@ -103,11 +103,11 @@ Optional. When configured, Spree uses [Meilisearch](../../integrations/search/me
 | `MEILISEARCH_URL` | `http://localhost:7700` | Meilisearch server URL |
 | `MEILISEARCH_API_KEY` | — | Meilisearch master key. Not needed for local development — only required when Meilisearch is started with `MEILI_MASTER_KEY`. |
 
-After setting these, enable the provider and reindex:
+After setting these, add the `spree_meilisearch` gem, enable the provider and reindex:
 
 ```ruby
 # config/initializers/spree.rb
-Spree.search_provider = 'Spree::SearchProvider::Meilisearch'
+Spree.search_provider = 'SpreeMeilisearch::SearchProvider'
 ```
 
 

package/dist/developer/deployment/render.md

@@ -27,11 +27,11 @@ The database is seeded on first boot. Your store is ready in a few minutes — i
 ### Admin
 
 ```
-https://<your-app-name>.onrender.com/admin        # admin panel
+https://<your-app-name>.onrender.com/dashboard    # admin dashboard
 https://<your-app-name>.onrender.com/jobs         # background jobs dashboard
 ```
 
-Default credentials are created during seeding. Change them immediately after first login.
+No default admin account is created. Seeding prints a one-time setup link where you create the first admin account — print it again from the web service's **Shell** tab with `bin/rails spree:setup:token`.
 
 The `/jobs` dashboard uses HTTP Basic auth: user `jobs`, with a password the Blueprint generates — read it in the Render dashboard under the web service's **Environment** tab (`MISSION_CONTROL_PASSWORD`).
 

package/dist/developer/how-to/build-a-marketplace.md

@@ -30,7 +30,7 @@ To try the flow quickly, you can seed a sample seller with an owner account, a p
 
 
 ```bash Spree CLI
-spree run rake spree:sellers:sample_data
+spree rake spree:sellers:sample_data
 ```
 
 ```bash Without CLI
@@ -711,7 +711,7 @@ const tokens = await sellerClient.auth.login({
   email: 'owner@brightsparks.example',
   password: '…',
 })
-sellerClient.setToken(tokens.access_token)
+sellerClient.setToken(tokens.token)
 
 // A user who runs several sellers picks which one they are acting as
 sellerClient.setSeller('sel_xxx')

package/dist/developer/how-to/custom-api-authentication.md

@@ -58,7 +58,7 @@ Client → POST /api/v3/store/auth/login
 Client → subsequent calls with `Authorization: Bearer <Spree JWT>`
 ```
 
-The third-party JWT proves identity **once, at login**. After that, the client uses the Spree JWT for everything, and `/auth/refresh` rotates it via Spree's own refresh-token mechanism. Your existing CanCanCan rules, `current_user`, and serializer params just work.
+The third-party JWT proves identity **once, at login**. After that, the client uses the Spree JWT for everything, and `/auth/refresh` rotates it via Spree's own refresh-token mechanism. Your existing authorization, `current_user`, and serializer params just work.
 
 ## Step 1: Create the Strategy Class
 

package/dist/developer/how-to/custom-delivery-rate-provider.md

@@ -64,6 +64,10 @@ module SpreeAcmeCarrier
   class DeliveryRateProvider < Spree::DeliveryRateProvider::Base
     def self.integration_class = 'SpreeAcmeCarrier::Integration'
 
+    # A carrier quotes real parcels to an address, so it can only price
+    # delivery methods that ship (not pickup or digital).
+    def self.requires_address? = true
+
     def estimates(package)
       quotes_for(package).map do |quote|
         Spree::DeliveryRateProvider::Estimate.new(
@@ -148,10 +152,14 @@ end
 
 ```ruby
 # config/initializers/spree.rb
-Spree.delivery_rate_providers << 'SpreeAcmeCarrier::DeliveryRateProvider'.constantize
-Spree.integrations << 'SpreeAcmeCarrier::Integration'
+Rails.application.config.after_initialize do
+  Spree.delivery_rate_providers << SpreeAcmeCarrier::DeliveryRateProvider
+  Spree.integrations << 'SpreeAcmeCarrier::Integration'
+end
 ```
 
+Register inside `after_initialize`: Spree sets up its own integrations list after your initializers run, so an entry added at the top level of the file would be dropped.
+
 Registration is what makes a provider selectable: Spree validates `rate_provider` against this list, so a typo fails when the method is saved rather than deep inside checkout.
 
 ## 4. Use it
@@ -190,7 +198,7 @@ class SpreeAcmeCarrier::Integration < Spree::Integration
 
     {
       tracking_code: payload['tracking_code'],
-      tracking_status: STATUS_MAP.fetch(payload['status'], 'unknown'),  # Spree::Fulfillment::TRACKING_STATUSES
+      tracking_status: STATUS_MAP.fetch(payload['status'], 'unknown'),  # one of Spree::Delivery::STATUSES
       estimated_delivery_at: payload['eta'],
       delivered_at: payload['delivered_scan_at'],
       details: payload.slice('status_detail', 'carrier')

package/dist/developer/how-to/custom-document-numbers.md

@@ -7,7 +7,7 @@ description: Change the shape of order, return and other document numbers — fr
 
 Every order, return, exchange, claim, stock transfer, import and export carries a **document number** — the short, human-readable reference a merchant reads out on a support call and a customer quotes in an email. Orders look like `R1001`, returns like `RET1001`.
 
-Numbers are separate from IDs. Every record also has a prefixed ID (`order_86Rf07xd4z`) which is what the API uses and what you should reference in code. The number exists purely so people can read, say and type it.
+Numbers are separate from IDs. Every record also has a prefixed ID (`or_86Rf07xd4z`) which is what the API uses and what you should reference in code. The number exists purely so people can read, say and type it.
 
 There are two ways to change it. Merchants can reshape **order numbers** from the dashboard without any code. Developers can replace the generator for **any** document type when the settings are not enough.
 

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

@@ -8,14 +8,14 @@ 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:
+Order routing decides which [Stock Location](../core-concepts/inventory.md#stock-locations) fulfills an order when Spree builds the order's fulfillments (`Order#rebuild_fulfillments!`) — orders created or edited by staff through the Admin API or dashboard, and items added to an order after it was placed. Storefront checkout does not go through it: a cart builds its fulfillments with `Spree::Stock::Coordinator`, and completing checkout copies them onto the order. 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/fulfillments.md#order-routing).
+Before starting, make sure you understand how [fulfillments](../core-concepts/fulfillments.md) and [stock locations](../core-concepts/inventory.md) work in Spree.
 
 | If the answer is "yes" | Pick |
 |---|---|
@@ -159,8 +159,8 @@ The contract is `Spree::OrderRouting::Strategy::Base`. There are no defaults —
 
 | 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_allocation` | The order's fulfillments are built (`Order#rebuild_fulfillments!`) | `Array<Spree::Stock::Package>` |
+| `#for_sale(fulfillment:)` | A fulfillment 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) |
 
@@ -205,10 +205,11 @@ module Acme
 
       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
+        units = Spree::Stock::InventoryUnitBuilder.new(order).units
+                  .select { |unit| assignment.variant_ids.include?(unit.variant_id) }
 
-        package = Spree::Stock::Packer.new(location, units, Spree.stock_splitters).packages.first
-        package.shipping_rates = Spree::Stock::Estimator.new(order).shipping_rates(package)
+        package = Spree::Stock::Packer.new(location, units, Spree.stock_splitters, owner: order).packages.first
+        package.delivery_rates = Spree::Stock::Estimator.new(order).delivery_rates(package)
         package
       end
 
@@ -223,8 +224,8 @@ 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.
+- **`for_allocation` returns `Spree::Stock::Package` objects.** The order's `rebuild_fulfillments!` turns those into `Spree::Fulfillment`s by calling `package.to_fulfillment`. Returning fulfillments directly will break the call site.
+- **Reuse the existing primitives.** `Spree::Stock::Packer`, `Spree::Stock::Estimator`, and `Spree::Stock::InventoryUnitBuilder` handle packing, delivery rate estimation, and building the units to pack. Custom strategies are about the location decision, not re-implementing the packing pipeline.
 
 ### Step 2: Register the Strategy
 
@@ -258,7 +259,7 @@ Resolution order: `channel.preferred_order_routing_strategy` → `store.preferre
 
 ### 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.
+Strategy tests are integration tests — build an order, instantiate the strategy, exercise the four methods, assert on the resulting packages and mocked side effects.
 
 ```ruby spec/models/acme/oms/strategy_spec.rb
 require 'rails_helper'
@@ -293,15 +294,15 @@ end
 
 - **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.
+- **Side effects in `for_sale` / `for_release`.** These fire while the order or fulfillment is changing status, so 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.
+Stock reservations and order routing are independent systems — 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 |
+| **When it fires** | Cart changes during checkout (add item, change quantity); released when the order is placed | When an order's fulfillments are built (`Order#rebuild_fulfillments!`) |
 | **What it decides** | How many units of a variant are held for this cart | Which `StockLocation` fulfills the order |
 | **Granularity** | Per-variant | Per-order |
 
@@ -310,7 +311,7 @@ Stock reservations and order routing are independent systems in 5.5 — they mak
 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.
+- **Don't relocate reservations from a custom strategy's `for_allocation`.** Reservations belong to the cart workflows that create and release them; moving them from a strategy races against those workflows.
 - **`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

package/dist/developer/how-to/custom-payment-method.md

@@ -98,11 +98,12 @@ class MyGateway < Spree::PaymentMethod
     provider_session = MyProvider::Client.new(preferred_api_key).create_session(
       amount: (total * 100).to_i, # amount in cents
       currency: order.currency,
-      metadata: { order_number: order.number }
+      metadata: { cart_id: order.prefixed_id }
     )
 
+    # `order:` receives the cart during checkout — assign it as the owner
     payment_sessions.create!(
-      order: order,
+      owner: order,
       amount: total,
       currency: order.currency,
       external_id: provider_session.id,
@@ -130,8 +131,7 @@ class MyGateway < Spree::PaymentMethod
   #
   # Responsibilities:
   # - Verify payment status with the provider
-  # - Create the Spree::Payment record
-  # - Transition the payment to the correct state
+  # - Create the Spree::Payment record and move it to the right status
   # - Mark the session as completed/failed
   #
   # Must NOT complete the order — that is handled by Carts::Complete
@@ -143,21 +143,19 @@ class MyGateway < Spree::PaymentMethod
     )
 
     if result.status == 'succeeded'
-      payment_session.process!
+      payment_session.process if payment_session.can_process?
 
-      # Create the Spree::Payment record
-      payment = payment_session.find_or_create_payment!
+      # Create the Spree::Payment record (or find the one a webhook already
+      # created) and mark it completed — captured: false leaves it pending
+      # for an authorization-only payment
+      payment_session.settle_payment!(captured: true)
 
-      # Transition the payment to completed
-      if payment.present? && !payment.completed?
-        payment.started_processing! if payment.checkout?
-        payment.complete! if payment.can_complete?
-      end
-
-      payment_session.complete!
+      payment_session.complete unless payment_session.completed?
     else
-      payment_session.fail!
+      payment_session.fail if payment_session.can_fail?
     end
+
+    payment_session
   end
 
   def payment_icon_name
@@ -171,8 +169,8 @@ end
 The frontend creates a session, then uses the provider's SDK to collect payment:
 
 ```typescript
-// 1. Get available payment methods
-const methods = await client.carts.paymentMethods.list(cart.id, options)
+// 1. Get available payment methods (embedded in the cart)
+const methods = cart.payment_methods
 
 // 2. Find your gateway (check session_required flag)
 const myGateway = methods.find(m => m.session_required)
@@ -327,9 +325,9 @@ class MyGateway < Spree::PaymentMethod
       setup_session.update!(
         payment_source: credit_card
       )
-      setup_session.complete!
+      setup_session.complete
     else
-      setup_session.fail!
+      setup_session.fail
     end
 
     setup_session

package/dist/developer/how-to/custom-promotion.md

@@ -61,7 +61,7 @@ end
 
 The `options` hash passed to `eligible?` can include `:user`, `:email`, and other context from the checkout flow.
 
-> **WARNING:** Accept **both** `Spree::Cart` and `Spree::Order` in `applicable?`. Promotions are evaluated on every cart change, long before the cart becomes an order, and a cart is its own model rather than an unfinished order. A rule guarding on `Spree::Order` alone silently never applies during checkout — the promotion just appears not to work. Every built-in rule accepts both.
+> **WARNING:** Accept **both** `Spree::Cart` and `Spree::Order` in `applicable?`. Promotions are evaluated on every cart change, long before the cart becomes an order, and a cart is its own model rather than an unfinished order. A rule that isn't applicable is skipped rather than failed, so a rule guarding on `Spree::Order` alone is silently ignored during checkout — its condition is never checked and the promotion applies as if the rule weren't there. Every built-in rule accepts both.
 
 #### Using Preferences
 
@@ -258,7 +258,7 @@ Like rules, registered actions surface automatically in the dashboard's promotio
 
 ## Custom Adjusters
 
-Not every charge or reduction is a promotion. A gift wrap fee, a payment surcharge, or loyalty pricing has no rules, no coupon codes, and no competition — it just needs to be on the order whenever it applies. That's an **adjuster**: a class invoked on every recalculation that owns a family of [Fee](../core-concepts/fees.md) or [Discount](../core-concepts/discounts.md) rows.
+Not every charge or reduction is a promotion. A gift wrap fee or a payment surcharge has no rules, no coupon codes, and no competition — it just needs to be on the order whenever it applies. That's an **adjuster**: a class invoked on every recalculation that owns a family of [Fee](../core-concepts/fees.md) rows.
 
 ```ruby server/app/models/my_app/adjusters/gift_wrap.rb
 module MyApp
@@ -284,11 +284,11 @@ Rails.application.config.after_initialize do
 end
 ```
 
-The contract is one method: `update`. It runs on every recalculation, so it must be idempotent — write the rows that should exist, remove the ones that shouldn't (that's why the example uses `find_or_initialize_by` keyed by `kind` rather than `create`). The `order` it receives is the cart during checkout and the order after placement, and rows attach to it either way.
+The contract is one method: `update`. It runs on every recalculation, so it must be idempotent — write the rows that should exist, remove the ones that shouldn't (that's why the example uses `find_or_initialize_by` keyed by `kind` rather than `create`). The `order` it receives is the cart during checkout. Adjusters don't run once an order is placed — a placed order's discount, fee and tax rows are frozen and only re-summed, so post-placement changes go through the admin discount and fee endpoints.
 
 There's no totals bookkeeping to do: after all adjusters run, Spree re-sums the typed rows into the order totals and the tax provider estimates tax on the result — a fee you write here gets taxed in the same pass, like any other fee.
 
-Custom discounts work the same way, writing `order.discounts` rows with your own `kind` (e.g. `'loyalty'`). Use a kind other than `'promotion'` — promotion rows belong to the promotion engine, which removes any it didn't write itself.
+Discount rows are limited to two kinds, `promotion` and `manual`, and promotion rows belong to the promotion engine, which removes any it didn't write itself. Reductions that need rules, codes or stacking are best modeled as a [custom promotion action](#custom-promotion-actions); note that the order's `discount_total` counts promotion discounts only.
 
 ## Testing
 

package/dist/developer/how-to/custom-search-provider.md

@@ -14,7 +14,7 @@ This guide walks you through building a custom search provider for Spree. By the
 
 Before starting, make sure you understand [how search and filtering works in Spree](../core-concepts/search-filtering.md).
 
-> **INFO:** Spree ships with a built-in [Meilisearch provider](../../integrations/search/meilisearch.md). If Meilisearch fits your needs, you don't need to build a custom provider — just configure it.
+> **INFO:** Spree offers an official [Meilisearch provider](../../integrations/search/meilisearch.md) in the `spree_meilisearch` gem. If Meilisearch fits your needs, you don't need to build a custom provider — just install and configure it.
 
 ## Architecture
 
@@ -22,7 +22,7 @@ Before starting, make sure you understand [how search and filtering works in Spr
 Store API Request (locale=de, currency=EUR)
   │
   ├─ AR Scope (security + visibility)
-  │   store.products.active(currency).accessible_by(ability)
+  │   store.products.available(now, currency), narrowed to the channel/catalogs
   │
   └─ Search Provider (search + filter + facets)
        ├─ Database (default): ILIKE + Ransack + FiltersAggregator
@@ -109,7 +109,7 @@ Products are indexed as **one document per market × locale** combination. The `
 
 ```ruby app/models/my_app/search_provider/typesense.rb
 def index(product)
-  documents = Spree::SearchProvider::ProductPresenter.new(product, store).call
+  documents = presenter_class.new(product, store).call
   documents.each do |doc|
     client.collections[index_name].documents.upsert(doc)
   end
@@ -125,8 +125,15 @@ def remove_by_id(prefixed_id)
     filter_by: "product_id:=#{prefixed_id}"
   )
 end
+
+# The registered presenter — SpreeMeilisearch::ProductPresenter when the gem is installed
+def presenter_class
+  Spree::Dependencies.search_product_presenter_class
+end
 ```
 
+> **NOTE:** `SpreeMeilisearch::ProductPresenter` ships with the `spree_meilisearch` gem — add the gem to reuse its document shape. Otherwise, write your own presenter and register it with `Spree::Dependencies.search_product_presenter`.
+
 The `ProductPresenter` returns an array of documents. For a store with US (USD/English) and EU (EUR/German+French) markets, one product produces 3 documents — each with flat `name`, `price`, `locale`, `currency` fields.
 
 ## Step 4: Implement Bulk Reindex
@@ -198,7 +205,7 @@ Spree::SearchProvider::SearchResult.new(
 ### ProductPresenter
 
 ```ruby
-documents = Spree::SearchProvider::ProductPresenter.new(product, store).call
+documents = SpreeMeilisearch::ProductPresenter.new(product, store).call
 # => [
 #   { prefixed_id: "prod_abc_en_USD", product_id: "prod_abc", locale: "en",
 #     currency: "USD", name: "Blue Shirt", price: 29.99, ... },
@@ -233,4 +240,4 @@ Document shaping for `cf_*` fields stays on `search_product_presenter` — the o
 ## Related Documentation
 
 - [Search & Filtering](../core-concepts/search-filtering.md) — Store API search reference
-- [Meilisearch Integration](../../integrations/search/meilisearch.md) — Built-in Meilisearch provider setup
+- [Meilisearch Integration](../../integrations/search/meilisearch.md) — Meilisearch provider setup

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

@@ -1,15 +1,15 @@
 ---
 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).
+description: Step-by-step guide to extending Spree's stock splitter chain — break a location's allocation into multiple fulfillments along your own axis (refrigeration, gift wrap, bin size, hazmat, anything you need to physically separate).
 ---
 
 ## Overview
 
-When [Order Routing](../core-concepts/fulfillments.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.
+When [Order Routing](custom-order-routing.md) 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.
+Spree ships with three splitters out of the box: `DeliveryProfile` (keeps each package to a single [delivery profile](../core-concepts/delivery-setup.md#delivery-profiles)), `Backordered` and `Weight`. The default chain is `DeliveryProfile` then `Backordered`; `Weight` is opt-in. 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/fulfillments.md#stock-splitters) and the [order routing](../core-concepts/fulfillments.md#order-routing) layer that runs before splitters.
+Before starting, make sure you understand [how delivery profiles split a cart](../core-concepts/delivery-setup.md#delivery-profiles) and the [order routing](custom-order-routing.md) layer that runs before splitters.
 
 | If the answer is "yes" | Pick |
 |---|---|
@@ -74,12 +74,12 @@ end
 
 #### 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:
+Each `package.contents` is an array of `Spree::Stock::ContentItem` — wrappers around a `Spree::FulfillmentItem`. The 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.inventory_unit  # The Spree::FulfillmentItem (gives access to line_item, quantity, etc.)
+content.weight          # Convenience: variant.weight × quantity
 content.state           # :on_hand or :backordered
 ```
 
@@ -90,43 +90,44 @@ So the splitter's job is "look at each package's contents, decide which contents
 Splitters are registered globally on `Rails.application.config.spree.stock_splitters` — every order runs through the full chain. Add yours in `config/initializers/spree.rb`:
 
 ```ruby config/initializers/spree.rb
-Rails.application.config.to_prepare do
+Rails.application.config.after_initialize 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.
+Spree assigns its default chain in its own `after_initialize`, which runs after your initializer files — so a splitter appended at the top level of the file, or in a `to_prepare` block, is overwritten at boot. Registering in `after_initialize` runs after Spree's defaults. The chain holds the class loaded at boot, so restart the server in development after changing the splitter.
 
 #### 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
-]
+Rails.application.config.after_initialize do
+  Rails.application.config.spree.stock_splitters = [
+    Spree::Stock::Splitter::DeliveryProfile,
+    Spree::Stock::Splitter::Refrigerated,        # custom one slotted in
+    Spree::Stock::Splitter::Backordered
+  ]
+end
 ```
 
 #### 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).
+1. **Coarse before fine.** `DeliveryProfile` runs first by default because it groups packages by delivery profile — which decides the delivery methods a package can use — 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 profile (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.
+Splitter tests are unit tests — instantiate a `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(:packer)         { Spree::Stock::Packer.new(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) } }
 
@@ -162,8 +163,8 @@ RSpec.describe Spree::Stock::Splitter::Refrigerated, type: :model do
   end
 
   def content_item_for(variant)
-    inventory_unit = build_stubbed(:inventory_unit, variant: variant)
-    Spree::Stock::ContentItem.new(inventory_unit, :on_hand)
+    fulfillment_item = build_stubbed(:fulfillment_item, variant: variant)
+    Spree::Stock::ContentItem.new(fulfillment_item, :on_hand)
   end
 end
 ```
@@ -197,8 +198,8 @@ Splitters and routing run in series, not in parallel — every package a splitte
 |---|---|---|
 | 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 |
+| 3 | Cross-location dedup | `Prioritizer.Adjuster` walks packages in rank order, assigns each unit to the first package with on-hand stock |
+| 4 | Rate estimation | `Estimator` attaches delivery rates |
 
 Practical implications:
 
@@ -208,6 +209,6 @@ Practical implications:
 
 ## Next Steps
 
-- [Shipments — Stock Splitters](../core-concepts/fulfillments.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
+- [Delivery Setup — Delivery profiles](../core-concepts/delivery-setup.md#delivery-profiles) — Why every package keeps to a single delivery profile
+- [Build Custom Order Routing](custom-order-routing.md) — The other layer of split-fulfillment customization
 - [Custom Fields](../core-concepts/metafields.md) — Tag variants with the data your splitter reads