Official Communication: Lekya Logistics will never ask for your password or OTP. Stay safe from fraud!

For Developers & Partners

Carrier API Documentation

Integrate our lightning-fast logistics directly into your app. Powerful, secure, and developer-friendly.

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": "",
    "delivery_proofs": [
      {
        "url": "https://parceluncle.com/media/shipments/proofs/proof_001.jpg",
        "uploaded_at": "2024-05-10T16:30:00Z"
      }
    ],
    "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"
    },
    "delivery_proofs": [
      {
        "url": "https://parceluncle.com/media/shipments/proofs/proof_001.jpg",
        "uploaded_at": "2024-05-10T16:30:00Z"
      }
    ],
    "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

Tracking Status Codes

Every shipment moves through the following statuses. Use these codes to map your internal tracking system with Parcel Uncle's tracking updates.

Status Code Display Name Description Terminal?
CREATED Created Order has been created and is awaiting payment or processing. —
PENDING Pending Payment Payment is pending. Shipment will not be processed until payment is confirmed. —
PAID Payment Confirmed Payment received. Shipment is queued for rider assignment. —
ASSIGNED Assigned to Rider A rider has been assigned. Waiting for the rider to accept the pickup. —
ACCEPTED Accepted by Rider Rider has accepted the shipment and is en route to the pickup location. —
WAITING_PICKUP Waiting for Pickup Rider has arrived at the pickup location and is waiting for the parcel. —
PICKED_UP Picked Up Parcel has been collected by the rider from the pickup location. —
IN_TRANSIT In Transit Parcel is in transit to the delivery location. —
OUT_FOR_DELIVERY Out for Delivery Rider is near the delivery address and will deliver shortly. —
DELIVERED Delivered Parcel has been successfully delivered to the recipient. ✓ Final
FAILED Delivery Failed Delivery attempt failed (recipient unavailable, address incorrect, refused, etc.). May be reattempted or marked RTO. ✓ Final
CANCELLED Cancelled Shipment was cancelled by the merchant or admin before delivery. ✓ Final
RETURNED Returned (RTO) Parcel is being returned to the sender after failed delivery (Return to Origin). ✓ Final

Typical Status Flow

CREATED PAID ASSIGNED ACCEPTED WAITING_PICKUP PICKED_UP IN_TRANSIT OUT_FOR_DELIVERY DELIVERED
💡 Tip: Not every shipment goes through all statuses. For example, a shipment may go directly from PAID to CANCELLED if cancelled before rider assignment. Use the timeline array from the Track endpoint for the actual sequence of events for a specific shipment.
⚠️ Terminal Statuses: Once a shipment reaches DELIVERED, FAILED, CANCELLED, or RETURNED, no further status transitions will occur. These are final states.
GET

NDR List

NEW

/carrier/v1/merchant/ndr/

Retrieve all Non-Delivery Report (NDR) entries for your shipments. NDR entries are created when a delivery attempt fails.

Query Parameters

  • status: Filter by NDR status — OPEN, ACTION_TAKEN, RESOLVED, ESCALATED
  • action: Filter by action taken — PENDING, REATTEMPT, RTO, ADDRESS_UPDATE, HOLD
Request
curl -X GET "https://parceluncle.com/carrier/v1/merchant/ndr/?status=OPEN" \
  -H "X-API-Key: pu_live_..."
Response (200 OK)
{
  "success": true,
  "data": [
    {
      "ndr_id": "a1b2c3d4-...",
      "tracking_number": "PU1234567890",
      "attempt_number": 1,
      "reason": "RECIPIENT_UNAVAILABLE",
      "reason_detail": "Customer not at home",
      "rider_remarks": "Called twice, no answer",
      "status": "OPEN",
      "action": "PENDING",
      "action_taken_at": null,
      "reattempt_date": null,
      "reattempt_slot": "",
      "updated_address": "",
      "updated_phone": "",
      "created_at": "2024-05-10T16:45:00Z"
    }
  ]
}

NDR Reason Codes

Code Description
RECIPIENT_UNAVAILABLERecipient not available at delivery address
ADDRESS_INCORRECTIncorrect delivery address
ADDRESS_INCOMPLETEIncomplete address details
REFUSEDDelivery refused by recipient
DOOR_LOCKEDDoor locked / no response
COD_NOT_READYCOD amount not ready with recipient
RESCHEDULE_REQUESTEDCustomer requested reschedule
WEATHERWeather conditions prevented delivery
SECURITY_ISSUESecurity restriction at location
OTHEROther reason (see reason_detail)
POST

NDR Action

NEW

/carrier/v1/merchant/ndr/{tracking_number}/action/

Take action on an open NDR case. You can reattempt delivery, update the address, or initiate a Return to Origin (RTO).

Available Actions

Action Required Fields Description
REATTEMPT reattempt_date (YYYY-MM-DD), reattempt_slot (optional) Schedule a re-delivery attempt on the specified date
ADDRESS_UPDATE updated_address (required), updated_phone (optional) Update the delivery address and reattempt
RTO remarks (optional) Return the parcel to the sender (Return to Origin)

Example: Reattempt Delivery

Request
curl -X POST "https://parceluncle.com/carrier/v1/merchant/ndr/PU1234567890/action/" \
  -H "X-API-Key: pu_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "action": "REATTEMPT",
    "reattempt_date": "2024-05-12",
    "reattempt_slot": "10AM-1PM"
  }'
Response (200 OK)
{
  "success": true,
  "message": "NDR action REATTEMPT applied successfully",
  "data": {
    "ndr_id": "a1b2c3d4-...",
    "tracking_number": "PU1234567890",
    "attempt_number": 1,
    "reason": "RECIPIENT_UNAVAILABLE",
    "status": "ACTION_TAKEN",
    "action": "REATTEMPT",
    "action_taken_at": "2024-05-11T08:30:00Z",
    "reattempt_date": "2024-05-12",
    "reattempt_slot": "10AM-1PM"
  }
}

Example: Update Address

Request Payload
{
  "action": "ADDRESS_UPDATE",
  "updated_address": "B-15, Block C, Sector 62, Noida, UP 201309",
  "updated_phone": "9876543210"
}

Example: Return to Origin

Request Payload
{
  "action": "RTO",
  "remarks": "Customer refused delivery"
}
⚠️ Note: Only OPEN NDR cases can have actions taken on them. If no open NDR exists for the shipment, the API will return a 404 error.
POST

Cancel Shipment

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

Cancel a shipment and receive a wallet refund. The behavior depends on whether a rider has been assigned:

No Rider Assigned
  • Instant cancellation
  • Full wallet refund (auto-approved)
  • Returns 200 OK
Rider Assigned
  • Cancellation request created
  • Admin reviews & decides refund (full/partial/none)
  • Returns 202 Accepted

Request Body

Field Type Required Description
reason string Yes Reason for cancelling the shipment

Cancellable Statuses

CREATED PENDING PAID ASSIGNED ACCEPTED

Example: Instant Cancel (No Rider)

Request
curl -X POST "https://parceluncle.com/carrier/v1/merchant/shipments/PU1234567890/cancel/" \
  -H "X-API-Key: pu_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Customer changed delivery address"
  }'
Response (200 OK)
{
  "success": true,
  "data": {
    "tracking_number": "PU1234567890",
    "status": "CANCELLED",
    "cancellation_status": "AUTO_APPROVED",
    "refund_type": "FULL",
    "refund_amount": "149.00",
    "message": "Shipment cancelled successfully. Full refund processed.",
    "sandbox": false
  }
}

Example: Pending Review (Rider Assigned)

Request
curl -X POST "https://parceluncle.com/carrier/v1/merchant/shipments/PU9876543210/cancel/" \
  -H "X-API-Key: pu_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Order cancelled by buyer"
  }'
Response (202 Accepted)
{
  "success": true,
  "data": {
    "tracking_number": "PU9876543210",
    "status": "ASSIGNED",
    "cancellation_status": "PENDING",
    "rider_assigned": "Rahul Sharma",
    "message": "Rider \"Rahul Sharma\" is assigned. Cancellation request submitted for admin review.",
    "sandbox": false
  }
}

Response Fields

Field Type Description
tracking_number string Tracking number of the shipment
status string CANCELLED (instant) or the current status (pending review)
cancellation_status string AUTO_APPROVED (no rider) or PENDING (rider assigned, awaiting admin)
refund_type string FULL, PARTIAL, or NONE. Only present for auto-approved.
refund_amount string Refund amount credited to wallet. Only present for auto-approved.
rider_assigned string Name of assigned rider. Only present when status is PENDING.
💡 Refund Flow: When no rider is assigned, the full shipment amount is automatically refunded to your wallet. When a rider is assigned, an admin will review your request and can approve a full refund, partial refund, or no refund depending on the circumstances.
⚠️ Non-cancellable: Shipments that are already PICKED_UP, IN_TRANSIT, OUT_FOR_DELIVERY, DELIVERED, FAILED, RETURNED, or CANCELLED cannot be cancelled via this endpoint. The API will return 400 Bad Request.
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
delivery_proofs array Proof of delivery images. Each entry has url (absolute image URL) and uploaded_at (ISO 8601 timestamp). Empty array if no proofs uploaded.