@spree/docs 0.1.223 → 0.1.224

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

@@ -17,6 +17,13 @@ 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
@@ -53,10 +60,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 +85,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 +97,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 +124,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
 
@@ -165,10 +176,100 @@ 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: 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
-const { data: transfers } = await adminClient.stockTransfers.list()
+await adminClient.purchaseOrders.close(order.id, { reason: 'Supplier out of stock' })
+await adminClient.stockTransfers.close(transfer.id, { reason: 'Two fell off the van' })
 ```
 
 ## Turning tracking off

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/package.json

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