Last update 07/06/2022


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

  • Subscribe to the 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".
  • Check claims resource
  • Verify if the claim type is "return" (/claims resource)


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


  "last_updated": "2019-01-04T22:51:47.459-04:00",
  "shipping": {
    "id": "27768896524",
    "status": "cancelled",
    "tracking_number": null,
    "lead_time": {
      "estimated_delivery_time": {
        "date": "2018-12-28T00:00:00.000-03:00"
    "status_history": [
        "status": "handling",
        "substatus": null,
        "date": "2018-12-20T08:31:14.000-04:00"
        "status": "ready_to_ship",
        "substatus": "ready_to_print",
        "date": "2018-12-20T08:31:14.000-04:00"
        "status": "cancelled",
        "substatus": "return_expired",
        "date": "2019-01-04T22:47:01.000-04:00"
    "origin": {
      "type": "selling_address",
      "sender_id": 388146803,
      "shipping_address": {
        "address_id": 1018791372,
        "address_line": "Testing Street 1450",
        "street_name": "Testing Street",
        "street_number": "1450",
        "comment": "Referencia: The Testing Cavern",
        "zip_code": "1430",
        "city": {
          "id": "TUxBQlNBQTM3Mzda",
          "name": "Saavedra"
        "state": {
          "id": "AR-C",
          "name": "Capital Federal"
        "country": {
          "id": "AR",
          "name": "Argentina"
        "neighborhood": {
          "id": null,
          "name": "The Neighborhood"
        "municipality": {
          "id": null,
          "name": null
        "types": [
        "latitude": -34.554242,
        "longitude": -58.491549,
        "geolocation_type": "APPROXIMATE"
  "refund_at": "delivered",
  "date_closed": null,
  "resource": "order",
  "date_created": "2018-12-20T08:31:13.813-04:00",
  "claim_id": 1028414216,
  "status_money": "available",
  "resource_id": 1893698454,
  "type": "express",
  "status": "expired"


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

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

The /shipments/$SHIPMENT_ID/costs resource returns the shipment cost from user.


bug structure

   "error":Error Type,
   "code":Error code,
   "message":error message,
   "cause":list of error cause

Example invalid claim_id

    "error": "Can’t obtain data with id: 18",
    "code": 403,
    "message": "Cant get data with id: 18, status_code: 403 , response: {'error':'not_owned_order','status':403,'message':'The user has not access to the order.','cause':[]}, url:",
    "cause": []

Example invalid_param

    "error": "BAD_REQUEST",
    "code": 400,
    "message": "key: parameter claim_id must be a number, status_code:400",
    "cause": [
        "Invalid Param claim_id :aa"

Example access_token

    "code": 401,
    "message": "Error validating access token, status_code:401",
    "cause": [
        "Error validating access token",
banner footer

Subscribe to our Newletter

or register to recieve the latest news about our API