What a good shipping API looks like – business perspective

A carrier API is, at its simplest, a way for your system and a carrier's system to talk to each other without a person retyping anything in between. Instead of someone logging into DHL's or InPost's website and filling in a shipment by hand, your software sends the shipment details straight to the carrier's system, and gets back a label, a tracking number, or an error, all through code, in one exchange. That exchange is what "carrier integration" means in practice.

A parcel doesn't know it's part of one of those exchanges, though.

It gets scanned at a depot by someone on the tail end of a night shift, sorted by a machine, driven across a border where a customs officer might decide to open the box, and eventually handed to a courier who has forty other stops before yours. The API request that started all this took maybe 200 milliseconds. Everything it's describing takes days, involves several companies, and can go wrong in more places than most product specs ever account for.

That is exactly why carrier documentation deserves more than a skim of the request and response samples.

I read a lot of this documentation, across a fair number of carriers, some local, some global. A handful were genuinely well thought out. A few made me want to email their product team and ask what happened.

By the time a developer opens a task and starts coding, most of the decisions that actually matter have already been made – by teams who read the carrier's documentation first. That's usually people on the business side: BAs, product owners, etc. This text is for any of you.

This is the first of a short series, split along that same line. Here, I'm covering what a business person should catch before a technical review even starts. Next up, we'll look at the same documentation from a developer's perspective, because a business read and a technical read tend to catch different issues.

Does the API describe a shipment, or just a label?

Some APIs stop caring about a parcel the moment a label is generated. You get a tracking number, a PDF, and then silence until the carrier's own tracking page decides to tell you something.

A good API keeps talking. It represents the shipment as something with a lifecycle – collected, in transit, at a sorting facility, out for delivery, delivered, returned, whatever the actual states are – and lets you build a picture of where things stand without scraping a public tracking page or waiting for a support ticket. If the contract between you and the carrier effectively ends at "label created," everything after that becomes your problem to solve.

This matters more than it sounds like it should, because customer service teams live or die by this. When a customer asks where their parcel is, "we don't know, the carrier does" is not an answer anyone gets to give twice.

Can you ask the API what's possible, or do you already have to know?

A weak API expects you to maintain your own reference table of service codes, country restrictions, and weight limits – usually built from a PDF you were emailed once, updated by hand whenever someone remembers to check. A strong API exposes that logic directly: given a destination, a weight, a set of dimensions, tell me what's actually available right now, not what was available when the spreadsheet was last touched.

The difference shows up the first time a carrier quietly drops a route or changes a weight threshold. With a static spreadsheet, you find out when a shipment fails. With a discovery endpoint, you find out before you ever try to send it.

When something goes wrong, does the error tell you what to fix?

I've read error responses that amount to little more than "something didn't work." No code you can build logic around, no message a customer support team can act on, nothing that survives being translated into a Jira ticket as a task for developers.

A carrier that treats its error responses as part of the actual contract – stable codes, specific enough to map to a real cause, consistent release over release – makes it possible to write proper acceptance criteria against failure states, not just the happy path. That's a small thing until you're the one explaining to an ops team why a shipment failed, and the only honest answer you can give is "the carrier didn't say."

Does the API stop you before the mistake becomes expensive?

Some things are cheap to get wrong early and expensive to get wrong late. An address typo caught before a label is purchased costs nothing. The same typo, caught after a shipment has been manifested and physically handed to a courier, can mean a lost parcel, a refund, and an unhappy customer, in that order.

A good API validates as early as it reasonably can – flagging what it's able to catch before an action becomes irreversible, rather than accepting anything you send and letting the consequences surface downstream, in a warehouse, or worse, in a customer's inbox.

Is customs data treated as real input, or an afterthought field?

Cross-border shipping means customs data is core to whether the shipment moves at all. The best APIs handle customs data with real structure: proper subdivision codes, clear rules about what's mandatory for which destination, and sensible defaults where they make sense.

Any shortcuts in the customs data show up the moment you're shipping somewhere with actual customs complexity – anywhere the destination country distinguishes between regions for tax or regulatory reasons, for instance. If the API doesn't model that distinction, your integration has to invent it, and it usually gets invented under deadline pressure, which is not when you want to be designing customs logic.

Do labels survive contact with a warehouse floor?

A label that renders perfectly on a screen and looks fine in a PDF preview is not the same thing as a label that scans cleanly on a conveyor belt running at full speed. Barcode symbologies, label dimensions and print resolution tolerances are not just cosmetic details. A barcode that's a few millimetres off spec, or printed at the wrong resolution for a given scanner, can mean a parcel gets kicked off the sorting line and handled manually, which is exactly the kind of delay a business person ends up explaining to a customer, without ever knowing the actual cause was a label spec, not a lost parcel.

What shipping labels don't tell you goes deeper into this from an engineering angle – worth reading if you want the full picture of how much can go wrong between "label generated" and "label correctly processed."

What does going live actually involve?

A sandbox that returns success for requests that would fail in production teaches your team the wrong lessons before you've even gone live. Onboarding that requires a string of emails and a waiting period you can't predict turns "we're ready to launch" into "we're ready whenever they get back to us." Documentation that's accurate on day one but drifts out of sync with the actual API, with no clear versioning to tell you what changed, means every future update is a small investigation before it's an implementation.

Peak seasons don't wait for a carrier's onboarding queue, either. When a go-live slips because of exactly this kind of gap, the people who absorb it are usually the same senior engineers who are already stretched thin everywhere else. I wrote about that pattern in the 'anti-burnout' squad – a good API doesn't fix an overloaded team on its own, but a badly documented one makes the problem measurably worse.

Wrapping up

A shipment is a physical thing moving through a distributed, partly uncontrollable process, and the API is supposed to be the honest interface to that process. The carriers that get this right expose the parts of the process a business person actually needs to see, in a form that doesn't require an engineer standing next to you translating every gap.

The carriers that get it wrong leave you filling in those gaps yourself.

Reading a carrier's documentation carefully is the point where most of the real risk in an integration either gets caught or gets inherited.

Next up in this series: the same question, answered from the technical side.

FAQ

What's the first thing a BA or PM should check in new carrier documentation? Whether the documentation describes the full shipment lifecycle or stops at label creation. If tracking, exceptions, and returns aren't covered with the same care as the initial booking, that's usually a sign of where the gaps will show up later.

Why does customs data belong in a business discussion about API quality, not just a technical one? Because for cross-border shipments, customs data determines whether the shipment clears at all. If the business side doesn't understand how a carrier models that, requirements get written against an incomplete picture, and the gap gets discovered during implementation instead of during planning.

Why do test and production accounts often behave differently? Sandboxes are usually built to make integration easy, which means they tend to be more forgiving than production by design, accepting test addresses, skipping real customs checks, or ignoring account-specific restrictions that only apply once real money and real regulations are involved. That's reasonable up to a point. The problem is when that gap isn't documented, so the first time anyone learns about it is when something that worked fine in testing gets rejected live.

Who should be involved in evaluating a carrier API? More people than just whoever's going to write the code. A BA or PM to read the documentation for the kind of gaps covered here, someone from operations who knows what a failed pickup or a customs hold actually costs in practice, and a developer who can confirm what's genuinely feasible to build against what's documented.