@spree/docs 0.1.177 → 0.1.178

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

@@ -1,277 +0,0 @@
----
-title: Upgrading to Spree 5.4
-description: Upgrade a Spree 5.3 application to Spree 5.4 — remove spree_sample, update gems, run migrations, switch to AdminUserMethods, and backfill image thumbnail IDs.
----
-
-> **INFO:** Before proceeding to upgrade, please ensure you're at [Spree 5.3](5.2-to-5.3.md)
-
-## Upgrade steps
-
-### Remove `spree_sample` gem from your Gemfile
-
-Samples are now included in the `spree` gem. If you've added previously `spree_sample` to your Gemfile, remove it by running:
-
-  ```bash
-  bundle remove spree_sample
-  ```
-
-### Update gems
-
-  ```bash
-  bundle update
-  ```
-
-### Fetch and run missing migrations
-
-  ```bash
-  bin/rake spree:install:migrations && bin/rails db:migrate
-  ```
-
-### Fix your Admin user class
-
-Your admin user model needs to include the `Spree::AdminUserMethods` concern instead of `Spree::UserMethods`.
-Previously `UserMethods` bundled `AdminUserMethods` but that caused all kinds of issues.
-
-So if you have a model like this:
-
-```ruby
-class Spree::AdminUser < Spree::Base
-  include Spree::UserMethods
-  
-  # ... other model code ...
-end
-```
-
-You need to change it to this:
-
-```ruby
-class Spree::AdminUser < Spree::Base
-  include Spree::AdminUserMethods
-  
-  # ... other model code ...
-end
-```
-
-By default that file is located at `app/models/spree/admin_user.rb`.
-
-### Backfill Image Thumbnail IDs
-
-Spree 5.4 adds a `primary_media` association to both `Product` and `Variant` models. This greatly speeds up rendering Product lists everywhere (API, Admin Dashboard and `spree_storefront`), as previously we've had to load all media/images for each product and determine which one is the one to render a thumbnail.
-
-To generate the new association you will need to run a rake task (both in development and production environments):
-
-  ```bash
-  bin/rails spree:media:backfill_primary_media
-  ```
-
-As above, this process can take a while depending on the size of your product catalog.
-
-For new products this will be set automatically and you won't need to run this rake task more than once.
-
-### Prefixed IDs
-
-Spree 5.4 by default uses prefixed IDs for resources (eg. `prod_6VsgxZbenF`) instead of just IDs from the database. These IDs are now used in Admin Dashboard, API v3, Events system and Webhooks.
-
-#### Event Subscribers
-
-If you previously added Subscribers for Events, eg. `order.completed` with code such as:
-
-```ruby
-module MyApp
-  class OrderAuditSubscriber < Spree::Subscriber
-    subscribes_to 'order.completed'
-
-    on 'order.completed', :log_order_completed
-
-    private
-
-    def find_order(event)
-      Spree::Order.find(event.payload[:id])
-    end
-  end
-end
-```
-
-You will need to update your code to use the new prefixed IDs, from:
-
-```ruby
-Spree::Order.find(event.payload[:id])
-```
-
-to:
-
-```ruby
-Spree::Order.find_by_prefix_id!(event.payload[:id])
-```
-
-You can also use `find_by_prefix_id` without the bang (`!`) to gracefully handle cases where the record might not exist.
-
-#### Adding Prefixed IDs support to your custom models
-
-All models inheriting from `Spree::Base` (or `Spree.base_class`) can support Prefixed IDs by adding the following code to your model:
-
-```ruby
-class MyModel < Spree::Base
-  has_prefix_id :mm
-  
-  # ...
-end
-```
-
-Prefix length isn't limited by default, but we recommend to keep it short.
-
-### Migrate Checkout Zones to Markets
-
-Spree 5.4 introduces [Markets](../core-concepts/markets.md) as the primary way to manage which countries are available for checkout, along with their currencies and locales. The legacy `checkout_zone` field on the Store model is now deprecated and will be removed in Spree 6.0.
-
-New stores automatically get a default market created from their `default_country` — no manual setup needed. For existing stores that used `checkout_zone`, run the migration rake task:
-
-  ```bash
-  bin/rake spree:markets:migrate_checkout_zones
-  ```
-
-This will:
-1. Read the `checkout_zone` countries from each store
-2. Create a default Market with those countries, currency, and locale
-3. Clear the `checkout_zone_id` column
-
-> **WARNING:** You will need to run this rake task locally and on your production environment. After running, verify your markets are set up correctly in the Admin Dashboard under **Settings → Markets**.
-
-#### Deprecated Store methods
-
-The following Store methods now emit deprecation warnings and will be removed in Spree 5.5:
-
-| Deprecated method | Replacement |
-|---|---|
-| `store.checkout_zone` | Use [Markets](../core-concepts/markets.md) to manage countries |
-| `store.checkout_zone=` | Use [Markets](../core-concepts/markets.md) to manage countries |
-
-The `store.default_country` reader now returns the first country (by name) from the store's default market. The `store.default_country_iso=` setter still works and is used to set the country when creating a store — a default market is automatically created from it.
-
-#### Code that references `checkout_zone` for tax
-
-If your application used `store.checkout_zone` as a tax zone fallback, update it to use `Spree::Zone.default_tax` instead:
-
-```ruby
-# Before
-zone = current_store.checkout_zone
-
-# After
-zone = Spree::Zone.default_tax
-```
-
-### ActiveMerchant removed from Spree Core
-
-Spree 5.4 no longer depends on the `activemerchant` gem. All internal usages have been replaced with lightweight Spree-native classes:
-
-| ActiveMerchant class | Spree replacement |
-|---|---|
-| `ActiveMerchant::Billing::Response` | `Spree::PaymentResponse` |
-| `ActiveMerchant::ConnectionError` | `Spree::PaymentConnectionError` |
-
-`Spree::PaymentResponse` is a drop-in replacement with the same constructor signature:
-
-```ruby
-Spree::PaymentResponse.new(success, message, params = {}, options = {})
-```
-
-It supports the same methods: `success?`, `message`, `params`, `authorization`, `avs_result`, `cvv_result`, `test?`, and YAML serialization (for log entries).
-
-#### Updating custom payment methods
-
-If you have a custom payment method (gateway) that returns `ActiveMerchant::Billing::Response`, update it to return `Spree::PaymentResponse` instead:
-
-```ruby
-# Before
-def authorize(money, source, options = {})
-  # ...
-  ActiveMerchant::Billing::Response.new(true, 'Success', {},
-    authorization: transaction_id, test: test?)
-end
-
-# After
-def authorize(money, source, options = {})
-  # ...
-  Spree::PaymentResponse.new(true, 'Success', {},
-    authorization: transaction_id, test: test?)
-end
-```
-
-If your gateway rescues `ActiveMerchant::ConnectionError`, update it to rescue `Spree::PaymentConnectionError`:
-
-```ruby
-# Before
-rescue ActiveMerchant::ConnectionError => e
-
-# After
-rescue Spree::PaymentConnectionError => e
-```
-
-#### Using `spree_gateway` or other ActiveMerchant-based extensions
-
-If you use the [`spree_gateway`](https://github.com/spree/spree_gateway) gem or another extension that depends on ActiveMerchant, add `activemerchant` directly to your application's `Gemfile`:
-
-```ruby
-gem 'activemerchant'
-```
-
-These extensions will continue to work — Spree's `LogEntry#parsed_details` still deserializes `ActiveMerchant::Billing::Response` objects when the gem is present.
-
-#### Address hash method renamed
-
-`Spree::Address#active_merchant_hash` has been renamed to `#gateway_hash`. A backwards-compatible alias is provided, so existing code continues to work without changes.
-
-### (Optional) Install Legacy API v2 extension
-
-Spree 5.4 ships with API v3, which marks deprecation of API v2. API v2 is still available but you need to install it separately. If you currently use API v2, you can do this by running the following command:
-
-  ```bash
-  bundle add spree_legacy_api_v2
-  ```
-  
-If you have tests for API v2 endpoints in your application, you will need to include some files in your `rails_helper.rb`:
-
-  ```ruby
-  require 'jsonapi/rspec'
-  require 'spree_legacy_api_v2/testing_support/v2/base'
-  require 'spree_legacy_api_v2/testing_support/factories'
-  require 'spree_legacy_api_v2/testing_support/v2/current_order'
-  require 'spree_legacy_api_v2/testing_support/v2/platform_contexts'
-  require 'spree_legacy_api_v2/testing_support/v2/serializers_params'
-  
-  RSpec.configure do |config|
-    config.include JSONAPI::RSpec, type: :request # required for API v2 request specs
-  end
-  ```
-
-Also, add `jsonapi-rspec` gem to your `Gemfile`:
-
-  ```ruby
-  gem 'jsonapi-rspec', group: :test
-  ```
-  
-And run `bundle install`
-
-### (Optional) Install Legacy Product Properties extension
-
-Product Properties have been extracted from Spree core to a separate gem `spree_legacy_product_properties`. Product Properties were already deprecated in favor of [Metafields](../core-concepts/metafields.md) and disabled by default since Spree 5.1.
-
-If you have `product_properties_enabled: true` in your Spree configuration or rely on Product Properties in any way, install the extension:
-
-  ```bash
-  bundle add spree_legacy_product_properties
-  ```
-
-No data migration is needed — the gem uses the same database tables. All existing product properties, property definitions, and associations will continue to work as before.
-
-> **WARNING:** If you skip this step and had Product Properties enabled, any code referencing `product.product_properties`, `product.property()`, `product.set_property()`, or the admin Properties page will stop working.
-
-### (Optional) Install Spree Posts extension
-
-Posts and Post Categories management were extracted from Spree core into a separate gem `spree_posts`.
-
-If you use these features before run this command to restore them:
-
-```bash
-bundle add spree_posts
-```

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

@@ -1,301 +0,0 @@
----
-title: Upgrading to Spree 5.5
-description: Step-by-step guide to upgrading a Spree 5.4 application to Spree 5.5, including gem updates, migrations, and breaking changes to review.
----
-
-> **INFO:** Before proceeding to upgrade, please ensure you're at [Spree 5.4](5.3-to-5.4.md).
-
-The upgrade is usually completed in five steps:
-
-1. **Update the Ruby gems** which power Spree API
-2. **Run database migrations** — to migrate your existing schema to the new version
-3. **Run data backfills** — to move your existing data into the new schema and power new features
-4. Apply optional configuration and review behavior changes — to take advantage of new features and avoid surprises
-
-## How to upgrade
-
-For applications created via `create-spree-app` command we greatly recommend using the Spree CLI to perform the upgrade. It provides a guided experience with prompts and handles the first three steps for you. If you prefer to run the commands manually or not using docker for local development, you can follow the "Without Spree CLI" path.
-
-
-```bash Spree CLI (Docker)
-spree upgrade
-```
-
-```bash Without Spree CLI
-# cd backend if you're in the monorepo root
-bundle update
-bundle exec rake spree:install:migrations && bin/rails db:migrate
-bundle exec rake spree:upgrade
-```
-
-
-The **Spree CLI** path runs all three commands for you with prompts. Recommended for local development. If you don't have the CLI yet, either install it globally or run it through `npx`:
-
-```bash
-# install once and use `spree …` everywhere
-npm install -g @spree/cli
-
-# or invoke without installing (each command runs through npx)
-npx @spree/cli upgrade
-```
-
-The **Without Spree CLI** path is the bare equivalent. Use this on production: `bundle update` and `db:migrate` are part of your existing deploy pipeline (Heroku release phase, K8s init container, Capistrano hook, Render auto-migrate). Once the 5.5 release is up, run `bundle exec rake spree:upgrade` from a one-off dyno / job container / `kubectl exec` to perform the data backfills.
-
-Skipping versions and re-running are both safe — `bundle exec rake spree:upgrade` figures out what still needs to happen and does nothing on data that's already migrated.
-
-## What the upgrade does
-
-This is reference material — what `bundle exec rake spree:upgrade` (and equivalently `spree upgrade`) actually executes on your data. Skip if you trust the tool; read on if something failed or you're curious.
-
-### 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, the upgrade runs:
-
-
-```bash Spree CLI (Docker)
-spree rake spree:media:migrate_master_images_to_product_media
-```
-
-```bash Without Spree CLI
-bundle exec rake 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 Spree CLI (Docker)
-spree rake spree:media:migrate_master_images_to_product_media BATCH_SIZE=1000
-```
-
-```bash Without Spree CLI
-bundle exec rake 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 introduces [Sales Channels](../core-concepts/channels.md) — a per-store distribution surface (online storefront, POS, marketplace integration, wholesale portal). Products are published to a channel via the new `spree_product_publications` join table, and orders are attributed to a channel via `spree_orders.channel_id`.
-
-The migrations add a `default` boolean on `spree_channels`, a `store_id` column on `spree_products`, and create the new `spree_product_publications` table — **but they do not seed default channels, attach existing products to a store, or backfill order channels**. That work is done by an idempotent rake task:
-
-
-```bash Spree CLI (Docker)
-spree rake spree:channels:upgrade
-```
-
-```bash Without Spree CLI
-bundle exec rake spree:channels:upgrade
-```
-
-
-The task runs four sub-tasks in order:
-
-1. `spree:channels:create_defaults` — creates the default "Online Store" channel for every existing store (via `Store#ensure_default_channel`).
-2. `spree:upgrade:populate_publications` — for every product that doesn't yet have a `store_id`, picks a "home" store from the legacy `spree_products_stores` join (preferring the store flagged `default: true`, otherwise the earliest row), sets `spree_products.store_id`, and creates a `spree_product_publications` row on each attached store's default channel. Runs in a transaction per product so a partial failure leaves nothing half-applied.
-3. `spree:channels:backfill_order_channel_ids` — sets `spree_orders.channel_id` from the legacy `spree_orders.channel` string column. Unknown codes auto-create a new channel under that store. NULL/blank values map to the default channel.
-4. `spree:channels:backfill_product_publication_dates` — copies the deprecated `Product.available_on` and `Product.discontinue_on` columns into each publication's `published_at` / `unpublished_at` (only where the publication's date is currently NULL).
-
-The task is fully idempotent — safe to re-run if it fails partway, and a no-op on stores/products/orders that have already been upgraded.
-
-> **WARNING:** Until `spree:channels:upgrade` runs, every product has `store_id IS NULL` and is invisible to `Product.for_store(store)`. The admin product list, storefront catalog, and search indexer all return empty. Run the task immediately after `db:migrate`.
-
-### Reindex products
-
-The last step rebuilds the search index against the configured [search provider](../core-concepts/search-filtering.md):
-
-
-```bash Spree CLI (Docker)
-spree rake spree:search:reindex
-```
-
-```bash Without Spree CLI
-bundle exec rake spree:search:reindex
-```
-
-
-This is a no-op on the default Database provider (there is no external index to maintain). For Meilisearch — or any other external search provider — it is required, and it must run **after** the Channels upgrade: products only become visible to `Product.for_store` once they have a `store_id`, so reindexing before the channels step would index zero products. The manifest orders the steps accordingly.
-
-#### Multi-store catalogs
-
-If you have products attached to multiple stores via the legacy `spree_products_stores` join, the `populate_publications` task picks **one** "home" store per product and creates publications on every store's default channel. The `spree_products_stores` table is **kept** as legacy compat surface.
-
-For single-store deployments this is invisible; you can move on without touching `spree_products_stores` again.
-
-#### Behavioral changes from the Channels upgrade
-
-- Newly-created products in **the dashboard SPA** are auto-published on the store's default channel; the merchant can untick channels post-create via the Publishing card.
-- Newly-created products via the **Admin API** are NOT auto-published — the caller must supply `product_publications: [{ channel_id }]` on create or use `POST /api/v3/admin/channels/:id/add_products` afterwards.
-- `Product.available_on=` and `Product.discontinue_on=` setters emit deprecation warnings and now write to every per-channel publication's `published_at` / `unpublished_at`. Reading these attributes on a product prefers the current-channel publication's value over the legacy column.
-- `Spree::Channel#add_products(product_ids)` is idempotent and **preserves existing publication windows** when called without `published_at`/`unpublished_at` kwargs.
-
-Orders modified after the upgrade auto-set `channel_id` via the model's `before_validation :ensure_channel_presence` callback, so `backfill_order_channel_ids` is only strictly required for orders that aren't touched again post-upgrade — but running it 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 everyone has had a chance to run the backfill.
-
-## Update the Spree SDK
-
-Spree 5.5 ships alongside `@spree/sdk` 1.1. The backend upgrade never touches your frontend source — bump the SDK in every JavaScript consumer of the Store API and take it through your normal PR/CI cycle:
-
-```bash
-# create-spree-app projects: the Next.js storefront
-cd apps/storefront
-npm install @spree/sdk@^1.1
-```
-
-If you maintain a separate storefront repo or other integrations, repeat there. The `spree upgrade` command detects the conventional `apps/storefront` and reminds you with the currently-declared version in its "Next steps" panel.
-
-| Spree backend | `@spree/sdk` |
-|---|---|
-| 5.4 | 1.0.x |
-| 5.5 | 1.1+ |
-
-The SDK bump pairs with one storefront code change in this release: the [payment method `type` shorthand](#payment-method-type-on-the-wire-is-now-a-shorthand-not-a-rails-class-name) — update your gateway map when you bump.
-
-## Required post-upgrade configuration
-
-`bundle exec rake spree:upgrade` doesn't touch your job-runner config — every app uses a different scheduler, so this one is on you.
-
-### 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).
-
-If you skip this step, expired reservations accumulate in the table indefinitely. The Quantifier still ignores them at availability-check time (so customers see correct stock), but the table grows unbounded.
-
-#### sidekiq-cron
-
-```yaml
-# config/sidekiq_cron.yml
-expire_stock_reservations:
-  cron: "* * * * *"
-  class: "Spree::StockReservations::ExpireJob"
-  queue: default
-```
-
-#### solid_queue
-
-```yaml
-# config/recurring.yml
-expire_stock_reservations:
-  schedule: every minute
-  class: Spree::StockReservations::ExpireJob
-```
-
-#### good_job
-
-```ruby
-# config/initializers/good_job.rb
-Rails.application.configure do
-  config.good_job.cron = {
-    expire_stock_reservations: {
-      cron: '* * * * *',
-      class: 'Spree::StockReservations::ExpireJob'
-    }
-  }
-end
-```
-
-## Optional tuning
-
-Defaults are sensible for most stores. Reach for these only if you have a specific reason.
-
-### Tune the reservation TTL
-
-The default reservation TTL is **10 minutes**. To override globally:
-
-```ruby
-# config/initializers/spree.rb
-Spree::Config[:default_stock_reservation_ttl_minutes] = 15
-```
-
-To override per Store, set the preference on the Store record:
-
-```ruby
-store.update!(preferred_stock_reservation_ttl_minutes: 20)
-```
-
-The per-Store value, when set, takes precedence over the global default.
-
-### Disable Stock Reservations
-
-Stock reservations are enabled by default. To opt out and revert to pre-5.5 behavior (no holds during checkout, Quantifier returns raw `count_on_hand`):
-
-```ruby
-# config/initializers/spree.rb
-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.
-
-### 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` **was removed in Spree 6.0**. It exists only on the 5.5/5.6 line, as a temporary escape hatch while you evaluate the Rules strategy. Stores still carrying this value fall back to the default Rules strategy on 6.0 (with a logged warning), so clear the preference before upgrading.
-
-## Behavior changes to review
-
-These don't require any rake task — but storefronts, integrations, and merchant-facing dashboards may need code changes to handle them correctly.
-
-### Cart changes during checkout can now fail with insufficient stock
-
-When a customer is in checkout and tries to add an item, increase a quantity, or remove a line item, Spree now re-checks whether the cart still fits in available stock (subtracting what other customers are holding in their own active checkouts). If it doesn't, the change is rejected up front instead of silently completing and failing later at order submission.
-
-Storefronts and custom integrations that act on the cart should expect this new failure path and surface the error to the customer.
-
-### 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.
-
-### Payment method `type` on the wire is now a shorthand, not a Rails class name
-
-The `type` attribute on `Spree::PaymentMethod` (returned by both the Store API and the Admin API) used to be the full Rails STI class name — `"SpreeStripe::Gateway"`, `"SpreeAdyen::Gateway"`, `"Spree::PaymentMethod::Check"`. In 5.5 it switches to a stable shorthand derived from `Spree::Base.api_type`:
-
-| Class                              | Pre-5.5 `type`                  | 5.5+ `type`        |
-| ---------------------------------- | ------------------------------- | ------------------ |
-| `Spree::PaymentMethod::Check`      | `Spree::PaymentMethod::Check`   | `check`            |
-| `Spree::PaymentMethod::StoreCredit`| `Spree::PaymentMethod::StoreCredit` | `store_credit` |
-| `SpreeStripe::Gateway`             | `SpreeStripe::Gateway`          | `stripe`           |
-| `SpreeAdyen::Gateway`              | `SpreeAdyen::Gateway`           | `adyen`            |
-| `SpreePaypalCheckout::Gateway`     | `SpreePaypalCheckout::Gateway`  | `paypal_checkout`  |
-| `SpreeRazorpayCheckout::Gateway`   | `SpreeRazorpayCheckout::Gateway`| `razorpay_checkout`|
-
-The shorthand is also what `POST /api/v3/admin/payment_methods` now expects as `type` when creating a new method, and what `GET /api/v3/admin/payment_methods/types` returns in its `type` field.
-
-This is a breaking change for any storefront or integration that **string-matches the payment method type** to pick which payment-gateway SDK to load. The official Spree Next.js storefront resolves the gateway in `src/lib/utils/payment-gateway.ts`; update its map to key on the new shorthand:
-
-```ts
-const GATEWAY_TYPE_MAP: Record<string, GatewayId> = {
-  // 5.5+ shorthands
-  stripe: "stripe",
-  adyen: "adyen",
-  paypal_checkout: "paypal",
-  razorpay_checkout: "razorpay",
-  // Pre-5.5 Rails class names — keep while you have older backends in
-  // the field; drop once everyone is on 5.5+.
-  "SpreeStripe::Gateway": "stripe",
-  "SpreeAdyen::Gateway": "adyen",
-  "SpreePaypalCheckout::Gateway": "paypal",
-  "SpreeRazorpayCheckout::Gateway": "razorpay",
-};
-```
-
-If you maintain a custom storefront, search it for the legacy class strings (`"SpreeStripe::Gateway"`, `"SpreePaypalCheckout::Gateway"`, etc.) and add the corresponding 5.5+ shorthand alongside each one. The symptom of missing this is checkout rendering a generic "this payment method is not yet supported" placeholder instead of the gateway's SDK form.
-
-### 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](#opt-out-of-rules-based-order-routing) above.