Courier API integration means your software does directly what someone would otherwise do in a courier's web portal: check whether an address is serviceable, get a rate, create a shipment, print a label, and follow the parcel afterwards.

The individual calls are not complicated. What makes integration work substantial is the order they happen in, the state you have to keep between them, and what you do when one of them fails.

Step 1: Authentication

Every courier API needs to know who you are. The common patterns are a static API key, a username and password exchanged for a token, or OAuth-style credentials with a refresh cycle.

Two things matter here more than the mechanism. First, credentials are stored securely, per partner and per environment — sandbox keys and production keys must never share a configuration. Second, token refresh has to be handled centrally rather than in each call site, or you will eventually have several pieces of code racing to refresh the same expired token.

Step 2: Serviceability check

Before promising anything to a customer, you ask the carrier whether they deliver to that pincode or postcode, and with which service types. This is usually a lightweight call and it is worth making early — at order time rather than at dispatch — because a serviceability failure discovered in the warehouse is a parcel that has already been picked and packed.

Serviceability data changes, so caching it helps performance but needs an expiry. A cache that never refreshes will eventually promise delivery to an area the carrier has withdrawn from.

Step 3: Rate lookup

Given origin, destination, weight, dimensions and service level, the carrier returns a price. If you work with several partners, this is the call that makes automated carrier selection possible — you compare rates across partners and pick by cost, speed or a rule of your own.

Two practical notes. Dimensional weight often matters more than actual weight, so your dimensions need to be accurate. And rates returned at quote time can differ from what is finally billed, so treating a rate response as a binding price is a reconciliation problem waiting to happen.

Step 4: Shipment creation

This is the call that matters. You send sender and receiver details, package information, service type and payment mode, and the carrier returns an AWB number — the tracking identifier for that parcel.

This is also the call you must never accidentally make twice. A network timeout does not tell you whether the shipment was created; it only tells you that you did not hear back. Without protection, the retry ships the parcel twice and you pay twice. The protection is an idempotency key, covered in courier API failure handling.

Step 5: Label generation

The carrier returns a shipping label, usually as a PDF or an image, sometimes as raw printer commands for thermal label printers. Your system stores it against the shipment and makes it printable.

Labels are less trivial than they look. The format has to match what the carrier's hub expects, including barcode symbology and label size. A label that does not scan cleanly at a sorting facility becomes a manual exception, and manual exceptions are where parcels go missing.

Step 6: Tracking

Once the parcel is moving, you need status updates. There are two ways to get them:

Polling — you ask the carrier periodically for the current status of shipments you care about. Simple, works everywhere, but delayed and wasteful of API calls.

Webhooks — the carrier calls your system when something changes. More efficient and closer to real time, but only available if the partner supports it and you can receive reliably.

Most production systems use both, and we compare them properly in webhooks vs polling for shipment tracking.

Step 7: Cancellation and returns

Orders get cancelled after booking. Most carriers allow cancellation up to a point in their process, after which the shipment is in motion and has to be handled as a return instead. Your system needs to know which state it is in, because attempting to cancel an already-dispatched parcel fails in ways that are easy to mishandle.

The parts that take the most time

If you are estimating an integration, the API calls above are rarely the bulk of the work. These are:

• Status normalisation — mapping each carrier's vocabulary into one model
• Failure handling — retries, backoff, idempotency, queuing
• Reconciliation — matching quoted rates against billed amounts
• Testing — sandbox environments vary in quality and some behave differently from production
• Maintenance — carriers change APIs, and an integration is an ongoing commitment

A note on what is possible

Every integration depends on the other side. What you can do, and how deeply, comes down to what that carrier's API exposes and what your commercial account with them permits. Two businesses integrating "the same" carrier can have materially different capabilities. That is worth confirming before scoping, not after.

Where we come in

We build courier API integrations with retries, idempotency, status normalisation and monitoring as part of the work rather than as later additions. See also the integrations we build more broadly.