| name | shiprocket |
| description | Use this skill whenever the user wants to integrate Shiprocket logistics APIs. Triggers include: creating shipment orders, generating AWB numbers, tracking parcels by AWB or order ID, checking courier serviceability between pincodes, calculating shipping rates, generating shipping labels, handling NDR (Non-Delivery Reports), cancelling orders, requesting pickups, or building any eCommerce shipping workflow using Shiprocket. Also trigger when user mentions Shiprocket courier, logistics API, AWB tracking, or delivery partner selection. |
Source
- Official docs: https://apidocs.shiprocket.in/
- Base URL (confirmed across all implementations):
https://apiv2.shiprocket.in/v1/external/
- Auth: Bearer token (JWT), expires every 24 hours — must refresh daily
Bundled Files
| File | Purpose |
|---|
scripts/shiprocket_client.py | Reusable Python client — import in any project |
scripts/test_shiprocket.py | Smoke-test script |
scripts/requirements.txt | Python dependencies |
references/endpoints.md | Full endpoint reference table |
Step 0 — Get Credentials
- Sign up at https://app.shiprocket.in/register
- Go to Settings → API → Configure → Create an API User
- Enter email + password → these are your API credentials (separate from login)
- Max 4 API users allowed per account
SHIPROCKET_EMAIL=your_api_user@email.com
SHIPROCKET_PASSWORD=your_api_password
Authentication — Generate Token
Every request needs a Bearer token. Token expires in 24 hours.
POST https://apiv2.shiprocket.in/v1/external/auth/login
import requests, os
BASE = "https://apiv2.shiprocket.in/v1/external"
def get_token(email: str, password: str) -> str:
res = requests.post(f"{BASE}/auth/login", json={
"email": email,
"password": password
})
return res.json()["token"]
TOKEN = get_token(os.environ["SHIPROCKET_EMAIL"], os.environ["SHIPROCKET_PASSWORD"])
HEADERS = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}
⚠️ Token is valid for 24 hrs. Cache it; don't generate a new one per request.
Core Flow
1. Check Serviceability → Is delivery possible between 2 pincodes?
2. Create Order → Register order in Shiprocket
3. Generate AWB → Assign courier + get AWB number
4. Request Pickup → Schedule courier to collect
5. Generate Label → Print shipping label (PDF)
6. Track Shipment → Live tracking by AWB or order ID
7. Handle NDR → Re-attempt failed deliveries
1. Check Courier Serviceability
GET https://apiv2.shiprocket.in/v1/external/courier/serviceability/
params = {
"pickup_postcode": "110001",
"delivery_postcode": "400001",
"weight": 0.5,
"cod": 0
}
res = requests.get(f"{BASE}/courier/serviceability/", headers=HEADERS, params=params)
couriers = res.json()["data"]["available_courier_companies"]
best = min(couriers, key=lambda c: c["rate"])
courier_id = best["courier_company_id"]
print(f"Best courier: {best['courier_name']} @ ₹{best['rate']}")
2. Create an Order
POST https://apiv2.shiprocket.in/v1/external/orders/create/adhoc
order_data = {
"order_id": "ORD-001",
"order_date": "2025-04-25 10:00",
"pickup_location": "Primary",
"billing_customer_name": "Rahul Sharma",
"billing_last_name": "Sharma",
"billing_address": "123 MG Road",
"billing_city": "Mumbai",
"billing_pincode": "400001",
"billing_state": "Maharashtra",
"billing_country": "India",
"billing_email": "rahul@example.com",
"billing_phone": "9876543210",
"shipping_is_billing": True,
"order_items": [
{
"name": "Cotton Kurta",
"sku": "KURTA-001",
"units": 2,
"selling_price": 499,
"discount": "",
"tax": "",
:
}
],
: ,
: ,
: ,
: ,
: ,
:
}
res = requests.post(, json=order_data, headers=HEADERS)
data = res.json()
order_id = data[]
shipment_id = data[]
()
3. Generate AWB (Assign Courier)
POST https://apiv2.shiprocket.in/v1/external/courier/assign/awb
res = requests.post(f"{BASE}/courier/assign/awb", headers=HEADERS, json={
"shipment_id": shipment_id,
"courier_id": str(courier_id)
})
awb_code = res.json()["response"]["data"]["awb_code"]
print(f"AWB: {awb_code}")
4. Request Pickup
POST https://apiv2.shiprocket.in/v1/external/courier/generate/pickup
res = requests.post(f"{BASE}/courier/generate/pickup", headers=HEADERS, json={
"shipment_id": [shipment_id]
})
print(res.json())
5. Generate Shipping Label
POST https://apiv2.shiprocket.in/v1/external/courier/generate/label
res = requests.post(f"{BASE}/courier/generate/label", headers=HEADERS, json={
"shipment_id": [shipment_id]
})
label_url = res.json()["label_url"]
print(f"Label: {label_url}")
6. Track Shipment
By AWB code
GET https://apiv2.shiprocket.in/v1/external/courier/track/awb/{awb}
res = requests.get(f"{BASE}/courier/track/awb/{awb_code}", headers=HEADERS)
tracking = res.json()["tracking_data"]
print(tracking["shipment_track"][0]["current_status"])
By Order ID
GET https://apiv2.shiprocket.in/v1/external/orders/show/{order_id}
res = requests.get(f"{BASE}/orders/show/{order_id}", headers=HEADERS)
Multiple AWBs (batch)
GET https://apiv2.shiprocket.in/v1/external/courier/track?awb=AWB1,AWB2,AWB3
7. Cancel Order
POST https://apiv2.shiprocket.in/v1/external/orders/cancel
res = requests.post(f"{BASE}/orders/cancel", headers=HEADERS, json={
"ids": [order_id]
})
8. NDR — Non-Delivery Report (Failed Delivery)
res = requests.get(f"{BASE}/ndr/all", headers=HEADERS)
res = requests.get(f"{BASE}/ndr/{awb_code}", headers=HEADERS)
res = requests.post(f"{BASE}/ndr/reattempt", headers=HEADERS, params={
"awb": awb_code,
"address1": "New Address Line 1",
"address2": "Landmark",
"phone": "9876543210",
"deferred_date": "2025-04-30"
})
Important Notes
| Rule | Detail |
|---|
| Token expiry | 24 hours — cache it, use env vars or Redis |
shipment_id vs order_id | Shiprocket creates both; AWB needs shipment_id |
| Weight unit | Always kilograms (kg), not grams |
| Dimensions | Always centimetres (cm) |
payment_method values | "Prepaid" or "COD" (case-sensitive) |
pickup_location | Must match exact warehouse name in your Shiprocket panel |
| HSN code | Required for GST compliance on order items |
| COD charge | Shiprocket deducts COD fee from remittance automatically |
