A large retailer, a freight broker or a health plan has told your team to "connect by EDI." They don't want a portal upload or a PDF in an email. They want your orders, load updates or claims to arrive as standard documents their systems can read without anyone retyping them, and they want their own documents to land in your systems the same way. EDI integration is the software in between: it turns records in your TMS, WMS, ERP or billing system into those documents, sends them to each partner, and turns what comes back into records again.
None of this is new technology, and that's partly why it gets underestimated. Every partner uses the standard a little differently, and a document that fails quietly can hold up a load or a payment until someone notices. This guide covers the X12 documents you're likely to meet in logistics and healthcare, how they travel, what a project involves, and where an API is the better fit.
What is EDI integration?
EDI integration connects your own systems, such as a TMS, WMS, ERP or practice management system, to your trading partners so that business documents move as standard electronic messages. In the US those messages are usually X12. Your data is mapped into each partner's format, sent over an agreed channel such as AS2, and acknowledged by the receiver.
What is X12, and what is a transaction set?
X12 is the standards body whose specifications define the documents most US companies exchange by EDI, and each document type in its catalog is a numbered transaction set: 204 for a load tender, 837 for a health care claim, and so on. X12 calls itself "an ANSI-accredited, consensus-based, non-profit organization" and says its standards cover ordering, shipping, invoicing and payment, with "more than 320 transaction standards available for use." No single company uses more than a fraction of them. When people say "X12 EDI," they mean this family of documents in the format X12 defines.
Transaction sets rarely travel one at a time. X12's description of its 997 acknowledgement notes that transaction sets "are grouped in functional groups," which is why EDI traffic often arrives in batches and why one acknowledgement can report on several documents at once.
The standard is broad on purpose. Each partner picks the version it supports, uses a subset of the segments and codes, and writes its own rules down in an implementation guide. That guide is what your developers will work from day to day. X12 is the American standard; partners abroad often use UN/EDIFACT instead (the FAQ covers the difference).
Which X12 documents will you see?
That depends on your industry, and in practice a team works with the few transaction sets its partners actually send and expect. The table covers the ones you're likely to meet in transport, warehousing, retail supply chains and US healthcare, plus the two acknowledgements that apply to all of them. The descriptions are shortened from X12's own transaction set summaries.
| Code | X12 name | Industry | What it carries (per X12, shortened) |
|---|---|---|---|
| 204 | Motor Carrier Load Tender | Transport | A shipper offers a full truckload to a carrier, with schedule, equipment and shipping instructions |
| 990 | Response to a Load Tender | Transport | The carrier's response to a 204 |
| 214 | Transportation Carrier Shipment Status Message | Transport | Shipment status: dates, times, locations, route and identifying numbers |
| 210 | Motor Carrier Freight Details and Invoice | Transport | Charges for the carrier's services; used as the freight invoice |
| 940 | Warehouse Shipping Order | Warehousing | The depositor tells the warehouse to ship, confirm, change or cancel an order |
| 945 | Warehouse Shipping Advice | Warehousing | The warehouse confirms the shipment was made; ordered and shipped quantities are reconciled |
| 850 | Purchase Order | Retail, distribution | Placing a purchase order (not changes or acknowledgements) |
| 856 | Ship Notice/Manifest | Retail, distribution | Contents and configuration of a shipment |
| 837 | Health Care Claim | Healthcare | Claim billing and encounter information from providers to payers, directly or via clearinghouses |
| 835 | Health Care Claim Payment/Advice | Healthcare | Payment and/or remittance advice (EOB) from insurer to provider |
| 270/271 | Eligibility, Coverage or Benefit Inquiry / Information | Healthcare | An eligibility, coverage or benefit question and its answer |
| 276/277 | Health Care Claim Status Request / Information Status Notification | Healthcare | A claim status question and its answer |
| 997 | Functional Acknowledgment | All | The result of the syntax check on received documents |
| 999 | Implementation Acknowledgment | All | A syntax and relational check against the implemented subset |
Two limits in X12's wording matter before you scope anything. The 204 is for full truckload: X12 says it isn't meant for a less-than-truckload bill of lading, pickup notification or manifest, so an LTL partner may expect other documents. And the 850 only places an order. X12 says it "should not be used to convey purchase order changes or purchase order acknowledgment information," so a retail partner that changes or confirms orders will need more than one transaction set from you.
How does a load move by EDI?
A truckload moves through four business documents, from the tender to the invoice, and an acknowledgement should come back for each one.
- The shipper sends an EDI 204 load tender with the schedule, equipment and shipping instructions for the load.
- The carrier's system returns a 997. That means the 204 arrived and passed the syntax check, and nothing more: the carrier hasn't said yet whether it wants the load.
- The carrier accepts or declines with a 990, the response to the load tender.
- While the truck is on the road, the carrier sends EDI 214 status messages with dates, times and locations, and the shipper's system matches each one to the load by its reference numbers.
- After delivery the carrier bills for the move with a 210 freight invoice.
Most trouble in this flow is quiet. A 997 that never comes back usually means the partner didn't receive the document or couldn't parse it, and unless your system expects that acknowledgement and raises an alert when it's overdue, the first sign may be a load nobody covered. A 214 can also arrive for a shipment your system doesn't recognize, often because the reference the carrier sent back doesn't match the one you sent out. It should wait in a queue where someone can match it by hand. And a partner may send the same 204 or 214 twice after a timeout, so the integration has to recognize a document it has already processed and skip it.
In the logistics software with EDI built in that we build, we monitor each partner connection and track the 997 or 999 that should come back for every document. A document that bounces or comes in garbled waits in a queue where your team can fix it and send it again.
What about healthcare: 837, 835 and HIPAA?
For the transactions HIPAA covers, X12 isn't optional. HIPAA required HHS to set national standards for electronic transactions, and CMS states that "ASC X12 Version 5010 is the adopted standard format for transactions, except those with retail pharmacies," which use NCPDP standards instead. CMS is also clear about who this reaches: "Any provider who accepts payment from any health plan or other insurance company must comply with HIPAA if they conduct the adopted transactions electronically."
The claim itself is the EDI 837. X12 describes it as carrying claim billing and encounter information "from providers of health care services to payers, either directly or via intermediary billers and claims clearinghouses," and the CMS table lists it for institutional, professional and dental claims. Payment comes back as an 835, which carries the payment, the Explanation of Benefits remittance advice, or both, from the insurer to the provider. Around those two sit the 270/271 pair for eligibility and benefit questions and the 276/277 pair for claim status.
Most of the engineering sits between those documents. A billing or practice management system has to keep the identifiers it sent in each 837, because that's how each 835 gets matched to the claims it pays, and a denied or partly paid line needs to reach a person instead of being posted without anyone looking at it. We build revenue cycle apps and integrations for healthcare, and much of that work is X12 traffic with clearinghouses and payers.
Clinical data is a separate track. HL7 International is the standards body behind HL7 v2, FHIR and CDA, so a health platform often runs HL7 or FHIR for patient records and X12 for billing. Our guide to how HL7 and X12 divide the work covers that comparison.
How do EDI files travel? AS2, SFTP and VANs
The X12 document is the content, and how it travels is agreed separately with each partner. You'll usually settle on one of three channels.
AS2 sends EDI over HTTP. RFC 4130, the IETF specification, covers exchanging structured business data securely over HTTP, names both ANSI X12 and UN/EDIFACT as the formats it carries, and lists "data confidentiality, data integrity/authenticity, non-repudiation of origin, and non-repudiation of receipt over HTTP" as its security services. The sender can ask the receiver to return a Message Disposition Notification, or MDN, and to sign it, which is how AS2 gives you an authenticated receipt. The RFC is plain about what an MDN is: "A MDN is a receipt."
SFTP is simpler. Each side drops files into an agreed folder on a server and collects the files waiting for it. The transfer has no receipt of its own, so the 997 is the first confirmation you'll get.
A VAN (value-added network) is a third party that routes EDI documents between partners' electronic mailboxes.
Whichever channel you use, keep three kinds of confirmation apart, because a connection can pass one and fail the next. An AS2 MDN tells you the message was received. A 997 tells you the transaction sets passed X12's syntax check, and X12 says outright that the standard "does not cover the semantic meaning of the information encoded in the transaction sets." Business acceptance comes later and in business terms: a 990 that accepts the load, or a 277 that reports where a claim stands. A dashboard that only watches the first two can look healthy while a partner is turning documents down.
What does an EDI integration project involve?
Mostly mapping and testing, one partner at a time. Setting up the connection is the smaller job. Most of the hours go into making each partner's version of a document line up with your data model, then proving it does before real traffic starts.
- List each partner, the transaction sets you'll exchange with them in each direction, and the implementation guide for each.
- Map each partner's segments to your data model. Keep one map per partner, versioned and covered by tests, because partners revise their guides and a change for one partner shouldn't break the others.
- Agree on the transport with each partner (AS2, SFTP or a VAN) and set up the certificates or credentials it needs.
- Exchange test documents with the partner and get their sign-off before production traffic starts.
- Track the acknowledgement for every document you send, and alert when one is late or reports an error.
- Give operations staff a queue where failed or unmatched documents wait with the reason attached, so they can fix the data and resend without calling a developer.
- Add the next partner. The transport setup and the queue carry over, but the map usually doesn't, so treat each new partner as a small project of its own.
Our EDI and API integration work covers the SOAP, EDI and file-based links that older systems still depend on, and we treat them as first-class integration work because they still carry a lot of critical business workflows.
EDI vs API: which should you use?
Usually both. Your partners decide where EDI is required, and for HIPAA-covered healthcare transactions the rules decide it for them. Between your own systems, or with a partner that offers an API and doesn't ask for EDI, the choice is yours, and an API is usually easier to build and to change.
The rows below are our own analysis, built on the standards cited earlier.
| EDI (X12) | API | |
|---|---|---|
| Format | Standard documents defined by X12, narrowed by each partner's implementation guide | A schema set by whoever owns the API |
| Who sets it | The standards body, then the partner | The API provider |
| Timing | Documents sent one at a time or in batches; replies come back as separate documents | Request and response, often in real time |
| Confirmation | With AS2, an MDN receipt; then a 997 or 999 | An HTTP status code in the response |
| Adding a partner | A new map and a test cycle for each partner | One integration per API, which every caller shares |
| Typical use | Load tenders, purchase orders, ship notices, HIPAA claims | App-to-app data, carrier rates and labels, live lookups |
The pattern we'd recommend in most cases is EDI at the edge and APIs inside. The EDI layer translates partner documents into internal API calls or events, so the rest of your systems never parse X12, and if a partner later moves to an API, only the edge changes.
An API wins outright when you need an answer inside the same request. A rate quote or a shipping label can't wait for a separate reply document, which is why carriers that take EDI tenders often offer carrier APIs for rates and labels as well. If you want the API side explained from the ground up, start with our guide to what API integration means.
FAQ
What is the difference between a 997 and a 999?
In X12's words, the 997 reports "the results of the syntactical analysis" of the documents received, while the 999 reports "syntactical and relational analysis" based on "a full or implemented subset" of the transaction sets. So a 999 can also reject a well-formed document that breaks the subset's rules. Your partner's guide names the one they send.
Is EDI being replaced by APIs?
Not in a way you can plan around. X12 also publishes XML schemas, so the standard isn't tied to one file format, but that doesn't change what your partners send. As long as a payer or a large retailer sends X12, you'll need to receive it and reply in X12, whatever your own systems use internally.
What is an EDI implementation guide?
It's a partner's rulebook on top of the X12 standard: which version they use, which transaction sets and segments they send, which fields they require, which code values they accept and how testing works. Ask for every guide before you scope the work, because the guides, more than the transaction set names, decide how much mapping there will be.
Do we need a VAN?
Only if a partner requires one, or if the number of connections makes it worth paying for. AS2 and SFTP connect you to a partner directly. A VAN puts a third party in the middle, so you keep one connection instead of one per partner, in exchange for its fees and one more place where a document can stall.
Is X12 the same as EDIFACT?
No. They cover many of the same business documents, but UN/EDIFACT is the United Nations standard, with its own message names, structure and code lists, so an X12 map can't read an EDIFACT file. If some of your partners are overseas, plan for both. We can also work in EDIFACT for partners overseas who use it.
Planning an EDI connection
If a partner has asked you to connect by EDI, or an existing connection keeps failing without anyone noticing, a discovery call is a sensible first step. We'll go through your partners, the documents and guides involved, and how your systems should send, receive and track them.
Buttons: "Book a Technical Discovery Call" → /contact · "Get a Project Estimate" → /project-estimate