This feature is available only for full shipments in Mexico.

The new /returns resource allows you to get the details of a product return, know its reasons and status. Now, Mercado Libre works with 2 types of returns:

  • Express: depends on the buyer's decision.
  • Those that are generated through a claim.

Currently it allows you to consult the "express" returns and manage them in a simple way. Soon, from the same resource you will be able to access those that come from a claim.


→Identify a return
→Response fields
→Return statuses

Identify a return

Subscribe to the marketplace claims notifications to know those associated with an order. In addition, you can see the claims resource and validate if the claim type is a "return".


curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'$CLAIM_ID/returns


   "last_updated": "2021-03-05T15:30:53.402-04:00",
   "shipping": {
       "id": "40438870744",
       "status": "ready_to_ship",
       "tracking_number": "101010456281978",
       "lead_time": {
           "estimated_delivery_time": {
               "date": "2021-03-11T00:00:00.000-06:00"
       "status_history": [
               "status": "handling",
               "substatus": null,
               "date": "2021-03-05T15:29:07.000-04:00"
               "status": "ready_to_ship",
               "substatus": "ready_to_print",
               "date": "2021-03-05T15:29:10.000-04:00"
               "status": "ready_to_ship",
               "substatus": "printed",
               "date": "2021-03-05T15:30:45.000-04:00"
       "origin": {
           "type": "selling_address",
           "sender_id": 602687555,
           "shipping_address": {
               "address_id": 1115213135,
               "address_line": "Testing Street 1450",
               "street_name": "Testing Street",
               "street_number": "1450",
               "comment": "Referencia: The Testing Cavern",
               "zip_code": "45200",
               "city": {
                   "id": "TUxNQ1pBUDM4NzE",
                   "name": "Zapopan"
               "state": {
                   "id": "MX-JAL",
                   "name": "Jalisco"
               "country": {
                   "id": "MX",
                   "name": "Mexico"
               "neighborhood": {
                   "id": null,
                   "name": "The Neighborhood"
               "municipality": {
                   "id": null,
                   "name": null
               "types": [
               "latitude": 20.815572,
               "longitude": -103.454067,
               "geolocation_type": "ROOFTOP"
   "refund_at": "shipped",
   "date_closed": null,
   "resource": "order",
   "date_created": "2021-03-05T15:29:06.613-04:00",
   "claim_id": 5061452327,
   "status_money": "retained",
   "resource_id": 4408624464,
   "type": "express",
   "status": "opened"


Response fields

last_updated: last update of the return

shipping: shipping detail

  • id: shipment identification number
  • status: shipment status
  • tracking_number: return shipment tracking number
  • estimated_delivery_time: estimated time of arrival of the return shipment

status_history: history of status that the return shipment had

  • status: 4 possible status of the return:
  • handling: when the label is generated

    ready_to_ship: ready to ship label

    shipped: sent

    delivered: delivered

  • substatus
  • date

origin: the seller's address, where the return is sent

refund_at: when the money is returned to the buyer


  • shipped: when the buyer dispatches the return shipment
  • delivered: 3 days after the seller receives the shipment

date_closed: date the return is closed

resource: name of the resource to which the return is associated

date_created: date the return is created

claim_id: claim ID the return is associated with

status_money: refund money status


  • retained: money in account, but not available (withheld)
  • refunded: money returned to buyer
  • available: available money in account

resource_id: resource ID

type: expres

status: possible statuses of a return

Return statuses

opened: the seller initiates a claim to Mercado Libre for a return

shipped: return sent and not available money.

closed: return final status at the close of the same and the associated claim_id. This status triggers the money return to the buyer.

delivered: shipped by seller but there was NOT the 3 days to review yet.

cancelled: canceled return, available money.

expired: expired return, available money.


Invalid parameter example

   "message": "Invalid Parameter",
   "error": "Bad Request",
   "status": 400,
   "cause": [
       "Invalid or empty id"

Invalid access token example

   "message": "invalid_token",
   "error": "not_found",
   "status": 401,
   "cause": []