Home›ONDC Transaction›Update / Return

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

POST/ret11/update
Auth Required

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.highwaydelite.com",
      "bap_uri": "https://ondc.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
Completed Orders Only

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.

Get Return Reason IDs

Retrieve valid reasonId values from the return-reasons endpoint before calling this endpoint.

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