Documentation Mercado Libre

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


Last update 21/02/2024


The /v2/claims/$CLAIM_ID/ each return details $CLAIM_ID with types, subtypes and status.

In Mercado Libre we work with diffent types of returns:

  • claim: return created through a claim
  • dispute: return through mediation
  • automatic: automatic return

Identify a return

To correctly identify a return, we make the following recommendations:

  • Subscribe to the claims notifications (feed claims) which contains the order information where it caused.
  • Check claims API in the resource /v1/claims/search, validating if the type is "return".

Consult a return

To consult a return you must call /v2/claims/$CLAIM_ID/returns, specifying the $CLAIM_ID, examples below:

Request example:

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


  "last_updated": "2023-05-30T16:06:08.207-04:00",
  "shipping": {
      "id": 42313159782,
      "status": "delivered",
      "tracking_number": "10101015808",
      "lead_time": {
          "estimated_delivery_time": {
              "date": "2023-06-06T00:00:00.000-05:00"
      "status_history": [
              "status": "handling",
              "substatus": null,
              "date": "2023-05-30T15:52:05.206-04:00"
              "status": "ready_to_ship",
              "substatus": "ready_to_print",
              "date": "2023-05-30T15:52:09.736-04:00"
              "status": "shipped",
              "substatus": null,
              "date": "2023-05-30T16:04:00.689-04:00"
              "status": "delivered",
              "substatus": null,
              "date": "2023-05-30T16:06:07.644-04:00"
      "origin": {
          "type": "selling_address",
          "sender_id": 1206328181,
          "shipping_address": {
              "address_id": 1303663780,
              "address_line": "Calle 3 #01-22",
              "street_name": "Calle 3",
              "street_number": "#01-22",
              "comment": "Referencia: casa",
              "zip_code": "252201",
              "city": {
                  "id": "TUNPQ1BBUzQ4NjY4",
                  "name": "Pasca"
              "state": {
                  "id": "CO-CUN",
                  "name": "Cundinamarca"
              "country": {
                  "id": "CO",
                  "name": "Colombia"
              "neighborhood": {
                  "id": null,
                  "name": "Paca"
              "municipality": {
                  "id": null,
                  "name": null
              "types": [],
              "latitude": 4.307708,
              "longitude": -74.301528,
              "geolocation_type": "ROOFTOP"
  "refund_at": "shipped",
  "date_closed": "2023-05-30T16:04:01.763-04:00",
  "resource": "order",
  "date_created": "2023-05-30T15:52:04.476-04:00",
  "claim_id": 5195217090,
  "status_money": "refunded",
  "resource_id": 2000005748875612,
  "type": "claim",
  "subtype": null,
  "status": "closed"

Response parameters description

  • last_updated: return last update.
  • shipping: shipping detail of the return.
    • id: identification number of the shipment.
    • status: status of the shipment.
    • tracking_number tracking number of the return shipment.
    • lead_time:
      • estimated_delivery_time: estimated time of arrival of the return shipment.
        • date: estimated date of arrival of the return shipment.
    • status_history: represents the history of the states through which the return shipment has passed.
      • status: are the states through which the return shipment can pass:
          • pending: when the shipment is generated.
          • ready_to_ship: label ready to ship.
          • shipped: shipped.
          • not_delivered: not delivered.
          • delivered: delivered.
          • cancelled: shipment canceled.
      • substatus: null
      • date: status date.
    • origin: address of origin of the return shipment.
  • 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 shipmen.
    • n/a: or low cost cases a return is not generated.
  • date_closed: date on which the return ends.
  • resource: name of the resource to which the return is associated.
  • date_created: date on which the return is created.
  • claim_id: the ID of the claim to which the return is associated.
  • status_money: state in which the money of the return is.
    • retained: money in account but not available, retained.
    • refunded: money returned to the buyer.
    • available: money available on account.
  • resource_id: resource ID.
  • type: return type;
    • claim: return by claim.
    • dispute: return by mediation.
    • automatic: automatic return.
  • subtype: the subtype of return.
    • low_cost: automatic return of low cost type.
    • return_partial: automatic return of type return partial.
  • status: status through which a return can pass.
    • Return status:
        • opened: opened: when the buyer initiates a complaint to Mercado Libre for a return.
        • shipped: return shipped, money held.
        • closed: final status of the return at the end of the return and the associated claim_id.
        • delivered: sent by hand to the seller.
        • not_delivered: return not delivered.
        • cancelled: return canceled, money available.
        • failed: return failed.
        • expired: return expired.
  • warehouse_review: result of the triage process done in the warehouse (product review), this array has information only if the "destination" attribute is equal to warehouse, otherwise it is null.
    • product_condition:
      • saleable: means that the product is fit to be sold again and restock is done automatically.
      • unsaleable: the product is not in saleable condition.
      • discard: the product is discarded because it is different from the one the buyer got from the transaction and had to return, for example a stone.
    • product_destination: can be "buyer", "seller" or "meli".
    • benefited:
      • the seller is refunded the money from the sale.
      • false: the buyer is refunded the money from the transaction.
The /shipments/$SHIPMENT_ID/costs resource returns the shipment cost from user.


The following are the error messages that the resource may respond to, and which await corrective action:

1. Error when sending a $CLAIM_ID that you do not have access to using that access token:

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

1. Error when sending a $CLAIM_ID that you do not have access to using that access token:

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

3. Error si el $CLAIM_ID enviado no existe.

    "message": "Error executing GET [client:claims]",
    "error": "rest_client_error",
    "status": 404,
    "cause": [
        "{\"status\":404,\"error\":\"not_found\",\"message\":\"Claim not found. claimId: xxxx\"}"

4. Error if the $CLAIM_ID sent is empty or invalid.

    "message": "key: parameter claim_id is invalid or empty, status_code: 400",
    "error": "bad_request",
    "status": 400,
    "cause": [
        "Invalid Param claim_id",