Shiprocket API Integration Guide

Suprith · May 27, 2025, 11:47am

This documentation will help integrate Shiprocket’s shipping and logistics services into their applications or backends, enabling automated order fulfillment, shipment tracking, rate fetching, and more.

About Shiprocket

Shiprocket is a shipping platform that aggregates multiple courier partners and provides businesses with an easy-to-use interface and powerful APIs for managing logistics and deliveries across India.

With Shiprocket APIs, you can:

Create and manage orders
Calculate shipping rates
Track shipments
Schedule pickups
Handle return orders

Understanding Shiprocket: Basics of Shipping & Modes

Before diving into API endpoints, it’s important to understand how Shiprocket handles shipping logistics and rate calculations.

How Are Shipping Rates Calculated?

Shipping charges in Shiprocket are calculated based on several key factors:

Factor	Description
Pickup Pincode	The origin of the shipment
Delivery Pincode	The destination pincode
Weight	Volumetric or actual weight, whichever is higher
Courier Partner	Each courier has its own pricing slabs and serviceability
Shipping Mode	Surface, Air, or Hyperlocal (affects cost and speed)
COD or Prepaid	Cash-on-Delivery usually has an additional charge

You can fetch live rates using the /courier/serviceability API.

Modes of Shipment

Shiprocket supports three major types of delivery services:

Mode	Use Case	Speed	Example Couriers
Surface	Cost-effective for non-urgent deliveries	3–7 business days	Delhivery, XpressBees, Ecom
Air	Fast delivery for metro-to-metro or premium zones	1–3 business days	Bluedart, Delhivery Air
Hyperlocal	Same-day or next-day delivery within a city	Few hours	Shadowfax, Dunzo, Wefast

Hyperlocal delivery is only available in select pincodes.

Volumetric vs Actual Weight

Shiprocket calculates the chargeable weight using the greater of:

Actual Weight: weight in KG (e.g., 2 kg)
Volumetric Weight: calculated using
[(length × breadth × height) / 5000]
in centimeters.

Example Rate Calculation

A 1kg prepaid shipment from Delhi (110001) to Mumbai (400001) via Surface mode might cost:

₹40–₹60 depending on the courier partner
COD will have an additional ₹20–₹30 COD fee

You can simulate rates using the Rate Calculator API.

Recommendations

Always provide accurate package dimensions and weight to avoid penalties.
Use the rate API to auto-select the best courier based on cost + serviceability.
Prefer Air shipments for urgent deliveries and Surface for bulk or non-urgent.

What This Guide Covers

This step-by-step documentation will walk you through:

Authenticating with the Shiprocket API (Token generation)
Creating orders and assigning couriers
Tracking shipment statuses
Handling returns and cancellations

Requirements

Before you start, make sure you have:

A Shiprocket Seller account
API access credentials from your Shiprocket dashboard

Getting Started

First, you need to register with Shiprocket and create an account.

Once you’ve completed the sign-up process, follow these steps to create an API user:

Log in to your Shiprocket account.
From the left-hand sidebar, navigate to:
Settings → API → Configure → Create API User
In the popup form:
- Enter a new email address (must be different from the one used for registration).
- Set a password and confirm it.
Click on Generate API Credential.

Upon successful completion, a new API user will be created.

Note: The order_id defined by you at the time of order creation is your reference order id. The order_id returned in the API response is the Shiprocket order id. All APIs will use this Shiprocket order id to access your created order unless stated otherwise.

Next Step: Authentication

Use the Authentication API to obtain an auth token.
This token is required to authenticate all future API calls.

Authentication (Login)

To interact with Shiprocket APIs, you must first authenticate using your API user credentials. This will return a Bearer Token which must be included in the headers of all subsequent API requests.

API Endpoint

POST https://apiv2.shiprocket.in/v1/external/auth/login

Request Headers

Content-Type: application/json

Request Body

{
  "email": "your-api-user-email@example.com",
  "password": "your-api-user-password"
}

Replace the email and password with the credentials of the API user you created earlier.

Sample Response

{
    "company_id": 1717241,
    "created_at": "2025-05-06 05:19:38",
    "email": "email@example.com",
    "first_name": "API",
    "id": 4474317,
    "last_name": "USER",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9................"
}

About the Token

This token is a JWT (JSON Web Token) and is unique to your Shiprocket account.
Validity: The token is valid for 10 days.
You can reuse the token in your application until it expires.

How to Use the Token

Include the token in the Authorization header of every request as shown:

Authorization: Bearer <your-token-here>

Order Creation

After successful authentication, you can create an order in Shiprocket using the API below.
This will register your order, calculate shipping charges, and generate an order ID for further processing.

API Endpoint

POST https://apiv2.shiprocket.in/v1/external/orders/create/adhoc

Request Headers

Content-Type: application/json  
Authorization: Bearer <your-token-here>

Sample Request Body

{
 "order_id": "1741089117729-183",
 "order_date": "2025-07-03 18:51",
 "pickup_location": "asdfasdf",
 "billing_customer_name": "customer",
 "billing_last_name":"name",
 "billing_address":"xxxxxx",
 "billing_city": "yyyyy",
 "billing_pincode": "110001",
 "billing_state": "Delhi",
 "billing_country": "India",
 "billing_email": "email@example.com",
 "billing_phone": "3456789011",
 "shipping_is_billing":true,
 "order_items":[
      {
   "selling_price": 1.4,
   "sku":"14325ks",
   "units": 1,
   "name": "1"
  }
  ],
 "total_discount":0,
 "sub_total": 0,
 "payment_method": "Prepaid",
 "length": 10,
 "breadth": 10,
 "height": 10,
 "weight": 2.5
}

Ensure pickup_location matches the one configured in your Shiprocket account.
Supported payment methods: “Prepaid” or “COD”.

Sample Response

{
    "order_id": 779035607,
    "channel_order_id": "1741089117729-182",
    "shipment_id": 775493747,
    "status": "NEW",
    "status_code": 1,
    "onboarding_completed_now": 0,
    "awb_code": "",
    "courier_company_id": "",
    "courier_name": "",
    "new_channel": false,
    "packaging_box_error": ""
}

Notes

Use a unique order_id every time you create a new order.
If shipping_is_billing is false, include separate shipping fields.
Make sure all mandatory fields are provided, otherwise the API will return an error.

Assigning AWB & Generating Pickup

Once an order is created, you need to assign a courier and schedule a pickup to move the shipment forward.
This step generates the AWB number (tracking number) and confirms pickup with the selected courier.

Step 1: Assign AWB to Shipment

API Endpoint

POST https://apiv2.shiprocket.in/v1/external/courier/assign/awb

Request Headers

Content-Type: application/json  
Authorization: Bearer <your-token-here>

Request Body

{
  "shipment_id": 987654321,
  "courier_id": 12
}

You must pass the shipment_id returned from the order creation step and a valid courier_id.

courier_id is optional.
If not provided, Shiprocket will automatically assign the most suitable courier based on pricing, serviceability, and performance.

Example to fetch available couriers for a shipment, use:

GET https://apiv2.shiprocket.in/v1/external/courier/serviceability?pickup_postcode=400703&delivery_postcode=575022&cod=0&weight=1

Step 2: Schedule Pickup

Once AWB is assigned, you can request a pickup.

API Endpoint

POST https://apiv2.shiprocket.in/v1/external/courier/generate/pickup

Request Body

{
  "shipment_id": [987654321]
}

Send shipment_id as an array, even if you’re scheduling pickup for a single shipment.

Notes

AWB must be assigned before scheduling pickup.
Courier assignment must match serviceability for the shipment’s destination.
The pickup will be attempted based on your default or selected pickup location.

Cancelling an Order

If an order is no longer needed or was created by mistake, you can cancel it before it is shipped.
Once the courier has picked up the order, cancellation is no longer possible via the API.

API Endpoint

POST https://apiv2.shiprocket.in/v1/external/orders/cancel

Request Headers

Content-Type: application/json  
Authorization: Bearer <your-token-here>

Request Body

{
  "ids": [123456789]
}

Replace 123456789 with the actual order_id (not shipment_id) that you want to cancel.
You can cancel multiple orders at once by passing multiple order IDs in the array.

Sample Response

{
    "status": 200,
    "message": "Your request to cancel order id 1741089117729-181 has been taken.The freight amount against the order is blocked and will be added back automatically to your wallet in 3-4 working days subject to confirmation from the courier."
}

Important Notes

You must cancel before the order moves to the “Shipped” state.
Cancelled orders cannot be restored.
If AWB is already assigned, cancellation will also notify the courier to halt pickup.
This API does not handle returns; use the Return API for post-shipping issues.

Tracking Shipments

You can track the real-time status of a shipment either by using the Shiprocket API or through Shiprocket’s public tracking URL. This helps you and your customers stay updated with delivery progress.

Option 1: Public Tracking URL (Recommended for Customers)

You can generate a public tracking link using the tracking number (awb_code):

AWB Not Found - Shiprocket<tracking_number>

Example:

https://shiprocket.co/tracking/SR123456789

You can share this link with your customers for direct access to shipment status.

Option 2: Tracking via Shiprocket API (Recommended for Server)

API Endpoint

GET https://apiv2.shiprocket.in/v1/external/courier/track/awb/{awb_code}

Creating a Return Order

If a customer wants to return a delivered item, you can initiate a Return Order using the Shiprocket API.
This triggers a reverse pickup from the customer’s address and delivers it back to your warehouse.

API Endpoint

POST https://apiv2.shiprocket.in/v1/external/orders/create/return

Request Headers

Content-Type: application/json  
Authorization: Bearer <your-token-here>

Sample Request Body

{
 "order_id": "1741089117729-185",
 "order_date": "2025-07-03 18:51",
 "shipping_customer_name": "customer name",
 "shipping_address":"xyz",
 "shipping_city": "zzzz",
 "shipping_pincode": "732867",
 "shipping_state": "Maharashtra",
 "shipping_country": "India",
 "shipping_email": "email@example.com",
 "shipping_phone": "1234567890",
 "pickup_customer_name": "name",
 "pickup_address": "Qui fugiat in velit qui in et",
 "pickup_city": "Dakshina Kannada",
 "pickup_pincode": "574240",
 "pickup_country": "India",
 "pickup_state": "Karnataka",
 "pickup_email": "name@example.com",
 "pickup_phone": "3456789011",
 "order_items":[
  {
   "selling_price": 1.4,
   "sku":"31e36dea-00f1-701a-025c-2cd26e17c944",
   "units": 1,
   "name": "1"
  }
  ],
 "total_discount":0,
 "sub_total": 1,
 "payment_method": "Prepaid",
 "length": 10,
 "breadth": 10,
 "height": 10,
 "weight": 2.5
}

Generate AWB for Return Shipment

This API is used to assign an AWB (Air Waybill) to a return shipment.
The AWB is a unique tracking number used by courier partners and Shiprocket to track the shipment status.

API Endpoint

POST https://apiv2.shiprocket.in/v1/external/courier/assign/awb

Request Headers

Content-Type: application/json  
Authorization: Bearer <your-token-here>

Request Body

{
  "shipment_id": 16016920,
  "courier_id": 10,         // Optional
  "status": "reassign",     // Optional - use only to change courier (once in 24 hrs)
  "is_return": 1            // Required - 1 for return orders
}

courier_id is optional. If not provided, Shiprocket will auto-select the best courier.
status: “reassign” can only be used once per 24 hours to switch couriers.
is_return must be set to 1 for return orders.

Then pick up schedule api is called.It is same as order flow.

Shiprocket Webhooks for Tracking Updates

Shiprocket allows you to configure webhooks so your system can receive real-time tracking updates automatically.
Whenever there’s a tracking event for any shipment (forward or return), Shiprocket will send a POST request to your configured endpoint.

Setup Instructions

Login to your Shiprocket account.
Go to Settings → API → Webhooks.
Click Add Webhook URL.
Enter your Webhook URL (your server endpoint).
Enable the Webhook Toggle to activate the integration.

Webhook Specifications

Key	Value
Method	POST
Content-Type	application/json
Header	x-api-key: `<your-token>`
Response	Must return HTTP `200 OK`

Avoid using these keywords in the webhook URL:
shiprocket, kartrocket, sr, kr (they will be blocked for security reasons)

Conclusion

By integrating Shiprocket’s APIs, you can automate your logistics workflow—from order placement to last-mile delivery and returns. This guide walked you through every essential step, including:

Authenticating and generating a token
Creating forward and return shipments
Assigning AWB numbers and scheduling pickups
Tracking shipments via webhook and API
Cancelling and managing return orders

Implementing these APIs ensures a streamlined and efficient delivery process while offering real-time tracking and better customer experience.

Reference Materials

Here are official and helpful resources for deeper exploration:

Sonal_Monis · May 27, 2025, 12:08pm

Awsome tutorial @Suprith

Suprith · May 27, 2025, 2:09pm

Thank you @Sonal_Monis