Documentation Mercado Libre

Check out all the necessary information about APIs Mercado Libre.
circulos azuis em degrade


Last update 28/12/2022


This feature is available only for full shipments in Mexico.

The new /returns resource allows you to get the details of a product return, and know its reasons and status. Now, Mercado Libre works with 3 types of returns. Two of them depend on the buyer’s decision when there’s an express return or a return generated by a claim/complaint. The third one depends on Mercado Libre’s decision when there is an ongoing mediation:

  • Fulfilled by the seller: Mercado Libre is going to refund the buyer. The seller is not getting the payment for the product and it will need to afford the cost of the return shipment.
  • Fulfilled by Mercado Libre: Mercado Libre is going to refund the buyer and there is no extra cost for the return shipment.

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. Furthermore, sellers need to have a Local return address registered in order to get their products back for sale. See more information about Types of Returns (Local Return, Return to origin, Returnless refund and Fulfillment 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".


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