⚠ This document is superseded (v1 reference — not confirmed v2 design).

Module 3: Customer Orders

⛔ 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: orders Feature count: 149 features in v1.0 Build estimate: Strategic spec only — implementation effort TBD Last updated: 2026-05-12

Overview

Customer Orders handles all future-dated transactions — reservations (hold-for-pickup), pre-orders (item arriving soon), special orders (item not normally stocked), contractor orders (B2B with charge accounts and project tagging), quotes/estimates, layaway, and the entire order fulfillment workflow.

Customer Orders is distinct from POS (immediate walk-in sales) because orders are future-dated, often tied to a customer (required for B2B), and may involve deposits, multi-stage payments, or specialized fulfillment workflows.

Customer Orders depends on Inventory (reservation of stock), CRM (customer attached and credit terms), and POS (sale completion when order is fulfilled).

Target Customer Profile

  • Mid-size growth-stage retail nursery, $500K–$5M revenue
  • 20% of revenue from landscape contractor orders
  • 10% of revenue from commercial / HOA orders
  • Daily reservations from phone/email customers
  • Spring-weighted seasonality affects order volume dramatically
  • Charge accounts for contractors; deposit handling for special orders

Architecture Principle: Configurability

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

Feature Hierarchy (149 features across 15 groups)

Group 1: Reservation Workflow (17 features)

# Feature Notes
1.1 Create reservation Customer + items + qty + pickup/delivery date. Inventory reserved (not deducted).
1.2 Reservation requires customer attached Cannot reserve anonymously.
1.3 Reservation lines (multi-item) One reservation can hold multiple items.
1.4 Reserved quantity tracked separately from on-hand Available = on-hand - reserved.
1.5 Reservation hold duration (default 7 days, configurable) After expiry, reservation auto-cancels and stock released.
1.6 Hold expiration warning Notifies customer + staff before expiry (3 days, 1 day).
1.7 Manual reservation extension Staff can extend with reason; audit-logged.
1.8 Reservation cancellation Customer or staff cancels; stock released; audit.
1.9 Reservation conversion to sale at pickup POS picks up reservation; sale completes; inventory deducts.
1.10 Partial fulfillment "5 of 7 ready, take those now" — balance stays reserved.
1.11 Reservation status states draft / active / partially_fulfilled / fulfilled / cancelled / expired
1.12 Reservation note Free-text note attached to reservation.
1.13 Reservation per site (multi-loc) Reservation belongs to a site; cross-site fulfillment at v1.5+.
1.14 Reservation search and list view Staff operational view.
1.15 Reservation filter by status, date, customer Operational filters.
1.16 Order priority levels VIP / Rush / Standard — affects fulfillment order.
1.17 Order line note Per-line free text for special handling.

Group 2: Pre-orders & Special Orders (13 features)

# Feature Notes
2.1 Pre-order for in-stock-soon items "Our spring shipment arrives April 1." Customer pays/commits.
2.2 Special order from vendor (not normally stocked) Customer asks for plant nursery doesn't carry; staff orders specifically.
2.3 Vendor order triggered automatically Pre-order/special-order generates a draft PO in Purchasing module.
2.4 Expected delivery date on order When nursery expects to fulfill (based on vendor lead time).
2.5 Customer payment options Full prepay / deposit + balance / pay-at-pickup.
2.6 Deposit handling Capture deposit at order creation; balance owed tracked.
2.7 Customer notification at receiving When vendor delivers, customer auto-notified.
2.8 Cancellation policy for special orders More restrictive than reservations (nursery already ordered from vendor).
2.9 Substitution if vendor can't fulfill Vendor short — staff offers similar item; customer accepts/cancels.
2.10 Multi-vendor special order One customer order requires plants from multiple vendors.
2.11 Special order vs pre-order distinction Pre-order = item normally stocked but out. Special order = item not normally carried.
2.12 Special order minimum order qty Vendor MOQs may force "we can only order if you commit to N."
2.13 Explicit backorder workflow Split order into "ship now" + "backorder" when stock is short.

Group 3: Contractor Orders (B2B Workflow) (18 features)

# Feature Notes
3.1 Contractor order template Pre-populated with contractor's typical items + qty + pricing tier.
3.2 Contractor pricing tier auto-applied Wholesale tier 1/2/3 pricing based on customer record.
3.3 Job / project reference per order Order tagged to contractor's specific project.
3.4 Customer PO number capture Contractor provides PO number for their accounting.
3.5 Bulk order entry Quickly add many items via SKU list or paste from spreadsheet.
3.6 Bulk pricing applied Quantity break pricing automatically based on order total.
3.7 Contractor charge to account Order charged to A/R account at fulfillment.
3.8 Order delivery / pickup at job site Site-of-delivery captured (not the nursery, the project site).
3.9 Delivery scheduling per order Specific date/time window for delivery.
3.10 Substitutions allowed flag per line Contractor accepts substitutions: yes/no (default: ask first).
3.11 Order acceptance / approval flow Contractor may need to approve before fulfillment (text or email signature).
3.12 Multi-day fulfillment for large orders One order, multiple delivery dates as stock available.
3.13 Contractor order history per customer All past contractor orders on customer record.
3.14 Contractor outstanding balance visible at order entry "Customer is over credit limit" warning.
3.15 Order via SKU shortcut entry Power-user fast entry — type SKU + qty without searching.
3.16 Customer's preferred substitutions auto-applied Per-customer "if X is out, substitute Y" rules.
3.17 Order via phone workflow optimization Fast workflow for inbound phone orders.
3.18 Payment terms visible during order entry Net 30, 2/10, etc. — from customer record.

Group 4: Quotes & Estimates (10 features)

# Feature Notes
4.1 Create quote / estimate Items + qty + pricing; sent to customer for review. No inventory reservation.
4.2 Quote validity period Default 30 days; configurable. Auto-expires.
4.3 Quote line items with details Plant variants, sizes, pricing, optional notes per line.
4.4 Quote PDF generation + email Branded PDF sent to customer.
4.5 Quote acceptance by customer Customer responds yes/no via email link or in-person.
4.6 Quote conversion to order One-click convert accepted quote to reservation or pre-order.
4.7 Quote modification before acceptance Edit quote, send revised version; customer sees both versions.
4.8 Quote vs estimate distinction Quote = firm pricing valid for X days. Estimate = approximate.
4.9 Quote search and list Open, expiring soon, accepted, declined views.
4.10 Quote follow-up reminders Auto-reminder to customer if no response after X days.

Group 5: Order Fulfillment (15 features)

# Feature Notes
5.1 Pick list generation List of items to pull from yard/greenhouse for an order.
5.2 Pick list grouped by zone Optimize walking — items grouped by zone/bin.
5.3 Staging area assignment Each order gets a staging area code (e.g., "Staging Bay 3").
5.4 Item check-off during picking Mark each item as picked; system updates pick status.
5.5 Quality check on picked items Staff confirms quality before staging (especially for contractor orders).
5.6 "Ready for pickup" status When all items picked and staged, status → ready.
5.7 Customer notification on ready Auto-email/SMS customer.
5.8 Pickup verification Customer arrives; staff verifies identity; reservation converts to sale.
5.9 Pick exception handling Picker found 4 of 5 expected — log shortage; trigger reorder or notify customer.
5.10 Damaged item during picking Flag as damaged; remove from order; suggest substitute or partial fulfillment.
5.11 Pick assignment Manager assigns specific picker to an order.
5.12 Pick performance reporting Time-to-ready per picker; helps staffing decisions.
5.13 Allocation logic for limited stock Multiple customers want same scarce item — allocate by priority/rules.
5.14 Order packing slip generation Document accompanying delivery or staged pickup.
5.15 Inventory allocation by promised date Pre-allocate stock for future orders.

Group 6: Deposits & Payment Schedule (10 features)

# Feature Notes
6.1 Deposit at order creation Configurable: 0%, 25%, 50%, 100% of order total.
6.2 Deposit payment methods Credit/debit, cash, check, charge to account.
6.3 Balance owed visible on order Real-time balance, paid amount, deposit amount.
6.4 Balance payment at fulfillment Customer pays remaining at pickup/delivery.
6.5 Multiple payments over time Customer can make partial payments before fulfillment.
6.6 Payment schedule "$200 deposit now, $300 in 2 weeks, balance at pickup" — flexible.
6.7 Payment reminder notifications Auto-notify customer of upcoming payment due.
6.8 Refund of deposit on cancellation Configurable: full refund / partial / forfeit.
6.9 Deposit aging report Open deposits, time since paid, fulfillment status.
6.10 Deposit-to-deposit transfer "Move my deposit from this canceled order to this new one."

Group 7: Order Modifications (11 features)

# Feature Notes
7.1 Edit order after creation Add/remove items, change qty, change date. Audit-logged.
7.2 Manager approval if total changes >X% Configurable threshold; manager PIN required.
7.3 Customer notification on modification Auto-email customer when order changes.
7.4 Reservation hold extension via modification Add date extension as a modification action.
7.5 Item substitution within order Replace one variant with another; price adjusts.
7.6 Delete entire order (vs cancel) Permanent delete only for unfulfilled orders.
7.7 Modification history per order Full audit trail of every change.
7.8 Restore previous version of order Undo recent modifications.
7.9 Order discount approval workflow Large discounts require manager approval before order finalized.
7.10 Internal vs customer-facing notes Some notes the customer sees, some are internal only.
7.11 Order pricing override at line level Override line price on order before finalization.

Group 8: Order Communications (10 features)

# Feature Notes
8.1 Order confirmation email Auto-sent when order created.
8.2 Order receipt SMS (Pro+ tier) Twilio integration.
8.3 Reservation reminder "Your reservation expires in 3 days."
8.4 Ready-for-pickup notification Email + optional SMS.
8.5 Order modified notification When staff edits order.
8.6 Order cancelled notification With reason if provided.
8.7 Special-order receiving notification When vendor delivers a special-order item.
8.8 Payment due reminder For deposit balances or scheduled payments.
8.9 Custom notification templates per tenant Branded email templates.
8.10 Notification opt-in/out per customer Customer controls what they receive.

Group 9: Order Reporting & Analytics (10 features)

# Feature Notes
9.1 Open orders dashboard All active orders, sorted by pickup date.
9.2 Order aging report Orders open >X days; flags neglected ones.
9.3 Reservation conversion rate What % of reservations convert to sales? Lost revenue tracking.
9.4 Contractor orders summary Total value, count, avg ticket per contractor.
9.5 Special order pipeline What's been ordered from vendors but not yet fulfilled.
9.6 Quote-to-order conversion rate What % of quotes turn into orders?
9.7 Order revenue forecast Projected revenue from pending orders for next 30/60/90 days.
9.8 Picker performance Time-to-ready, accuracy, error rate per cashier.
9.9 Backorder report All open backorders, expected delivery, customer notification status.
9.10 Order fulfillment SLA tracking "Customer expected by X, where are we?" — flags at-risk orders.

Group 10: Order Search & Discovery (6 features)

# Feature Notes
10.1 Search orders by customer Name, phone, email — list customer's open and past orders.
10.2 Search orders by status All "ready" orders, all "expired", etc.
10.3 Search orders by date Pickup date range.
10.4 Search orders by item "Who has reservations for Bloodgood Japanese maple?"
10.5 Search orders by project / PO Contractor work tracking.
10.6 Quick order lookup at register Scan customer phone/loyalty barcode → see pending orders.

Group 11: Multi-Site Fulfillment (Schema-ready v1.0, UI v1.5+) (6 features)

# Feature Notes
11.1 Customer-chosen pickup site "I'll pick up at Site B even though I ordered at Site A."
11.2 Site-of-fulfillment per order Order assigned to one specific site for fulfillment.
11.3 Inter-site stock transfer for fulfillment Move plants from Site B to Site A to fulfill order; tracked.
11.4 Split fulfillment across sites (Enterprise) One order, some items from each site.
11.5 Per-site reservation queue Each site sees its own pending orders.
11.6 Cross-site reservation reporting Owner sees all reservations across all sites.

Group 12: Order Templates (Recurring Contractor Orders) (8 features)

# Feature Notes
12.1 Save order as template After creating, save as reusable template.
12.2 Apply template to new order Pick template, customer is asked for modifications, order created.
12.3 Template per customer "Smith property weekly maintenance" specific to one contractor.
12.4 Template per project "Sunset Hills HOA annual landscaping" tied to a project.
12.5 Template scheduling Auto-create order on schedule (e.g., every Tuesday) — Pro+ tier.
12.6 Template modifications Edit existing template; new orders use updated version.
12.7 Template list view All saved templates, customer association, last-used date.
12.8 Template-driven bulk order generation "Create 12 weekly maintenance orders for next 12 weeks" — one click.

Group 13: Order Cancellation & Refunds (8 features)

# Feature Notes
13.1 Customer-initiated cancellation Customer (via app or call) cancels their reservation.
13.2 Staff-initiated cancellation Staff cancels (e.g., "we ran out of stock, sorry").
13.3 Cancellation reason capture Required for cancellations over $X (configurable).
13.4 Stock release on cancellation Reserved inventory automatically released to available.
13.5 Refund/credit on cancellation If deposit was paid, refund processed per policy.
13.6 Partial cancellation "Cancel 3 of 7 items, keep 4." Stock partially released.
13.7 Cancellation cooling-off period Once cancelled, can't re-create same order for X hours (prevents accidental).
13.8 Cancellation reporting Cancelled order count, reasons, $ value over time.

Group 14: Bulk Order Operations (4 features)

# Feature Notes
14.1 Bulk create orders from CSV Upload customer + items + qty for many orders at once.
14.2 Bulk update order status "Mark all of Friday's orders as ready" — manager-only.
14.3 Bulk cancel orders "Cancel all orders for product X because we're out of stock" — manager-only.
14.4 Bulk notification send Send custom email to all open orders matching criteria.

Group 15: Order Holds (3 features)

# Feature Notes
15.1 Hold order Order created but on hold pending credit check, customer approval, or other gate.
15.2 Credit-check hold Auto-hold orders that exceed customer credit limit until manager releases.
15.3 Hold release with approval Manager releases held order with PIN + audit trail.

Tier Behavior (Module-Level)

Tier Customer Orders capability
Starter Basic reservations only (no contractor B2B features, no quotes, no templates)
Pro Full reservations + contractor orders + quotes + templates + single-site fulfillment
Enterprise + Multi-site fulfillment + advanced allocation rules + custom workflows + SLA tracking

Configurable Defaults (Owner Dashboard)

Configurable Default
Deposit required at reservation OFF
Default reservation hold duration 7 days
Hold expiration warning 3 days, 1 day before
Auto-cancel on expiry ON (with email + audit)
Manager PIN for modifications ON if total changes >20%
Default quote validity 30 days
Default deposit % 0% (configurable per order type)
Contractor substitution default Ask first
Customer self-reservation via app OFF (future)
Cancellation reason required Required over $X
Cancellation cooling-off 1 hour
Order template scheduling OFF (Pro+ tier)
Order priority levels enabled OFF
Auto-allocation by priority on stock conflicts OFF
Manager approval for order discounts over X% ON at 20%
Packing slip auto-print at fulfillment OFF
SLA tracking enabled OFF (Pro+ feature)
Hold order auto-release timeout Indefinite (manual release only)
Credit-check hold trigger Auto when customer over limit

AI Features in Customer Orders

Feature # AI capability
2.9 AI substitution suggestions when vendor is short
5.9 AI partial fulfillment recommendation
9.5 AI reservation conversion forecasting
9.7 AI revenue forecast accuracy improvement
14.1 AI-assisted bulk order CSV mapping

All AI features use AWS Bedrock with Claude Haiku 4.5.

Events Emitted

  • orders.reservation_created
  • orders.reservation_cancelled
  • orders.reservation_expired
  • orders.reservation_fulfilled
  • orders.reservation_partial_fulfilled
  • orders.special_order_created
  • orders.special_order_received
  • orders.contractor_order_created
  • orders.quote_created
  • orders.quote_accepted
  • orders.deposit_received
  • orders.payment_received
  • orders.order_modified
  • orders.order_cancelled
  • orders.ready_for_pickup
  • orders.fulfilled
  • orders.order_held
  • orders.hold_released
  • orders.backorder_created

Events Consumed

  • inventory.stock_changed (update available qty for reservations)
  • inventory.variant_updated (refresh cached variant info)
  • crm.customer_updated (refresh customer info)
  • pos.sale_completed (mark reservation as fulfilled when sale converts)
  • purchasing.po_received (notify customer their special order arrived)
  • billing.subscription_changed (enforce tier limits)

API Contract (OrdersService — public methods)

High-level surface (detailed signatures during implementation):

  • Reservation lifecycle: createReservation, modifyReservation, cancelReservation, extendReservation, fulfillReservation, partialFulfill
  • Pre-orders/special orders: createPreOrder, createSpecialOrder, linkVendorPO
  • Contractor orders: createContractorOrder, applyContractorPricing, checkCredit
  • Quotes: createQuote, sendQuote, acceptQuote, convertQuoteToOrder
  • Fulfillment: generatePickList, markItemPicked, markReadyForPickup, allocateStock, generatePackingSlip
  • Modifications: modifyOrder, addLine, removeLine, changeQty, overrideLinePrice
  • Cancellation: cancelOrder, partialCancel, releaseStock
  • Holds: holdOrder, releaseHold
  • Reports: openOrdersDashboard, agingReport, slaReport, backorderReport
  • Templates: saveOrderTemplate, applyTemplate, bulkGenerateFromTemplate

Out of Scope

Capability Why excluded
Online customer self-ordering Future v1.2 (e-commerce module)
Online customer payment via web Future v1.2
Real-time inventory visible to public website Future v1.2
Wholesale RFQ (request for quote) workflows Wholesale territory — Module 4 (Purchasing)
Order routing optimization (which warehouse picks) Beyond retail scale
EDI order intake Wholesale territory
Multi-currency order support (UI) Schema-ready, deferred UI
Fax order intake Almost obsolete
AI email order parsing Future v2.0

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
4 Job costing / landscaping Module 3 Group 3 has contractor orders with project tags; no central job object Research §6.1 + §10.C Deferred (v1.5) — Job costing as first-class module ships with Enterprise launch. See ROADMAP v1.5.
10 Workshops as sellable items No event/workshop reservation type with capacity/schedule/attendee list Research §3 — Dig Gardens Deferred (v1.2) — Bundle with v1.2 scheduling expansion.
Last modified: Jun 17, 2026, 6:57 PM PT
← Previous02_pos
On this page
Esc
↑↓ navigate↵ openEsc close