Parse the 856 HL loop structure: the BSN segment contains the ship notice number and date; HL01/HL02/HL03 identify hierarchy levels (Shipment=S, Order=O, Item=I); TD1 contains packaging; SN1 contains shipped quantity.
Resolve the purchase order reference from the PRF segment (PO number) by querying NetSuite via SuiteQL: SELECT id FROM Transaction WHERE type='PurchOrd' AND tranId='<PO>'.
In the RESTlet POST handler, create an itemReceipt record in dynamic mode using record.transform({fromType: record.Type.PURCHASE_ORDER, toId: poId, toType: record.Type.ITEM_RECEIPT, isDynamic: true}).
For each SN1 segment (item line), match on itemNumber (PO1 or LIN segment VC qualifier) to the PO line, set the quantity on the receipt line, and populate inventorydetail with lot/serial numbers from the MAN or PID segments if present.
Set the item receipt header fields: tranDate from the BSN02 date segment, externalId from BSN02 ship notice number for idempotency.
Save and return the NetSuite internal ID; send an EDI 997 Functional Acknowledgment back to the trading partner to confirm receipt of the 856.
Known gotchas
The 856 HL loop hierarchy can have varying levels (Shipment > Order > Pack > Item) depending on the trading partner's implementation guide; the integration must inspect HL03 (level code) dynamically rather than assuming a fixed depth.
NetSuite item receipt transform from a purchase order marks received lines and reduces open PO quantities; creating an item receipt directly (not via transform) bypasses PO line linkage and leaves the PO quantities as still-open.
If the 856 contains an item not on the referenced PO, attempting to set that item on the receipt transform will fail — pre-validate all item numbers from the 856 against PO lines before starting the record transform to surface errors early.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp