API Documentation | TrackCourier.io

Introduction

The TrackCourier.io API provides a unified interface to track shipments across major Indian and international couriers. With one integration, you can track packages from Blue Dart, Delhivery, DTDC, FedEx, DHL, and many more.

Base URL: https://api.trackcourier.io/v1

All API requests are made over HTTPS. Requests made over plain HTTP will fail.

Authentication

All API requests require authentication via the X-API-Key header.

X-API-Key: your_api_key_here

Get your API key from your dashboard after signing up.

Rate Limits

Plan	Monthly Requests	Rate Limit
Free	100	10/minute
Starter	5,000	60/minute
Pro	50,000	300/minute

🚀 Get Started in 3 Steps

Start tracking shipments in under 5 minutes. No complex setup required.

Get Your Free API Key

Get API Key →

Make Your First Tracking Request

Copy this code and replace your_api_key with your actual key:

curl "https://api.trackcourier.io/v1/track?courier=delhivery&tracking_number=1234567890" \
  -H "X-API-Key: your_api_key"

import requests

response = requests.get(
    "https://api.trackcourier.io/v1/track",
    params={"courier": "delhivery", "tracking_number": "1234567890"},
    headers={"X-API-Key": "your_api_key"}
)
data = response.json()
print(data["data"]["status"])  # "in_transit", "delivered", etc.

const response = await fetch(
  "https://api.trackcourier.io/v1/track?courier=delhivery&tracking_number=1234567890",
  { headers: { "X-API-Key": "your_api_key" } }
);
const data = await response.json();
console.log(data.data.status);  // "in_transit", "delivered", etc.

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.trackcourier.io/v1/track?courier=delhivery&tracking_number=1234567890");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: your_api_key"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$data = json_decode($response, true);
echo $data["data"]["status"];  // "in_transit", "delivered", etc.

Handle the Response

You'll get back a JSON response with the shipment status and tracking history:

{
  "success": true,
  "data": {
    "status": "in_transit",           // Current status
    "MostRecentStatus": "In Transit - Package at Delhi Hub",
    "OriginCity": "Mumbai",
    "DestinationCity": "Delhi",
    "ExpectedDeliveryDate": "2024-01-28",
    "checkpoints": [...]              // Full tracking history
  },
  "usage": {
    "used": 1,
    "quota": 100,
    "remaining": 99
  }
}

That's it! You're now tracking shipments. Check the API Reference for more details.

Common Use Cases

🛒 E-commerce

Show customers real-time order status on your website

📱 Mobile Apps

Push delivery notifications to your app users

🤖 Automation

Trigger workflows based on delivery status changes

Track Shipment

GET /v1/track

Track a shipment by courier and tracking number. Returns current status and checkpoint history.

Query Parameters

Parameter	Type	Description
courier required	string	Courier slug (e.g., "bluedart", "delhivery")
tracking_number required	string	AWB or tracking number

Response

{
  "success": true,
  "data": {
    "status": "in_transit",
    "MostRecentStatus": "In Transit - Package at Delhi Hub",
    "OriginCity": "Mumbai",
    "DestinationCity": "Delhi",
    "ExpectedDeliveryDate": "2024-01-28",
    "checkpoints": [
      {
        "timestamp": "2024-01-25T10:30:00Z",
        "status": "Package picked up",
        "location": "Mumbai"
      },
      {
        "timestamp": "2024-01-26T08:15:00Z",
        "status": "In transit to Delhi",
        "location": "Delhi Hub"
      }
    ]
  },
  "usage": {
    "used": 45,
    "quota": 100,
    "remaining": 55
  }
}

Status Values

Status	Description
`pending`	Shipment created, not yet picked up
`in_transit`	Shipment moving through network
`out_for_delivery`	With delivery agent
`delivered`	Successfully delivered
`exception`	Delivery issue (RTO, failed attempt)

Response Codes

200	Success - tracking data returned
401	Invalid or missing API key
402	Quota exceeded - upgrade your plan
404	Courier not found

List Couriers

GET /v1/couriers

Get the list of all supported couriers and their slugs. This endpoint does not count against your quota.

Response

{
  "success": true,
  "data": {
    "couriers": [
      {"slug": "bluedart", "name": "Blue Dart"},
      {"slug": "delhivery", "name": "Delhivery"},
      {"slug": "dtdc", "name": "DTDC"}
    ],
    "count": 25
  }
}

Get Courier Details

GET /v1/couriers/{slug}

Get details for a specific courier by its slug. This endpoint does not count against your quota.

Response

{
  "success": true,
  "data": {
    "slug": "delhivery",
    "name": "Delhivery"
  }
}

Webhooks

Webhooks let you receive real-time notifications when shipment status changes. Instead of polling our API, we'll push updates to your server as they happen.

Coming Soon: Webhook configuration will be available in your dashboard. Contact api@trackcourier.io for early access.

How It Works

1. Configure your webhook URL in the dashboard
2. Subscribe to tracking numbers you want to monitor
3. Receive POST requests when status changes

Webhook Event Types

We send different event types based on shipment status changes.

Event	Description
`tracking.updated`	New checkpoint added to shipment
`tracking.in_transit`	Shipment is moving through the network
`tracking.out_for_delivery`	Shipment is out for delivery
`tracking.delivered`	Shipment successfully delivered
`tracking.exception`	Delivery issue (failed attempt, RTO, etc.)

Webhook Payload

All webhook events are sent as POST requests with a JSON body:

{
  "event": "tracking.delivered",
  "timestamp": "2024-01-28T14:30:00Z",
  "data": {
    "tracking_number": "1234567890",
    "courier": "delhivery",
    "status": "delivered",
    "MostRecentStatus": "Delivered - Signed by JOHN",
    "OriginCity": "Mumbai",
    "DestinationCity": "Delhi",
    "DeliveredDate": "2024-01-28T14:25:00Z",
    "checkpoints": [
      {
        "timestamp": "2024-01-28T14:25:00Z",
        "status": "Delivered",
        "location": "Delhi"
      }
    ]
  }
}

Webhook Security

Verify that webhook requests are from TrackCourier.io by checking the signature.

Signature Verification

Every webhook includes an X-Trackcourier-Signature header containing an HMAC-SHA256 signature of the request body.

X-Trackcourier-Signature: sha256=a1b2c3d4e5f6...

Verification Example (Python)

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    """Verify webhook signature."""
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()

    # signature format: "sha256=..."
    received = signature.replace("sha256=", "")
    return hmac.compare_digest(expected, received)

# In your webhook handler:
@app.post("/webhook")
async def handle_webhook(request: Request):
    payload = await request.body()
    signature = request.headers.get("X-Trackcourier-Signature", "")

    if not verify_webhook(payload, signature, WEBHOOK_SECRET):
        return {"error": "Invalid signature"}, 401

    data = json.loads(payload)
    # Process the webhook...
    return {"received": True}

Retry Policy

If your endpoint returns a non-2xx status code, we'll retry the webhook:

Retry 1: After 1 minute
Retry 2: After 5 minutes
Retry 3: After 30 minutes
Retry 4: After 2 hours
Retry 5: After 24 hours

After 5 failed attempts, the webhook is marked as failed. You can view failed webhooks in your dashboard.

Best Practices

Respond quickly: Return 200 within 5 seconds. Process async if needed.
Handle duplicates: Use the event timestamp for idempotency.
Verify signatures: Always validate the HMAC signature.
Use HTTPS: Only configure HTTPS webhook URLs.

Error Handling

Errors return a consistent JSON structure with an error code and message.

{
  "success": false,
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Monthly quota of 100 requests exceeded. Upgrade your plan."
  }
}

Error Codes

Code	HTTP Status	Description
`INVALID_API_KEY`	401	API key is invalid or missing
`QUOTA_EXCEEDED`	402	Monthly request quota exceeded
`COURIER_NOT_FOUND`	404	Unknown courier slug
`TRACKING_NOT_FOUND`	404	Tracking number not found
`TIMEOUT`	504	Courier backend timeout - retry
`SERVICE_ERROR`	502	Temporary service error - retry

Supported Couriers

We support 25+ major couriers. Use the slug in your API requests.

Indian Couriers

Blue Dart bluedart

Delhivery delhivery

DTDC dtdc

India Post indiapost

Speed Post speedpost

Ecom Express ecomexpress

XpressBees xpressbees

Shadowfax shadowfax

Ekart ekart

Trackon trackon

Shree Maruti shreemaruti

Professional professional

Gati gati

Safexpress safexpress

International Couriers

DHL dhl

FedEx fedex

UPS ups

Aramex aramex

USPS usps

Australia Post auspost

Canada Post canadapost

China Post chinapost

Japan Post japanpost

Correios correios

4PX 4px