@spree/docs 0.1.223 → 0.1.225

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

@@ -17,10 +17,19 @@ erDiagram
     StockLevel ||--o{ StockReservation : "held by checkouts"
     Order ||--o{ Fulfillment : "ships as"
     Fulfillment ||--o{ FulfillmentItem : "contains"
+    Supplier ||--o{ PurchaseOrder : "supplies"
+    PurchaseOrder ||--o{ PurchaseOrderItem : "orders"
+    StockTransfer ||--o{ StockTransferItem : "moves"
+    PurchaseOrder ||--o{ StockReceipt : "received as"
+    StockTransfer ||--o{ StockReceipt : "received as"
+    StockReceipt ||--o{ StockReceiptItem : "counts"
+    StockReceipt ||--o{ StockMovement : "lands"
 
     StockLevel {
         integer count_on_hand
         integer allocated_count
+        integer reserved_count
+        integer incoming_count
         boolean backorderable
     }
     StockLocation {
@@ -30,15 +39,21 @@ erDiagram
     }
 ```
 
-## The three numbers
+## The five numbers
 
-A stock level carries two counts, and a third is derived from them. Keeping them apart is what stops a warehouse from disagreeing with a website.
+A stock level carries four counts, and a fifth is derived from them. Keeping them apart is what stops a warehouse from disagreeing with a website.
 
 | | What it means |
 |---|---|
 | `count_on_hand` | What is physically on the shelf, right now |
 | `allocated_count` | How much of that is already spoken for by orders not yet shipped |
-| **`available_count`** | `count_on_hand − allocated_count` — what's actually sellable |
+| `reserved_count` | How much is held by checkouts still in progress |
+| `incoming_count` | How much is on its way here — on a purchase order placed with a supplier, or a transfer already in transit |
+| **`available_count`** | `count_on_hand − allocated_count` — what's actually sellable, before checkout holds |
+
+Reserved and incoming are kept as counters rather than worked out on every read, because the Inventory page in the dashboard reads them for every row, many times a day, and only a handful of things change them: entering or leaving checkout moves reserved; placing, cancelling, closing or receiving a purchase order or transfer moves incoming. Nothing else writes them. If a figure ever looks wrong, `rake spree:stock:recount_levels` recomputes both from their sources and reports every row it corrected — the same task the 6.0 upgrade runs to fill them in for existing stock.
+
+A transfer counts as incoming from the moment it is marked in transit, not when it is drafted: until the van leaves, nothing is moving. Units a delivery rejects at the dock leave incoming too — they are recorded on the receipt, but they are not coming.
 
 > **NOTE:** **Selling an item does not reduce `count_on_hand`.** Placing an order raises `allocated_count`; the physical count only drops when the parcel actually ships.
 > 
@@ -53,10 +68,11 @@ A stock location is somewhere stock physically sits: a warehouse, a shop, a thir
 | `name` | What staff call it |
 | `active` | Whether it can be used for new orders |
 | `default` | Used first when nothing else decides |
+| `kind` | What sort of place it is — `warehouse`, `store` or `fulfillment_center` |
 | `country_code`, `state_code`, `city`, `postal_code` | Where it is — used for shipping rates and for finding the nearest one |
 | `backorderable_default` | Whether new stock levels here allow backorders |
-| `fulfillable` | Whether orders can ship from here, or it's display-only stock |
-| `pickup` | Whether customers can collect here |
+| `pickup_enabled` | Whether customers can collect here |
+| `returns_enabled` | Whether customers can bring returns here |
 
 ```typescript Admin SDK
 const { data: locations } = await adminClient.stockLocations.list()
@@ -77,11 +93,11 @@ A stock level is the intersection of a variant and a location. They're created f
 ```typescript Admin SDK
 // Stock for one location
 const { data: levels } = await adminClient.stockLevels.list({
-  filter: { stock_location_id_eq: 'sl_xxx' },
+  stock_location_id_eq: 'sloc_xxx',
 })
 
 // Correct a single count
-await adminClient.stockLevels.update('slv_xxx', {
+await adminClient.stockLevels.update('sl_xxx', {
   count_on_hand: 150,
   backorderable: true,
 })
@@ -89,15 +105,15 @@ await adminClient.stockLevels.update('slv_xxx', {
 // Set many at once — the right call for a nightly sync
 await adminClient.stockLevels.bulkUpsert({
   stock_levels: [
-    { variant_id: 'var_xxx', stock_location_id: 'sl_xxx', count_on_hand: 40 },
-    { variant_id: 'var_yyy', stock_location_id: 'sl_xxx', count_on_hand: 12 },
+    { variant_id: 'variant_xxx', stock_location_id: 'sloc_xxx', count_on_hand: 40 },
+    { variant_id: 'variant_yyy', stock_location_id: 'sloc_xxx', count_on_hand: 12 },
   ],
 })
 ```
 
 ```bash CLI
-spree api get '/stock_levels?q[stock_location_id_eq]=sl_xxx'
-spree api patch /stock_levels/slv_xxx -d '{"count_on_hand": 150}'
+spree api get '/stock_levels?q[stock_location_id_eq]=sloc_xxx'
+spree api patch /stock_levels/sl_xxx -d '{"count_on_hand": 150}'
 ```
 
 
@@ -116,12 +132,15 @@ Every change to stock is recorded as a movement, so "why is this number what it
 | `adjusted` | A manual correction, such as after a stock count |
 
 ```typescript Admin SDK
+// Everything that happened to one SKU, across every location
 const { data: movements } = await adminClient.stockMovements.list({
-  filter: { variant_id_eq: 'var_xxx' },
+  stock_level_variant_id_eq: 'variant_xxx',
 })
 ```
 
-Each movement points at what caused it — the order, the fulfillment, the transfer — so an audit trail reads as a sequence of business events rather than a list of numbers that changed.
+Each movement points at what caused it — the order, the fulfillment, the transfer, the purchase order, and for stock that arrived, the delivery it came in on — so an audit trail reads as a sequence of business events rather than a list of numbers that changed.
+
+A movement that arrived through a purchase order also carries what the units cost, so "what did this stock cost us" is answerable from the ledger rather than reconstructed from the orders that bought it.
 
 ## What a shopper sees
 
@@ -151,7 +170,7 @@ A reservation is a short, time-limited hold placed when a customer enters checko
 | They complete the order | The hold becomes a real allocation |
 | They abandon it | The hold expires and stock returns |
 
-Reservations never touch `count_on_hand` — they're a separate layer consulted when availability is read. A backorderable item is skipped entirely, since unlimited supply needs no holding.
+Reservations never touch `count_on_hand` — they're a separate layer consulted when availability is read, and their total per stock level is what `reserved_count` shows. A backorderable item is skipped entirely, since unlimited supply needs no holding.
 
 How long the hold lasts is a **store setting**, because it's a decision about the checkout experience rather than a property of a warehouse. Reservations can also be switched off entirely.
 
@@ -165,12 +184,108 @@ When new stock arrives, backorders are filled first, and only the remainder beco
 
 ## Moving stock between locations
 
-A stock transfer moves inventory from one location to another, and reflects that this takes time: stock is booked out of the source, is in transit, and is received at the destination — where a partial receipt is a normal outcome, because sometimes not everything arrives.
+A stock transfer moves inventory from one location to another, and reflects that this takes time: stock is booked out of the source, is in transit, and is counted in at the destination — where a partial delivery is a normal outcome, because sometimes not everything arrives at once.
+
+That is four steps, not one. A transfer is planned as a draft, packed, sent, and finally counted in:
+
+```typescript Admin SDK
+const transfer = await adminClient.stockTransfers.create({
+  source_location_id: 'sloc_xxx',
+  destination_location_id: 'sloc_yyy',
+  items: [{ variant_id: 'variant_xxx', quantity_shipped: 10 }],
+})
+
+// The units leave the source here — and are on no shelf until they arrive.
+await adminClient.stockTransfers.markInTransit(transfer.id)
+
+// Eight arrived intact and two were crushed. See "Counting a delivery in".
+await adminClient.stockTransfers.stockReceipts.create(transfer.id, {
+  items: [{ id: 'sti_xxx', quantity_accepted: 8, quantity_rejected: 2, rejection_reason: 'damaged' }],
+})
+```
+
+| Status | What it means |
+|---|---|
+| `draft` | A plan. Lines can still change; nothing has moved |
+| `ready_to_ship` | Packed. Lines are frozen, nothing has left yet — `markDraft` unfreezes it |
+| `in_transit` | The units have left the source and are on no shelf |
+| `partially_received` | Some units have been counted in; the rest are still on the road |
+| `received` | Everything that left has arrived — or the balance was closed short |
+| `over_received` | More arrived than was sent |
+| `canceled` | Called off. Once units have left, the merchant says whether they come back or are written off |
+
+Two things follow from the middle step. Availability at the destination does not rise until somebody counts the goods in, which is what makes the number trustworthy. And cancelling a transfer whose units have already left is a decision rather than an undo: either they come back to the source, or they are written off as lost.
+
+## Buying stock in
+
+Stock that comes from a supplier is a purchase order, not a transfer — it has a supplier, a cost per unit and a date it was promised for, none of which apply to moving goods you already own.
+
+```typescript Admin SDK
+const order = await adminClient.purchaseOrders.create({
+  supplier_id: 'sup_xxx',
+  destination_location_id: 'sloc_xxx',
+  expected_at: '2026-10-01',
+  cancel_by: '2026-10-15',
+  items: [{ variant_id: 'variant_xxx', quantity_ordered: 100, unit_cost: '12.50' }],
+})
+
+await adminClient.purchaseOrders.markOrdered(order.id)
+
+// A delivery arrives: 58 accepted, 2 refused. The order stays open for the rest.
+await adminClient.purchaseOrders.stockReceipts.create(order.id, {
+  reference: 'DN-4471',
+  items: [{ id: 'poi_xxx', quantity_accepted: 58, quantity_rejected: 2, rejection_reason: 'damaged' }],
+})
+```
+
+| Status | What it means |
+|---|---|
+| `draft` | Being put together. Lines and costs can still change |
+| `ordered` | Sent to the supplier. Lines are frozen — `markDraft` reopens it while nothing has arrived |
+| `partially_received` | Some units have been counted in; the supplier still owes the rest |
+| `received` | Every line has what it expected — or the balance was closed short |
+| `over_received` | The supplier sent more than was ordered |
+| `canceled` | Called off. Units already received stay on the shelf |
+
+Ordered stock is never available stock. Nothing reaches `count_on_hand` until a delivery is counted in, because a merchant who has ordered goods does not have them — and suppliers under-ship often enough that receiving in parts is the ordinary case.
+
+An order carries the day the supplier promised (`expected_at`) and, optionally, the day after which the goods are no longer wanted (`cancel_by`). Both are calendar dates. The dashboard lists filter on *Overdue* and *Past cancel-by*; nothing cancels automatically, because that is a call to confirm with the supplier.
+
+Purchase orders export to CSV, one row per line, which is the file a merchant sends a supplier. They import from one too: rows sharing a `reference` become one draft order, naming the supplier, warehouse and SKU by name — a name that does not exist fails the row rather than creating anything.
+
+Suppliers themselves are an address book, kept per store:
+
+```typescript Admin SDK
+const { data: suppliers } = await adminClient.suppliers.list()
+```
+
+## Counting a delivery in
+
+Transfers and purchase orders are received the same way: each delivery is a **stock receipt**, numbered and dated, carrying the packing-slip reference and — per line — what was accepted and what was refused, with a reason.
 
 ```typescript Admin SDK
-const { data: transfers } = await adminClient.stockTransfers.list()
+const { data: deliveries } = await adminClient.purchaseOrders.stockReceipts.list(order.id, {
+  expand: ['items'],
+})
 ```
 
+A receipt records *this delivery's* counts, not running totals: a second box adds to the first rather than restating it. Accepted units land on the destination's shelf, each as a `received` movement that names the receipt. Refused units are recorded and never stocked; the reason is one of `damaged`, `wrong_item`, `expired` or `other`. Omit `items` to count in everything still outstanding, intact.
+
+> **NOTE:** **Refused units count differently on the two documents.** A supplier's refused units are still owed — the goods go back, and the order stays `partially_received` until they are replaced. A transfer's refused units have *arrived*, in whatever state: a crushed unit is not still in the van, so it counts toward the trip being over.
+
+When the balance is not coming — the supplier is out of stock, the missing units fell off the van — the document is **closed short**: it settles in `received` with `closed_short_at` and the reason recorded, and the outstanding count stays on each line as the record of the gap. Nothing moves.
+
+```typescript Admin SDK
+await adminClient.purchaseOrders.close(order.id, { reason: 'Supplier out of stock' })
+await adminClient.stockTransfers.close(transfer.id, { reason: 'Two fell off the van' })
+```
+
+## The Inventory page
+
+The dashboard's Inventory section opens on a list with one row per variant per location: on hand, allocated, reserved, available and incoming — the page uses the column names, with the location as a filter and SKU or product name as the search. Every figure on it is a column read off the stock level.
+
+The on-hand figure is corrected in place — set it to a count, or adjust it by a delta, and say why — and the change lands in the stock history like any other adjustment. The incoming figure links to the two ways of making it grow: a transfer from another warehouse, or a purchase order from a supplier.
+
 ## Turning tracking off
 
 Some things don't need counting — a service, a made-to-order item, a digital download. Tracking can be switched off, and those variants are always purchasable.

package/dist/developer/sdk/admin/resources.md

@@ -71,7 +71,9 @@ await client.customers.addresses.create('cus_xxx', {
 |---|---|
 | `client.stockLocations` | CRUD on stock locations. |
 | `client.stockItems` | List, get, update, delete stock items. |
-| `client.stockTransfers` | List, get, create, delete stock transfers. |
+| `client.stockTransfers` | CRUD plus the lifecycle: `markReady`, `markInTransit`, `receive`, `cancel`. |
+| `client.suppliers` | CRUD on the suppliers you buy from. |
+| `client.purchaseOrders` | CRUD plus `markOrdered`, `receive`, `cancel`. |
 
 ## Sales channels
 

package/dist/developer/upgrades/5.6-to-6.0.md

@@ -130,6 +130,14 @@ bundle exec rake spree:backfill_order_markets
 
 Orders missing a market get the store default — `market` is required on carts and orders in 6.0.
 
+### Fill in the stock level counters
+
+```bash
+bundle exec rake spree:stock:recount_levels
+```
+
+`spree_stock_levels` gains `reserved_count` (units held by checkouts in progress) and `incoming_count` (units on their way on a purchase order placed with a supplier or a transfer in transit). Both are kept by the workflows that change them and start at zero on an existing install; this recomputes them from active reservations and open documents and prints every level it corrected. Until it runs, the dashboard's Inventory page shows zero reserved and incoming for stock that predates the upgrade. Safe to re-run at any time.
+
 ## The Cart/Order split
 
 The single biggest change. What used to be one `Spree::Order` living through checkout and beyond is now two models:

package/package.json

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