NS sales order — master

Email intake, 3 fulfillment paths, Finance handoff

The NS sales order lifecycle is the canonical revenue flow — the way orders actually move at GFS. Most customer orders arrive by email at orders@globalfoodsolutions.co or danielle@globalfoodsolutions.co. The team reads each order against the customer file, confirms item details / shipping / pricing / special instructions, then keys it into NetSuite as a Sales Order.

From there the SO branches by item type into three parallel fulfillment paths: fulfill from inventory (already on hand), assembly build (Work Orders are created FROM the SO — records stay linked), or drop ship (Purchase Orders are created FROM the SO and sent to a vendor). A single SO routinely spans multiple paths because items often differ in type.

All three paths converge at Item Fulfillment. That fulfillment fires an automated alert to Finance — the single named handoff between Operations and Finance. Finance reviews, invoices the customer, monitors payment terms, and triggers dunning if the invoice goes past due. On the drop-ship path, the vendor-bill cycle runs in parallel.

Diagram: ns-sales-order-master.html. Path detail docs: Path 1 inventory · Path 2 assembly · Path 3 dropship. Open STUBs: EDI 850 auto-intake, auto path classifier, NS workflow build for the Finance alert (next round). TBD: Work Order customer PO# field — pending Mike's review (expected pattern bodyFields.memo).

Trigger conditions

• Customer emails an order to orders@globalfoodsolutions.co or danielle@globalfoodsolutions.co (the dominant intake channel).
• Customer transmits EDI 850 — today lands in a mailbox and is keyed into NS by an operator (auto-parse STUB).
• Customer self-serves via the customer portal upload form.
• CS desk enters directly into NS UI from phone or fax.
• Bid award triggers a release order against a bid contract (e.g. B5875 weekly draws).

Driscoll weekly mixed-path order

Intake → SO entry → 3 paths → Finance

Common steps run first. Then the SO branches into one of three paths (a single SO can hit multiple). All paths converge at Item Fulfillment, which fires the automation alert to Finance.

Common steps (every SO)

1. 01

   Receive customer order

   Most orders arrive by email at orders@globalfoodsolutions.co or danielle@globalfoodsolutions.co. Other channels: NS UI direct entry, customer portal, EDI 850 (manual keying today, auto-parse STUB), phone keyed by CS.

   Mailboxes orders@, danielle@
2. 02

   Review against customer file

   Team reads the order against the customer record: ship-to address, pack/UOM details, pricing alignment (contract / program / list), special instructions, delivery windows.

   Reads customers, pricing_master, customer_programs, contracts
3. 03

   Enter SO in NetSuite

   SO posted as system-of-record. D1 mirror lands on the next 2-min hot-tier sync.

   Writes NS SalesOrd, transactions, so_lines
4. 04

   Classify each line by item type

   Operator (today) sorts each line into Path 1 / 2 / 3. A single SO can fan out into multiple paths. Auto-classification on intake is a STUB.

   Decision inventory · assembly · dropship

Path 1 — Fulfill from inventory

1. 1.1

   Allocate from inventory

   Check inventory_balance.quantityavailable ≥ line qty at the fulfillment location. Reserve qty against the SO.

2. 1.2

   Pick, pack, stage

   Warehouse executes the pick list (scan + label), palletizes, and stages for carrier pickup.

3. 1.3

   Item Fulfillment completed

   Fulfillment record closes (status='Shipped'). ★ Automation alert fires to Finance. Continues to the Finance steps below.

Path 2 — Assembly build (Work Orders FROM SO)

1. 2.1

   Create Work Orders FROM the SO

   For each assembly-build line, a Work Order is created with parent_so_id linking it back to the originating Sales Order. Records stay linked end-to-end. Alternate: if the assembly is already in inventory, fulfill from inventory and close the Work Order.

   Writes NS workorder with parent_so_id
2. 2.2

   Complete the assembly build

   Production crew executes the build on the floor — capture qty + waste + scrap, consume raw components, credit finished goods. Mike approves at /assembly-build.html.

   Writes assemblybuild, inventory_balance
3. 2.3

   SO fulfilled to customer · Item Fulfillment completed

   Once the assembly is on hand, the SO ships. ★ Automation alert fires to Finance. Continues to the Finance steps below.

Path 3 — Drop ship (Purchase Orders FROM SO)

1. 3.1

   Create Purchase Order FROM the SO

   For each drop-ship line, a PO is created with parent_so_id linking it back to the originating Sales Order. PO is transmitted to the vendor.

   Writes NS purchaseorder with parent_so_id
2. 3.2

   Vendor ships · Item Receipt posted

   Vendor ships product (directly to customer or to GFS for crossdock). Item Receipt posted against the PO; PO line closes.

   Writes NS itemreceipt
3. 3.3

   SO fulfilled to customer · Item Fulfillment completed

   ★ Automation alert fires to Finance. Continues to the Finance steps below.

4. 3.4

   Vendor bill cycle (parallel)

   Separate from the customer-side invoice cycle: vendor bill entered against the PO, paid per vendor terms.

   Writes NS vendorbill, vendorpayment

★ Finance steps (every path converges here)

1. F1

   ★ Automation alert → Finance

   On every Item Fulfillment completion (across all 3 paths), an automated alert fires to Finance. This is the single named handoff between Operations and Finance. The actual NS workflow trigger config still needs code-level verification (STUB on confirmation, not on existence).

   Trigger itemfulfillment.status='Shipped'
2. F2

   Finance reviews fulfillment

   Finance checks fulfilled qty matches expected, pricing carried through, customer terms + tax handling correct, short-ships flagged.

3. F3

   Invoice customer

   Finance posts CustInvc using shipped qty (not ordered qty). AR balance updates.

   Writes NS CustInvc, invoice_lines
4. F4

   Invoice open · monitor payment terms

   Invoice remains open until payment received. v_customer_ar_aging tracks the bucket (current / 30 / 60 / 90+).

5. F5

   If past due → dunning fires

   The ar_aging_action_plan workflow kicks in. Dunning email drafted at escalating tone for 30 / 60 / 90+ buckets. Email send remains HITL-confirmed. Loops until paid or escalated to service hold.

   Workflow ar_aging_action_plan
6. F6

   Payment received · apply · close

   Customer remits; CustPymt posted; payment_applications matches payment to invoice(s). SO closes; events.order.closed fires for the customer health watcher.

   Writes NS CustPymt, customer_payments, payment_applications

What's different after the cycle

• Customer received goods; we received payment (eventually).
• AR aging buckets reflect the current state of every invoice.
• Customer health score updated with new velocity + DSO data.
• Events ledger has a full audit trail per SO — replayable for any consumer.

What can go wrong

Adjacent flows + diagrams

Code paths + invariants

Dated trail · spot stale claims

Dated trail of when this doc was last touched, what changed, and what to look at if it feels stale.

The machine-readable spec

Canonical fields, table names, endpoint signatures. What code should match, what tests should assert. Master workflow_type · sales_order_lifecycle · risk_level · 2. Sub-contracts: so_lifecycle_inventory_path (risk 2), so_lifecycle_assembly_path (risk 3), so_lifecycle_dropship_path (risk 3).

Customer PO# threading (THE trace thread across every connected NS record)

The customer PO# (entered as otherrefnum on the SO) threads through every connected NS record. Grep this single field across the whole lifecycle to find every record for a given customer order.

Trace recipe: grep "72622" across transactions.otherrefnum + purchase_orders.memo + customer_invoices.otherrefnum + vendor_bills.memo + vendor_bills.tranid + item_fulfillments.otherrefnum lights up every record in the SO chain. WO field TBD pending Mike's review.

Inbound sources (where orders come from)

Inputs (required + optional)

D1 tables touched (across the 3 paths)

Endpoints called

Events fired

It broke at 2am — what now

Different from "how do I use this." This is the page Mike pulls up when something is wrong: logs to check, recovery steps, who to escalate to.

Logs to check

• workflow_run_log · top-level run audit
• workflow_step_log · per-step trace
• workflow_verify_results · post-window verify outcomes
• cron_locks · stuck cron lock detection
• events · workflow.completed / workflow.failed event trail
• reflexion_log · per-run narrative (if reflexion_enabled)
• npx wrangler tail · live Worker logs

Kill switch · emergency stop

If this workflow is misbehaving in a high-impact way (creating bad proposed_actions in volume, pushing wrong things to NS), flip a kill switch:

• kill:ns_writes · stops every NS push platform-wide
• kill:proposed_apply · stops HITL approvals from executing fan-out
• kill:high_risk_ops · stops risk_level >= 4 fan-out

See kill-switches-state-machine.html for the full state machine + recovery procedure.

Escalation

Primary: Mike Levine (single-admin) · mikelevine@globalfoodsolutions.co. For prolonged outage during business hours, notify warehouse lead + accounting lead so they can defer dependent work.

What's not done · what's uncertain

What's not done, what's uncertain, what we punted. Captured so it survives context switches and doesn't die in someone's head.

• STUB
  EDI 850 auto-intake

  EDI orders today land in a mailbox and are keyed into NS by hand. No AS2 endpoint, no X12 parser wired to /api/so/create. Wire as a Cloudflare Worker once volume justifies.

• STUB
  Auto-classify which path applies (inventory / assembly / dropship)

  Today operators classify each line by item type mentally. Classifier could surface mixed-path orders earlier and auto-stage WO + PO from the SO via a single fan-out.

• STUB
  Verify the Finance automation alert in code

  The "automation alert → Finance" is a documented concept. The NS workflow trigger on itemfulfillment.status='Shipped' needs code-level confirmation. Check NS workflow studio config and walk one fulfillment end-to-end.

• DECISION
  Add finance_invoice_review as the 27th v2 workflow contract?

  The Finance steps (review → invoice → monitor → dunning → payment apply → close) currently live as fan-out targets of sales_order_lifecycle. Could be promoted to a standalone workflow contract that bridges fulfillment and AR. Pending Mike's call.

• DECISION
  Credit-check precondition: keep block or keep warn?

  Mike's documented process does not show an explicit credit-check gate. The current contract has under_credit_limit as a warn precondition. Confirm with Mike whether NS-side enforces this or whether it should be removed.

• OPEN
  NS webhook for real-time SO sync

  Today 2min polling. Webhook would shrink the email-to-D1-mirror gap.

• DEFER
  SO profitability snapshot at SO creation

  Capture margin at SO creation time, not just at month-end. Useful for Finance review step.