Update / Return
Request a return for items from a delivered order. Requires proof images and a valid return reason code from the return-reasons endpoint. Returns can only be initiated on completed orders.
Initiate Return
Include a Bearer token. See Authentication.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| orderId | string | required | Order ID of the completed order to return items from |
| items | array | required | List of items to return. See items[] below. |
| images | string[] | required | Proof image URLs as evidence for the return. Example: ["https://images.com"] |
items[]
| Field | Type | Required | Description |
|---|---|---|---|
| itemId | string | required | ID of the item to return |
| quantity | number | required | Number of units to return |
| reasonId | string | required | Return reason code from the return-reasons endpoint. Example: "003" |
| reasonDesc | string | required | Description explaining the return reason |
| parentItemId | string | optional | For customizable items: the parent item grouping ID |
Request Example
{
"orderId": "019c2ed4b42a79b4b093b41d5dcd1352",
"items": [
{
"itemId": "id_ancc5_0_0",
"quantity": 1,
"reasonId": "003",
"reasonDesc": "Item not as described"
}
],
"images": ["https://images.com"]
}Response
Returns an ONDC update acknowledgment. The context.action is "update" and message.ack.status is "ACK" when the return request is accepted.
| Field | Type | Description |
|---|---|---|
| context | object | ONDC context block with action: "update" |
| message.ack.status | string | "ACK" when the return request is accepted |
Response Example
{
"data": {
"context": {
"domain": "ONDC:RET11",
"country": "IND",
"city": "std:080",
"action": "update",
"core_version": "1.2.0",
"bap_id": "ondc.preprod.highwaydelite.com",
"bap_uri": "https://ondc.preprod.highwaydelite.com/ret11",
"bpp_id": "pramaan.ondc.org/beta/preprod/mock/seller",
"bpp_uri": "https://pramaan.ondc.org/beta/preprod/mock/seller",
"transaction_id": "56a55c3f-8052-4bb6-91d6-47e1a178a0c0",
"message_id": "d4e5f6a7-b8c9-0123-defa-456789012345",
"timestamp": "2026-06-10T11:00:00.000Z",
"ttl": "PT30S"
},
"message": {
"ack": {
"status": "ACK"
}
}
}
}Return States
After initiating a return, track its progress via the order-details endpoint. The current return state is available in the orderCancelFulfillments field.
| State | Meaning |
|---|---|
| Return_Requested | Return request submitted, awaiting seller review |
| Return_Initiated | Return approved by seller, process started |
| Liquidated | Return complete, refund initiated |
Returns can only be initiated for orders that have been delivered. Attempting to return items from an order that is not yet completed will result in an error.
Retrieve valid reasonId values from the return-reasons endpoint before calling this endpoint.
Related Endpoints
| Endpoint | Purpose |
|---|---|
| Return Reasons | Fetch valid reasonId values to use in the request |
| Order Details | Track return status via orderCancelFulfillments after initiating a return |
| Cancel | Cancel an order before delivery instead of returning after |