POST /v3/returns/tasks/shipments

Description - After the Start OTC has been validated, the shipment scanning page is shown for the FE in the FK Seller Hub. As shipments get scanned, the count of shipments in Handover in progress keeps increasing. The response contains information if more shipments are there to be scanned (hasMore Parameter), along with the encoded URL of the next shipment to be scanned (nextUrl Parameter). After all shipments have been scanned, the hasMore Parameter becomes false and nextUrl becomes null, indicating scanning completion.

Purpose: Poll for scanned shipments for a specific FE. Supports pagination for retrieving historical data. It should be called every 30 seconds.

Note

How Pagination Works:

• First Request: POST to get the initial scanned shipments
• Subsequent Requests: GET using nextUrl from previous response
• The nextUrl is base64 encoded and contains all query parameters
• Use the hasMore flag to determine if more data might be available

Request and Response Parameters

☰ SHOW | HIDE

First Request URL: https://api.flipkart.net/sellers/v3/returns/tasks/shipments

Subsequent Requests URL: https://api.flipkart.net/sellers/v3/returns/tasks/shipments/{encoded_url}

Request Header Parameters (Both Requests)

Parameter	Type	Requirement	Description
Content-Type	String	Mandatory	Must be application/json
Authorization	String	Mandatory	Bearer token for authentication

Request Body Parameters (First Request - POST)

Parameter	Type	Requirement	Description
taskId	String	Mandatory	Task identifier
feId	String	Mandatory	Field Executive identifier
pageSize	Integer	Optional	Number of shipments per page (default: 25)

Sample First Request (POST)

{
  "taskId": "123",
  "feId": "fe12303",
  "pageSize": 25
}

Sample Subsequent Request (GET)

Use the nextUrl from the previous response. The URL is base64 encoded and contains all query parameters.

GET https://api.flipkart.net/sellers/v3/returns/tasks/shipments/ewogICAgInRhc2tJZCI6ICIxMjMiLAogICAgImZlSWQiOiAiMTIzODkwIiwgIAogICAgImV0YWciOiAiRk1QMTA0NSIsIAogICAgInBhZ2VTaXplIjogMjAgCiAgfQ==

Response Body Parameters (Success - 200 OK)

Sample Response (Success - 200 OK)

{
  "hasMore": true,
  "nextUrl": "/sellers/v3/returns/tasks/shipments/ewogICAgInRhc2tJZCI6ICIxMjMiLAogICAgImZlSWQiOiAiMTIzODkwIiwgIAogICAgImV0YWciOiAiRk1QMTA0NSIsIAogICAgInBhZ2VTaXplIjogMjAgCiAgfQ==",
  "scannedShipments": [
    {
      "trackingId": "FMP01",
      "shipmentId": "SH123",
      "status": "ACCEPTED",
      "reason": null,
      "flyerDetails": {
        "actualFlyerId": "TEST_FLYER",
        "capturedFlyerId": "TEST_FLYER",
        "status": "FlyerMatch"
      },
      "obdDetails": {
        "eligible": true,
        "remark": "NoIssues",
        "imageLinks": ["url1", "url2"]
      },
      "scannedAt": 1732000000
    }
  ]
}

Sample Response (No Shipments - 200 OK)

{
  "scannedShipments": []
}

Possible Error Response Codes

Error Codes	Reason for Error
TASK_CLOSED	Task is closed
TRIPSHEET_TASK_NOT_FOUND	No RETURN task found for seller
INVALID_TASK_TYPE_ERROR	Task type is not RETURN
UNAUTHORIZED_ERROR	Authentication failed
INTERNAL_SERVER_ERROR	Internal server error
BAD_GATEWAY_ERROR	Bad gateway error
SERVICE_UNAVAILABLE_ERROR	Service unavailable
GATEWAY_TIMEOUT_ERROR	Gateway timeout

---