@spree/docs 0.1.45 → 0.1.47

package/dist/api-reference/webhooks-events.md

@@ -37,7 +37,7 @@ For details on creating webhook endpoints and verifying signatures, see [Webhook
 
 Events: `order.created`, `order.updated`, `order.completed`, `order.canceled`, `order.resumed`, `order.paid`, `order.shipped`
 
-Order payloads include nested `items`, `shipments`, `payments`, `bill_address`, `ship_address`, `payment_methods`, and `promotions`.
+Order payloads include nested `items`, `fulfillments` (the Store API name for shipments), `payments`, `billing_address`, `shipping_address`, `payment_methods`, and `discounts`.
 
 ```json
 {
@@ -49,12 +49,12 @@ Order payloads include nested `items`, `shipments`, `payments`, `bill_address`,
   "special_instructions": null,
   "currency": "USD",
   "item_count": 3,
-  "shipment_state": "shipped",
+  "fulfillment_status": "shipped",
   "payment_state": "paid",
   "item_total": "89.99",
   "display_item_total": "$89.99",
-  "ship_total": "10.00",
-  "display_ship_total": "$10.00",
+  "delivery_total": "10.00",
+  "display_delivery_total": "$10.00",
   "adjustment_total": "0.00",
   "display_adjustment_total": "$0.00",
   "promo_total": "0.00",
@@ -90,19 +90,20 @@ Order payloads include nested `items`, `shipments`, `payments`, `bill_address`,
       "..."
     }
   ],
-  "shipments": [
+  "fulfillments": [
     {
-      "id": "shp_9xPq4wMn",
+      "id": "ful_9xPq4wMn",
       "number": "H123456789",
-      "state": "shipped",
+      "status": "shipped",
+      "fulfillment_type": "shipping",
       "tracking": "1Z999AA10123456784",
       "tracking_url": "https://tools.usps.com/go/TrackConfirmAction?tLabels=1Z999AA10123456784",
       "cost": "10.00",
       "display_cost": "$10.00",
-      "shipped_at": "2025-01-16T14:00:00Z",
-      "shipping_method": { "id": "sm_2wMn7xRt", "..." },
+      "fulfilled_at": "2025-01-16T14:00:00Z",
+      "delivery_method": { "id": "dm_2wMn7xRt", "..." },
       "stock_location": { "id": "sl_2wMn7xRt", "..." },
-      "shipping_rates": [],
+      "delivery_rates": [],
       "..."
     }
   ],
@@ -268,29 +269,30 @@ Payment setup session payloads include a nested `payment_method`.
 
 Events: `shipment.created`, `shipment.updated`, `shipment.shipped`, `shipment.canceled`, `shipment.resumed`
 
-Shipment payloads include nested `shipping_method`, `stock_location`, and `shipping_rates`.
+The Store API/SDK exposes shipments as `fulfillments`, and webhook payloads use the same V3 serializer. Payloads include nested `delivery_method`, `stock_location`, and `delivery_rates`.
 
 ```json
 {
-  "id": "shp_9xPq4wMn",
+  "id": "ful_9xPq4wMn",
   "number": "H123456789",
-  "state": "shipped",
+  "status": "shipped",
+  "fulfillment_type": "shipping",
   "tracking": "1Z999AA10123456784",
   "tracking_url": "https://tools.usps.com/go/TrackConfirmAction?tLabels=1Z999AA10123456784",
   "cost": "10.00",
   "display_cost": "$10.00",
-  "shipped_at": "2025-01-16T14:00:00Z",
+  "fulfilled_at": "2025-01-16T14:00:00Z",
   "created_at": "2025-01-15T10:30:00Z",
   "updated_at": "2025-01-16T14:00:00Z",
-  "shipping_method": {
-    "id": "sm_2wMn7xRt",
+  "delivery_method": {
+    "id": "dm_2wMn7xRt",
     "..."
   },
   "stock_location": {
     "id": "sl_2wMn7xRt",
     "..."
   },
-  "shipping_rates": []
+  "delivery_rates": []
 }
 ```
 
@@ -448,7 +450,7 @@ Events: `stock_movement.created`, `stock_movement.updated`, `stock_movement.dele
   "quantity": -1,
   "action": "sold",
   "originator_type": "Spree::Shipment",
-  "originator_id": "shp_9xPq4wMn",
+  "originator_id": "ful_9xPq4wMn",
   "stock_item_id": "si_6nRt2xLq",
   "created_at": "2025-01-15T10:30:00Z",
   "updated_at": "2025-01-15T10:30:00Z"

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

@@ -70,7 +70,7 @@ Adjustments are created by two sources:
 
 ## Store API
 
-Adjustments appear in order responses when you expand line items or shipments:
+Adjustments appear in order responses when you expand line items or fulfillments:
 
 
 ```typescript SDK
@@ -93,7 +93,7 @@ order.included_tax_total
 ```
 
 ```bash cURL
-curl 'https://api.mystore.com/api/v3/store/orders/or_abc123?expand=items,shipments' \
+curl 'https://api.mystore.com/api/v3/store/orders/or_abc123?expand=items,fulfillments' \
   -H 'Authorization: Bearer pk_xxx' \
   -H 'X-Spree-Token: <token>'
 ```

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

@@ -306,10 +306,10 @@ Spree includes V3 serializers for all core models in [`api/app/serializers/spree
 
 | Serializer | Model |
 |------------|-------|
-| `OrderSerializer` | Orders with totals, states, nested line items, shipments, payments, addresses |
+| `OrderSerializer` | Orders with totals, statuses, nested line items, fulfillments, payments, addresses |
 | `ProductSerializer` | Products with pricing, stock status, availability |
 | `PaymentSerializer` | Payments with amounts, states, nested payment method and source |
-| `ShipmentSerializer` | Shipments with tracking, nested shipping method and rates |
+| `FulfillmentSerializer` | Fulfillments (shipments) with tracking, nested delivery method and delivery rates |
 | `LineItemSerializer` | Line items with quantity, pricing, nested option values |
 | `VariantSerializer` | Variants with SKU, pricing, nested option values |
 | `PriceSerializer` | Prices with amounts, currency, price list |

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/core-concepts/orders.md

@@ -67,13 +67,13 @@ The API returns these key fields on every order:
 | `currency` | Order currency (e.g., `USD`) |
 | `item_count` | Total number of items |
 | `item_total` / `display_item_total` | Sum of line item prices |
-| `ship_total` / `display_ship_total` | Shipping cost |
+| `delivery_total` / `display_delivery_total` | Delivery cost |
 | `tax_total` / `display_tax_total` | Total tax |
 | `promo_total` / `display_promo_total` | Total discount from promotions |
-| `adjustment_total` / `display_adjustment_total` | Sum of all adjustments (tax + shipping + promos) |
+| `adjustment_total` / `display_adjustment_total` | Sum of all adjustments (tax + delivery + promos) |
 | `total` / `display_total` | Final order total |
 | `payment_state` | Payment status (`balance_due`, `paid`, `credit_owed`, `failed`, `void`) |
-| `shipment_state` | Shipment status (`pending`, `ready`, `partial`, `shipped`, `backorder`) |
+| `fulfillment_status` | Fulfillment status (`pending`, `ready`, `partial`, `shipped`, `backorder`) |
 | `completed_at` | Timestamp when the order was placed |
 
 The `display_*` fields return formatted strings with currency symbols (e.g., `"$15.99"`).
@@ -183,10 +183,11 @@ await client.carts.update(cartId, {
   },
 })
 
-// Get shipments and select a shipping rate
-const { data: shipments } = await client.carts.shipments.list(cartId)
-await client.carts.shipments.update(cartId, shipments[0].id, {
-  selected_shipping_rate_id: 'sr_xxx',
+// Get fulfillments and select a delivery rate
+// (the Store API/SDK exposes shipments as `fulfillments`)
+const cart = await client.carts.get(cartId, { expand: ['fulfillments'] })
+await client.carts.fulfillments.update(cartId, cart.fulfillments[0].id, {
+  selected_delivery_rate_id: 'rate_xxx',
 })
 
 // Create a payment session (e.g., Stripe)
@@ -218,12 +219,12 @@ curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx' \
     }
   }'
 
-# Select a shipping rate
-curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx/shipments/shp_xxx' \
+# Select a delivery rate
+curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx/fulfillments/ful_xxx' \
   -H 'Authorization: Bearer pk_xxx' \
   -H 'X-Spree-Token: abc123' \
   -H 'Content-Type: application/json' \
-  -d '{ "selected_shipping_rate_id": "sr_xxx" }'
+  -d '{ "selected_delivery_rate_id": "rate_xxx" }'
 
 # Complete the order
 curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/complete' \
@@ -271,7 +272,7 @@ const { data: orders } = await client.customer.orders.list()
 
 // Get a specific order with details
 const order = await client.orders.get('or_xxx', {
-  expand: ['items', 'shipments', 'payments'],
+  expand: ['items', 'fulfillments', 'payments'],
 })
 ```
 
@@ -281,7 +282,7 @@ curl 'https://api.mystore.com/api/v3/store/customer/orders' \
   -H 'Authorization: Bearer <jwt_token>'
 
 # Get a specific order
-curl 'https://api.mystore.com/api/v3/store/orders/or_xxx?expand=items,shipments,payments' \
+curl 'https://api.mystore.com/api/v3/store/orders/or_xxx?expand=items,fulfillments,payments' \
   -H 'Authorization: Bearer <jwt_token>'
 ```
 
@@ -306,14 +307,16 @@ When a variant is added to an order, the price is locked on the line item. If th
 | `failed` | Most recent payment attempt failed |
 | `void` | Order was canceled and payments voided |
 
-## Shipment States
+## Fulfillment Statuses
 
-| State | Description |
-|-------|-------------|
-| `pending` | All shipments are pending |
-| `ready` | All shipments are ready to ship |
-| `partial` | At least one shipment is shipped, others are not |
-| `shipped` | All shipments have been shipped |
+The order's `fulfillment_status` field summarizes the state of all fulfillments (the Store API/SDK exposes shipments as `fulfillments`).
+
+| Status | Description |
+|--------|-------------|
+| `pending` | All fulfillments are pending |
+| `ready` | All fulfillments are ready to ship |
+| `partial` | At least one fulfillment is shipped, others are not |
+| `shipped` | All fulfillments have been shipped |
 | `backorder` | Some inventory is on backorder |
 
 For more details, see [Shipments](shipments.md) and [Payments](payments.md).

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

@@ -237,7 +237,7 @@ After the customer completes payment, the frontend calls the Complete Payment Se
 
   **Step 4: Complete Order**
 
-The frontend calls `POST /carts/:id/complete` to finalize the order. Spree validates the order is ready (addresses, shipments, payment), advances through any remaining checkout states, and marks the order as complete.
+The frontend calls `POST /carts/:id/complete` to finalize the order. Spree validates the order is ready (addresses, fulfillments, payment), advances through any remaining checkout states, and marks the order as complete.
 
     This separation ensures the same flow works for all payment types — inline cards, offsite redirects, and wallet payments.
 

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

@@ -49,15 +49,19 @@ erDiagram
 
 ## Shipment Attributes
 
+The Store API/SDK exposes shipments as `fulfillments` with these attributes:
+
 | Attribute | Description | Example |
 |-----------|-------------|---------|
-| `number` | Unique shipment identifier | `H12345678901` |
+| `number` | Unique fulfillment identifier | `H12345678901` |
 | `tracking` | Carrier tracking number | `1Z999AA10123456784` |
-| `state` | Current shipment state | `shipped` |
-| `cost` | Shipping cost | `9.99` |
-| `shipped_at` | When the shipment was shipped | `2025-07-21T14:36:00Z` |
+| `status` | Current fulfillment status | `shipped` |
+| `fulfillment_type` | `shipping` or `digital` | `shipping` |
+| `cost` | Delivery cost | `9.99` |
+| `fulfilled_at` | When the fulfillment was shipped | `2025-07-21T14:36:00Z` |
 | `stock_location` | Where items ship from | `Warehouse NYC` |
-| `selected_shipping_rate` | The rate chosen by the customer | `{ cost: 9.99, name: "UPS Ground" }` |
+| `delivery_method` | The selected delivery method | `{ id: "dm_xxx", name: "UPS Ground" }` |
+| `delivery_rates` | Available rates for the customer to pick from | `[{ id: "rate_xxx", cost: "9.99", selected: true, ... }]` |
 
 ## Shipment States
 
@@ -84,35 +88,36 @@ During checkout, after the customer provides a shipping address, Spree calculate
 
 
 ```typescript SDK
-// Get shipments with available shipping rates
+// Get fulfillments with available delivery rates
+// (the Store API/SDK exposes shipments as `fulfillments`)
 const order = await client.orders.get(orderId, {
-  expand: ['shipments'],
+  expand: ['fulfillments'],
 })
 
-// Each shipment has available shipping rates
-order.shipments?.forEach(shipment => {
-  console.log(shipment.number)           // "H12345678901"
-  console.log(shipment.shipping_rates)   // [{ id: "sr_xxx", name: "UPS Ground", cost: "9.99", selected: true }, ...]
+// Each fulfillment has available delivery rates
+order.fulfillments?.forEach(fulfillment => {
+  console.log(fulfillment.number)         // "H12345678901"
+  console.log(fulfillment.delivery_rates) // [{ id: "rate_xxx", name: "UPS Ground", cost: "9.99", selected: true }, ...]
 })
 
-// Select a shipping rate
-await client.carts.shipments.update(cartId, shipment.id, {
-  selected_shipping_rate_id: 'sr_xxx',
+// Select a delivery rate
+await client.carts.fulfillments.update(cartId, fulfillment.id, {
+  selected_delivery_rate_id: 'rate_xxx',
 })
 ```
 
 ```bash cURL
-# Get shipments
-curl 'https://api.mystore.com/api/v3/store/carts/cart_xxx?expand=shipments' \
+# Get fulfillments
+curl 'https://api.mystore.com/api/v3/store/carts/cart_xxx?expand=fulfillments' \
   -H 'Authorization: Bearer pk_xxx' \
   -H 'X-Spree-Token: abc123'
 
-# Select a shipping rate
-curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx/shipments/shp_xxx' \
+# Select a delivery rate
+curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx/fulfillments/ful_xxx' \
   -H 'Authorization: Bearer pk_xxx' \
   -H 'X-Spree-Token: abc123' \
   -H 'Content-Type: application/json' \
-  -d '{ "selected_shipping_rate_id": "sr_xxx" }'
+  -d '{ "selected_delivery_rate_id": "rate_xxx" }'
 ```
 
 

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

@@ -132,7 +132,7 @@ Each webhook delivery sends a JSON payload with the following structure. The `da
     "item_count": 3,
     "currency": "USD",
     "items": [ ... ],
-    "shipments": [ ... ],
+    "fulfillments": [ ... ],
     "payments": [ ... ]
   },
   "metadata": {

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.45",
+  "version": "0.1.47",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",