Returns

Return types by buyer

Depending on specific order conditions, the user, and the type of complaint, the buyer can start:

- An Express return: The buyer starts a return without having to talk to the seller or Mercado Libre. In this case, we notify the seller about the initiated return to follow up. It’s available only for sellers with a registered local return address.

- A return by complaint/claim: The buyer opens a complaint with a return request. The seller and buyer talk to resolve the problem. The seller can accept the return, refund the order’s money, or ask Mercado Libre for help.

- A direct mediation with return: A Mercado Libre representative reviews the case. They will talk with both parties to find a suitable solution.

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".

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/claims/$CLAIM_ID/returns

Response:

{
   "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": [
                   "billing",
                   "default_buying_address",
                   "default_selling_address",
                   "shipping"
               ],
               "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

values:

• 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

values:

• 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.

Errors

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": []
}