API Documentation | Parcel Uncle

Introduction

The Parcel Uncle Merchant API provides programmatic access to manage your logistics operations. Build directly into your storefront, ERP, or custom dashboard.

Base URL: https://parceluncle.com/carrier/v1/merchant/

All requests must be made over HTTPS. Responses are served in JSON format. We provide both Sandbox (TEST) and Production (LIVE) environments accessible through different API keys.

Authentication

Authenticate your API requests by including your API key in the X-API-Key header. You can manage your API keys in the Developer section of your Seller Dashboard.

Sandbox Mode

Keys prefixed with pu_test_. Actions are simulated and no real wallet deductions occur. COD is forced.

Live Mode

Keys prefixed with pu_live_. Actions are real and shipments will be dispatched. Wallet/Credit deductions apply.

Authentication Example

curl -X GET https://parceluncle.com/carrier/v1/merchant/shipments/ \
  -H "X-API-Key: pu_live_1234567890abcdef1234567890abcdef1234567890abcdef"

Rate Limits

To ensure service stability, API requests are rate-limited per API key on a 1-minute sliding window. If you exceed the limit, you will receive a 429 Too Many Requests response.

Key Type	General Endpoints	Tracking Endpoint
Live (Production)	60 req / min	20 req / min
Test (Sandbox)	30 req / min	20 req / min

GET

Serviceability Check

/carrier/v1/merchant/serviceability/?pincode={pincode}

Check if Parcel Uncle provides delivery services to a specific pincode. Unauthenticated requests are allowed for this endpoint if you provide a valid API key.

Query Parameters

pincode Required — The 6-digit postal code to check.

Request

curl -X GET "https://parceluncle.com/carrier/v1/merchant/serviceability/?pincode=110014" \
  -H "X-API-Key: pu_live_..."

Response (200 OK)

{
  "success": true,
  "data": {
    "pincode": "110014",
    "is_serviceable": true,
    "city": "South Delhi"
  }
}

POST

Rate Quote

/carrier/v1/merchant/rates/

Calculate estimated shipping costs before creating a shipment. Prices vary based on service type, weight, and distance.

Payload Details

service_type: "SAME_DAY" | "NEXT_DAY" | "EXPRESS_4H"
weight_kg: float
pickup_pincode: string
delivery_pincode: string
is_cod: boolean (optional)
distance_km: float (optional)
length_cm, width_cm, height_cm: float (optional)

Response (200 OK)

{
  "success": true,
  "data": {
    "service_type": "EXPRESS_4H",
    "currency": "INR",
    "total": "145.50",
    "breakdown": {
      "distance_charge": 100,
      "weight_charge": 25,
      "gst_amount": 20.50
    },
    "sandbox": false
  }
}

POST

Create Shipment

/carrier/v1/merchant/shipments/

Create a new shipment request. This will instantly deduct funds from your Wallet or Credit Line if in LIVE mode.

🆕 New Fields: You can now use payment_mode, order_number, and total_amount for a cleaner integration. These fields are optional and fully backward-compatible — existing integrations continue to work without changes.

New Optional Fields

Field	Type	Required	Description
`order_number`	string	Optional	Your own order reference number (e.g., Shopify order ID)
`payment_mode`	"COD" \| "Prepaid"	Optional	Controls whether the recipient pays on delivery (COD) or the order is already paid (Prepaid)
`total_amount`	number	Required if payment_mode	Complete order value (must be > 0)
`cod_amount`	number	Required if COD	Amount to collect from recipient. Must be > 0 for COD, must be 0 for Prepaid.

Payment Mode Rules:

If payment_mode is "COD": cod_amount is mandatory and must be > 0. The rider will collect this amount from the recipient.
If payment_mode is "Prepaid": cod_amount must be 0. The order is already paid by the customer.
total_amount should always contain the complete order value.
payment_method (WALLET/CREDIT/COD) controls how you pay Parcel Uncle for shipping.

Example: COD Order

COD Payload

{
  "service_type": "SAME_DAY",
  "payment_method": "COD",
  "payment_mode": "COD",
  "order_number": "ORD-2024-001",
  "total_amount": 800,
  "cod_amount": 800,
  "pickup_address": "114/7, Second Floor, Hari Nagar Ashram",
  "pickup_city": "New Delhi",
  "pickup_state": "Delhi",
  "pickup_pincode": "110014",
  "delivery_address": "A-42, Sector 4",
  "delivery_city": "Noida",
  "delivery_state": "UP",
  "delivery_pincode": "201301",
  "sender_name": "Lekya Store",
  "sender_phone": "9876543210",
  "recipient_name": "John Doe",
  "recipient_phone": "9998887776",
  "weight_kg": 1.5,
  "parcel_type": "PACKAGE"
}

Example: Prepaid Order

Prepaid Payload

{
  "service_type": "SAME_DAY",
  "payment_method": "WALLET",
  "payment_mode": "Prepaid",
  "order_number": "ORD-2024-002",
  "total_amount": 800,
  "cod_amount": 0,
  "pickup_address": "114/7, Second Floor, Hari Nagar Ashram",
  "pickup_city": "New Delhi",
  "pickup_state": "Delhi",
  "pickup_pincode": "110014",
  "delivery_address": "A-42, Sector 4",
  "delivery_city": "Noida",
  "delivery_state": "UP",
  "delivery_pincode": "201301",
  "sender_name": "Lekya Store",
  "sender_phone": "9876543210",
  "recipient_name": "John Doe",
  "recipient_phone": "9998887776",
  "weight_kg": 1.5,
  "parcel_type": "PACKAGE"
}

Payment Methods: Use WALLET to debit from prepaid balance, CREDIT for post-paid credit line, or COD for Cash on Delivery. If COD is selected, you must also provide cod_amount.

Success Response (201 Created)

Response

{
  "success": true,
  "sandbox": false,
  "message": "Shipment created successfully",
  "data": {
    "tracking_number": "AWB987654321",
    "status": "PAID",
    "service_type": "SAME_DAY",
    "payment_method": "WALLET",
    "is_cod": false,
    "cod_amount": "0.00",
    "shipment_amount": "145.50",
    "order_number": "ORD-2024-002",
    "payment_mode": "Prepaid",
    "total_amount": "800.00",
    "pickup": {
      "address": "114/7, Second Floor, Hari Nagar Ashram",
      "city": "New Delhi",
      "state": "Delhi",
      "pincode": "110014",
      "landmark": ""
    },
    "delivery": {
      "address": "A-42, Sector 4",
      "city": "Noida",
      "state": "UP",
      "pincode": "201301",
      "landmark": ""
    },
    "sender": {
      "name": "Lekya Store",
      "phone": "9876543210",
      "email": ""
    },
    "recipient": {
      "name": "John Doe",
      "phone": "9998887776",
      "email": ""
    },
    "parcel": {
      "type": "PACKAGE",
      "weight_kg": "1.50",
      "length_cm": null,
      "width_cm": null,
      "height_cm": null
    },
    "cost_breakdown": {
      "distance_charge": 100,
      "weight_charge": 25,
      "gst_amount": 20.50
    },
    "assigned_rider": null,
    "special_instructions": "",
    "created_at": "2024-05-10T10:00:00Z",
    "updated_at": "2024-05-10T10:00:00Z",
    "delivered_at": null
  }
}

New Response Fields: The response now includes order_number, payment_mode ("COD" or "Prepaid"), and total_amount. These are returned for all shipments, even those created without these fields (they will default to empty/null/derived values).

GET

List Shipments

/carrier/v1/merchant/shipments/

Retrieve a paginated list of shipments associated with your account.

Query Parameters

page: Page number (default: 1)
limit: Items per page (default: 20, max: 100)
status: Filter by status (e.g. DELIVERED)
date_from / date_to: Filter by creation date (YYYY-MM-DD)

Response Format

{
  "success": true,
  "pagination": {
    "total": 142,
    "page": 1,
    "page_size": 20,
    "total_pages": 8,
    "has_next": true,
    "has_previous": false
  },
  "data": [
    {
      "tracking_number": "AWB123456789",
      "status": "DELIVERED",
      "service_type": "SAME_DAY",
      "payment_method": "WALLET",
      "is_cod": false,
      "cod_amount": "0.00",
      "shipment_amount": "145.50",
      "order_number": "ORD-2024-001",
      "payment_mode": "Prepaid",
      "total_amount": "800.00",
      "created_at": "2024-05-10T10:00:00Z"
    }
  ]
}

GET

Get Shipment

/carrier/v1/merchant/shipments/{tracking_number}/

Retrieve the full details of a specific shipment using its tracking number.

Path Parameters

tracking_number Required — The unique AWB/tracking number of the shipment.

Response Format

{
  "success": true,
  "data": {
    "tracking_number": "AWB123456789",
    "status": "DELIVERED",
    "service_type": "SAME_DAY",
    "payment_method": "COD",
    "is_cod": true,
    "cod_amount": "800.00",
    "shipment_amount": "145.50",
    "order_number": "ORD-2024-001",
    "payment_mode": "COD",
    "total_amount": "800.00",
    "pickup": {
      "address": "114/7, Second Floor, Hari Nagar Ashram",
      "city": "New Delhi",
      "state": "Delhi",
      "pincode": "110014",
      "landmark": ""
    },
    "delivery": {
      "address": "A-42, Sector 4",
      "city": "Noida",
      "state": "UP",
      "pincode": "201301",
      "landmark": ""
    },
    "sender": {
      "name": "Lekya Store",
      "phone": "9876543210",
      "email": ""
    },
    "recipient": {
      "name": "John Doe",
      "phone": "9998887776",
      "email": ""
    },
    "parcel": {
      "type": "PACKAGE",
      "weight_kg": "1.50",
      "length_cm": null,
      "width_cm": null,
      "height_cm": null
    },
    "cost_breakdown": {
      "distance_charge": 100,
      "weight_charge": 25,
      "gst_amount": 20.50
    },
    "assigned_rider": "Ramesh Kumar",
    "special_instructions": "",
    "created_at": "2024-05-10T10:00:00Z",
    "updated_at": "2024-05-10T16:45:00Z",
    "delivered_at": "2024-05-10T16:30:00Z"
  }
}

GET

Track Shipment

/carrier/v1/merchant/shipments/{tracking_number}/track/

Retrieve the real-time tracking timeline and current status of a specific shipment. Perfect for embedding tracking directly into your frontend.

Response Format

{
  "success": true,
  "data": {
    "tracking_number": "AWB123456789",
    "current_status": "OUT_FOR_DELIVERY",
    "description": "Out for delivery",
    "is_delivered": false,
    "rider": {
      "name": "Ramesh Kumar"
    },
    "timeline": [
      {
        "status": "CREATED",
        "description": "Order created and awaiting processing",
        "timestamp": "2024-05-10T10:00:00Z",
        "note": "Created via Merchant API v1 [LIVE]"
      },
      {
        "status": "PICKED_UP",
        "description": "Parcel picked up by rider",
        "timestamp": "2024-05-10T12:30:00Z",
        "note": ""
      }
    ]
  }
}

REF

Response Fields Reference

Complete reference of all fields returned in shipment responses across Create, List, and Get endpoints.

Field	Type	Description
`tracking_number`	string	Unique AWB number for the shipment
`status`	string	Current status: CREATED, PAID, ASSIGNED, PICKED_UP, IN_TRANSIT, OUT_FOR_DELIVERY, DELIVERED, FAILED, CANCELLED
`service_type`	string	SAME_DAY, NEXT_DAY, or EXPRESS_4H
`payment_method`	string	How the merchant pays: WALLET, CREDIT, or COD
`payment_mode` 🆕	string	Recipient-side payment: "COD" or "Prepaid". Derived from `is_cod`.
`order_number` 🆕	string	Merchant's own order reference. Empty string if not provided.
`total_amount` 🆕	string \| null	Complete order value. Null for shipments created before this feature.
`is_cod`	boolean	Whether this is a Cash on Delivery order
`cod_amount`	string	Amount to collect from recipient ("0.00" if not COD)
`shipment_amount`	string	Shipping cost charged to the merchant
`pickup`	object	Pickup address details (address, city, state, pincode, landmark)
`delivery`	object	Delivery address details (address, city, state, pincode, landmark)
`sender`	object	Sender contact info (name, phone, email)
`recipient`	object	Recipient contact info (name, phone, email)
`parcel`	object	Parcel details (type, weight_kg, length_cm, width_cm, height_cm)
`cost_breakdown`	object	Itemized pricing (distance_charge, weight_charge, gst_amount, etc.)
`assigned_rider`	string \| null	Name of the assigned rider, or null if not yet assigned
`created_at`	string (ISO 8601)	Timestamp when the shipment was created
`delivered_at`	string \| null	Timestamp when delivered, null if not yet delivered

Carrier API Documentation

Introduction

Authentication

Sandbox Mode

Live Mode

Rate Limits

Serviceability Check

Query Parameters

Rate Quote

Payload Details

Create Shipment

New Optional Fields

Example: COD Order

Example: Prepaid Order

Success Response (201 Created)

List Shipments

Query Parameters

Get Shipment

Path Parameters

Track Shipment

Response Fields Reference