EDI to API: Mapping the Core Freight Messages (204, 990, 214, 210, 856) to Their API and Webhook Equivalents in 2026

An EDI-to-API mapping is a crosswalk from each X12 freight message to the API call, webhook or event that carries the same business fact, with the differences in acknowledgment, timing and error handling spelled out. The aim is not to retire EDI, since many carriers and retailers still mandate it, but to know what each message means so that one decision layer can consume either rail without changing the business logic. This guide is for integration architects and IT leads at shippers and 3PLs, and it works from published carrier and shipper implementation guides because X12’s own code lists are licensed and not public.

Why EDI-to-API Mapping Matters: The Business Case

Both rails will coexist for years, and the published sources show why the mapping has to be explicit.

• X12 defines the 204 as the message that lets shippers tender a shipment to a full-load motor carrier, and the 990 as the response to that tender, so every tender cycle starts with a pair of messages and a clock.
• CN’s guide says a 990 is generated within a half hour of every 204 received, and Ryder’s guide requires a 997 within one hour and a 990 by the must-respond-by time or the load may be reassigned.
• C.H. Robinson’s dray guide asks for a 214 at least every 4 hours, with status within one hour of the event and In Transit repeated every 4 hours.
• DCSA published Track and Trace 3.0.0 on 30 September 2026, with IoT and reefer events and clearer handling of corrected or withdrawn events, and its 2.2 release added a subscription callback API for shippers and consignees.
• FedEx’s visibility webhook retries failed events 3 times over 15 minutes, then holds missed events in a queue, and says you need to monitor failures on your own side.

We found no independent source for how much freight communication still runs over EDI, so plan for both and measure your own mix.

Also Read: TMS Integration: How Enterprise Logistics Teams Connect, Orchestrate, and Scale

X12 Messages vs API and Webhook Equivalents: Key Differences

The table maps the business fact in each message to a generic API pattern. API names are patterns and not any vendor’s endpoints, and the EDI details come from the partner guides cited in the steps below.

X12 set	Business fact	Key EDI elements in published guides	API or event equivalent	What changes
204 Motor Carrier Load Tender	A shipper offers a load to a carrier	B2 (SCAC, shipment ID in B204, payment method), B2A (purpose: original, cancel, update or replace), S5 stops, N1 parties, L11 references, G62 must-respond-by	Create tender: shipment ID, stops, equipment, references, response deadline	The deadline becomes a field and a timer, and updates are explicit versions of one tender
990 Response to a Load Tender	The carrier accepts, declines or changes the offer	B1 (SCAC, shipment ID matching B204, B104 action code), N9 PRO number when accepted, K1 free-text reason	Tender response: status, reason code, PRO number, equipment	Decline reasons become enumerated values and not free text
214 Transportation Carrier Shipment Status	A shipment event happened	B10 (PRO, shipment ID, SCAC), AT7 (status, reason, appointment, date, time), MS1 location, L11 references	Status webhook: event type, reason, appointment, timestamp, location	Events arrive when they happen, not in half-hourly batches
210 Motor Carrier Freight Details and Invoice	Charges for a shipment	Charge detail segments tied back to the shipment reference	Invoice object with line charges and shipment reference	Charge lines can be validated against the tender at ingest
856 Ship Notice/Manifest	What is in the shipment	Shipment, order, packaging, carrier and item hierarchy	Ship notice object with items, packages and carrier	Nested structures map to arrays, and ASN timing becomes an event
997 and 999	The message arrived and parsed	997 reports syntax only, 999 adds relational analysis	HTTP 2xx, plus retry and idempotency rules	Receipt is no longer a separate message, and delivery semantics replace it
315 Status Details (Ocean)	An ocean or container event	Status or event details for shipments and containers	DCSA Track and Trace events and subscription callbacks	Standard event vocabulary and callbacks replace batch files

How to Map an EDI Message to an API in Seven Steps

The steps move from meaning to mechanics, and each has a trap from the published guides.

1. Start from the business fact, not the segment

Write one sentence for each message: a tender, a response, a status, a charge, a ship notice. Map the fact first and the segments second, so the API design does not inherit EDI’s batching.

2. Pin the partner guide and its version

Every guide we read was X12 004010, and the code lists behind elements such as AT701 and B104 sit in X12’s licensed directory, so the real codes live in each partner’s guide. Keep one mapping table per trading partner.

3. Carry one identifier through the cycle

Ryder’s guide says the 204’s B204 shipment ID must be mapped to the 990’s B102 and the 214’s B1002. Use one tender or shipment ID across tender, response and status so events always join back.

4. Map the response semantics

The 990’s B104 code is where guides disagree: XGS prints “A” for accepted and shows a decline with “D” and a free-text reason, XPO’s generic layout lists “D” as reservation cancelled, and Aljex treats A, D and U as accept, decline and update. State that “D” means declined by partner convention, and map decline reasons such as capacity constraints, insufficient lead time or rate not competitive to an enumeration.

5. Map status codes with their context

The 214’s AT7 segment carries a status code, a reason, an appointment code, a date and a time. In truckload guides from ArcBest, C.H. Robinson and Aljex, X3 is arrived at pick-up, AF is departed pick-up, X6 is en route or in transit, X1 is arrived at delivery and D1 is completed unloading, while a CN rail guide uses X1 for placed for unloading and X3 for placed for loading. The codes AF and D1 also appear in reason elements with different meanings, so map by element and not by code alone.

6. Replace acknowledgments with delivery semantics

A 997 says a file parsed, and a 2xx response says a request arrived. Stripe documents that endpoints may receive the same event more than once and that order is not guaranteed, and Shopify documents duplicates, 8 retries over 4 hours and reconciliation jobs. DHL’s push API requires a 200 within 5 seconds, retries after 1 hour and again 6 hours later, and deactivates a subscription after 10,000 consecutive failures. Deduplicate by event ID and reconcile.

7. Run both rails in parallel and reconcile

Send and receive the same cycle over EDI and API until the results match, then retire the EDI path partner by partner. Mirror reads and hold writes on the shadow path, so a tender is never issued twice.

Also Read: How to Test a Logistics Integration Before Go-Live: Sandbox, Replay, Reconciliation and Parallel Run

What to Look for in EDI and API Connectivity

Stated message coverage

The vendor should list which X12 sets it sends and receives and which API objects correspond, not just say it supports EDI.

Explicit code mapping per partner

Look for configurable mapping tables for 990 action codes, 214 status and reason codes and decline reasons, since every partner guide differs.

Acknowledgment and retry semantics

Ask how 997 and 999 are handled, how long a response can take, how duplicates are detected and what retry and dead-letter behavior exists on webhooks.

Transport options

Ask which transports are supported, such as AS2, SFTP, VAN and REST, since carriers publish different preferences and some offer both EDI and API.

Message-level audit

Every tender, response and status should be logged with its source, version and outcome, so a dispute can be reconstructed.

Also Read: What “API-First” Actually Means for Modern Logistics Platforms

EDI to API Mapping in Action: A Worked Tender Cycle

A tender cycle on a partner guide’s codes. The example uses codes and timing from the published guides cited above and a generic event vocabulary, and the identifiers are invented.

Step	EDI message and elements	API or webhook event
Tender	204 with B204 shipment ID L-48213, B2A purpose original, S5 stops with reasons CL and CU, G62 must-respond-by	tender.created with shipmentId L-48213 and respondBy time
Response	990 with B102 L-48213, B104 A, N9 carrier PRO	tender.accepted with PRO number, or tender.declined with reason capacity_constraint
Pick-up	214 with AT7 X3, then AF	shipment.arrived_pickup, then shipment.departed_pickup
In transit	214 with AT7 X6	shipment.in_transit
Delivery	214 with AT7 X1, then D1	shipment.arrived_delivery, then shipment.unloaded
Invoice	210 referencing L-48213	invoice.created with line charges

What the clocks do to freshness, on illustrative arithmetic. CN’s rail guide has it send 214 status in batches up to 46 times a day at half-hour intervals, so an event can wait up to 30 minutes and about 15 minutes on average if events are spread evenly. A partner that only meets a minimum of one 214 every 4 hours leaves status up to 4 hours stale, about 2 hours on average. A webhook that fires on the event and retries on failure shifts the delay from the schedule to the retry policy.

An ASEAN apparel retailer. Each carrier reported its own status codes, and each new carrier had been a full engineering project. Locus harmonized carrier statuses into one standard set, synced to the OMS and WMS, and the retailer reported more than 40% fewer WISMO and returns queries and carrier onboarding down from three months to three days. The case shows the value of one standard status vocabulary above many partner-specific codes. Read the apparel case study.

A Canadian grocery brand. The brand’s Locus agents are integrated by API with every contracted 3PL, create the order and label the moment a shipment is ready, and track each shipment to proof of delivery. It reported 25% less time on manual shipping tasks and 15% lower fulfillment costs. The case shows API-first connectivity replacing carrier portals. Read the Canadian grocery case study.

Common EDI to API Mapping Mistakes to Avoid

Treating a 997 as business confirmation. A 997 says the file parsed, and it says nothing about whether the carrier accepted the load.

Reusing status codes across modes. X1 and X3 mean different things in rail and truckload guides, so key mappings by partner and mode.

Assuming “D” always means declined. It is a partner convention, and one published layout lists D as reservation cancelled.

Retiring EDI before the partner is ready. Run both rails in parallel and reconcile before switching any trading partner.

Also Read: The 3PL Integration Stack: How to Connect TMS, WMS, ERP, and Carrier APIs in 2026

How Locus Handles EDI and API Connectivity, and What to Confirm

Locus, the world’s first Decision-Intelligent, Agentic TMS, says it operates as the system of execution, connecting through documented REST APIs and webhooks and consuming partner-mandated EDI where trading relationships require it. Its published OpenAPI specifications cover order management, entity management and platform entities, and its order callbacks are configured per event type, with order statuses such as open, planned, assigned, executing, completed and cancelled and sub-statuses such as pickup en route, drop done and attempt failed, plus tour callbacks for dispatched, started and completed. ShipFlex harmonizes carrier statuses into one standard set. Locus has optimized 1.5B+ deliveries for 360+ enterprise customers across 30+ countries.

Recognized by analysts and selected after evaluation. Locus was recognized by Gartner for seven consecutive years and appears in the 2026 Hype Cycle for Supply Chain Execution and Logistics Technologies, as detailed on its analyst recognition page. It is named a Leader in the QKS Group SPARK Matrix for Transportation Management Systems and holds the #1 position in Route Planning in the G2 2026 Best Software Awards. In October 2025, Ingka Investments, the investment arm of Ingka Group, the world’s largest IKEA retailer, acquired Locus. Ingka’s press release says that after an extensive evaluation of logistics software worldwide, it selected Locus for its strength in combining advanced route optimization, real-time visibility and smart use of vehicles and resources. Locus continues to operate independently.

What this means for the mapping. Locus’s callback vocabulary gives the API side for the 214 status steps in the worked cycle, and its standard carrier status set reduces the partner-specific code tables you maintain. Its API reference page states that API integrations are available to Locus clients, with authentication details shared after a request, and the published specifications define basic and API-key authentication.

What to confirm. Locus’s public pages do not state which X12 transaction sets it supports, how 997 and 999 acknowledgments are handled, whether AS2, SFTP or VAN transports are offered, whether it provides a mapping or translation service, or its webhook retry and signature behavior. Its blogs list OAuth 2.0 as an evaluation criterion, but the published specifications show basic and API-key authentication, so ask which applies to your integration.

To walk through your trading partners and message mix, schedule a demo.

For architects asking how to run EDI and API side by side, Locus offers documented callbacks, standardized carrier statuses and consumption of partner EDI in one execution layer, so each message maps to one decision.

Frequently Asked Questions

What is the difference between EDI and an API in freight? EDI exchanges standardized batch messages such as the X12 204, 990 and 214 over transports like AS2, SFTP or a VAN, while an API exchanges requests and events over HTTP, often with webhooks. Many carriers support both, and the business meaning of each message is what you map.

What does an EDI 214 map to in an API? A 214 is a carrier shipment status message, so it maps to a status event with an event type, a reason, an appointment, a timestamp and a location. Map by the AT7 status, reason and appointment elements and by mode, because the same code can mean different things in rail and truckload guides.

Is a 997 the same as an HTTP 200? No. A 997 reports that a file passed syntax checks, and a 999 adds relational checks, while an HTTP 2xx says a request arrived. Webhooks add their own rules for retries, duplicates and ordering, so you still need deduplication and reconciliation.

What does the EDI 990 code D mean? In several partner guides D marks a declined tender, but the published code list in at least one generic layout lists D as reservation cancelled, so treat it as a partner convention. Map decline reasons to an enumeration.

Is EDI going away in freight? We found no independent data on the EDI versus API share. NMFTA’s Digital LTL Council has published API standards for electronic bills of lading, pickup, visibility and preliminary freight charges, and carriers such as ODFL list both EDI sets and API options, so expect both for years.

Does Locus support EDI? Locus states it consumes partner-mandated EDI where trading relationships require it, and publishes REST specifications and callbacks. It does not publish which X12 sets, transports or mapping services it supports, so ask in evaluation.