Verdict first: API and EDI integration troubleshooting after go-live is not about fixing the broken link as fast as possible. It is about not making it worse. The most expensive mistakes I have seen were not caused by the original failure. They were caused by someone panicking, resending everything, hand-editing inventory, and restarting the interface, turning a traceable fault into a mess nobody could reconcile. So before you touch anything, classify the failure. Did the message never arrive? Did it arrive but never get processed? Was it processed but never acknowledged? Or do three systems each insist their own numbers are right? Get the classification wrong and every step after it is wrong too. I have seen this pitfall three times, in three different warehouses, with the same script.
The first story comes from last fall, at a home-goods third-party warehouse outside Ontario, California. In the third week after go-live, on a Tuesday morning, the retailer reported that more than four hundred orders had never reached the warehouse. The person on duty assumed the interface was down and restarted it twice. Nothing changed. The check showed the retailer had sent the orders and our gateway had received them, but they were stuck at order validation because the retailer had changed a suffix on a product code without telling us. Nothing was broken. Both sides had simply assumed the other side had not changed anything. We got shipments moving by mapping the old codes temporarily, then pushed the code change through a formal notification process. Since then, I check the change log before the system log.
The second story is more painful. A small-appliance warehouse near Chicago spent its first month after go-live with inventory off by more than a hundred units a day, sometimes high, sometimes low, and nobody could find the pattern for a week. It turned out to be two problems stacked on top of each other. Return receipts were being sent twice by the retailer's system, and our side had no idempotency check, so the same returns were booked twice. On top of that, cycle-count adjustments were keyed directly into the WMS and never sent back to the retailer. Each side kept editing its own numbers, and the gap kept growing. The fix was not clever: deduplicate every resent message on the business document number, and route every inventory adjustment through the interface instead of letting anyone change a quantity and walk away. Those two lines have been on my go-live night checklist ever since.
API/EDI Breaks: Classify First, Then Act
Classification takes four sentences, and you should match your failure to one of them before opening a log file. One, the message never arrived: not sent, sent to the wrong endpoint, an expired certificate, a network break. Two, it arrived but was never processed: stuck on validation, mapping, or a missing field. Three, it was processed but never acknowledged: the business document was created, but the confirmation never went back, so the sender assumed you never got it and sent it again. Four, everyone disagrees: order, shipment, and inventory systems use different definitions, so each side looks right on its own.
Ten minutes of classification can save four hours of searching through thousands of log lines without knowing what kind of problem you are looking for. And one rule: do not restart a production interface without evidence. A restart wipes the state of messages in flight, and a trail you could have followed becomes a trail you can no longer follow.
Many post-live problems were planted during selection, when nobody nailed down who owns the master data or who detects an exception first. If you are revisiting those decisions, the API versus EDI selection comparison is a useful reference for writing the responsibilities you skipped into your operating agreement.
API/EDI Message Tracing: Find the Message Before You Argue About It
My message-tracing routine has five steps, and they work in this order. Step one, take the business document number to the sender's system and confirm the send record: was it sent, to which endpoint, and what response code came back? Step two, check your own gateway's receive record and confirm the original message was stored. Step three, validate the original message: is this a format problem, an encoding problem, or a business rule blocking it? Step four, read the business processing log to see exactly where it stopped, and whether it stopped on a system error or a manual hold. Step five, check the acknowledgment record: was a confirmation sent, and did the other side accept it?
Here is the counterintuitive part: a success response does not mean business success. Many interfaces return a 200 just to say "received," not to say the order was created or the inventory was deducted correctly. I once watched two teams wave 200 logs at each other for two days while the orders sat in a middleware queue. Judge by the business document status, never by the response code alone. The response code only proves the transmission did not break. It does not prove the business got done right.
Another classic failure: the team tested only the happy path in the test environment and never tested a resend, an out-of-order message, or an empty field. Those three belong on the go-live night checklist as separate tests. A resend tests idempotency, an out-of-order message tests the document state machine, and an empty field tests whether the system errors loudly or silently drops the document. Silent drops are the worst of the three, because an error at least tells someone, while a silent drop is only discovered when a customer complains.
Stuck Orders: Work This Checklist, Box by Box
When orders get stuck, API and EDI integration troubleshooting starts with one rule: do not hand-create them to save the day. A hand-created order solves today's shipment and guarantees a reconciliation problem tomorrow, either a duplicate or a missing order. Work this checklist instead, and demand evidence for every box, a log entry or a document status, not "I think it was sent." Does the document number exist in the sender's system? Did the message reach the gateway? Did it pass validation? Did the product and location codes map? Is there enough inventory? Is the document sitting on a manual hold?
Once you find the root cause, the order of repair matters. Protect shipments first, fix the data second, and argue about blame last. If it is a mapping problem, put a temporary mapping in place to protect today's shipments while the formal change goes through. If it is a stock shortage, confirm whether the shortage is real or just stale inventory data before releasing the order; a data lag calls for reconciliation, a real shortage calls for the shortage process, and forcing the order through helps nobody. After fixing one order, check whether the rest of the batch shares the same cause.
Do the math on why manual workarounds do not scale. Suppose four hundred orders get stuck in a day, and each one takes eight minutes of manual checking and handling. That is 3,200 minutes, more than fifty hours, and two people working overtime will still not finish. Once stuck orders pass a certain volume, the right response is to fix the link and process in bulk, not to add people. Adding people turns a system problem into a labor problem, and it only gets more expensive.
Inventory Mismatches: The Three-Step Reconciliation
For inventory mismatches, API and EDI integration troubleshooting comes down to three steps. Step one, reconcile the totals: the WMS on-hand quantity, the other system's on-hand quantity, and the last quantity both sides agreed on, then state the size of the gap and the date it first appeared. Step two, reconcile the flows: from the baseline date to today, compare receipts, shipments, returns, and adjustments as four separate categories, and find which category's cumulative gap equals the total gap. Step three, reconcile the documents: take the category with the largest gap, sample a few transactions, and check them one by one for duplicates, omissions, or definition differences.
Definition differences are the most overlooked cause: one side may count in-transit stock as on-hand while the other does not. The numbers can disagree without anyone being wrong, because the two sides are not counting the same thing. Before reconciling, write down what on-hand, available, and in-transit mean, and get both sides to agree. Without agreed definitions, reconciliation ends with each side insisting it is right.
One last operating rule. An interface is not finished on go-live day. The first thirty days are the highest-risk period, when the other side may change a code, rotate a certificate, or change a send frequency without telling you. My practice now is weekly reconciliation for the first month, plus certificate rotation two weeks before expiry. Interface operations are won by sticking to these unglamorous routines.
By Lin Xiao, WMS Implementation Consultant
