Returns
Return orders
The Return Order APIs allow you to manage reverse logistics - including fetching cost estimates, creating return shipments, tracking them, and cancelling if needed. The flow mirrors the forward shipment flow: estimate → book → track → cancel.
Return Order Cost Estimate
This uses the same cost estimates endpoint as forward shipments. The key difference is setting "returnOrder": true in the request body.
Request Example
curl --location '<HOST>/api/v1/open/cost-estimates' \
--header 'siteCode: CARRIER' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic xxxxxxxxxxxxxxxxxx' \
--data '{
"returnOrder": true,
"codOrder": true,
"destinationPin": 500081,
"originPin": 500032,
"weightInGrams": 250,
"declaredValue": 1000,
"packageLength": 10,
"packageBreadth": 10,
"packageHeight": 10
}'Request Parameters
| Parameter | Type | Description |
|---|---|---|
returnOrder | Boolean | Must be set to true for return shipments |
codOrder | Boolean | Whether this is a COD order |
destinationPin | Integer | Destination pincode (seller's pickup location) |
originPin | Integer | Origin pincode (customer's location) |
weightInGrams | Integer | Package weight in grams |
declaredValue | Integer | Declared value of shipment |
packageLength | Integer | Package length in cm |
packageBreadth | Integer | Package breadth in cm |
packageHeight | Integer | Package height in cm |
The response structure is identical to the forward cost estimates response. Note down the carrierCode and requestId from the response - you will need these to create the return shipment.
Create Return Shipment
Key points to note
- It is mandatory to fetch return cost estimates before creating a return shipment.
- Use the
carrierCodeandrequestIdfrom the cost estimates response. - For return shipments, pickup_location is the customer's address and delivery_location is the seller's address.
- Both locations can be specified using an
addressUid(existing address) or full address details.
Request Example
curl --location '<HOST>/api/v1/open/return' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic xxxxxxxxxxxxxxxxxx' \
--data '{
"carrier_code": "XB",
"request_id": "x1/pT7jVcxsEwmPEZZo7kt...",
"auto_carrier_selection_enabled": false,
"pickup_location": {
"addressUid": 311910
},
"delivery_location": {
"addressUid": 306160
},
"shipment": {
"delivery_instructions": "Handle with care",
"shipment_value": 1000,
"return_reason_code": "CHNGDMND",
"qc_needed": false,
"weight_grams": 250,
"product_details": [
{
"quantity": 1,
"description": "Blue T-Shirt - Size L",
"hsn_code/sku_code": "SKU-12345",
"category_of_goods": "Apparel",
"commodity_value": 1500,
"weight_grams": 500,
"height_cm": 10,
"length_cm": 30,
"breadth_cm": 25
}
],
"dimensions": {
"length_cm": 10,
"breadth_cm": 10,
"height_cm": 10
}
}
}'Payload Parameters Guide
| Parameter | Required | Description |
|---|---|---|
carrier_code | Required | Obtained from the return cost estimates API response |
request_id | Required | Obtained from the return cost estimates API response |
auto_carrier_selection_enabled | Optional | Set to true to let the system auto-select the best carrier. If false, carrier_code and request_id are used |
pickup_location | Required | Customer's address (origin of return). Use either addressUid or full address details |
delivery_location | Required | Seller's address (destination of return). Use either addressUid or full address details |
shipment_value | Optional | Declared value of the return shipment |
return_reason_code | Optional | Reason code for the return (e.g., CHNGDMND for Change of Mind) |
qc_needed | Optional | Set to true if quality check is required upon return delivery |
delivery_instructions | Optional | Special handling instructions for the courier |
product_details | Optional | Array of product objects being returned (same structure as forward shipment) |
dimensions | Optional | Package dimensions in cm (length_cm, breadth_cm, height_cm) |
Response Example
Success Response
{
"data": {
"carrierCode": "XB",
"trackingNumber": "24344960035209",
"shippingLabelUrl": "https://carrier-v2.s3.ap-south-1.amazonaws.com/.../ShippingLabel-XXXXX.pdf",
"invoiceUrl": null,
"manifestUrl": null,
"success": true,
"responseMessage": null
},
"errorMessage": null
}The trackingNumber returned is the AWB number for the return shipment. Save this - it is required for tracking and cancellation.
Track Return Shipment
Query Parameters
| Parameter | Required | Description |
|---|---|---|
returnAWBNumber | Required | The AWB/tracking number returned when the return shipment was created |
Request Example
curl --location '<HOST>/api/v1/open/return/track?returnAWBNumber=243449600352189' \
--header 'Authorization: Basic xxxxxxxxxxxxxxxxxx'The tracking response structure is identical to the forward shipment tracking response, including the trackingDetails array with scanStatus, scanLocation, and scanDateTime for each event.
Cancel Return Shipment
Request Parameters
| Parameter | Required | Description |
|---|---|---|
carrier_code | Required | Carrier code used when the return shipment was created |
tracking_number | Required | AWB number of the return shipment to cancel |
Request Example
curl --location '<HOST>/api/v1/open/return/shipment/cancel' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic xxxxxxxxxxxxxxxxxx' \
--data '{
"carrier_code": "XB",
"tracking_number": "24344960035209"
}'Response Example
Success Response
{
"data": true,
"errorMessage": null
}Stuck on an integration?
Your account manager can put you in touch with our tech team.