Developers

Documentation Mercado Libre

Check out all the necessary information about APIs Mercado Libre.

Last update 21/07/2025

Returns

A return is a crucial process in the buying experience on our platform, through which a buyer can return an item to the seller. This process can be triggered for various reasons, such as discrepancies between the product description and its actual condition, functionality issues, or even a change of mind by the buyer. Effectively managing returns is key to maintaining customer trust and satisfaction, ensuring any issues are resolved transparently and efficiently.

Note:

The resource /post-purchase/v2/claims/$CLAIM_ID/returns is an essential tool that allows you to access the specific details of each return, identified by its $CLAIM_ID, including types, subtypes, and statuses.

At Mercado Libre, we manage various types of returns to ensure a transparent and fair buying experience:

claim: A return initiated through a buyer’s claim.
dispute: A return resulting from a dispute between the buyer and seller.
automatic: A return initiated by the buyer, automatically processed by the system.

These different types of returns allow us to handle each situation specifically, ensuring both buyers and sellers receive the proper support throughout the post-purchase process.

Manage a return

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

Monitor the claim notification: Listen to the feed Marketplace claims, which contain the order information where the claim originated.
Check the resource /claims/$CLAIMS to access the "related_entities" field, which offers a list of entities linked to the claim. If the value "return" exists, it means there is a return associated with this claim. Now you can check the /returns resource to get the return details and take the necessary actions within the established timeframes.

For more information, check the Claims Management documentation..

Check a return

Call:

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

Example:

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

Response:

{
    "last_updated": "2024-09-09T22:35:11.717+00:00",
    "shipping": {
        "id": 43822268076,
        "status": "delivered",
        "tracking_number": null,
        "lead_time": {
            "estimated_delivery_time": {
                "date": "2024-09-11T00:00:00.000-06:00"
            }
        },
        "status_history": [
            {
                "status": "handling",
                "substatus": null,
                "date": "2024-09-09T17:49:32.277-04:00"
            },
            {
                "status": "ready_to_ship",
                "substatus": "ready_to_print",
                "date": "2024-09-09T17:49:32.641-04:00"
            },
            {
                "status": "ready_to_ship",
                "substatus": "printed",
                "date": "2024-09-09T17:49:32.641-04:00"
            },
            {
                "status": "shipped",
                "substatus": null,
                "date": "2024-09-09T18:07:11.695-04:00"
            },
            {
                "status": "shipped",
                "substatus": "first_visit",
                "date": "2024-09-09T18:13:44.426-04:00"
            },
            {
                "status": "delivered",
                "substatus": null,
                "date": "2024-09-09T18:13:44.426-04:00"
            }
        ],
        "origin": {
            "type": "selling_address",
            "sender_id": 1517482146,
            "shipping_address": {
                "address_id": 1400526513,
                "address_line": "Calle Sin Nombre SN",
                "street_name": "Calle Sin Nombre",
                "street_number": "SN",
                "comment": "Referencia: 222222",
                "zip_code": "05000",
                "city": {
                    "id": "TUxNQ0NVQTgxNTY",
                    "name": "Cuajimalpa De Morelos"
                },
                "state": {
                    "id": "MX-DIF",
                    "name": "Distrito Federal"
                },
                "country": {
                    "id": "MX",
                    "name": "Mexico"
                },
                "neighborhood": {
                    "id": null,
                    "name": "Cuajimalpa"
                },
                "municipality": {
                    "id": null,
                    "name": null
                },
                "types": [
                    "default_buying_address"
                ],
                "latitude": 19.3557507,
                "longitude": -99.2993504,
                "geolocation_type": "GEOMETRIC_CENTER"
            }
        },
        "destination": {
            "name": "seller_address"
        }
    },
    "refund_at": "delivered",
    "date_closed": "2024-09-09T18:35:11.994-04:00",
    "resource": "order",
    "date_created": "2024-09-09T21:49:32.037+00:00",
    "claim_id": 5298893830,
    "status_money": "retained",
    "resource_id": 2000009255685274,
    "type": "claim",
    "subtype": "return_total",
    "status": "closed",
    "warehouse_review": {
        "product_condition": "",
        "product_destination": "",
        "benefited": false
    },
    "seller_review": {
        "status": "success",
        "reason_id": null
    }
}

Response fields:

The GET response from the v2/claims/$CLAIM_ID/returns resource will provide the following fields:

last_updated: last return update.
shipping: return shipment details.
- id: shipment identification number.
- status: shipment status.
- tracking_number: return shipment tracking number.
- lead_time
- estimated_delivery_time: estimated return shipment arrival time.
- date: estimated return shipment arrival time.
status_history: represents the history of return shipment statuses.
- status: return statuses can include:
  - pending: when the shipment is generated.
  - ready_to_ship: label ready for dispatch.
  - shipped: sent.
  - not_delivered: not delivered.
  - delivered: delivered.
  - cancelled: shipment canceled.
- substatus: null
- date: status date.
origin: return shipment origin address.
- type: address type.
- sender_id: buyer code (buyer_id).
- shipping_address: address details.
  - address_id:
  - address_line:
  - street_name:
  - street_number:
  - comment:
  - zip_code:
  - city:
  - state:
  - country:
  - neighborhood:
  - municipality:
  - types:
  - latitude:
  - longitude:
  - geolocation_type:
destination: return destination information.
- name
  - seller_address: seller’s destination.
  - warehouse: Mercado Libre’s warehouse destination.
refund_at: when the buyer’s money is refunded.
- shipped: when the buyer dispatches the return shipment.
- delivered: 3 days after the seller receives the shipment.
- n/a: for low-cost cases where no return is generated.
date_closed: return closure date.
resource: name of the resource associated with the return.
date_created: return creation date.
claim_id: ID of the claim associated with the return.
status_money: return money status.
- retained: money in account but not available, retained.
- refunded: money returned to the buyer.
- available: money in available account.
resource_id: resource ID.
type: type of return.
- claim: return due to claim.
- dispute: return due to dispute.
- automatic: automatic return.
subtype: return subtype.
- low_cost: automatic low-cost return.
- return_partial: automatic partial return.
status: statuses a return can go through.
- opened: when the buyer initiates a return claim to Mercado Libre.
- shipped: return sent, money retained.
- closed: final status of the return upon closing and associated claim_id.
- delivered: return shipment in seller’s hands.
- not_delivered: return not delivered.
- cancelled: return canceled, money available.
- failed: return failed.
- expired: return expired.
warehouse_review: result of the triage process at the warehouse (product review). This array only contains information if the attribute “destination” equals warehouse; otherwise, it is null.
- product_condition
  - saleable: means the product is fit for resale, and it is automatically restocked.
  - unsaleable: the product is not in a saleable condition.
  - discard: the product is discarded because it differs from the item the buyer received and was supposed to return, e.g., a rock.
- product_destination
  - buyer
  - seller
  - meli
- benefited
  - true: the seller is reimbursed the sale amount.
  - false: the buyer is refunded the transaction amount
seller_review: provides information on the review conducted by the seller.
- status: review status. It can take one of the following values:
  - pending: the return is pending seller review.
  - claimed: the seller reviewed the product and decided it is not in the expected condition.
  - failed: the CX team decided the seller is the beneficiary (previous status is claimed).
  - success: the seller reviewed the return and indicated it arrived in the expected condition.
- reason_id: identifier for the reason the seller indicated an issue with the product. Possible values are returned by the reasons/return-fail resource. Currently, the possible values are:

Note:

Remember that the resource /shipments/$SHIPMENT_ID/costs returns the shipping costs the user will need to bear.

Return Review OK

When a return arrives to the seller, they have the possibility to review it, indicating whether the product arrived in the expected condition or if there is any issue with it.

To perform a "review OK" of a return, confirming that the product arrived as expected, the /claims/$CLAIM_ID/actions/return-review-ok resource has been enabled.

To know if the seller already has the option to perform a return review OK enabled, you can use the /claims/$CLAIM_ID resource. Within the "players" array, look for the player with "type": "seller" and check if their "available_actions" includes an "action": "return_review_ok".

Request:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/post-purchase/v1/claims/$CLAIM_ID/actions/return-review-ok

Example:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -d 
https://api.mercadolibre.com/post-purchase/v1/claims/5255026166/actions/return-review-ok

Response:

{
   "id":5255026166,
   "resource_id": 2000007760636316,
   "status": "closed",
   "type": "mediations",
   "stage": "claim",
   "parent_id": null,
   "resource": "order",
   "reason_id": "PDD9949",
   "fulfilled": true,
   "quantity_type": "total",
   "players": [
       {
           "role": "complainant",
           "type": "buyer",
           "user_id": 1277895049,
           "available_actions": []
       },
       {
           "role": "respondent",
           "type": "seller",
           "user_id": 1582937623,
           "available_actions": [
               {
                   "action": "return_review_fail",
                   "mandatory": false,
                   "due_date": null
               },
               {
                   "action": "return_review_ok",
                   "mandatory": true,
                   "due_date": "2024-06-03T22:43:00.000-04:00"
               }
           ]
       },
       {
           "role": "mediator",
           "type": "internal",
           "user_id": 46122402,
           "available_actions": []
       }
   ],
   "resolution": {
       "reason": "item_returned",
       "date_created": "",
       "benefited": [
           "complainant"
       ],
       "closed_by": "mediator",
       "applied_coverage": true
   },
   "site_id": "MLA",
   "date_created": "2024-05-29T23:48:32.000-04:00",
   "last_updated": "2024-05-29T23:51:26.370-04:00"
}

Response Fields

A successful GET request to the /actions/return-review-ok resource will return a status code 201 and the following fields:

id: Claim ID
resource: ID of the resource for which the claim was created. Depends on the “resource”
status: Claim status
- opened
- closed
type: Type of claim
- mediations: Claim between buyer and seller.
- return: Product return.
- fulfillment: Claim between buyer and Mercado Libre from a purchase with Full shipping.
- ml_case: Purchase cancellation by the buyer due to late delivery.
- cancel_sale: Purchase cancellation by the seller. Always in status: "closed" and stage: "none". The complainant role will always be of type seller, collector, or sender depending on the claim resource.
- cancel_purchase: Purchase cancellation by the buyer.
- change: Product exchange.
- service: Cancellation of an order bundle service.
stage: Claim stage
- claim: Stage where both buyer and seller participate.
- dispute: Mediation stage involving a Mercado Libre representative.
- recontact: Stage where one of the parties recontacts after the claim/dispute is closed.
- none: Not applicable.
- stale: Stage where buyer and Mercado Libre intervene for claims of type ml_case.
parent_id: ID of another claim on which this claim depends
resource: Identifier of the resource for which the claim was created. Determines the actors in the claim.
- payment: Payment
- order: Order
- shipment: Shipment
- purchase: Purchase
reason_id: Reason why the claim was created. Directly impacts the solutions that may be proposed.
- PNR: Product Not Received
- PDD: Product Different or Defective
- CS: Purchase Canceled
fulfilled: Indicates whether the claim was initiated for a delivered product or not
quantity_type: Indicates whether the claim is partial or not
- partial: Indicates that the claim is partial
- total: Indicates that the claim is total
players: List of actors participating in the claim, with their respective actions and available time
- role: Role in the claim
  - complainant: The person making the claim.
  - respondent: The person to whom the claim is addressed.
  - mediator: The person intervening to help resolve the issue.
  - warehouse_dispatcher: The person responsible for reviewing the product on returns to the warehouse.
- type: The role the person plays in the operation under claim
  - payment: buyer - collector.
  - order: buyer - seller.
  - shipment: receiver - sender.
  - purchase: buyer - Mercado Libre.
- user_id: User ID in ML performing the role
- available_actions: List of actions that each party involved can perform
  - players: List of actors participating in the claim with their respective actions and available times.
    - action: Name of the action
      - send_message_to_complainant: send message to the buyer (with or without attachments).
      - send_message_to_mediator: send message to the mediator (with or without attachments).
      - recontact (not yet available): reopen a closed claim through an interaction, such as a message.
      - refund: refund the buyer's money. Must be performed from Mercado Libre or Mercado Pago front end.
      - open_dispute: start a mediation.
      - send_potential_shipping: send a shipping promise, a date.
      - add_shipping_evidence: provide evidence that the product was shipped.
      - send_attachments: send message with attachments.
      - allow_return_label: generate return label.
      - allow_partial_refund: offer a partial refund to the buyer. Must be performed from Mercado Libre front end.
      - send_tracking_number: send the tracking number.
      - return_review_fail: perform a failed return review.
      - return_review_ok: perform a return review OK.
      - mandatory: type of action
        
        respondent: The person to whom the claim is addressed.
        
        warehouse_dispatcher: The person responsible for reviewing the product on returns to the warehouse.
resolution: List of actors participating in the claim, with their respective actions and available times
- reason: Reason for resolution/closure
  - already_shipped: Product in transit
  - buyer_claim_opened: Return closed due to another claim opened by the buyer
  - buyer_dispute_opened: Return closed due to another claim opened in dispute (with Mercado Libre mediation)
  - charged_back: Closed due to chargeback
  - coverage_decision: Dispute closed with ML coverage
  - found_missing_parts: Buyer found the missing parts
  - item_returned: Product returned
  - no_bg: Closed without ML coverage
  - not_delivered: Product not delivered
  - opened_claim_by_mistake: Buyer opened the claim by mistake
  - other: Other case
  - partial_refunded: Partial refund to the buyer
  - payment_refunded: Payment refunded to the buyer
  - preferred_to_keep_product: Buyer preferred to keep the product
  - product_delivered: Decision by a Mercado Libre representative
  - reimbursed: Refund
  - rep_resolution: Decision by a Mercado Libre representative
  - respondent_timeout: Seller did not respond
  - return_cancelled: Return canceled by the buyer
  - return_expired: Return expired with no exchange or shipment
  - seller_asked_to_close_claim: Seller asked the buyer to close the claim
  - seller_did_not_help: Buyer managed to solve the issue without the seller's help
  - seller_explained_functions: Seller explained how the item worked
  - seller_sent_product: Seller sent the product
  - timeout: Closed due to buyer's action time expiring
  - warehouse_decision: Closed after warehouse product review
  - warehouse_timeout: Closed due to delay in warehouse product review
  - worked_out_with_seller: Buyer solved the issue directly with the seller outside ML
  - low_cost: Closed because shipping cost is higher than product value
  - item_changed: Closed because the exchange was handled internally
  - change_expired: Exchange was not made and the permitted time has passed
  - change_cancelled_buyer: Exchange closed by the buyer
  - change_cancelled_seller: Proactive exchange closure by the seller
  - change_cancelled_meli: Exchange closed by Meli
  - shipment_not_stopped: Closed because the shipment could not be stopped
  - cancel_installation: Cancellation of installation service
- created: Claim resolution/closure date
- benefited: Beneficiaries of the resolution
  - respondent
- closed_by: Actor who closed the claim
  - mediator
  - buyer
  - respondent
  - false
- applied_coverage: Payment to the buyer
- site_id: Site ID where the claim was opened
- date_created: Claim creation/opening date
- last_updated: Date of the last claim update

Failed Return Review

When a return arrives to the seller, they have the possibility to review it, indicating whether the product arrived in the expected condition or if there is any issue with it.

To check if the seller already has the option to perform a failed review enabled, you can query the /claims/$CLAIM_ID resource. Within the "players" array, look for the player with "type": "seller" and verify if their "available_actions" contains "action": "return_review_fail".

To perform a failed return review, indicating that the product arrived with an issue, you need to use three resources described below:

Get reasons to create a failed return review

To create a failed review, you must know the reason why the seller identifies that the product did not arrive in the expected condition.

The list of possible reasons the seller can select is obtained as follows:

Request:

curl --location 'https://api.mercadolibre.com/post-purchase/v1/returns/reasons?flow=$FLOW&claim_id=$CLAIM_ID' \
    --header 'Authorization: Bearer $ACCESS_TOKEN'

Example:

curl --location 'https://api.mercadolibre.com/post-purchase/v1/returns/reasons?flow=seller_return_failed&claim_id=55555' \
    --header 'Authorization: Bearer $ACCESS_TOKEN'

You must provide:

flow: Indicates for which flow you want to obtain the reasons (for now, only the value seller_return_failed is valid)
claim_id: Unique identifier of the claim.

Response:

[
    {
        "id": "SRF2",
        "name": "product_damaged",
        "detail": "The product arrived damaged",
        "position": 1,
        "apply": [
            "order"
        ]
    },
    {
        "id": "SRF3",
        "name": "return_incomplete",
        "detail": "The return is incomplete",
        "position": 2,
        "apply": [
            "order"
        ]
    },
    {
        "id": "SRF4",
        "name": "returned_product_different",
        "detail": "A different product was returned than the one I sent",
        "position": 3,
        "apply": [
            "order"
        ]
    },
    {
        "id": "SRF5",
        "name": "product_not_in_package",
        "detail": "The product is not in the package",
        "position": 4,
        "apply": [
            "order",
         "package"
        ]
    },
    {
        "id": "SRF6",
        "name": "another_failure_with_product",
        "detail": "Report another issue with the product",
        "position": 5,
        "apply": [
            "order"
        ]
    },
    {
        "id": "SRF7",
        "name": "return_has_not_arrived",
        "detail": "It has not arrived yet",
        "position": 6,
        "apply": [
         "package"
        ]
    }
 ]

Errors:

Nonexistent claim:

{
   "code": 404,
   "error": "not_found_error",
   "message": "claim_Not Found",
   "cause": null
 }

Invalid flow:

{
   "code": 400,
   "error": "bad_request_error",
   "message": "flow: invalid_flow does not exist. claimId: 5358155244",
   "cause": null
 }

Currently, only the seller_return_failed flow is valid. Any other value will return this error.

Response Fields

A successful GET request to the /returns/reasons/return-fail resource will return a status code 200 and the following fields:

id: Reason identifier. This is the value you must send when creating a failed review.
name: Reason code
detail: Reason for the failed return, to give context to the seller when selecting the reason
- return_product
position: Recommended position of the reason when displaying all reasons to the seller
apply: Indicates for what the reason can be used. This is because now it’s possible to perform reviews for cart returns (which include multiple orders), so some reasons apply only to the entire package, others to individual orders, and others can be used for both cases. The possible values for this field in cart cases are: package and order, and for non-cart cases, only order.

Get the evidence file name to attach to a failed return review

When creating a failed review, it is also possible to send evidence in order to provide more information for the case. Therefore, you can use the /claims/$CLAIM_ID/returns/attachments resource to upload files.

As a result, you will obtain the file name to be sent as evidence in the review.

This resource should be used for each piece of evidence you want to attach to a failed review.

Request:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' 
    https://api.mercadolibre.com/post-purchase/v1/claims/$CLAIM_ID/returns/attachments
    -F 'file=@"/Users/usuer/Downloads/file.png'

Example:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/post-purchase/v1/claims/5255026166/returns/attachments
    -F 'file=@"/Users/usuer/Downloads/file.png'

Response:

{
    "user_id": 1277895049,
    "file_name": "1117895119_9d6zaaz8-a1c7-4f1f-a68b-fz0z0135gd6.png"
}

Errors:

Nonexistent claim

{
    "code": 404,
    "error": "not_found_error",
    "message": "Claim not found. claimId: 5255026166",
    "cause": null
 }

Body error (for example, no image was sent)

{
    "code": "bad_request",
    "message": "Error retrieving uploaded file. claim_id: 5356116886. caller_id: 1985874106"
}

Invalid key

{
    "code": "not_found",
    "message": "Request error: [{\"status\":404,\"error\":\"not_found\",\"message\":\"Can not get attachment\"}]"
}

Response Fields

A successful GET request to the /claims/$CLAIM_ID/returns/attachments resource will return a status code 200 and the following fields:

user_id: user identifier
file_name: file name that can be used when creating a failed review

Create a Failed Return Review

To create a failed return review, indicating that the product arrived with an issue, the /claims/$CLAIM_ID/actions/return-review-fail resource has been enabled.

Parameters

params	Type	Value detail
claim_id	Integer	Unique identifier of the claim for which you want to submit the failed return review (required)
reason	String	Unique identifier of the reason why the seller indicates that the product did not arrive as expected (required). Possible values for this field are obtained from the returns/reasons resource
message	String	Message entered by the seller indicating the reason for the failed review (required)
attachments	Array[String]	Names of the evidences to be attached in the review. The values for this field are obtained from the returns/attachments resource (required for reason_id SRF2 and SRF4)
order_id	Integer	Unique identifier of the order. This value should only be used for cart cases where you want to perform the review for a specific order. For reviews of non-cart cases or for the complete cart, this parameter should not be sent.

Request:

curl --location 'https://api.mercadolibre.com/post-purchase/v1/claims/$CLAIM_ID/actions/return-review-fail' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--data '[
  {
    "reason" : $REASON_ID,
    "message": $MESSAGE,
    "attachments": [$ATTACHMENTS],
    "order_id": $ORDER_ID
  }
]'

The endpoint for creating failed return reviews now accepts a list of reviews. This is because it is now possible to perform reviews for carts. Let’s see an example of usage. If you have a case with 5 products and want to return only 2, you should specify for each of these 2 the reason, the message, images if necessary, and the order_id.

Example:

curl --location 'https://api.mercadolibre.com/post-purchase/v1/claims/555555555/actions/return-review-fail' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--data '[
  {
    "reason" : "SRF2",
    "message": "Hello",
    "attachments": ["1117895119_9d6zaaz8-a1c7-4f1f-a68b-fz0z0135gd6.png"],
    "order_id":2000011248679992
  },
  {
    "reason" : "SRF4",
    "message": "Hello",
    "attachments": ["1117895119_9d6zaaz8-a1c7-4f1f-a68b-fz0z0135gd6.png"],
    "order_id":2000011248679992
  }
]'

You should take into account that there are reasons that apply to the entire package, so you must not send order_id and should submit only one review. For example, if you have 5 products and none have arrived yet, then the reason would be SRF7, which as we saw in our GET for reasons, applies to the whole package. In this case, you should use the endpoint as follows:

curl --location 'https://api.mercadolibre.com/post-purchase/v1/claims/555555555/actions/return-review-fail' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--data '[
  {
    "reason" : "SRF7",
    "message": "Not delivered",
    "attachments": ["1117895119_9d6zaaz8-a1c7-4f1f-a68b-fz0z0135gd6.png"]
  }
]'

Finally, for cases that do not involve a cart, you should send only one review without the order_id:

curl --location 'https://api.mercadolibre.com/post-purchase/v1/claims/555555555/actions/return-review-fail' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--data '[
  {
    "reason" : "SRF7",
    "message": "Not delivered",
    "attachments": ["1117895119_9d6zaaz8-a1c7-4f1f-a68b-fz0z0135gd6.png"]
  }
]'

Response:

{
    "id": 5255026166,
    "resource_id": 2000007760636316,
    "status": "closed",
    "type": "mediations",
    "stage": "claim",
    "parent_id": null,
    "resource": "order",
    "reason_id": "PDD9949",
    "fulfilled": true,
    "quantity_type": "total",
    "players": [
        {
            "role": "complainant",
            "type": "buyer",
            "user_id": 1277895049,
            "available_actions": []
        },
        {
            "role": "respondent",
            "type": "seller",
            "user_id": 1582937623,
            "available_actions": [
                {
                    "action": "return_review_fail",
                    "mandatory": false,
                    "due_date": null
                },
                {
                    "action": "return_review_ok",
                    "mandatory": true,
                    "due_date": "2024-06-03T22:43:00.000-04:00"
                }
            ]
        },
        {
            "role": "mediator",
            "type": "internal",
            "user_id": 46122402,
            "available_actions": []
        }
    ],
    "resolution": {
        "reason": "item_returned",
        "date_created": "",
        "benefited": [
            "complainant"
        ],
        "closed_by": "mediator",
        "applied_coverage": true
    },
    "site_id": "MLA",
    "date_created": "2024-05-29T23:48:32.000-04:00",
    "last_updated": "2024-05-29T23:51:26.370-04:00"
 }

Response Fields

A successful POST request to the /claims/$CLAIM_ID/actions/return-review-fail resource will return status code 201 and the following fields:

Response parameters:

id: Claim ID.
resource_id: ID of the resource on which the claim was created. Depends on the “resource”.
status: Claim status. Can have two values: opened and closed.
type: Type of claim. Can take one of the following values:
- mediations: Claim between buyer and seller.
- return: Product return. In this case, there are no messages. To work with returns, follow the Returns documentation.
- fulfillment: Claim between buyer and Mercado Libre in purchases with Full shipping.
- ml_case: Purchase cancellation by the buyer due to shipping delay.
- cancel_sale: Purchase cancellation by the seller.
- cancel_purchase: Purchase cancellation by the buyer.
- change: Product exchange. Indicates that an exchange will be made.
- service: Cancellation of a service orders bundle.
stage: Stage of the claim. Can take the following values:
- claim: Stage where buyer and seller interact.
- dispute: Mediation stage with a Mercado Libre representative.
- recontact: Stage where one of the parties contacts after the dispute is closed.
- none: Not applicable.
- stale: Stage where buyer and Mercado Libre interact for claims of type ml_case.
claim_version: Version of the claim. Example: 1.0, 1.5, 2.0.
claimed_quantity: Number of items associated with the claim.
parent_id: ID of the claim on which this one depends.
resource: Identifier of the resource the claim refers to. Can be:
- payment
- order
- shipment
- purchase
reason_id: Reason for the claim. Directly influences the possible solutions:
- PNR: Product Not Received
- PDD: Product Different or Defective
- CS: Purchase Canceled
fulfilled: Indicates if the product was delivered. Possible values: true | false.
quantity_type: Indicates if the claim is partial or total.
- partial: Partial claim
- total: Total claim
players: List of actors involved in the claim:
- role:
  - complainant: person making the claim.
  - respondent: person the claim is against.
  - mediator: person who intervenes to solve the problem.
  - purchase: buyer - Mercado Libre.
- type: depends on the resource (payment, order, shipment).
- user_id: User ID.
- available_actions:
  - action: possible action
  - mandatory: true if mandatory
  - due_date: due date
resolution: Way the claim was resolved.
- reason:
  - already_shipped: Product in transit
  - buyer_claim_opened: Return closed due to a new claim
  - buyer_dispute_opened: Return closed due to a new dispute with Mercado Libre mediation
  - charged_back: Closed due to chargeback
  - coverage_decision: Dispute closed with ML coverage
  - found_missing_parts: Buyer found missing parts
  - item_returned: Product returned
  - no_bpp: Closed without ML coverage
  - not_delivered: Product not delivered
  - opened_claim_by_mistake: Claim opened by mistake
  - partial_refunded: Partial refund granted
  - payment_refunded: Payment refunded
  - preferred_to_keep_product: Buyer preferred to keep the product
  - product_delivered: Decision by Mercado Libre representative
  - reimbursed: Refunded
  - rep_resolution: Decision by Mercado Libre representative
  - respondent_timeout: Seller did not respond
  - return_canceled: Return canceled by the buyer
  - return_expired: Return expired without status update
  - seller_asked_to_close_claim: Seller asked to close the claim
  - seller_did_not_help: Buyer solved the problem without seller's help
  - seller_explained_functions: Seller explained the item's functionality
  - seller_sent_product: Seller sent the product
  - timeout: Claim closed due to buyer inactivity
  - warehouse_decision: Closed due to delay in warehouse analysis
  - warehouse_timeout: Closed due to warehouse analysis time expiration
  - worked_out_with_seller: Solved directly with the seller
  - low_cost: Shipping cost higher than product value
  - item_changed: Exchange completed successfully
  - change_expired: Exchange not completed within the deadline
  - change_cancelled_buyer: Exchange proactively canceled by the buyer
  - change_cancelled_seller: Exchange proactively canceled by the seller
  - change_cancelled_meli: Exchange canceled by Mercado Libre
  - shipment_not_stopped: Shipment was not stopped
  - cancel_installation: Installation service cancellation
data_created: Date of claim resolution/closure.
benefited: Claim beneficiary (complainant | respondent).
closed_by: Party who closed the claim (mediator | buyer).
applied_coverage: Claim with coverage (false | true).
site_id: Site ID where the claim was created.
created_date: Claim creation/opening date.
last_updated: Date of the last claim update.
related_entities: List of entities related to the claim.
return: Indicates whether the claim has a linked return.

Errors

Below are the possible error messages that the resource might generate:

If the claim does not belong to the seller:

{
   "code": 400,
   "error": "bad_request_error",
   "message": "Invalid roleId :12343234 in claim :123454323",
   "cause": null
}

If the claim does not exist

{
   "code": 404,
   "error": "not_found_error",
   "message": "claim id: 5255026166 not found",
   "cause": null
}

If the token is not sent:

{
   "code": 401,
   "error": "unauthorized_request_error",
   "message": "Invalid caller.id",
   "cause": null
}

If the token has expired or is invalid:

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

If the token is incorrect:

{
   "message": "{\"message\":\"Malformed access_token: toke n\",\"error\":\"bad_request\",\"status\":400,\"cause\":[]}",
   "error": "",
   "status": 400,
   "cause": []
}

If the seller is not enabled to review a return.

{
   "code": 400,
   "error": "bad_request_error",
   "message": "Not valid action return_review_ok for player role respondent",
   "cause": null
}

If the format of the file to be attached is not valid:

{
   "code": 400,
   "error": "bad_request_error",
   "message": "Invalid mime_type",
   "cause": null
}

If the file name is not valid:

{
   "code": 400,
   "error": "bad_request_error",
   "message": "Invalid file_name: ",
   "cause": null
}

If the "file" field is not sent:

{
   "code": 400,
   "error": "bad_request_error",
   "message": "Current request is not a multipart request",
   "cause": null
}

If one of the required fields is missing

{
   "code": 400,
   "error": "bad_request_error",
   "message": "Required request body is missing or incorrect, please see the documentation.",
   "cause": null
}