API Integration

The API 48% of Our Bookings Run Through

Q: How do I authenticate with the iCargos courier API?

Every call takes two credentials: your client_code and an auth_key. You generate the key on the portal API Setting page (an admin enables API access first), then send both on each request. There is no OAuth flow.

Q: How do I book a shipment through the API?

POST to /API/CreateOrder.php with origin, destination, receiver details, pieces, weight, service type, collection amount and description. On success it returns a tracking number, the assigned carrier, an order id and an invoice link.

Q: Which endpoint should I use for tracking updates?

Use CurrentStatus for polling — it returns only the latest status and is lighter. Use TrackOrder when you need the full status history for a shipment.

Q: Do I need to code against the API to integrate?

Not necessarily. On Shopify or WooCommerce, the iCargos app and plugin book, track and label orders from inside your store using the same API. The REST API is for custom storefronts, marketplaces and ERPs.

A courier API lets your systems book shipments, track parcels and cancel orders programmatically instead of through a portal. The iCargos REST API covers booking, full and latest-status tracking, cancellation, serviceable-city lookup and pickup-profile creation — authenticated with a client code and key.

Book a Demo See Pricing

API-first, in practice

This isn't a bolt-on. Nearly half of every parcel booked on iCargos comes in through the API — it's the primary way high-volume merchants integrate.

48%

of all bookings come through the API

15,508

API orders booked in the last 30 days

REST

simple HTTP endpoints, JSON responses

Authentication

Two credentials on every call — no OAuth dance.

Client Code

Your account identifier, shown read-only on the portal's API Setting page.

API Auth Key

Generated on the same page with Generate API Auth Key, then saved. Send it as auth_key on every request.

Enable it first

An admin enables API access on the account before a key will work — worth confirming up front, since a key generated on a disabled account authenticates as invalid.

[ Screenshot: API Setting page ]Real product capture of the merchant API Setting screen (Client Code + Generate Auth Key) — awaiting capture from design.

The endpoints you'll use

A focused REST surface for the full shipment lifecycle.

Endpoint	Purpose
POST /API/CreateOrder.php	Book a shipment
POST /API/TrackOrder.php	Full tracking history
POST /API/CurrentStatus.php	Latest status only — use this for polling
GET /API/CancelOrder.php	Cancel an order
POST /API/GetCitiesList.php	Serviceable cities — pre-validate destinations
POST /API/ProductAndService.php	Products, services, cities, profiles
POST /API/CreateProfile.php	Create a pickup profile
GET /API/getThirdpartyApiAndGateways.php	Available carrier list

Booking a shipment

One POST to CreateOrder with the shipment details returns a tracking number and the assigned carrier.

Request — POST /API/CreateOrder.php

// required fields
{
  "auth_key": "<your key>",
  "client_code": "<your code>",
  "origin": "karachi",
  "destination": "lahore",
  "receiver_name": "Ayesha Khan",
  "receiver_phone": "03001234567",
  "receiver_address": "House 12, Gulberg III",
  "pieces": 1,
  "weight": 0.5,
  "service_type": "Overnight",
  "collection_amount": 2500,
  "product_description": "Cotton kurta",
  "special_instruction": "Call before delivery"
}

Success response

{
  "tracking_no": "CN000123456",
  "thirdparty_tracking_no": "LEP987654",
  "thirdparty_name": "Leopards",
  "id": "88213",
  "invoice_link": "https://.../invoice/88213"
}

Developer notes worth knowing up front

The honest edge-cases that save an integration day two.

Poll with CurrentStatus, not TrackOrder. CurrentStatus returns just the latest status and is the lightweight choice for scheduled polling; TrackOrder returns the full history.

Pre-validate cities. City names are matched literally and are case-sensitive — call GetCitiesList and send an exact match, or an unknown city can price the shipment at zero.

service_type is matched by name. Pass the service name (e.g. "Overnight"), not an ID.

Detect errors by response shape. Errors come back as a bare JSON string rather than an object — treat "the response is a string" as a failure and log the message.

No rate-quote or edit-order endpoint. Pricing is resolved at booking from your tariff, and there's no edit endpoint — cancel and re-book to change a shipment.

Prefer a plugin to raw API?

If you sell on Shopify or WooCommerce, you don't have to touch the API at all.

Shopify app

An embedded Shopify app books, tracks, bulk-labels and fulfils from inside your store — with multiple couriers built in. See the integrations hub.

WooCommerce plugin

Push single or bulk orders to your courier from the WooCommerce orders list, print labels and show tracking — without leaving WordPress.

Or build direct

For custom storefronts and ERPs, the REST API above gives you the same booking, tracking and cancellation the plugins use.

Frequently asked questions

How do I authenticate with the iCargos courier API?

Every call takes two credentials: your client_code and an auth_key. You generate the key on the portal's API Setting page (an admin enables API access on the account first), then send both on each request. There's no OAuth flow.

How do I book a shipment through the API?

POST to /API/CreateOrder.php with origin, destination, receiver details, pieces, weight, service type, collection amount and description. On success it returns a tracking number, the assigned carrier, an order id and an invoice link.

Which endpoint should I use for tracking updates?

Use CurrentStatus for polling — it returns only the latest status and is lighter. Use TrackOrder when you need the full status history for a shipment.

Is there a rate-quote or edit-order endpoint?

No. Pricing is resolved at booking time from your configured tariff, and there is no edit endpoint — to change a shipment you cancel it and book again. Serviceable cities can be validated ahead of booking with GetCitiesList.

Do I need to code against the API to integrate?

Not necessarily. If you're on Shopify or WooCommerce, the iCargos app and plugin book, track and label orders from inside your store using the same API under the hood. The REST API is for custom storefronts, marketplaces and ERPs.

Integrate in an afternoon

Book a demo and we'll enable API access and walk your team through a first live booking.