The new retail contract starts earning in week ten

A carrier API sold as real-time can still hide an SFTP drop, a scheduled job, and an unowned legacy script. The label does not tell you the latency or the failure path.

It is the same story one layer over, in retail EDI, where the brochure says “standards-based” and the reality is that your trading partner’s implementation guide is a sixty-page PDF describing all the ways they differ from the standard.

This piece makes a specific claim. When a new retail account takes eight to ten weeks to start producing revenue (C05), nobody in the building believes that is an engineering problem. It gets logged as onboarding, or contracting, or “the EDI thing.” It is an engineering problem, it is measurable, and the fix bends the curve so the eleventh partner does not cost what the first one did.

Very little of it is writing code, which is why it does not look like engineering.

The routing guide arrives, usually as a PDF, and it is a compliance contract disguised as a document: label placement, carton marking, appointment windows, the ASN timing rule, the deduction schedule for each violation. Then the trading partner’s implementation guide arrives and someone maps it — the 850 inbound, the 856 outbound, the 810, the 940 and 945 pair into the warehouse. Then connectivity: a VAN mailbox, or AS2 with certificate exchange and MDN receipts, or SFTP with PGP keys, each with its own approval queue on the partner’s side. Then a test cycle where you exchange transactions against their test environment and wait for a human to review the results. Then a parallel run.

Every one of those steps is a queue with someone else’s calendar in it. The engineering content is maybe a fifth of the elapsed time. But the engineering decisions you made three years ago determine how many of those steps you have to run at all, and that is the part you control.

It tells you the shape of the document. It does not tell you what any given country will do with it.

The envelope is genuinely universal — ISA, GS, ST, with control numbers at each level and an acknowledgment keyed to them. Below that, variation is the norm. Two retailers on the same 004010 version of the 856 will disagree about which qualifiers are acceptable, which segments are mandatory beyond the base spec, how the HL hierarchy nests, and what belongs in a reference segment. One wants shipment-order-tare-pack-item. One collapses tare and pack. One will reject the transaction if a field they consider optional is absent.

So the mapping work is real, and it recurs — versions move, partners publish revisions, a retailer changes its label spec ahead of peak. The failure is not that mapping exists. The failure is treating each map as bespoke code rather than as a partner profile over a shared engine.

The position: if connecting a trading partner requires a deployment, you do not have an EDI capability, you have a backlog. In C05 we built the maps for 850, 856, 810, 940 and 945 as prebuilt profiles for large US retail-chain formats, configured per partner without code changes. Onboarding went 8–10 weeks → 12 days, and the first new retail contract of that period was connected through the accelerator during the project itself (C05).

The functional acknowledgment is the cheapest reliability control in this entire stack and it is almost always unowned.

You send an 856. The partner’s system returns a 997 saying the functional group was accepted, accepted with errors, or rejected. If it is rejected, your shipment has no valid ASN. The truck is still going. The pallets are still arriving. The compliance failure is already committed, and you will find out about it on a deduction statement, when the batch is gone and so is your evidence.

In C05, nobody tracked 997s. Rejections accumulated silently until a client called or a penalty letter arrived — which is the slowest possible detector and the most expensive one, because it costs the relationship as well as the money. We put a response timeout on every outbound transaction, so a 997 that does not arrive is itself an event, and surfaced rejections on the operations dashboard within 15 minutes with a notification to the account coordinator (C05).

The position: a 997 without a deadline is not an acknowledgment. Silence has to be a monitored state, not a default. Same for the 824 application advice, which is where a partner tells you the document parsed fine and the content was wrong — a distinction most systems throw away.

The most expensive gap in retail 3PL is not between two systems. It is between a system and a physical object.

At the 3PL in C05, the SSCC-18 label generator was a disconnected desktop tool and carton-to-pallet structure was typed into the EDI by hand. The gap between what was on the pallet and what the 856 said was on the pallet ran about 4% (C05). At that level it is not an error rate. It is a deduction schedule, and the retailer’s receiving scan is what enforces it.

The fix is not more diligence. We wired label generation into warehouse pick confirmation, so confirming a carton is the transaction that both prints the GS1-128 with its SSCC-18 and writes the carton record in the 856 hierarchy. One write, two outputs, no reconciliation step, no second person who thinks the first person was authoritative. Discrepancy went 4% → 0.3%, and chargebacks from EDI errors were eliminated within 60 days (C05).

Physical and transmitted data now match by construction rather than by diligence. That sentence is the whole design principle, and it generalizes: anywhere a human retypes something that a machine already knows, you have installed a defect rate and agreed to pay for it monthly.

The REST endpoint is a presentation layer over the same operational reality: at-least-once delivery, out-of-order arrival, duplicated events, a partner-side schema change announced in a quarterly PDF. The 214 says AF when the carrier departed the pickup and X1 when it arrived at delivery; the tracking API says something similar with different field names and a different clock. Both are true. Neither is authoritative.

Three engineering positions follow, and we hold all three:

Normalize at the edge, never in the domain. A carrier adapter converts that carrier’s shape into your canonical event model and nothing downstream ever learns the carrier’s vocabulary. In C01 we put every carrier behind one internal API with a circuit breaker per carrier, so a single carrier failing stops cascading. Before that, one carrier changed its API and the rating flow was down for three weeks. After: zero cascading outages in the six months following launch, and adding a carrier became configuration rather than code — 3 weeks → 4 days (C01).

Assume duplicates and design them out. Every inbound event carries an idempotency key and is filtered at entry. At the omnichannel retailer in C03, duplicate webhooks were causing the same order to be processed twice; with keyed ingestion, double processing was eliminated architecturally rather than patched, and middleware failures went from 2–3 per week to zero in the first month (C03).

Treat the status feed as telemetry, not as truth. Position pings backfill after dead zones, arrive out of order, and disagree with the carrier’s own milestones. Order by event time, not arrival time; keep both; make late-arriving data a supported case rather than an incident.

Two months of revenue per new account, on a contract you have already won and already staffed. Then deductions arriving after each silent failure — when the evidence is gone — priced against cost of goods on a schedule the retailer published and you agreed to. Then the OTIF scorecard, which is not a cost line at all — it is the number that decides whether the account renews.

Multiply the first item by the number of retail accounts you intend to sign next year. That figure is your actual EDI budget, and it is currently being spent whether you approve it or not.

How many trading-partner maps do you have, and how many of them are one-off code rather than a profile? Do you alert when a 997 fails to arrive inside a defined window, or only when a rejection comes back? Is your SSCC-18 generated by the same transaction that confirms the pick, or by a different tool? And when a carrier deprecated an endpoint last year, how many other integrations went down with it?

If the answers are “profiles,” “yes,” “same transaction,” and “none” — you are in good shape and this article is not about you. If you had to ask someone for three of the four, the eight-to-ten-week number is not going to move on its own.