Shipping Automation — Module 5: Courier Approval & Set Ship Date

Saved-search entry criteria ("Sales Orders NSSS")

An order only enters when all hold:

• Sales order balance owing = 0
• At least 1 item not shipped
• "Exported to Courier" = false
• "Hold Order" = false
• "Courier Approval" = false
• Orders / items not closed
• No item has a Drop Ship PO
• Item default shipping method is 2 Man Sensitive or Standard
• Ship Date not on/before today OR Ship Date empty & "Reason for service change" empty

What it reads, and where from.

Each flow is fed by a NetSuite saved search returning one row per order line (rows sharing SO_internalID belong to the same order).

SO_shipTogetherWithID (7136 only) is the internal ID of another SO this order must ship with — the field mergeSalesOrders follows to build ship-together groups. Search 7132 omits it, which is why nswo has no merge step.

Key columns: SO_postcode/SO_state (postcode + linehaul), SO_shipVia/SO_shipViaId (current courier), SO_lifeRegion/SO_lifeTruckNumber (scheduling/CBM), SO_cxRequestedDate, SO_courierServiceLevel (paid level), item_defaultShippingMethod (item mix), item_packageCBM (× committed qty = CBM), item_qtyCommitted (drives the "all committed?" gate).

Ship-via reference (from live data): 3420 = TBC · 201100 = Life 2 Man · 247628 = Life Standard · 253939 = Life Full Service · 112729 = TLC · 112728 = Pedemont · 17186 = AusPost · 39973 = Allied · 2864 = Designer Transport.

Customer requested delivery date

Field: SO_cxRequestedDate — the date the customer asked to receive the order by. Present in both saved searches, format DD/MM/YYYY, and may be blank. For a merged swo group the automation uses maxCxRequestedDate — the latest requested date across all linked orders — so the whole group lands on or after the latest customer ask.

How it's used: it sets a floor on the scheduled date. The Date Check base date is the SO committed date / today, or the CX requested date when that is later than the committed / PO dispatch date. The chosen ship/delivery date is then the first valid courier day on or after that floor. Blank = no customer preference → the courier buffer governs instead.

Ship together with this order

Field: SO_shipTogetherWithID — the internal ID of another sales order this order must be delivered with. Present only in the 7136 (swo) search; blank means the order ships on its own.

It drives two mechanisms:

1. Flow 1 (nswo): an order flagged to ship together with another SO has its Ship Complete set to Yes, so it drops out of Flow 1 and is picked up by Flow 2 (swo) on the next run. (nswo's search has no SO_shipTogetherWithID column — this is the "Ships together with another SO?" gate.)
2. Flow 2 (swo): mergeSalesOrders follows SO_shipTogetherWithID to build a group, which:
   • ships together — updateGroupedSalesOrders writes the same courier + dates to every linked SO;
   • only proceeds when every item across all linked SOs is committed (allSOsCommitted) — otherwise the whole group waits;
   • uses group totals — total CBM across all items, and maxCxRequestedDate;
   • pulls in a linked SO that isn't in the search results via SuiteQL (ns.getSalesOrder).

Example (reciprocal group): a Float modular sofa split across two orders that reference each other:

They merge into one group (VIC 3754, Full Service). Because the third piece is 0/1, allSOsCommitted is false → the group waits, nothing is booked, and it retries next run once the piece is committed.

Data quirks:

• Self-reference: some rows set SO_shipTogetherWithID to their own internal ID (e.g. S311157, S312794) — a group of one; the merge logic tolerates it.
• Chains: links can chain (A↔B, B↔C) — the group is the whole connected set of orders.

What it does with that, step by step.

Base date = SO committed date / today, or the CX requested date when it is later than the SO committed date or the PO dispatch date (SO_cxRequestedDate in nswo; maxCxRequestedDate across the group in swo).

• Buffer: non-Life count business days; Life trucks may count weekend days when marked available in the schedule sheet.
• CBM: for Life trucks, capacity is checked against the schedule sheet per region (limited to the first few candidate dates); capacity is reserved on selection. Ordering resolved by which SO was placed first.
• Schedule/CBM loop: schedule check → if no available date, ignore order + error email; else CBM check → fits ⇒ approve, else find next available date and repeat.
• Life deliveries to states other than NSW/VIC/QLD are rejected (no partial update).

The above is the current behaviour. A revised date model is planned — see below.

Planned change — ship date, SDD & linehaul

Status: planned — not yet implemented in shipping-v6-nswo / shipping-v6-swo. Documented here ahead of the code change; until it ships, the current logic above applies.

The revised model computes the ship date first and derives the delivery date forward, and it removes the fixed weekly linehaul weekday (Tue/Thu) anchoring.

What changes vs the current (OLD) logic:

When this ships, the Which day it ships diagram and the linehaul rows in Test cases (group F) should be updated to match.

First courier whose postcode check passes wins (each courier has a whitelist CSV in S3).

When no courier in the hierarchy covers the postcode, the customer's checkout pick is approved instead, under reason code 14 — see LI-BL-FRT-001 rows 2 and 3 for the rule, and SA-D9 for the mechanism swo now uses.

⚠️ Board vs code mismatch: the disapprove note is labelled (10) on the Miro board, but every deployed config sets N_RFSC_DIS_PCODENOTCOV = 5. Treat 5 as the live value; confirm in NetSuite.

A Google Sheet (single tab INTEGRATION SCHEUDULE) maintained by the fulfilment team. The Courier Schedule microservice reads it; the automation only reads it.

Layout: columns A–H are per-courier/truck settings; every following column is one calendar day with a TRUE/FALSE availability flag.

Two dedicated linehaul rows mark departure days (toggleable per week):

• LINEHAUL - VIC — every Thursday (SYD → MEL)
• LINEHAUL - QLD — every Tuesday (SYD → BRIS)

Rules baked into the sheet:

• Life availability sets the scheduled delivery date; other couriers set the ship date.
• Buffers exclude weekends unless the weekend day is selected (e.g. order Thursday, buffer 3 → Fri + Mon + Tue; if Saturday available → Fri + Sat + Mon).
• Tiebreak: prefer the lower-CBM truck — "all loaded first".
• One Life row's three NetSuite IDs serve Standard, 2 Man, and Full Service ship-vias at once.

The same logic as a path through the decisions, in the order they run.

Four decisions, taken in this order: does it enter · which pile · which courier · which day. Each stage assumes the one above it has already run — the courier decides which buffer and which schedule row the date stage reads, so reading the date rules without the courier gives the wrong answer.

Every branch names the rule it implements. The codes down the right margin are this entry's test cases — prefix them with SA-TC- to find one (F4 is SA-TC-F4). Where an open defect changes what actually happens, the branch says so and names it: the tree describes deployed behaviour, not the board, which is the whole reason it is worth reading next to the tables above.

Stage 1 — does the order enter at all? LI-BL-FUL-001

Nothing here is code. The saved search is the gate, and an order failing any one of these is never seen by the automation — it is not held, not logged, and not counted anywhere.

sales order
 ├─ balance owing > 0 ?                     ──► never selected              E1
 ├─ Hold Order = true ?                     ──► never selected              E2
 ├─ Courier Approval already true,
 │    or order / items closed ?             ──► never selected              E3
 ├─ every item has a Drop Ship PO ?         ──► never selected              E4
 ├─ no item still to ship ?                 ──► never selected
 ├─ an item is neither Standard
 │    nor 2 Man Sensitive ?                 ──► never selected
 ├─ Ship Date on/before today AND a
 │    reason for service change present ?   ──► never selected              E5
 └─ all of the above pass                   ──► enters, at stage 2

A silent run and a quiet day look identical from here: if the search stops returning rows, nothing is processed and nothing errors. That is a recorded failure mode, not a defect.

Stage 2 — which pile, and does the group wait? LI-BL-FUL-001, LI-BL-FUL-002

The one people get wrong: a Flow 1 order that must travel with another order is not merged now. It is flagged Ship Complete = Yes and picked up by Flow 2 on the next run, so it is a run behind. Search 7132 has no ship-together column at all, which is why Flow 1 has no merge step.

order
 ├─ Ship Complete = No   ──► Flow 1 · search 7132 (nswo)
 │    ├─ ships together with another SO ?
 │    │    └─ yes ──► set Ship Complete = Yes, stop.
 │    │               Flow 2 collects it NEXT RUN                           F2
 │    └─ no      ──► process alone, go to stage 3                           F1
 │
 └─ Ship Complete = Yes  ──► Flow 2 · search 7136 (swo), always second
      ├─ follow SO_shipTogetherWithID to build the group
      │    · a link that chains (A↔B, B↔C) pulls in the whole set
      │    · a self-reference is a group of one, and is tolerated
      │    · a linked SO missing from the search is fetched by SuiteQL      F5
      ├─ EVERY item across EVERY order in the group committed ?
      │    ├─ no  ──► the whole group WAITS. Nothing is written,
      │    │          nothing is booked, retried next run                   F4
      │    └─ yes ──► one group from here on:
      │               total CBM across all items,
      │               maxCxRequestedDate across all orders                  F3
      └─ go to stage 3

Stage 3 — which courier? LI-BL-FRT-001

The paid service level picks a hierarchy; the hierarchy is walked in order and the first courier whose postcode whitelist covers the address wins. A missing whitelist is indistinguishable from a genuine no-cover, which is what makes SA-D2 invisible in production.

paid service level
 ├─ Standard, but ≥1 item needs 2 Man handling ?
 │    └─ UPGRADE the whole order to the Two Man hierarchy, reason 21        C9
 │       (a margin loss by design — the customer paid Standard · SA-D4)
 │
 ├─ Full Service  ──► Life Full → DT Full
 │                    ⚠ SA-D8: the rules table and the courier diagram put
 │                      TLC here, auto-approved with no postcode check. In
 │                      swo TLC is tried in the TWO MAN branch instead, and
 │                      is auto-approved only when it is the front-end
 │                      pre-selection — otherwise the order falls through
 ├─ Two Man       ──► Life 2 Man → DT 2 Man → Pedemont → TT                 C3 C4
 │                    ⚠ SA-D2: TT has no postcode file, so it can never win    P3
 │                    ⚠ SA-D7: a PR titled "remove fallback to dt" did not
 │                      remove DT — DT 2 Man and DT Standard are both still
 │                      in nswo's hierarchy at that commit. Which fallback
 │                      it meant to drop is unestablished; the tree shows
 │                      what is deployed
 ├─ Standard, ≥1 Life item      ──► Life Standard → DT ATL                  C5 C6
 ├─ Standard, all AusPost items ──► AusPost                                 C7
 └─ Standard, other            ──► Allied                                   C8
      │
      ▼
 walk the hierarchy, first postcode match wins
 ├─ one covers the postcode ?  ──► APPROVED, reason 15                      C1 C2
 └─ none covers it ──► what did the customer pick at checkout?
      ├─ a real courier ──► approve the customer's pick, reason 14          P1
      │                     ⚠ SA-D9: swo no longer looks up the rate card;
      │                       it calls autoApproveFECourier instead
      └─ "To Be Confirmed" ──► HELD FOR REVIEW, reason 5                    P2
                               ⚠ SA-D1: the board says 10, every deployed
                                 config says 5. 5 is what runs

A 2 Man order whose committed items are all Standard_Auspost goes to manual review, not through this tree at all. That is deliberate scope, recorded as SA-D3 — case X1.

Stage 4 — which day? LI-BL-FUL-003

Two independent things set the date and they are easy to confuse: the buffer says how soon, the customer's requested date says no sooner than. Whichever is later wins. Only then is capacity checked, and only for Life trucks.

approved courier
 ├─ not a Life truck ──► the sheet's buffer sets the SHIP date
 │                       (non-Life buffer = 1 day)
 └─ a Life truck     ──► the sheet's buffer sets the SCHEDULED DELIVERY date
                         (Sydney 2–3 days · Melbourne / Brisbane 7)
   │
   ├─ 1. base date = SO committed date / today, OR the customer's
   │       requested date when that is later than the committed date
   │       or the PO dispatch date. The buffer runs from there, and
   │       the answer is the first valid courier day on/after it     S1 S4
   │       · blank requested date ──► the buffer alone governs
   │       · a merged group uses maxCxRequestedDate across the group
   │       · buffer days skip weekends UNLESS the sheet marks that
   │         weekend day available                                          S5
   │
   ├─ 2. state decides the shape of the answer
   │       ├─ NSW or ACT  ──► ship and deliver the SAME day                 L1
   │       ├─ QLD         ──► deliver on a Brisbane day; ship on the
   │       │                  weekly SYD→BRIS linehaul — TUESDAY            L2
   │       ├─ VIC         ──► ship on the weekly SYD→MEL linehaul —
   │       │                  THURSDAY                                      L3
   │       └─ anything else on a Life truck
   │                       ──► REJECTED, left for review, no partial
   │                           update written                               L4
   │
   ├─ 3. does the order's CBM fit that truck's remaining capacity?
   │       ├─ no  ──► take the next available date and repeat from 3        S2
   │       └─ yes ──► reserve the capacity on selection
   │                  two trucks both fit ? take the LOWER-CBM truck        S6
   │                  two orders compete ? the one placed FIRST wins
   │
   └─ 4. no date at all fits ──► order ignored, error email to fulfilment   S3

A revised date model is planned and is not live. It would work the ship date out first and derive the delivery date forward from it, dropping the fixed Tuesday / Thursday linehaul days. Until it ships, stage 4 above is what runs. See Planned change in this reading.

What is written, and what is not — case X2 checks the code on every outcome

Two mechanics sit outside the tree and change nothing it decides. A run nearing the ~14 minute Lambda limit re-invokes itself, up to three times, and the orders it had not reached are processed by the next invocation (X3). If the Courier Schedule service is unavailable the automation falls back to a cached schedule, and terminates without writing if there is none (X4).

What it writes, and who reads it afterwards.

What a run leaves behind on an approved order. The ids for most of these are not yet in the field registry — only SO_shipVia is — so they are listed here by the name they carry on the NetSuite Sales Order form. Confirming the ids is outstanding.

Real records carried end to end, so the logic can be checked against something that happened.

Real orders traced end-to-end (dates computed from a 31 Jul 2026 run against the schedule sheet).

A · Local 2-Man (nswo) — S315316

NSW 2112, Syd R5 - North West, paid 2 Man, 2 items (Standard-Life), CBM 4.8 m³, CX date 30/10/2026. → Life 2 Man; CBM 4.8 vs 6 m³ truck (tight fit); CX date 30/10 overrides the 3-day buffer; NSW = local so ship = delivery on the first Syd R5 truck day on/after 30 Oct 2026. Approved (15).

B · Local Full Service (swo) — S308550

NSW 2040, Syd R4 - West, paid Full Service, 1 item, CBM 1.39 m³, no CX date. → Life Full; CBM fits 16 m³; 3-day buffer → ship & deliver Fri 7 Aug 2026. Approved (15).

C · Interstate QLD linehaul (swo, merged) — S310492 + S310562

QLD 4173, Bris R3 - East, Full Service, both orders committed, group CBM 0.74 m³. → Life Full; fits 13 m³ truck; latest CX date (5/7/2026) is past so 7-day buffer applies; first Bris R3 truck day = deliver Tue 18 Aug 2026; QLD linehaul → ship Tue 11 Aug 2026 (SYD → BRIS), applied to both linked orders. Approved (15).

D · Merged group — waiting (swo) — S301287 + S306157

VIC 3754, Full Service, a Float modular sofa split across two linked orders; one piece 0/1 in stock. → allSOsCommitted = false → whole group skipped this run, retried next run when the last piece is committed. Waiting — nothing booked.

What to run to know the behaviour is intact. Expected values, never “should work”.

Scenario, input and expected outcome for each rule. Reason codes: 15 approved · 21 upgraded · 14 rate-card · 5 disapproved (postcode).

What a person checks, by hand, before it is trusted.

How the business signs this off. The Result column on every table below doubles as the sign-off sheet — tick it against a real run, and record who ticked it.

How to run UAT (staging)

• Environment: run on staging — AWS_LAMBDA_FUNCTION_VERSION=$LATEST selects the staging config (sandbox NetSuite, staging courier API).
• Dry-run first: swo exposes N_QUEUER_DRY_RUN, NS_SAVED_SEARCH_DRY_RUN, COURIER_SCHEDULE_API_DRY_RUN; nswo has AWS_RDS_IN_DRY_RUN + a courier dry-run. Trace decisions without writing to NetSuite.
• Seed: create a sandbox sales order that meets the entry criteria (paid, not on hold, not already approved, correct item shipping methods).
• Trigger: invoke the Lambda (manual kickoff / test.index.mjs).
• Verify in NetSuite: Courier Approval set, Ship Via updated, RFSC reason code, Ship Date + Scheduled Delivery Date (and linehaul fields for QLD/VIC). Check the logs; confirm no error email unless the case expects one.

What breaks it, how that shows, and how to recover.

These are read from the documented behaviour, not from an incident log. Detection is honestly recorded as "not detected automatically" wherever nothing watches for it.

Scope that was deliberately chosen. A limitation is a decision.

Deliberate scope, not mistakes. Keeping them here stops them being re-raised as defects.

Where it does something other than what was decided. A defect is a mistake.

Where the deployed code and the documented or expected behaviour do not line up. Each carries a reference so it can be quoted in a ticket, the same way the Lead Time defects are. These describe code, never people.

The code and searches this reading was written from.

Business logic lives in these files (do not edit — read-only per the access policy). The two controllers/app.mjs files are the entries' pinned code_refs (front-matter) and were re-verified at the commits below; the remaining files are the wider source map and were not individually re-verified in this pass.

Verified this pass (main decision loop):

• shipping-v6-nswo/controllers/app.mjs @ 0ed5ee9 — nswo decision loop (verified 2026-08-04)
• shipping-v6-swo/controllers/app.mjs @ 69029d7 — swo decision loop, grouping (verified 2026-08-04)

Wider source map (not re-verified this pass):

• helper/courierScheduleClient.mjs — buffers, CBM, date selection
• helper/formatter.mjs — order formatting (swo adds mergeSalesOrders)
• controllers/ns.mjs — NetSuite writes (swo adds updateGroupedSalesOrders)
• controllers/aws.mjs — postcode validation, S3, SES
• helper/enums.mjs — couriers & service levels
• config/{staging,production}.mjs — reason codes, saved-search IDs

Full architecture, repo differences, and file-by-file detail are captured in this entry itself, across the three readings — this registry is the self-contained reference.

What moved on this page, and when.

Inputs

Outputs