The AI TMS Blueprint · Sheet 01

Freight EDI integration: onboarding and repair

A reference flow for the four messages a brokerage lives on — the load tender, the response, the status stream and the invoice — and the failure modes that actually break partner go-lives. Written from published X12 implementation guides, not from any customer's system.

Book a 30-minute call with our expert The rest of the blueprint

Free reference

The EDI partner onboarding checklist

Twelve things to settle with a trading partner before the first file moves. One page, sent to your inbox.

204 · 990 · 214

Tender, response and status — the three a brokerage lives on

210 · 997

Invoice and functional acknowledgement, inside ISA/GS/ST envelopes

$4,500

Fixed-price pilot: one partner, one lane, three weeks

Failure modes this sheet documents, with the handling for each

The flow

Every step is a message leaving or entering your system.

The two that get skipped in a rushed build are the acknowledgement going back to the partner and the queue catching what cannot be classified — and those are exactly the two that make a partner telephone you.

1Partner VAN or AS2inbound mailbox
2Validateenvelope, delimiters, code lists
3Map tender to a loadby qualifier, never by position
4TMS load recordidempotent write
5990 tender responseaccept or decline
6214 status streamone message per milestone
7210 invoiceafter delivery is confirmed
exceptionHuman queueRaw segment kept — nothing is discarded.

The messages

The four messages, with payloads.

Illustrative values, standard shapes. The notes mark the elements that decide whether a load is created once, twice or not at all.

204 — load tender

shipper or broker → you

ST*204*0001~
B2**SHPR**ORD-88213**PP~
B2A*00~
L11*88213*BM~
L11*PO-4471*PO~
L11*CUST-9920*CR~
N1*SH*MIDWEST FOODS*93*SH4417~
N4*KANSAS CITY*MO*64120*US~
S5*1*LD~
N1*CN*GREAT LAKES DC*93*CN8802~
N4*CHICAGO*IL*60632*US~
S5*2*UL~
N7**53FT*****TL~
SE*14*0001~

B2A carries the purpose: 00 original, 01 cancellation, 04 change. Treat a change as a new tender and you get two loads for one shipment.
L11 references are identified by the qualifier in the second element — BM bill of lading, PO purchase order, CR customer reference. Read them positionally and every partner breaks you differently.
S5 is the stop sequence. Stop order and appointment order are not the same thing.

990 — tender response

you → shipper

ST*990*0001~
B1*YOURSCAC*ORD-88213*20261003*A~
SE*3*0001~

B1 echoes your SCAC and the tender's shipment id, so the reply can be matched to the tender it answers.
The last element is the one people get backwards. The base standard reads A as accepted and D as cancelled, and partner guides disagree — some use D for decline, others E. The code list belongs to the partner's guide, never to the standard.
A 997 is not an acceptance. Syntax passing and a load being accepted are different events, and conflating them is how a shipper comes to believe a truck is coming.

214 — shipment status

you → shipper, one per milestone

ST*214*0001~
B10*100012345*88213*YOURSCAC~
L11*88213*BM~
N1*SH*MIDWEST FOODS*93*SH4417~
LX*1~
AT7*AF*NS***20261006*1058*LT~
MS1*KANSAS CITY*MO*US~
MS2*YOURSCAC*TRL-4417~
SE*9*0001~

AT7 carries the status code, a reason code, then date, time and a time code. Here: departed the pickup, normal status, local time.
A common base set is X3 arrived at pickup, AF departed pickup with the shipment, X6 en route to delivery, X1 arrived at delivery, D1 completed unloading. Appointment codes sit in their own element: AA pickup, AB delivery.
That time code is why status events land on the wrong day. Local time with no offset has to be normalised against the stop's own zone before anything is ordered by it.

997 — functional acknowledgement

both directions

ST*997*0001~
AK1*SM*12947~
AK2*204*0001~
AK5*A~
AK9*A*1*1*1~
SE*6*0001~

AK5 is one transaction set's verdict, AK9 the whole group's: A accepted, E accepted with errors, R rejected.
The acknowledgement loop is the monitoring surface nobody builds. Reconcile every interchange you receive against the acknowledgements you sent, and you learn a partner's file failed before the partner rings to ask where the truck is.

Failure modes

Where freight EDI integrations break.

The happy path is a weekend's work. These are the reasons a go-live slips a month, in the order they tend to bite.

What ops sees	What is actually happening	How it gets handled
“We sent it.” Nothing in the TMS.	The interchange was rejected at the envelope, or no acknowledgement ever went back, and nobody is watching the loop.	Reconcile every interchange received against the acknowledgements sent. Alert on a missing or negative ack, not on a missing load.
The same load appears twice.	A resend with fresh control numbers, or a change tender processed as a new one.	Idempotency on partner, shipment id and purpose code. Changes and cancellations update the load that already exists.
A cancelled load keeps dispatching.	The parser only ever handled the original purpose code, so cancellations fall on the floor.	The purpose code drives the write path, and a cancellation for an unknown shipment is queued rather than dropped.
The shipper thinks a truck is coming. It isn’t.	A functional acknowledgement was read as a business acceptance.	Syntax and acceptance are separate states. A tender is accepted only on a response carrying that partner’s accept code.
Declines read as accepts.	The response code list differs between the standard and the partner’s own guide.	Code lists are per-partner configuration, loaded from their guide and tested against their samples before go-live.
Tracking events arrive out of order, or on the wrong day.	Status timestamps are local time with no offset, and the stream is ordered by arrival instead.	Normalise every event to UTC using the stop’s own zone, keep the original, and order by event time.
Some status updates never show.	The partner sends codes outside the subset their own guide lists, and unmapped codes are discarded.	Unknown codes land as unclassified with the raw segment attached, visible in a queue a human clears.
Every new partner takes weeks.	Delimiters, envelope ids, qualifiers and code lists were hard-coded for the first partner.	One profile per partner holds all of it, so onboarding is configuration and a sample run, not a release.
References don’t match the customer’s system.	Reference segments were read by position, and each partner orders them differently.	Map by qualifier into named fields, and keep the full raw set for audit and disputes.
Rejects nobody can explain.	Acknowledgement error codes are logged where no human looks.	Every negative acknowledgement is decoded to plain English — segment, element, expected value — and routed to the partner contact.

The surfaces

What your team sees.

Four surfaces, each answering a row from the table above. They sit beside your TMS rather than replacing it. Sketches with stand-in data, cropped to the part that matters.

Partner profile and sample runSHIPPERSCAC

Delimiterselement * · segment ~ · component >
Their codesaccept A · decline D · status subset X3 AF X6 X1 D1
Sample run12 files · 12 parsed · 2 warnings
WarningReference qualifier SI appears in 4 files and not in their guide — mapped to shipper reference.
WarningOne tender with no equipment segment — defaulted to 53ft dry van and flagged.

cropped

Answers “every new partner takes weeks”. Delimiters, qualifiers and code lists are fields on a profile, so a go-live is a sample run rather than a release.

Tenders — today4 of 38 shown

ORD-88213Kansas City, MO → Chicago, IL · pickup 6 Oct 08:00997 sent 09:14990 accepted 09:15load L-44120
ORD-88213change tender · purpose 04 · delivery moved to 7 Octapplied to L-44120no duplicate created
ORD-88402Columbus, OH → Detroit, MI997 sent 10:02990 declined — no capacity
ORD-88455Joliet, IL → Indianapolis, IN997 sent 11:48990 due in 12 min

cropped

Answers “the same load appears twice” and “the shipper thinks a truck is coming”. One load per shipment id, and the acknowledgement and the acceptance are different chips.

Exception queue3 open · oldest 18 min

Status code not in partner subsetGreat Lakes DC · 18 min agoAT7*OO*NS***20261006*1142*LTLoad L-44120 is unaffected. One click maps the code for every future message.
Cancellation for a shipment we don’t haveMidwest Foods · 41 min agoB2**SHPR**ORD-88999**PP~ B2A*01~Held 48 hours in case the original tender arrives late, then expires with a note to the partner.
No acknowledgement came backNorthstar Carrier · 31 min agoInterchange 000012951 was delivered at 11:02. No 997 inside the agreed 30 minutes, so this opened before anyone called.

cropped

Answers “some status updates never show” and “we sent it, nothing arrived”. Nothing is discarded, and the raw segment travels with the item so it is fixed once, properly.

Partner health — last 7 days3 partners

Midwest Foodsacks in window 100% · negative 0.4 per 100 · status lag p95 6 min
Great Lakes DCacks in window 98% · negative 1.2 per 100 · status lag p95 14 min
Northstar Carrieracks in window 87% · negative 3.1 per 100 · status lag p95 41 minNorthstar’s acknowledgements are slipping and status is arriving 41 minutes late. That is a Tuesday conversation, not a complaint.

cropped

Answers “rejects nobody can explain”. Per-partner numbers, so a degrading connection is visible while it is still cheap to fix.

Data contract

What maps to what.

Inbound: tender to load

B2 → shipment id, payment terms, partner SCAC
B2A → create, change or cancel
L11 → named references, by qualifier
N1 N3 N4 → party, street, city and state, per stop
S5 → stop sequence, and whether it loads or unloads
N7 → equipment type and length
NTE → driver and dock notes, kept verbatim

Outbound: milestone to 214 status

Arrived at pickup → X3
Departed pickup with the shipment → AF
En route to delivery → X6
Arrived at delivery → X1
Unloading complete → D1
Pickup and delivery appointments → AA · AB

Each event carries location, equipment and the references the partner sent, so their system can match it without a telephone call.

Instrumentation

What a pilot reports back.

Numbers the integration produces about itself, from the first day. No baseline, no argument later about whether it worked.

Tender to load

Median and worst-case minutes from interchange received to load visible in the TMS.

Hands off the keyboard

Share of tenders completing with no human touch, and the reasons the rest needed one.

Acknowledgement health

Acks returned inside the agreed window, and negative acks per hundred transactions.

Status lag

Gap between the event time a carrier reports and the moment your customer can see it.

Queue volume

Items landing in the human queue each week, grouped by cause, so the list shrinks on purpose.

Duplicate rate

Loads created more than once per thousand tenders — the number that should stay at zero.

The engagement

One partner, one lane, three weeks.

Fixed scope and a fixed price: $4,500. We take one trading partner and the tender, response and status messages for one lane, stand up the profile, the acknowledgement loop and the exception queue, and hand back the runbook and the numbers above.

What we need from you: the partner's implementation guide, ten sample files, a test mailbox, and one person in operations who answers questions.

Book a 30-minute call with our expert

Delivered

Partner profile: delimiters, envelope ids, qualifier map, code lists
Parser and writer, with idempotent load creation
Acknowledgement loop with reconciliation and alerting
Exception queue with the raw segment attached
Runbook your team onboards the next partner with

FAQ

Freight EDI questions we get actually asked.

What does freight EDI onboarding actually involve?

Reading the trading partner's implementation guide, building a profile from it — delimiters, envelope identifiers, reference qualifiers, status and response code lists — then proving it against their sample files before anything touches production. The work that decides success is the acknowledgement loop and the exception path, not the happy path.

Why do EDI 214 status updates arrive out of order?

Because AT7 timestamps are local time with a time code and no UTC offset, so a stream ordered by arrival time rather than event time drifts across time zones and midnight. Normalise every event to UTC against the stop's own zone, keep the original values, and order by the event time.

What is the difference between a 997 and a 990?

A 997 functional acknowledgement says the file was syntactically readable. A 990 says the load was accepted or declined. Treating the first as the second is one of the most common and most expensive EDI mistakes in brokerage.

Does A always mean accepted in an EDI 990?

Not reliably. The base standard reads A as accepted and D as cancelled, while partner implementation guides differ — some use D for a decline, others E. The accept and decline codes have to come from each partner's guide and be tested against their samples.

Do you replace our TMS or our VAN?

Neither. This sits beside the systems you already run: it reads what arrives in your mailbox, writes clean records into your TMS, and sends the responses and status messages back out through the same connection.

What does an EDI pilot cost and how long does it take?

$4,500 fixed for three weeks, covering one trading partner, one lane and the tender, response and status messages. You get the partner profile, the parser and writer, the acknowledgement loop, the exception queue, the runbook and the measurements.

Let's build it

Book a 30-minute call with our expert

Bring one trading partner and one workflow. You will leave the call knowing whether it is a fit, what a pilot would cover, and what it would cost — $4,500 fixed, three weeks.

Book a discovery call

Reply within 1 business day · India & USA

Payloads and identifiers on this page are illustrative, assembled from published X12 implementation guides. No customer data, configuration or code appears here. Status, acknowledgement and qualifier codes follow carrier implementation guides; each trading partner's own guide governs their connection.

Next sheet: freight invoice and accessorial audit, or the rest of the AI TMS Blueprint.