Module 4: Purchasing & Suppliers

⛔ SUPERSEDED 2026-06-11 — Sprig-era feature spec (pre-pivot). The authoritative current design is the locked schema in docs/SCHEMA.md, the module's entry in docs/PROJECT_DECISIONS.md, and the responsibility/seam maps in docs/MODULE_INDEX.md + docs/CROSS_MODULE_CONTRACTS.md. This file is retained for historical feature context only; do NOT treat its scope/table/feature claims as current (it predates the nursery→generic pivot, the HR-out-of-scope cut, the identity/payments/integrations/files extractions, and the schema locks). Superseded note added 2026-06-11.

Status: ✅ Locked for v1.0 Schema: purchasing Feature count: 134 features in v1.0 Build estimate: Strategic spec only — implementation effort TBD Last updated: 2026-05-12

Overview

Purchasing & Suppliers handles the full inbound supply chain — vendor management, purchase orders, receiving with three-way match, invoice reconciliation, vendor performance tracking, reorder forecasting, and special workflows (drop ship, consignment, returns/RMA).

This module is the Full Purchasing build that ships in v1.0. Note: 5 lighter purchasing features already exist in the Inventory module (shopping list, cost change alerts, vendor pricing comparison, basic QuickBooks export, vendor cost history) — those remain in Inventory; this module is the comprehensive purchasing workflow.

Purchasing depends on Inventory (variants, vendor records, receiving), Customer Orders (special orders trigger PO drafts), and integrates with QuickBooks for AP/payables.

Target Customer Profile

• Mid-size growth-stage retail nursery, $500K–$5M revenue
• 15–50 active vendors (plant growers + hard goods suppliers)
• Spring-weighted purchasing (40–50% of annual purchases Jan–May)
• Mix of standing reorders, seasonal bulk orders, special customer orders
• 3-way match required for accounting integrity
• Multi-vendor sourcing common for popular items

Architecture Principle: Configurability

Every threshold, policy, and default in Purchasing is configurable per tenant via the Owner Dashboard (Module 10).

Feature Hierarchy (134 features across 16 groups)

Group 1: Vendor Management (13 features)

#	Feature	Notes
1.1	Vendor master record	Name, contact, billing address, shipping address, terms, tax ID.
1.2	Multiple contacts per vendor	Sales rep, AR contact, customer service contact.
1.3	Vendor categorization	Plant grower / hard goods supplier / both / service provider.
1.4	Vendor payment terms	Net 30, Net 60, 2/10 Net 30, COD, prepay — captured per vendor.
1.5	Vendor lead time tracking	Average days from PO to receipt; auto-derived from history.
1.6	Vendor minimum order quantity (MOQ)	Per vendor or per item.
1.7	Vendor catalog / price list	Items vendor sells, prices, availability.
1.8	Vendor catalog import (CSV)	Upload vendor's catalog quickly.
1.9	Vendor preferred status	Mark preferred vendors; auto-suggest first for reorders.
1.10	Vendor notes	Free-text — quirks, preferences, special instructions.
1.11	Vendor active/inactive status	Deactivate vendors no longer used.
1.12	Vendor account number / customer code	Your code with the vendor (for their references).
1.13	Vendor blackout dates	Closed periods, plant production cycles; PO won't ship in those windows.

Group 2: Purchase Order Creation (17 features)

#	Feature	Notes
2.1	Create draft PO	Vendor + items + qty + expected cost + delivery date.
2.2	Multi-line PO	Multiple variants on one PO.
2.3	Add items by SKU or scan	Fast entry.
2.4	Add items from vendor catalog	Pre-populated price suggestions.
2.5	PO line cost capture	Per-line cost; system warns if differs significantly from last cost.
2.6	PO subtotal, tax, freight, total	Calculated in real-time.
2.7	PO destination (which site to deliver to)	Multi-loc-aware.
2.8	PO expected delivery date	Vendor's promised date.
2.9	PO notes (to vendor)	Free text accompanying PO.
2.10	PO internal notes	Visible to staff, not vendor.
2.11	PO from low-stock report (one-click)	"These items are low — generate POs."
2.12	PO from reorder suggestions	AI-assisted reorder list (Group 8).
2.13	PO templates	Save common POs as templates.
2.14	PO copy from past PO	"Same as last spring's order" — duplicate.
2.15	Multi-line discount rules at PO	Vendor offers "2% off if 100+ qty" — auto-applied.
2.16	Freight terms per PO	Vendor pays / Vrida pays / Split — affects landed cost.
2.17	PO project tagging	Link PO to specific contractor/internal project.

Group 3: PO Lifecycle & Sending (13 features)

#	Feature	Notes
3.1	PO status states	draft / sent / acknowledged / partially_received / received / closed / cancelled.
3.2	Send PO to vendor via email	PDF attached, branded.
3.3	Send PO to vendor via print	For vendors who require paper.
3.4	PO confirmation from vendor	Vendor acknowledges (manual entry or email response capture).
3.5	PO modification after sending	Edit with vendor approval; audit trail.
3.6	PO cancellation	With reason; notify vendor; audit.
3.7	PO acknowledgment changes	Vendor modifies (price, qty); staff accepts/disputes.
3.8	PO expiration / aging	Open POs >X days flagged for follow-up.
3.9	PO export to PDF	Standalone document.
3.10	PO numbering	Sequential, customizable prefix per site/year.
3.11	PO approval workflow (multi-level by amount)	POs over $X require manager; over $Y require owner.
3.12	PO confirmation deadline tracking	Flag if vendor doesn't acknowledge within X days.
3.13	PO release scheduling	Create now, send on future date.

Group 4: Receiving Workflow (16 features)

#	Feature	Notes
4.1	Receive against PO	Cashier opens PO at receiving zone; scans/counts arrived items.
4.2	Receiving by line item	Mark received qty per line; partial receiving supported.
4.3	Receiving captures actual cost	Match against PO cost; flag discrepancies.
4.4	Receiving captures destination zone	Where to put away.
4.5	Receiving capture photo of shipment	Document condition; optional.
4.6	Damage / defect codes at receiving	Cracked pot, root-bound, dead, wrong variety.
4.7	Receiving discrepancy capture	Expected 100, received 95 — explicit short tracking.
4.8	Substitution capture at receiving	Vendor sent variety B instead of A — staff accepts/disputes.
4.9	Receiving updates inventory	Stock incremented atomically with receipt.
4.10	Receiving completes PO line	Line marked received when qty matches.
4.11	Receive without a PO (ad-hoc)	Rare but supported; auto-create PO afterward.
4.12	Receiving print put-away labels	"These plants go to North Yard" — print labels at receiving.
4.13	Multiple receipts per PO	"First truckload today, second next week" — incremental receipts.
4.14	Cost allocation per line	Freight charges split proportionally across line items.
4.15	Landed cost calculation	Item cost + freight + duty + handling = true cost basis for inventory.
4.16	Receipt tally / count verification	High-value items ($500+) counted twice independently.

Group 5: Three-Way Match & Invoice Reconciliation (12 features)

#	Feature	Notes
5.1	Capture vendor invoice	PDF upload, photo, or manual entry.
5.2	Invoice line items	Each line: item, qty, unit cost, total.
5.3	Three-way match	PO line + Receipt line + Invoice line — system reconciles.
5.4	Match discrepancy highlighting	Show differences (price, qty) for review.
5.5	Discrepancy resolution workflow	Approve/dispute/adjust each line.
5.6	Invoice approval for payment	Once matched, mark approved for QuickBooks.
5.7	Vendor invoice list	Open, matched, approved, paid views.
5.8	Invoice aging report	How long since received, how long until payment due.
5.9	Multi-PO invoice	One invoice covering multiple POs.
5.10	Invoice partial approval	Approve part now, dispute part separately.
5.11	Cash discount tracking	2/10 Net 30 — actively track and capture discounts if paid early.
5.12	Vendor credit memo tracking	Vendor issues credit; track to apply against future invoices.

Group 6: AI Invoice OCR (5 features)

#	Feature	Notes
6.1	Snap photo of vendor invoice	Phone camera captures PDF or paper.
6.2	AI extracts line items	OCR + Bedrock parsing: item descriptions, qty, prices.
6.3	AI matches extracted lines to inventory variants	Suggests which variant each line is.
6.4	Manual review/correction of AI suggestions	Cashier confirms or fixes.
6.5	One-click create invoice from AI extraction	After review, invoice record created in system.

Group 7: Vendor Performance Tracking (9 features)

#	Feature	Notes
7.1	Vendor on-time delivery rate	% of POs delivered by promised date.
7.2	Vendor fill rate	% of ordered qty actually received.
7.3	Vendor pricing trend	Cost over time per item per vendor.
7.4	Vendor quality score	Damage/defect rate at receiving.
7.5	Vendor scorecard	Composite metric: on-time + fill + quality + price.
7.6	Vendor comparison view	Side-by-side: 3 vendors for same item.
7.7	Vendor performance alerts	Auto-flag deteriorating performance.
7.8	Vendor rating	Manual 1-5 star rating with notes.
7.9	AI cost trend alerts	"Vendor X cost on lavender up 15% — investigate?"

Group 8: Reorder Suggestions & Forecasting (8 features)

#	Feature	Notes
8.1	Rule-based reorder suggestions	Low-stock + lead-time + sales velocity → suggested qty.
8.2	AI-powered reorder forecasting	Bedrock-trained on historical sales + seasonality.
8.3	Seasonal demand forecasting	"Spring is coming — order 30% more lavender."
8.4	Multi-vendor reorder suggestion	"Order from Vendor A (cheaper) or Vendor B (faster)?"
8.5	Reorder by category	"All annuals" or "all 1gal perennials" — bulk reorder suggestions.
8.6	Reorder by lead time	"Things to order today to arrive before next weekend."
8.7	Reorder budget alerts	"You've spent $X with this vendor this month" — budget tracking.
8.8	Forecasting accuracy tracking	Compare actual vs forecast over time; improve.

Group 9: PO Reporting & Analytics (9 features)

#	Feature	Notes
9.1	Open POs dashboard	All active POs sorted by expected delivery.
9.2	PO spend by vendor	Total $ spent with each vendor over period.
9.3	PO spend by category	Spend on plants vs hard goods vs services.
9.4	PO aging report	POs open >X days.
9.5	Vendor lead time report	Actual lead time per vendor; trend.
9.6	Cost variance report	Where receiving cost differed from PO cost.
9.7	Special order pipeline	What's been ordered for specific customers, when expected.
9.8	Purchasing seasonality	Spend patterns over time; identify trends.
9.9	PO commitment accounting (encumbrance)	Reserved $ once PO is sent; encumbrance reporting.

Group 10: Receiving Reports (4 features)

#	Feature	Notes
10.1	Daily receiving log	Everything received today, by zone, by vendor.
10.2	Damaged receiving report	What arrived damaged; by vendor, by item.
10.3	Discrepancy report	Short shipments, substitutions, over-deliveries.
10.4	Receiving by cashier	Who received what; performance tracking.

Group 11: Vendor Communication (8 features)

#	Feature	Notes
11.1	Email vendor from PO	Send message tied to specific PO.
11.2	Vendor portal (future v2.0)	Vendor self-service: see POs, confirm, update. Schema-ready in v1.0.
11.3	Vendor responses logged	Email replies captured against PO.
11.4	Vendor follow-up reminders	"PO sent 7 days ago, no response — follow up?"
11.5	Vendor catalog update notification	When vendor sends new catalog, system alerts.
11.6	Vendor newsletter / promotional email handling	Capture promotions, prices, availability.
11.7	Vendor RFQ (request for quote)	Send "what's your price on X qty of Y?" to multiple vendors.
11.8	Vendor bid comparison	Side-by-side quotes from multiple vendors.

Group 12: Bulk Operations (4 features)

#	Feature	Notes
12.1	Bulk PO creation	"Generate POs for all low-stock items" — one click.
12.2	Bulk PO sending	Email/print all today's POs at once.
12.3	Bulk vendor catalog update	Update prices for many items at once.
12.4	Bulk invoice approval	Mark multiple invoices as approved for payment.

Group 13: Compliance & Audit (5 features)

#	Feature	Notes
13.1	PO audit trail	Every change to PO logged with actor, time.
13.2	Receiving audit trail	Every receipt logged.
13.3	Invoice approval audit	Who approved, when, against which PO and receipt.
13.4	Vendor record changes audit	Anyone modifying vendor master record.
13.5	1099 tracking for vendors	Annual spend per vendor for tax reporting.

Group 14: Drop Ship & Special Vendor Workflows (5 features)

#	Feature	Notes
14.1	Drop ship vendor configuration	Mark vendor as drop ship; orders ship direct to customer.
14.2	Drop ship sale workflow	Sale at POS triggers PO that ships to customer address.
14.3	Drop ship tracking	Vendor provides tracking; system shows status.
14.4	Consignment vendor handling	Items on consignment — vendor owns until sold; revenue split.
14.5	Consignment reconciliation	Periodic settlement with consignment vendor.

Group 15: Integration Endpoints (3 features)

Routing note (Architecture Redesign 2026-05-13): All external-system endpoints in this group route via the Integrations module (Core & Platform Layer). The QuickBooks AP export job, the bidirectional vendor sync runtime, and future Vendor Catalog API connectors all use the unified connector pattern owned by Integrations. Purchasing surfaces the tenant-facing UI ("approve invoice for QB export"), emits the appropriate events, and consumes Integrations-module events for sync results. Purchasing does NOT import vendor SDKs directly.

#	Feature	Notes
15.1	QuickBooks AP export	Approved invoices flow to QB for payment.
15.2	QuickBooks vendor sync	Bidirectional sync of vendor master records.
15.3	Vendor catalog APIs (future)	Some larger vendors offer APIs; integrate later.

Group 16: Vendor Returns / RMA (3 features)

#	Feature	Notes
16.1	Vendor return / RMA workflow	Send something back to vendor; track credit.
16.2	Return shipping management	Label, tracking, follow-up.
16.3	RMA credit tracking	Vendor credit applied to future invoices; reconciled.

Tier Behavior (Module-Level)

Tier	Purchasing capability
Starter	Light purchasing only (shopping list, vendor records, cost history — features remain in Inventory module). No PO workflow.
Pro	Full Purchasing module: PO creation, receiving, three-way match, vendor performance, reorder suggestions, AI invoice OCR, vendor returns.
Enterprise	+ Multi-level PO approval workflows + commitment accounting + landed cost calculation + advanced forecasting + vendor portal (future).

Configurable Defaults (Owner Dashboard)

Configurable	Default
Default PO destination site	First site (for single-site tenants)
Auto-suggest reorder qty	OFF (configurable to ON, AI-assisted)
Three-way match required before invoice approval	ON
Manager PIN for invoice approval	ON above $X
Cost variance alert threshold	10% deviation flags
PO numbering format	SITE-YEAR-SEQUENTIAL (configurable)
Auto-send PO on creation	OFF (always reviewed first)
Vendor catalog auto-update	OFF
Forecast horizon	30 days, 60 days, 90 days
Budget alerts per vendor	OFF (configurable)
Drop ship enabled per vendor	Per-vendor flag
Consignment enabled per vendor	Per-vendor flag
PO approval threshold tier 1 (manager)	$1,000
PO approval threshold tier 2 (owner)	$10,000
Vendor confirmation deadline	7 days
Auto-release scheduled POs	ON
Freight terms default	Vendor pays (FOB destination)
Landed cost calculation enabled	OFF (configurable; defaults to simple cost)
Encumbrance / commitment accounting	OFF (Pro+ feature)
Receipt tally verification threshold	$500+ items require double-count
RMA tracking enabled	OFF (configurable to ON)

AI Features in Purchasing & Suppliers

Feature #	AI capability
6.1-6.5	AI Invoice OCR (entire group — OCR + line matching + variant suggestion)
7.9	AI cost trend alerts (vendor-specific cost anomaly detection)
8.2	AI-powered reorder forecasting (Bedrock on historical sales + seasonality)
8.3	AI seasonal demand forecasting
8.4	AI multi-vendor optimization suggestions
8.8	AI forecast accuracy improvement (feedback loop)

All AI features route via AIService (AI / Intelligence module; model-as-config; AWS Bedrock Claude Haiku 4.5 is the default model). Purchasing does not call Bedrock directly. This includes Group 6 AI Invoice OCR and Group 8 AI-powered reorder forecasting / seasonal demand / vendor optimization / forecast accuracy improvement.

Events Emitted

• purchasing.po_drafted
• purchasing.po_sent
• purchasing.po_acknowledged
• purchasing.po_modified
• purchasing.po_cancelled
• purchasing.po_approved
• purchasing.po_released
• purchasing.receipt_recorded
• purchasing.discrepancy_logged
• purchasing.invoice_captured
• purchasing.invoice_matched
• purchasing.invoice_approved
• purchasing.invoice_disputed
• purchasing.cash_discount_captured
• purchasing.credit_memo_received
• purchasing.vendor_created
• purchasing.vendor_updated
• purchasing.vendor_blackout_triggered
• purchasing.reorder_suggestion_generated
• purchasing.forecast_alert
• purchasing.cost_trend_alert
• purchasing.rma_created
• purchasing.rma_completed

Events Consumed

• inventory.stock_changed (trigger reorder suggestion logic)
• inventory.variant_updated (refresh variant data on PO lines)
• orders.special_order_created (auto-create vendor PO for special orders)
• orders.pre_order_created (auto-create vendor PO for pre-orders)
• pos.sale_completed (feed sales data to forecasting)
• billing.subscription_changed (enforce tier limits)

API Contract (PurchasingService — public methods)

High-level surface (detailed signatures during implementation):

• Vendor lifecycle: createVendor, updateVendor, deactivateVendor, manageVendorContacts
• PO lifecycle: createPO, addPOLine, applyDiscountRules, setFreightTerms, setPOProjectTag, submitPOForApproval, approvePO, sendPO, schedulePORelease, modifyPO, cancelPO
• Receiving: startReceiving, recordReceiptLine, recordDiscrepancy, recordSubstitution, allocateCost, calculateLandedCost, verifyHighValueReceipt, completeReceipt
• Invoice: captureInvoice, runThreeWayMatch, resolveDiscrepancy, approveInvoice, trackCashDiscount, recordCreditMemo
• AI OCR: scanInvoice, extractLines, suggestVariantMatches, confirmExtraction
• Performance: getVendorScorecard, compareVendors, triggerPerformanceAlert
• Forecasting: generateReorderSuggestions, forecastSeasonalDemand, compareVendorBids
• RMA: createRMA, manageReturnShipping, trackRMACredit

Out of Scope

Capability	Why excluded
EDI with vendors	Wholesale territory
Full vendor portal (self-service)	v2.0+; schema-ready in v1.0
Real-time vendor inventory API integration	Most vendors don't offer this
Automated AP / payment to vendors	QuickBooks integration handles
Currency conversion at PO (UI)	Multi-currency deferred to v1.5+; schema-ready
Vendor 3PL warehousing	Wholesale territory
Blanket POs (annual contracts with batched releases)	Wholesale territory
Multi-buyer / requisitioner workflows	Enterprise feature; deferred
Material certifications tracking (organic, USDA)	Niche; defer if customer asks
Capital vs expense PO classification	Niche accounting concern
Vendor sales tax handling per PO line	Edge case; defer

Gaps Identified from Market Research

Source: See docs/MARKET_RESEARCH_GAPS.md for the master gap registry. Status: All gaps below are Open — pending decision. None have been accepted into scope yet.

Gap #	Gap	What's missing in this module	Research source	Possible options
1	Shopify/Woo/Wix ecommerce sync	Module 4 has vendor POs and receiving; no inbound sync from external ecommerce platforms	Research §2.1 #6	Deferred (v1.5+) — Native connectors ship v1.5+; v1.0 tenants use manual CSV-sync. Connectors will live in the Integrations module (Core & Platform Layer) per Architecture Redesign 2026-05-13; Purchasing consumes the Integrations connector pattern, not vendor SDKs directly. See ROADMAP v1.5.
23	Hyper-local reorder with weather	No local-weather input yet	Research §6.3.5	Deferred (v1.2) — Coupled with Inventory Gap #23 + weather-tied bundle.