How to Evaluate a Freight Carrier’s API Before You Build the Integration

The evaluation step that gets skipped

The standard carrier evaluation compares rates, transit times, and coverage. Procurement runs it, the contract is signed, and engineering is handed an integration to build.

Nobody asks what the API does under load, what happens when a request fails, or whether the events it returns can support what the business intends to do with them. Those questions surface later, usually in the form of a discovery: the API polls rather than pushes, so status is minutes stale; the rate limit is undocumented and throttles during peak; a failed request returns a generic error with no indication of what was wrong.

By then the integration is built and the contract is signed, and the options are to work around the limitations or to absorb them as a permanent operating cost.

The scarcity of internal capacity to fix this after the fact makes prevention more valuable. Gartner found that 56 percent of chief supply chain officers cite integrating with legacy systems and processes as a major challenge, and 50 percent report limited internal expertise to implement and manage it. Engineering time spent working around a carrier API is time not spent on anything else.

The six criteria

1. Event granularity

The most consequential and the least examined. Does the API return events that describe what is happening to the shipment in terms a customer or a dispatcher can act on, or does it return internal carrier milestones?

Departed facility, arrived at sort, in transit are custody events. They were designed to support billing and dispute resolution, and they do that well. What they cannot support is a useful delivery ETA, because none of them tells you where the parcel is in a route or how many stops remain.

If your use case is customer notification or capacity-aware promising, weight this criterion above everything else. An API that returns coarse events quickly is still returning coarse events, and no amount of transport speed compensates for the resolution not being there.

Coarse event models are also how visibility gaps get designed into a stack from the beginning. Gartner has found that 80 percent of the supply chain is not accounted for in current digital decision models.

2. Webhook versus polling

A webhook-native carrier pushes events as they occur. A polling-dependent carrier requires your system to ask, on a schedule you choose within their rate limit.

Polling costs you twice. It introduces latency averaging half your polling interval, so a fifteen-minute cycle means the typical event is seven and a half minutes old when you see it. And it consumes rate limit on requests that mostly return nothing changed, which is the same budget you need during peak when things actually are changing.

Verify three things: whether webhooks exist, what delivery guarantee they carry, and whether they can be filtered by event type. At-least-once delivery is normal and means your endpoint must be idempotent; a carrier that cannot state its guarantee has not thought about it.

The latency question connects directly to whether the rest of your stack can function. Gartner found that while 95 percent of supply chains must react quickly to change, only 7 percent can execute decisions in real time, and upstream polling is frequently the constraint.

3. Rate limits and peak behaviour

Ask for the documented limit, and then ask the question that matters more: what happens when it is reached. Throttling with a retry-after header is manageable. Hard failure without one is an outage in your operation caused by someone else’s configuration.

Then ask whether the limit is per second, per minute, or per day, whether it is per account or per endpoint, and whether it can be raised for peak. Peak is precisely when you need more headroom and precisely when the carrier is least able to grant it, so agreeing it in advance is the difference between a plan and a hope.

Peak concentration is real and predictable. ShipMatrix found parcel networks absorbed a 30 percent volume increase during peak against the rest of the year while holding 98 percent on-time performance. Your integration has to absorb the same surge on the data side.

4. Error response quality

A failed request that returns a specific, documented error code tells your team what to fix. A generic 500 tells them to guess.

This criterion determines integration maintenance cost more than any other, because it sets how long each incident takes to diagnose. Test it directly during evaluation: send malformed requests deliberately and read what comes back. A carrier whose error responses are documented and specific is telling you something about how the API is maintained generally.

Also establish whether errors distinguish between retryable and terminal failures. Without that distinction your system either retries what will never succeed or gives up on what would have.

5. Documentation, versioning, and change communication

Four things to verify: whether a sandbox exists and behaves like production, whether there is a published versioning policy with a stated deprecation notice period, whether a changelog is maintained and how frequently it moves, and whether SDKs exist for your stack.

The deprecation notice period is the one to press on. A carrier that ships breaking changes without notice will break your integration on their schedule, and the cost lands entirely on you. Ask for the policy in writing rather than as an assurance.

6. Historical data access

Can you query past shipment status, or does the API return only current state?

Current-state-only APIs are adequate for tracking a live shipment and inadequate for everything afterwards: cost reconciliation, SLA reporting, carrier scorecarding, and exception investigation. If you cannot retrieve what happened last month from the carrier, you must store every event yourself as it arrives, which is a design decision worth making deliberately at the start rather than discovering in the first quarterly review.

A scoring template

Score each criterion 1 to 5, then weight by use case. The weights matter more than the scores, because a rate-shopping integration and a customer-notification integration fail on different criteria.

Two notes on using it. Fill it in from testing rather than from documentation, since documentation describes intent and testing describes behaviour. And record the date, because API quality changes and a score from eighteen months ago is a starting point rather than an answer.

Why this is an architecture problem, not only a selection problem

Suppose you run the framework properly and select carriers with strong APIs. You have reduced the risk and not removed it, because APIs change.

Endpoints deprecate. Event taxonomies get revised. Rate limits are adjusted. A carrier is acquired and its platform is migrated. Each of those events, in a directly integrated architecture, becomes an engineering project for you, and the frequency scales with the number of carriers you run.

The structural answer is an abstraction layer between your systems and individual carrier APIs. Your dispatch platform, TMS, and OMS integrate once to that layer, and carrier-specific variation is absorbed there. When a carrier changes, one integration is updated rather than every downstream system that consumed it.

This also solves the normalisation problem the framework surfaces. Different carriers return different events at different granularity with different reliability, and any system consuming raw carrier codes builds its own interpretation of them. Interpretations drift, and eventually two internal teams disagree about the same shipment. Normalising at the boundary prevents that by construction.

The cost of leaving these seams unmanaged is measurable at category level. McKinsey estimates that inefficient logistics handovers account for 13 to 19 percent of logistics costs, as much as 95 billion dollars annually in the US alone.

Where Locus fits

Locus, the world’s first Decision-Intelligent, Agentic TMS, operates as that abstraction layer for carrier connectivity. Your engineering team integrates once, and carrier-side variation, event taxonomies, polling behaviour, rate limits, and breaking changes, is handled at the Locus layer rather than surfacing into your dispatch and TMS integrations.

Practically that means three things. Carrier statuses are harmonised into one taxonomy before they reach your systems, so downstream consumers work from one vocabulary rather than several. ShipFlex provides 160+ pre-integrated active carriers drawn from a network of 1,000+ partners, which converts most carrier additions from a build into a configuration. And within DiSCO, the Carrier agent allocates across that network on cost, serviceability, and performance at dispatch time rather than at booking.

Locus has been recognized by Gartner for seven consecutive years, featured in the 2026 Hype Cycle for Supply Chain Execution and Logistics Technologies, named a Leader in TMS by QKS Group (SPARK Matrix), and ranked #1 in Route Planning on G2’s 2026 Best Software Awards. In October 2025, Ingka Investments, the investment arm of Ingka Group, the world’s largest IKEA retailer, acquired Locus. Locus continues to operate independently.

The clearest evidence is a leading ASEAN apparel retailer whose carrier onboarding had been a full engineering project each time, taking over three months, so entering a new market meant waiting out a build. Each carrier also reported delivery events in its own status codes, leaving internal systems without a common status. Moving to an abstraction layer cut new-carrier activation to three days, harmonised every carrier’s status into one standard set synced back to the retailer’s OMS and WMS, and generated labels in under 500 milliseconds at packing. Adding a carrier left the engineering queue entirely and became a business decision.

A leading Canadian grocery brand shows the cost of the alternative. Warehouse associates spent hours daily logging into each carrier’s website to create orders and generate labels one at a time, with status scattered across portals. Consolidating that produced 25 percent less time on manual shipping tasks alongside 33 percent faster deliveries and 15 percent lower fulfilment costs.

Before the next integration

Two things to add to your carrier onboarding process.

Run the six criteria during carrier evaluation rather than after contract signature, and give engineering sandbox access before procurement completes. An hour of testing changes the negotiation, because rate limits and deprecation notice periods are commercial terms and are considerably easier to secure before signing than after.

Then decide deliberately whether this carrier connects directly to your stack or through an abstraction layer. The answer will usually be the same for every carrier, which makes it an architecture decision to take once rather than a question to revisit each time.