New ingredient / vendor onboard

What this is

New ingredient / vendor onboard

New vendor onboarding is the lighter sibling of new_customer. The cascade covers vendor master data, baseline vendor_costs for initial items, NS vendor record, and a sourcing analysis pass that surfaces existing items the new vendor could supply (often the reason for the onboard in the first place).

Critical block: the no-duplicate precondition. Duplicate vendors are even worse than duplicate customers — they fragment cost history and break weighted-average computations.

Risk level 3 (medium).

When to use it

Trigger conditions

A vendor intake form is submitted from /intake.html.
A first PO is drafted for a vendor not yet in the system.
A vendor cost update arrives by email from an unknown vendor (chains via inbound_email_triage).
A new commodity supplier is added (USDA program expansion).

Heuristic

Vendor duplicate check uses name OR email — same logic as new_customer. A common pattern: subsidiary of an existing parent vendor. Mike confirms with the buyer before overriding.

Step-by-step what happens

The 2 beats

01

Write vendor + vendor_items

INSERT into vendors for the new entity. Batch INSERT into vendor_items for the initial item mappings (vendor_item_code → internal item).

Writes vendors, vendor_items

Time ~150ms

Kind d1_write

Status stub
02

NS vendor record

Enqueue NS vendor creation via customscript_gfs_platform_query RESTlet. NS internal id back-fills on drain.

Writes NetSuite vendor record

Time ~3–8s

Kind ns_push

Status stub

Note retry · 3 attempts exponential

Outcomes

What's different after the workflow runs

Vendor

Created

D1 + NS

Initial items

Linked

vendor_items batch

Duplicate guard

Blocked

name OR email

AP setup

Initialized

terms + tax_id

A new vendors row with NS internal id back-fill.
vendor_items rows for the initial product mapping.
Baseline vendor_costs ready for the first PO.
Sourcing analysis surfaces existing items that could use this vendor.
AP setup with payment terms.
reflexion_log carries a new_vendor tagged row.

Failure modes

What can go wrong and how to recover

Duplicate vendor found

Precondition blocks. Mike confirms: is this a subsidiary? If yes, override + tag. Often the right answer is to use the parent vendor record and add this as a new vendor_items mapping.

No initial items provided

Vendor is created but vendor_items is empty. The first PO will need to link items manually. Often happens for service vendors.

NS vendor push fails

Retry policy is 3 exponential attempts. Drainer recovers within 15 minutes.

Vendor also overlaps as customer

Per the R115 brain dump, several entities are both (Bongards, Echo Lake Foods). The customer + vendor records exist separately; they don't conflict.

Adjacent workflows + diagrams

For developers

Code paths + invariants

Concern	Where
Workflow contract	workflow_definitions WHERE workflow_type='new_ingredient_vendor_onboard'
Duplicate check	name (lower) OR email (lower)
Customer-vendor overlap	see feedback_customer_vendor_overlap memory
NS RESTlet	customscript_gfs_platform_query
Reflexion tag	new_vendor
Risk level	3
Expected duration	~30 min
Trigger	manual · sources=vendor_intake_form

// Same dup-check shape as new_customer const dup = await db.prepare( "SELECT id, companyname FROM vendors " + "WHERE LOWER(companyname) = LOWER(?) OR LOWER(email) = LOWER(?)" ).bind(name, email).first(); if (dup) throw new Error('duplicate_vendor');