@spree/docs 0.1.44 → 0.1.46

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

@@ -3,6 +3,8 @@ title: Inventory
 description: Stock locations, stock items, stock movements, and inventory tracking
 ---
 
+import { Since } from '/snippets/since.mdx';
+
 ## Overview
 
 Each [Variant](products.md#variants) has a `StockItem` that tracks its inventory at a specific location. A variant can have multiple stock items if it's available at multiple stock locations.
@@ -11,6 +13,8 @@ When products are sold or returned, individual `InventoryUnit` records track eac
 
 Adding new inventory to an out-of-stock product that has backorders will first fill the backorders, then update the available count with the remainder.
 
+During checkout, Spree holds stock with time-limited [Stock Reservations](#stock-reservations) to prevent two customers from buying the same last unit simultaneously.
+
 ### Inventory Model Diagram
 
 ```mermaid
@@ -52,14 +56,24 @@ erDiagram
         integer shipment_id
     }
 
+    StockReservation {
+        integer quantity
+        datetime expires_at
+        integer stock_item_id
+        integer line_item_id
+        integer order_id
+    }
+
     StockLocation ||--o{ StockItem : "has many"
     StockLocation ||--o{ StockTransfer : "source"
     StockLocation ||--o{ StockTransfer : "destination"
     Variant ||--o{ StockItem : "has many"
     Variant ||--o{ InventoryUnit : "has many"
     StockItem ||--o{ StockMovement : "has many"
+    StockItem ||--o{ StockReservation : "has many"
     StockTransfer ||--o{ StockMovement : "has many"
     Order ||--o{ InventoryUnit : "has many"
+    Order ||--o{ StockReservation : "has many"
     Shipment ||--o{ InventoryUnit : "has many"
 ```
 
@@ -69,6 +83,7 @@ erDiagram
 - **Stock Movement** → Records changes to Stock Item quantities (purchases, returns, transfers)
 - **Stock Transfer** → Moves inventory between Stock Locations, creating Stock Movements at source and destination
 - **Inventory Unit** → Represents individual units in [Orders](orders.md) and [Shipments](shipments.md)
+- **Stock Reservation** → Time-limited soft hold on a Stock Item during checkout, scoped to a specific Order and Line Item
 
 ## Inventory Management
 
@@ -151,6 +166,47 @@ Here's the list of attributes for the Stock Movement model:
 
 Stock Movements are crucial for maintaining accurate inventory levels and for historical tracking of inventory adjustments.
 
+## Stock Reservations 
+
+Stock Reservations are a time-limited soft hold on stock during checkout. When a customer enters checkout, Spree holds the items in their cart for a limited time so other shoppers see reduced availability immediately. Two customers can no longer both pass the availability check on the same last unit only to have one of them fail at order completion.
+
+### What changes for the storefront
+
+Availability now subtracts the units other customers are holding in active checkouts. Whenever you read whether a variant is in stock — whether for a product page, cart line, or checkout summary — Spree returns the post-reservation number automatically. There's nothing for the storefront to compute and physical stock counts on each `StockItem` are never modified by reservations; reservations are an independent layer that's consulted at read time and cleaned up by background jobs.
+
+### Lifecycle
+
+| Trigger | Action |
+|---|---|
+| Customer enters checkout | A reservation is created for each line item with an expiry timestamp |
+| Customer continues mutating the cart while in checkout | The expiry is pushed forward |
+| Customer completes the order | The reservation is released; physical stock is decremented as before |
+| Customer empties or abandons the cart | The reservation is released or expires automatically |
+
+Reservations attach to each line item; when a line item or order is removed, the reservation goes with it.
+
+### Configuration
+
+| Setting | Default | Purpose |
+|---|---|---|
+| `Spree::Config[:stock_reservations_enabled]` | `true` | Global kill switch. When `false`, reservations are not created and availability ignores them — behavior matches pre-5.5. |
+| `Spree::Config[:default_stock_reservation_ttl_minutes]` | `10` | Fallback hold duration when a Store doesn't override. |
+| `store.preferred_stock_reservation_ttl_minutes` | inherits global | Per-Store override. |
+
+TTL is a Store-level setting — it's a checkout-experience policy, not a warehouse property. A multi-location cart never has to merge conflicting TTLs from different warehouses.
+
+### Insufficient stock during checkout
+
+When a cart change in checkout would push the order beyond available stock, the change is rejected up front. The customer sees a validation error immediately, instead of progressing through payment only to fail at the final submit.
+
+### Background expiry
+
+Abandoned checkouts leave behind expired reservation rows. Spree provides a job to clean them up but does **not** auto-schedule it — your application's job runner needs to invoke it periodically (every minute is typical). See the [5.4 to 5.5 upgrade guide](../upgrades/5.4-to-5.5.md#schedule-the-stock-reservations-expiry-job) for sidekiq-cron, solid_queue, and good_job snippets.
+
+### Backorderable items
+
+If a stock item is marked backorderable, it represents unlimited supply, so reservations are skipped entirely for that item. Availability is unaffected.
+
 ## Inventory Units
 
 As we mentioned above, back-ordered, sold, or shipped products are stored as individual `InventoryUnit` objects so they can have relevant information attached to them.

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

@@ -0,0 +1,99 @@
+---
+title: Upgrading to Spree 5.5
+description: This guide covers upgrading a Spree 5.4 application to Spree 5.5.
+---
+
+> **INFO:** Before proceeding to upgrade, please ensure you're at [Spree 5.4](5.3-to-5.4.md).
+
+## Upgrade steps
+
+### Update gems
+
+  ```bash
+  bundle update
+  ```
+
+### Fetch and run missing migrations
+
+  ```bash
+  bin/rake spree:install:migrations && bin/rails db:migrate
+  ```
+
+### 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) 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.
+
+### (Optional) 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.
+
+## Behavior changes worth knowing
+
+### 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.

package/package.json

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