Pathao Courier API: Integration Guide for Online Shops

Pathao Courier moves a huge share of e-commerce parcels inside Dhaka and other metro cities, and if your shop ships more than a handful of orders a day, the Pathao courier API is how you stop typing those orders into a dashboard by hand. Connect your store’s backend to Pathao’s merchant API and every confirmed order can flow to the courier automatically — with the consignment ID written back to your order record for tracking and COD reconciliation.

This guide covers the integration the way a developer or technical shop owner should approach it: the authentication model, the data you need ready before creating orders, status updates, and the operational edge cases. As with every courier integration, the exact endpoint URLs, request fields, and limits belong to Pathao’s official merchant API documentation. The code in this post is illustrative pseudocode describing the typical flow — verify every specific detail against the official docs.

How the Pathao courier API flow typically works

Compared to some local couriers that use simple static API keys, Pathao’s developer platform has historically followed a more structured, token-based model. The typical lifecycle looks like this:

1. Get credentials. You register as a merchant and receive client credentials (an ID/secret pair or similar) for the API.
2. Issue an access token. You exchange those credentials for a short-lived access token, usually with a refresh mechanism to obtain new tokens without re-sending your secret.
3. Set up your store context. Pathao’s merchant model generally involves a registered store (your pickup point). Orders you create via API reference that store.
4. Resolve the delivery location. Deliveries are typically addressed against a structured location hierarchy (city, zone, area style) rather than free text alone, so your integration may need to look up and cache those location lists.
5. Create the order with recipient details, COD amount, weight or item info, and your own reference.
6. Track status by polling or receiving push updates until the parcel reaches a terminal state.

The exact names and shapes of all of these are defined by Pathao’s docs — the point here is the architecture: token issuance, store context, structured locations, order creation, status flow.

Handling token-based authentication properly

A short-lived token model needs slightly more engineering than a static key:

# Illustrative pseudocode — real endpoints, parameters, and
# token lifetimes are in Pathao's official API documentation.

function get_access_token():
    if cached_token exists and not near expiry:
        return cached_token
    response = POST {BASE_URL}/token   # placeholder
        body: { client_id, client_secret, ... }
    cache response.access_token with response.expires_in
    return response.access_token

Three rules keep this robust:

• Cache the token centrally. If ten processes each request their own token, you waste calls and can hit throttling. One shared cache (Redis, database row, in-memory singleton) is enough.
• Refresh before expiry, not after failure. Renew when, say, 80% of the lifetime has elapsed, but still handle an unexpected 401 by refreshing once and retrying.
• Never log tokens or secrets. Log that a token was refreshed, not its value.

Preparing your order data

The most common source of failed Pathao API calls is not code — it is data. Before you push an order, your system should guarantee:

• Phone number in valid Bangladeshi format (11 digits starting with 01). Normalize +880 prefixes before submission.
• A resolvable delivery location. If the API expects structured location IDs, you need a mapping step from your checkout’s free-text address to the courier’s location list. Cache those lists locally and refresh them periodically rather than fetching on every order.
• COD amount as an integer in BDT, matching what the rider should collect. A mismatch here creates reconciliation pain later.
• A unique merchant reference (your invoice or order number) so you can correlate everything the courier sends back.

Order creation itself is conceptually simple:

{
  "store_ref": "your-registered-store",
  "merchant_order_id": "SHOP-20871",
  "recipient_name": "Customer Name",
  "recipient_phone": "01XXXXXXXXX",
  "recipient_address": "House, Road, Area",
  "delivery_location": "resolved-location-reference",
  "cod_amount": 990
}

Field names above are placeholders. Persist the consignment/tracking ID from the response immediately, and treat a timeout as “unknown outcome” — look the order up by your merchant reference before retrying, so you never create duplicates.

Status updates, webhooks, and tracking

Pathao parcels move through the usual COD lifecycle: pending pickup, picked, at hub, out for delivery, then delivered, partially delivered, or returned. Your integration should:

• Map courier statuses to your own canonical set. Keep the mapping in configuration or a database table. When you later add Steadfast or RedX alongside Pathao, the same canonical statuses power all of them — see our Steadfast API integration guide for the same pattern from the other side.
• Prefer webhooks over polling where offered: expose an authenticated HTTPS endpoint, acknowledge quickly, process asynchronously, and deduplicate events.
• Keep a polling fallback for parcels stuck in a non-terminal state longer than expected — a daily sweep catches missed events.

Every status event should append to a per-parcel timeline, because that timeline is what your support team reads when a customer calls asking where their order is. This is precisely what a purpose-built parcel tracking solution provides: one searchable timeline per consignment, shared between your team and the customer, instead of screenshots from a courier app.

Delivered and returned events also drive money. Each delivered parcel adds its COD amount to what Pathao owes you; each return may add a return charge you owe them. If you reconcile that in Excel today, look at how COD management automates the matching between courier statements and parcel-level records.

Operational edge cases worth building for

• Pickup scheduling. Creating an order via API does not physically move the parcel — a rider still has to collect it. Understand how pickup requests work for your store and volume.
• Weight and size disputes. If charges depend on weight, record what you declared per parcel so you can challenge discrepancies with data.
• Partial delivery. Multi-item COD orders where the customer takes only some items change the collectable amount; your reconciliation logic must handle a delivered parcel whose collected COD differs from the original.
• Coverage gaps. Pathao is strongest in metro areas. Your checkout should decide courier by destination — Pathao for Dhaka metro, another courier elsewhere — which is exactly why the canonical status mapping and a courier-agnostic order model pay off.
• Cancellation windows. Cancel with the courier before pickup or expect charges; wire your shop’s cancel button to the courier API, not just your own database.

For the non-technical side of working with Pathao — onboarding, pricing negotiation, and dashboard workflows — see the Pathao courier merchant guide.

The courier’s side: offering an API like Pathao’s

Here is the strategic angle most integration guides skip. Merchants increasingly choose couriers based on integration quality — a courier with an API wins the F-commerce seller doing 100 orders a day, because manual entry at that volume is untenable. Pathao and Steadfast understood this early. Local and regional couriers that cannot offer an API lose exactly those high-volume merchants.

That is the gap Drix closes. Couriers running Drix, a courier management platform built for Bangladesh, get a merchant API layer out of the box: token-based auth, order creation, status webhooks, and tracking lookups, plus a merchant panel for shops that prefer a dashboard over code. A district courier on Drix can offer integrations that competitors twice its size do not — and merchants integrate once against a documented, stable API instead of reverse-engineering spreadsheets.

Summary and next steps

Integrating the Pathao courier API well means engineering around a token lifecycle, resolving structured delivery locations, keying every order to your own reference for idempotency, and treating status events as the source of truth for both customer communication and COD money flow. Build the canonical status mapping from day one so adding a second courier later is configuration, not a rewrite.

If you are a merchant who wants order pushing, tracking, and COD reconciliation without building all of this in-house — or a courier owner who wants to hand your merchants a real API — book a Drix demo and see the whole flow live, from order creation to settlement, with reports and analytics on top.