New customer onboard

What this is

New customer onboarding is the simpler sibling of new_assembly_item. The cascade is narrower but the duplicate check is critical — a duplicate customer creates two AR records, two pricing trees, and a downstream mess that takes hours to unwind.

The 10-step cascade culminates in a "first-quote-context bundle" — a pre-built reference dossier so when the customer's first quote drafts, the AI has the full context (terms, MDF tier, sales rep, expected SKU mix) already loaded.

Risk level 3 (medium). The block-severity duplicate check is the main guard.

When to use it

Trigger conditions

A sales intake form is submitted via /intake.html.
A bid award arrives for a previously-unknown customer (bid_award_notification chains here).
A K-12 district or NYC DOE feeder customer is added during bid prep.
A wholesale account is added during M&A integration.

Heuristic

Duplicate check runs by name AND email — both lowercase-matched. Common false positives are franchise locations of the same parent (e.g. "Driscoll Foods" vs "Driscoll Foods - Bronx"); Mike confirms with the sales rep before overriding.

Step-by-step what happens

The 4 beats

01

Write customer record

INSERT into customers with company name, contact, billing/shipping addresses, terms, credit limit, and sales rep.

Writes customers

Time ~80ms

Kind d1_write

Status stub
02

NS customer record

Enqueue NS customer creation. The NS internal id back-fills into D1 when the push drains.

Writes NetSuite customer record

Time ~3–8s

Kind ns_push

Status stub

Note retry · 3 attempts exponential
03

Assign default customer_programs

INSERT default customer_programs rows: payment_terms=Net 30, default MDF tier, default rebate tier. These can be edited later via program-specific workflows.

Writes customer_programs

Time ~120ms

Kind d1_write

Status stub
04

Welcome email draft

AI drafts a welcome email introducing GFS, listing the sales rep, and providing the first-quote-context. Mike approves before send.

Writes outbound_email_log

Time ~80ms

Kind hitl_email_draft

Status stub

Note target · customer

Outcomes

What's different after the workflow runs

Duplicate check

Blocked

by name + email

NS customer

Created

≤ 15 min

Default programs

Assigned

Net 30, default MDF

Welcome email

Drafted

awaiting Mike's tap

A new customers row + NS internal id back-filled.
Default customer_programs assigned.
AR setup with credit limit + terms.
Welcome email draft waiting for Mike.
First-quote-context bundle pre-built so first quote drafts faster.
reflexion_log carries a new_customer tagged row.

Failure modes

What can go wrong and how to recover

Duplicate customer found

Precondition blocks. Mike confirms with sales: is this truly a new location? If yes, override with a tagged note. If no, redirect to customer_record_review for the existing record.

Invalid email format

Precondition warns. Often a typo; sales fixes and re-stages.

NS push fails

Retry policy is 3 exponential attempts. D1 holds the proposed state; drainer recovers within 15 minutes.

Customer onboard from bid award

When chained from bid_award_notification, the bid context auto-populates the first-quote-context bundle — saves Mike a few minutes.

Adjacent workflows + diagrams

For developers

Code paths + invariants

Concern	Where
Workflow contract	workflow_definitions WHERE workflow_type='new_customer'
Duplicate check	name (lower) OR email (lower)
Default terms	Net 30
NS RESTlet	customscript_gfs_platform_query
First-quote-context	pre-built dossier for first quote
Reflexion tag	new_customer
Risk level	3
Expected duration	~20 min
Trigger	manual · sources=sales_intake_form

// Duplicate check is case-insensitive on both fields const dup = await db.prepare( "SELECT id, companyname FROM customers " + "WHERE LOWER(companyname) = LOWER(?) OR LOWER(email) = LOWER(?)" ).bind(name, email).first(); if (dup) throw new Error('duplicate_customer');