ShiftDocs

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

POST{host}/api/v1/open/cost-estimates

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

ParameterTypeDescription
returnOrderBooleanMust be set to true for return shipments
codOrderBooleanWhether this is a COD order
destinationPinIntegerDestination pincode (seller's pickup location)
originPinIntegerOrigin pincode (customer's location)
weightInGramsIntegerPackage weight in grams
declaredValueIntegerDeclared value of shipment
packageLengthIntegerPackage length in cm
packageBreadthIntegerPackage breadth in cm
packageHeightIntegerPackage 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

POST{host}/api/v1/open/return

Key points to note

  1. It is mandatory to fetch return cost estimates before creating a return shipment.
  2. Use the carrierCode and requestId from the cost estimates response.
  3. For return shipments, pickup_location is the customer's address and delivery_location is the seller's address.
  4. 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

ParameterRequiredDescription
carrier_codeRequiredObtained from the return cost estimates API response
request_idRequiredObtained from the return cost estimates API response
auto_carrier_selection_enabledOptionalSet to true to let the system auto-select the best carrier. If false, carrier_code and request_id are used
pickup_locationRequiredCustomer's address (origin of return). Use either addressUid or full address details
delivery_locationRequiredSeller's address (destination of return). Use either addressUid or full address details
shipment_valueOptionalDeclared value of the return shipment
return_reason_codeOptionalReason code for the return (e.g., CHNGDMND for Change of Mind)
qc_neededOptionalSet to true if quality check is required upon return delivery
delivery_instructionsOptionalSpecial handling instructions for the courier
product_detailsOptionalArray of product objects being returned (same structure as forward shipment)
dimensionsOptionalPackage 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

GET{host}/api/v1/open/return/track?returnAWBNumber={returnAWBNumber}

Query Parameters

ParameterRequiredDescription
returnAWBNumberRequiredThe 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

POST{host}/api/v1/open/return/shipment/cancel

Request Parameters

ParameterRequiredDescription
carrier_codeRequiredCarrier code used when the return shipment was created
tracking_numberRequiredAWB 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.

Talk to us