What to look for in a carrier API

Most carrier APIs demo well. You get a rate quote back, you get a label back, and the integration looks finished. The parts that decide whether it was a good decision surface in month three, when a webhook stops firing at 2am and nobody notices until a customer does.

This is a read on what’s worth evaluating before you commit engineering time to a carrier integration, and which questions separate an API built for operations from a portal with a REST endpoint attached.

Rating and labels are table stakes

Every carrier API quotes a rate and generates a label. Judge these on predictability rather than features:

• Does the quote match the invoice? A rate endpoint that returns a number the billing system later disagrees with costs more than no endpoint at all, because now you have a reconciliation process. Ask what accessorials the quote includes and which are applied after the fact.
• Is label generation idempotent? If your worker retries after a timeout, do you get the same label back or a second shipment and a second charge? This is the single most common source of duplicate-billing tickets in a new integration.
• How are addresses validated? Silent correction is worse than rejection. A carrier that quietly rewrites a suite number and delivers to the wrong door has taken a decision away from you without telling you.

None of this is exotic. It is worth asking explicitly, because the answers vary more than you would expect.

Tracking is where APIs diverge

Rating and labels are a request-response problem, which is easy. Tracking is a state-synchronisation problem, which is not.

The lazy implementation is a polling endpoint: you ask every fifteen minutes whether anything changed. It works, it is simple, and it means your customer-facing status is up to fifteen minutes stale on the one day it matters, at a volume that makes polling expensive precisely when you have the most packages moving.

The better implementation pushes. When a shipment’s state changes, the carrier posts to an endpoint you own. What to ask:

• Are deliveries retried, and for how long? A webhook that fires once and gives up will lose events during your next deploy.
• Is delivery ordered, and are events idempotent? Out-of-order status events are normal in a distributed network. If your system can process the same event twice without corrupting state, you can stop caring.
• Is the payload signed? An unauthenticated endpoint that mutates shipment status is an obvious problem, and it is surprisingly often the default.

Exceptions are the real test

Ninety-something percent of parcels move without incident, and any API can report those. The value of an integration is concentrated entirely in the exceptions: the address that failed, the delivery that was attempted, the shipment sitting at a facility past its promise date.

The question to ask a carrier is not “do you expose exceptions” but “how soon, and with what detail.” A status that flips to a generic exception code six hours after the fact tells you something went wrong long after you could have acted. An exception event that arrives with a reason and a recommended action, while the driver is still in the area, is a different product.

Hovership exposes carrier operations through an API for rates, labels, tracking, live ETAs, and exception webhooks, which is the shape we would want as a shipper: push rather than poll, and exceptions treated as first-class events rather than a status code you discover later.

What integration actually costs

The engineering estimate for a carrier integration is usually wrong in the same direction, because the estimate covers the happy path and the cost lives elsewhere:

• Sandbox fidelity. If the test environment cannot produce an exception, a delivery attempt, or a returned shipment, you will be writing that error handling in production against real customers.
• Versioning policy. Ask what happens when the carrier changes a field. A carrier that versions its API and deprecates on a published schedule is telling you it expects to be integrated with. One that ships breaking changes on a Tuesday is telling you something else.
• Who you talk to when it breaks. This is not a technical property, but it determines your mean time to recovery more than any of the above. A support path that starts with a web form and ends three days later is a real operational cost.

What’s worth evaluating

Five questions worth putting to any carrier before the integration starts:

1. Is label generation idempotent under retry? Ask for the specific behaviour, not a reassurance. This one has a dollar cost attached and it shows up in month one.

2. Push or poll for tracking? If polling is the only option, price the ongoing cost of staleness during peak, not the cost of the integration.

3. What does an exception event contain, and how quickly does it arrive? Ask to see a real payload for a failed delivery attempt. The gap between carriers is largest here.

4. Can the sandbox produce failure states? Request a test scenario for an address failure and a delivery exception. If it cannot, add error-handling time to the estimate.

5. What is the deprecation policy? A published schedule is a proxy for whether the carrier treats its API as a product or a checkbox.

If you are scoping a carrier integration and want to work through these against a real API rather than a brochure, our enterprise team will walk through the endpoints, the webhook contract, and the sandbox with your engineers. Hovership runs same-day, next-day, 2–4 day, big-and-bulky, and freight across 26 states and 9,500+ ZIP codes, and the API is the same one our own operation runs on.

The integration you regret is rarely the one that was hard to build. It is the one that was easy to build and impossible to operate.