Purchase Orders (PO), Smart Replenishment Radar, Goods Received Notes (GRN), FIFO/Serial Stock Intake & Studio
Master the end-to-end physical and financial procurement cycle: raising Price-Book-linked Purchase Orders, running the 1-Click Smart Replenishment Radar, receiving partial or full shipments via the Goods Received Note (GRN) Workbench, isolating QA rejects to Quarantine, registering FIFO Batch Lots and 360° Serial Numbers, and automating 3-Way Match Expense posting.
Plain-English Accounting Primer: The "3-Way Match" (PO → GRN → Expense/AP Bill)
In professional inventory and accounting control, you never pay a supplier invoice blindly. Keystone X enforces the gold-standard 3-Way Match:
Step 1: Purchase Order (PO)
"What we ordered & agreed to pay." Authorizes the supplier to ship specific quantities at negotiated Price Book unit costs. Issuing a PO does not inflate warehouse stock yet.
Step 2: Goods Received Note (GRN)
"What physically arrived in good condition." Recorded at the warehouse receiving bay against the courier's Delivery Note/Waybill. Increments multi-warehouse stock, creates FIFO cost layers, registers serial numbers, and isolates damaged units (`QA Rejected`) into a Quarantine hub.
Step 3: Accounting Expense / AP Bill
"What we financially recognise & pay." Upon confirming a GRN, Keystone X can automatically post a linked Expense Voucher under `Inventory Purchases` for the exact landed quantity received, referencing both the PO # and the Supplier's Tax Invoice #!
1. Purchase Order, GRN & Replenishment Command Center (PurchaseOrder/index)
Navigate to Procurement → Purchase Orders (`PurchaseOrder/index`).
📸 [SCREENSHOT PLACEHOLDER: po-grn-command-center.png]
- Where to Navigate: Go to
PurchaseOrder/index?mode=orders. - What to Capture: Capture the Command Center Header Banner, the 6 Executive KPI Cards, the 7-Pill Procurement Workflow Pipeline Strip, the 4 Mode Navigation Pills, and the Master Purchase Order table showing line fulfillment progress bars.
1.1 Header Banner Action Buttons
- Suppliers & Price Books (`vendor/index`): Opens the Supplier Directory & Price Book Command Center.
- Inventory & Hubs (`inventory/index`): Opens the Multi-Warehouse Inventory Catalog.
- + Direct Stock Intake (GRN): Opens the
#directStockIntakeModalto receive stock directly into a warehouse hub with an official GRN, FIFO Batch Lot, and Serial registration without requiring a prior Purchase Order. - Customize (`PurchaseOrder/settings`): Opens the 3-Tab PO, GRN & Stock Intake Governance Studio.
- + New Purchase Order (`PurchaseOrder/add`): Opens the Enterprise Purchase Order & Price Book Builder.
1.2 The 6 Telemetry KPI Cards & 7-Pill Workflow Pipeline
| KPI Card | Metrics Displayed |
|---|---|
| 1. Total PO Volume | Total committed value across all active Purchase Orders (`$stats->total_po_spend`), total PO count, and number of fully received POs. |
| 2. Open & In-Transit | Rand value of open/unfulfilled Purchase Orders (`$stats->open_commitment_value`), split into Open and Partial counts. |
| 3. Official GRNs | Total landed Ex-VAT value of all Goods Received Notes (`$stats->grn_total_value`) and total count of GRN documents issued. |
| 4. Fulfillment & QA | Overall line-item fulfillment percentage (`$stats->fulfillment_rate_pct`), total units stocked (`In`), and total damaged units quarantined (`QA Rej`). |
| 5. Restock Radar | Count of SKUs currently below their Reorder Point (`$stats->low_stock_count`), ready for 1-Click Auto-PO generation. |
| 6. 12M Spend Velocity | Rolling 12-month procurement volume (`$total12m`) and count of POs awaiting executive approval (`Pending Approval`). |
The 7 Workflow Pipeline Pills: All Purchase Orders • Drafts • Sent / In-Transit • Partially Received • Fully Received • Goods Received Notes (GRN) • Low-Stock Auto-PO Radar.
2. The 4 Operational Modes of PurchaseOrder/index
2.1 Mode 1: Purchase Orders & Fulfillment (?mode=orders)
Filterable by Search (`PO-`, Supplier, Quote/Ref #, Warehouse), Supplier dropdown, Warehouse Hub dropdown, and Status (`Draft`, `Sent`, `Partially Received`, `Received`, `Cancelled`). Displays:
- PO Number & Priority: Clickable `PO-1001` link (`PurchaseOrder/preview/{id}`) plus priority badge (`Urgent / AOG` in red, `High` in amber) and `Pending Approval` warning if above threshold.
- Supplier & Ref #: Clickable Supplier link (`vendor/view/{vendor_id}`) and Supplier Quote/Reference #.
- Target Warehouse Hub: Destination hub code and name (e.g., `WH-MAIN — Main Central Warehouse`) plus Shipping Method.
- Issue & ETA Dates: Issue Date and Expected Delivery Date (automatically flagged in red as **Overdue ETA** if past due and not yet received).
- Line Fulfillment Progress Bar: Visual progress bar showing `Received Units / Ordered Units (X%)` and count of official GRN documents recorded against the PO.
- Row Actions: 360° PO Cockpit (), Receive Stock & Issue GRN ( `PurchaseOrder/receive/{id}`), Download PDF (), Edit PO (), and Delete PO ().
2.2 Mode 2: Goods Received Notes (GRN) & Stock Intake Register (?mode=grn)
Displays the master audit register of every stock intake transaction (`GRN-1001`, etc.), whether originating from a Purchase Order (`PO Receipt`) or a walk-in/direct intake (`Direct Intake`). Columns include **GRN Number**, **Intake Type**, **Linked PO #**, **Supplier**, **Warehouse Hub**, **Delivery Note (`DN #`) & Supplier Tax Invoice #**, **Received Date & Receiver Name**, **Units Stocked vs. QA Rejected**, **Landed Value (Ex VAT)** (with a badge showing the auto-posted `Expense #ID`), and an action button to open the linked PO's GRN history tab.
2.3 Mode 3: Smart Replenishment & 1-Click Auto-PO Radar (?mode=replenish)
Automatically cross-references all stock-managed SKUs against their **Reorder Level (`Min`)**, **Target Max Stock (`Max`)**, and **Preferred Supplier Price Book Contracts**.
📸 [SCREENSHOT PLACEHOLDER: po-smart-replenishment-radar.png]
- Where to Navigate: Go to
PurchaseOrder/index?mode=replenish. - What to Capture: Capture the Smart Replenishment table showing On-Hand Stock vs. Min/Max targets, Preferred Supplier & Part #, Price Book Contract badge, Suggested Order Qty, and the 1-Click Raise Restock PO button.
- How Suggested Order Qty is Calculated: Calculates the shortfall needed to bring stock back up to the item's `max_stock_level` (or `2 × reorder_level`), while respecting the supplier's Minimum Order Quantity (`MOQ`).
- 1-Click Action (
Raise Restock PO): Clicking Raise Restock PO navigates to `PurchaseOrder/add?item_id={id}&vendor_id={vendor_id}&qty={suggested_qty}`, automatically selecting the Preferred Supplier, adding the SKU line item, setting the quantity, and applying the supplier's negotiated Price Book unit cost!
2.4 Mode 4: 12-Month Spend & Receiving Analytics (?mode=analytics)
Renders a 12-Month Procurement Spend Velocity bar chart (`#poAnalyticsChart`) alongside an **Active GRN & Governance Rules** summary card showing live sequences (`PO-` and `GRN-`), Partial Delivery status, Auto-Post Expense status, Auto-Sync Cost status, and Default FIFO Batch Lot prefix.
2.5 Modal: Direct Warehouse Stock Intake (Without Prior PO) (#directStockIntakeModal)
Triggered by clicking + Direct Stock Intake (GRN) in the header. Submits to `PurchaseOrder/directIntake` and allows warehouse managers to book walk-in purchases, emergency cash stock, or opening batch lots directly into a **Receiving Warehouse Hub** (`warehouse_id`) with an **Official GRN Number**, **Inventory SKU** (`item_id`), optional **Supplier** (`vendor_id`), **Quantity Received**, **Unit Cost (Ex VAT)**, **Put-Away Bin Location**, **Delivery Note #**, **Supplier Tax Invoice #**, **FIFO Batch / Lot Number**, **Expiry Date**, **Serial Numbers / IMEI** (with 1-click **Auto-Generate Serials**), and a toggle (`post_expense`) to simultaneously post an Accounting Expense under `Inventory Purchases`.
3. Creating or Editing a Purchase Order (PurchaseOrder/add & edit/{id})
The Purchase Order Builder features live JavaScript Price Book lookup (`PRICEBOOK_MAP`). Whenever you select a Supplier and an Inventory SKU, the builder checks if that supplier has a negotiated Price Book contract for that SKU—if found, it automatically substitutes the supplier's contracted unit cost and displays a green Price Book: PART-123 (MOQ: X) badge underneath the item selector!
| Form Section | Fields & Input Names | Behavior & Automation |
|---|---|---|
| 1. Supplier, Target Warehouse Hub & Logistics Metadata | vendor_id *, warehouse_id *, po_number *, po_date *, expected_date, priority (`Normal`, `High`, `Urgent / AOG`), shipping_method, reference_number, currency |
Selecting a Supplier (`onVendorChange()`) automatically updates the **Target Receiving Warehouse Hub** to the supplier's default warehouse, calculates the **Expected Delivery Date (ETA)** by adding the supplier's `lead_time_days` to the PO Issue Date, and re-evaluates all line items against that supplier's Price Book. |
| 2. Purchase Order Line Items & Price Book Lookup | item_id[], description[] *, quantity[] *, unit[], unit_price[] * |
Click + Add Line Item (`addPoItemRow()`) to add rows. Selecting an Inventory SKU populates the description, unit of measure, and negotiated Price Book cost (or standard catalog cost if no Price Book contract exists). |
| 3. Terms & Financial Summary | notes, discount_type (`fixed` or `percentage`), discount_value, shipping_cost (Freight Ex VAT), tax_code (SARS Input Tax dropdown) |
Calculates **Subtotal (Ex VAT)**, **Discount**, **Freight / Shipping**, **Input VAT**, and **Total PO Value (Inc VAT)** in real time. Includes two submit buttons: Save as Draft PO (`status=Draft`) and Issue & Mark Sent (`status=Sent`). |
4. Goods Received Note (GRN) & Multi-Warehouse Stock Intake Workbench (PurchaseOrder/receive/{id})
When a supplier shipment arrives at your loading bay, open the PO and click Receive Stock / Issue GRN (`PurchaseOrder/receive/{id}`).
📸 [SCREENSHOT PLACEHOLDER: po-grn-receiving-workbench.png]
- Where to Navigate: Open any `Sent` or `Partially Received` Purchase Order and click Receive Stock / Issue GRN (`PurchaseOrder/receive/{id}`).
- What to Capture: Capture both Card 1 (GRN & Waybill Header with the 2 automation switches) and Card 2 (Line-by-Line Goods Intake showing Receiving Now, QA Rejected, Landed Unit Cost, Put-Away Bin, FIFO Batch Lot #, Expiry Date, and Serial Number scanner box).
4.1 Header Quick-Fill Buttons & Card 1 (GRN & 3-Way Match Metadata)
- Fill All Remaining Qtys (`fillAllRemaining()`): Sets every line item's `Receiving Now` quantity to 100% of its remaining unfulfilled quantity.
- Zero All (Selective Partial) (`zeroAllReceiving()`): Sets all `Receiving Now` inputs to `0.00` so the warehouse clerk can type only the specific items delivered in a partial shipment.
- Top Automation Switches:
- Auto-Post Accounting Expense (`auto_create_expense`): Automatically creates an official Expense Voucher under `Inventory Purchases` for the exact landed value of this GRN.
- Sync Landed Cost & Price Book (`auto_update_cost`): Automatically updates the SKU's catalog cost price and Supplier Price Book if the actual landed unit cost on the GRN changed.
- GRN Header Fields: Official GRN Number (`grn_number`, e.g., `GRN-1001`), Receiving Warehouse Hub (`warehouse_id`), Receipt Date (`received_date`), Delivery Note / Waybill # (`delivery_note_number`), Supplier Tax Invoice # (3-Way Match) (`supplier_invoice_number`), and Receiving & QA Inspection Remarks (`grn_notes`).
4.2 Card 2: Line-by-Line Goods Intake, QA Quarantine, FIFO Batch & Serial Registration
| Workbench Column | Input Name & Exact Warehouse / Accounting Effect |
|---|---|
| SKU & Line Item | Displays SKU Code, Item Name, and traceability badges (Serialized Asset, FIFO Expiry Tracked, or FIFO Lot Tracked). |
| Ordered / Prev. Rec / Remaining | Shows total quantity ordered on the PO, quantity already received across prior partial GRNs, and remaining open balance. |
| Receiving Now (Good Stock) | qty_received[{poItemId}]: Quantity accepted in good condition. Increments sellable stock in the selected **Receiving Warehouse Hub** and updates the live badge (`#liveGrnSummaryBadge`). |
| QA Rejected (Quarantine) | qty_rejected[{poItemId}]: Damaged or defective units rejected upon arrival. Automatically isolated into the configured **QA Quarantine Warehouse Hub** (`WH-QUAR`) so they cannot be accidentally sold! |
| Landed Unit Cost | unit_cost[{poItemId}]: Defaults to the PO unit price, but can be adjusted to reflect actual landed cost on the supplier invoice. |
| Put-Away Bin | bin_location[{poItemId}]: Physical shelf/aisle location inside the warehouse (e.g., `A-01`). |
| FIFO Batch Lot & Serial Numbers |
|
5. The 360° Purchase Order Cockpit (PurchaseOrder/preview/{id}) & Governance Studio (PurchaseOrder/settings)
5.1 360° Purchase Order Cockpit (PurchaseOrder/preview/{id})
- Header Action Bar: Includes 1-click buttons for Approve PO (if flagged as `Pending Approval`), Mark as Sent (if `Draft`), Receive Stock / Issue GRN, Email PO (`PurchaseOrder/send/{id}`), PDF (`PurchaseOrder/pdf/{id}`), and Edit PO.
- 4 Cockpit Telemetry Cards: Committed PO Value (Inc/Ex VAT), Line Fulfillment Progress Bar (`Received / Ordered Units`), Official GRNs Issued & QA Pass Rate, and Traceability Footprint (`X Lots • Y Serials`).
- 3 Cockpit Tabs:
?tab=document(Official Purchase Order & Line Fulfillment): Displays Supplier & Destination Warehouse cards and the full line-item fulfillment breakdown (`Ordered`, `Received`, `Remaining`, `Unit Cost`, `Line Total`).?tab=grns(Goods Received Notes History): Lists every partial or full GRN recorded against this PO, including Delivery Note #, Supplier Invoice #, Units Stocked vs. Rejected, Landed Value, and linked `Expense #ID`.?tab=traceability(Received FIFO Batches & Serialized Units): Side-by-side tables displaying every **FIFO Batch Lot** and every **360° Serialized Unit** received under this Purchase Order.
5.2 Purchase Order, GRN & Stock Intake Governance Studio (PurchaseOrder/settings)
| Studio Tab | Settings & Governance Switches |
|---|---|
Tab 1: PO & GRN Numbering, Prefixes & Default Hubs (?tab=numbering) |
po_prefix (`PO-`), po_next_number (`1005`), po_padding (`4`); grn_prefix (`GRN-`), grn_next_number (`1001`), grn_padding (`4`); po_default_warehouse_id; po_default_shipping_method; and comma-separated po_shipping_methods_list. |
Tab 2: Procurement Governance, Partial Delivery & 3-Way Match (?tab=governance) |
|
Tab 3: Stock Intake, QA Quarantine, FIFO Batch & Serial Rules (?tab=intake) |
|