The label printed. The parcel never shipped. Nine times out of ten, the order died somewhere in the API chain.
During the 2023 peak season, a 3PL warehouse in Los Angeles called me in. They were pushing 12,000 orders a day, label printers running nonstop — but every evening, the carrier's actual pickup count came up 300-plus parcels short of the system's shipped count. Complaints, refunds, reships: several thousand dollars burned every single day. Picking was fine. Printing was fine. Every lost order had died in the chain between the WMS and the carrier's label API.
Here's my verdict up front: lost labels almost never die at the printer. The real killers are three: the request never left your building, a timeout retry created duplicate labels, or nobody was reconciling. This troubleshooting chain comes from years of integrating carrier label APIs. Walk it in order and you'll find the break.
Step one: did the request ever leave your building?
The dumbest way to lose an order is for your WMS to never send the request — or to send it, get nothing back, and assume it went through.
My first move is always the local request log. Not the order status in the WMS — the outbound gateway's call records. For this order, is there a record of a "request label from carrier" call? If there isn't, stop reading API docs and tuning timeouts. The problem is on your side. The usual suspects: a dead message-queue consumer with the queue quietly piling up, a scheduled job that never started, or an order stuck in a status transition — the OMS pushed the order over, but the WMS was still waiting on wave release, so the label request never fired. I've seen this more than once: peak season chaos, a misconfigured wave policy, and a few hundred orders sitting silently in "pending release" while the label request was never even sent.
There's a sneakier variant: the request went out, but the log didn't capture it. Some systems only log successes. Some rotate logs so aggressively that the minutes that matter are already gone. My standing rule for clients: log every label API call in full — what was sent, when, what came back, how long it took. When you're arguing with a carrier over a billing discrepancy or handling a customer claim, the log is your only evidence. Incomplete logs, and nobody can help you find the break.
So step one's verdict is simple: no record in the log, the problem is inside your own walls — fix the internal chain first. Record exists, move on.
Timeouts are the real killer: the carrier may have created the label anyway
This is the deadliest and most unfair way to lose an order.
Here's the scene: the WMS calls the carrier's label API, the carrier takes too long, the call exceeds the timeout (every carrier is different — follow their documentation), so the WMS marks it as timed out and retries automatically. The second call succeeds, the label comes back, everyone celebrates — except the first request had actually created the label on the carrier's side. The response just never made it back. Now this order has two labels and two tracking numbers.
Two consequences. First, you pay twice: some carriers bill per label created, and their void process is painful enough that small warehouses never bother voiding one by one — the money just quietly leaks away. Second, the warehouse only sticks one label on a parcel and ships it. The other becomes a ghost label — created in the system, trackable by the customer, but the parcel will never show a pickup scan. Customer service looks it up: valid tracking number, zero tracking events. Nobody can explain it. You eat the cost and reship. The maddening part: the WMS looks fine, the carrier tracking looks "fine" — both sides normal, and the freight never moved.
The fix is two words: idempotency and retry policy.
Idempotency means every label request carries a business-unique key — order number plus package sequence, for example — and the carrier's API returns the same label for repeated requests with the same key. Confirm this with the carrier during integration. Some APIs don't enable idempotency by default; you have to request it in the contract or the configuration. Shipping retries without it is planting your own landmine. Get it written into the contract during negotiation, not after something breaks.
Retry policy means never blindly resending after a timeout. My approach: on the first timeout, query the carrier first — use the order or package reference to check whether the label was actually created. If it was, use the existing one. Only resend if it wasn't. One lookup costs far less than cleaning up a pile of ghost labels. Cap your retries, space them out, and don't pile on while the carrier's system is already struggling. During peak season the carrier's API is already slow — blind retries just make it slower, a vicious cycle.
And the printer? It rarely loses orders. A label printed but never applied, or applied to the wrong parcel — that's floor management, solved with cameras and pick records, not an API problem. Of the orders that die in the API chain, nine out of ten die on the word "timeout."
Run reconciliation every day and let it catch everything else
The first two steps are "how to investigate when something breaks." This one is "how to know immediately when something breaks."
No matter how solid the chain is, I insist clients run a daily reconciliation job. The logic is three lines: pull the carrier's created-label count (via their reconciliation API or billing download), pull the WMS's actual shipped count, match them on order or tracking number, and the difference is your lost orders. Watch the definitions: exclude voided labels, reconcile each carrier separately — don't count carrier A's labels against carrier B — and run it at a fixed time each day. I usually recommend early morning, clear of the carrier's settlement window.
How do you set the alert threshold? My rule of thumb: alert when the gap exceeds 0.5% of the day's volume; call someone's phone when it exceeds 2%. Don't alert on any difference at all — carriers sometimes create labels in batches, like overnight settlement runs, so a label created today may not hit the billing file until tomorrow. Zero tolerance just trains everyone to ignore the alerts, and then nobody looks when it really matters. A threshold is meant to be used, not worshipped — set it too sensitive and it's the same as having none.
That Los Angeles 3PL survived on this reconciliation job. Before it existed, they couldn't even say how many orders they were losing each day — that's the scariest part, not knowing the size of the problem. After it went live, lost orders dropped from 300-plus a day to single digits, and the remaining few were mislabeled parcels on the floor — nothing to do with the API. Every morning, operations starts the day with the reconciliation report. Any gap gets investigated the same day. Problems don't get to spend the night.
Remember this chain: logs first, then timeouts, then the printer — and reconcile every single day.
