Documentación Mercado Libre

Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.
circulos azuis em degrade

Documentación

Última actualización 11/11/2024

What is a return?

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:

  1. Monitor the claim notification: Listen to the feed Marketplace claims, which contain the order information where the claim originated.
  2. 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

To check a return, make a request to post-purchase/v2/claims/$CLAIM_ID/returns, specifying the $CLAIM_ID. This will provide detailed information on the return associated with the corresponding claim.

Call:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/post-purchase/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:
      • null: when no reason is specified. This field is always null unless the status is ‘claimed’.
      • SRF2: The product arrived damaged.
      • SRF3: The return is incomplete.
      • SRF4: A different product was returned than what was sent.
      • SRF5: The product is not in the package.
      • SRF6: Report another product issue.
      • SRF7: The product has not yet been received.
Note:
Remember that the resource /shipments/$SHIPMENT_ID/costs returns the shipping costs the user will need to bear.

Return OK Review

When a return reaches the seller, they have the option to review the product, indicating whether it arrived in the expected condition or if there is a problem with it.

To perform an OK review of a return, confirming that the product arrived in the expected condition, the resource /claims/$CLAIM_ID/actions/return-review-ok is available.

To check if the seller has the option to perform an OK review of a return, you can use the resource /claims/$CLAIM_ID. Within the "players" array, look for the player "type": "seller" and verify in their "available_actions" that there is an "action": "return_review_ok".

Call:

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

Example:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -d 
https://api.mercadolibre.com/marketplace/v2/claims/5298893830/actions/return-review-ok

Response:

{
   "id": 5298893830,
   "resource_id": 2000009255685274,
   "status": "closed",
   "type": "mediations",
   "stage": "claim",
   "parent_id": null,
   "resource": "order",
   "reason_id": "PDD9939",
   "fulfilled": true,
   "quantity_type": "total",
   "players": [
       {
           "role": "complainant",
           "type": "buyer",
           "user_id": 1517482146,
           "available_actions": []
       },
       {
           "role": "respondent",
           "type": "seller",
           "user_id": 1317418851,
           "available_actions": [
               {
                   "action": "send_message_to_complainant",
                   "mandatory": false,
                   "due_date": null
               },
               {
                   "action": "open_dispute",
                   "mandatory": false,
                   "due_date": null
               },
               {
                   "action": "return_review_fail",
                   "mandatory": false,
                   "due_date": null
               },
               {
                   "action": "return_review_ok",
                   "mandatory": false,
                   "due_date": null
               },
               {
                   "action": "refund",
                   "mandatory": false,
                   "due_date": null
               }
           ]
       },
       {
           "role": "mediator",
           "type": "internal",
           "user_id": 46622406,
           "available_actions": []
       }
   ],
   "resolution": null,
   "site_id": "MLM",
   "date_created": "2024-09-09T17:47:08.000-04:00",
   "last_updated": "2024-09-09T18:35:12.306-04:00"
}

Response-fields:

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

  • id: Claim ID
  • resource: ID of the resource on which the claim was created, depending 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 originating from a purchase with full shipping.
    • ml_case: Purchase cancellation by the buyer due to delayed shipping.
    • cancel_sale: Purchase cancellation by the seller. Always with status: "closed" and stage: "none". The complainant role will always be the type seller, collector, or sender depending on the claim’s resource.
    • cancel_purchase: Purchase cancellation by the buyer.
    • change: Product exchange.
    • service: Service cancellation for bundled orders.
  • stage: Claim stage.
    • claim: Claim stage where the buyer and seller are involved.
    • dispute: Mediation stage where a Mercado Libre representative is involved.
    • recontact: Stage where one of the parties contacts after the claim/dispute has been closed.
    • none: Not applicable.
    • stale: Claim stage where the buyer and Mercado Libre are involved, for claims of type ml_case.
  • parent_id: ID of another claim it depends on.
  • resource: Identifier of the resource on which the claim was created. This affects the claim’s actors.
    • payment: Payment
    • order: Order
    • shipment: Shipment
    • purchase: Purchase
  • reason_id: Reason for which the claim was created. This directly affects the proposed solutions.
    • PNR: Product Not Received.
    • PDD: Product Different or Defective.
    • CS: Purchase Canceled.
  • fulfilled: Indicates whether the claim is for a delivered product.
  • quantity_type: Indicates if the claim is a partial claim.
    • partial: Indicates a partial claim.
    • total: Indicates a total claim.
  • players: List of actors involved in the claim, with their respective actions and available times.
    • role: Role within the claim.
      • complainant: Person making the claim.
      • respondent: Person the claim is made against.
      • mediator: Person who intervenes to help resolve the issue.
      • warehouse_dispatcher: Person responsible for reviewing the product in returns to the warehouse.
    • type: Role the person plays in the operation being claimed.
      • payment: Buyer - Collector.
      • order: Buyer - Seller.
      • shipment: Receiver - Sender.
      • purchase: Buyer - Mercado Libre.
    • user_id: User ID in Mercado Libre playing the role.
    • available_actions: List of actions each participant can take.
      • players: List of actors involved in the claim with their actions and available times.
        • action: Action name.
          • send_message_to_complainant: Send a message to the buyer (with or without attachments).
          • send_message_to_mediator: Send a message to the mediator (with or without attachments).
          • recontact (no disponible aún): Reopen a closed claim via an interaction, such as a message.
          • refund: Refund the buyer’s money. This must be done through Mercado Libre or Mercado Pago’s front end.
          • open_dispute: Start a mediation.
          • send_potential_shipping: Send a post promise, a date.
          • add_shipping_evidence: Submit evidence that the product was shipped.
          • send_attachments: Send a message with attachments.
          • allow_return_label: Generate a return label.
          • allow_partial_refund: Offer the buyer a partial refund. This must be done through Mercado Libre’s front end.
          • send_tracking_number: Send the return shipment tracking number.
          • return_review_fail: Conduct a failed return review.
          • return_review_ok: Conduct an OK return review.
          • mandatory: Type of action (true | false).
            • respondent: Person the claim is made against.
            • warehouse_dispatcher: person in charge of reviewing the product during returns to the warehouse.
  • resolution: List of actors involved in the claim with their actions and available times.
    • reason: Reason for resolution/closure.
      • already_shipped: Product in transit.
      • buyer_claim_opened: Return closure due to the opening of another claim.
      • buyer_dispute_opened: Return closure due to the opening of another claim in dispute (mediated by Mercado Libre).
      • charged_back: Closure due to chargeback.
      • coverage_decision: Dispute closed with coverage by Mercado Libre.
      • found_missing_parts: Buyer found the missing parts.
      • item_returned: Product returned.
      • no_bg: Closure without Mercado Libre coverage.
      • not_delivered: Product not delivered.
      • opened_claim_by_mistake: Buyer opened the claim by mistake.
      • other: Other case
      • partial_refunded: Partial refund given to the buyer.
      • payment_refunded: Payment refunded to the buyer.
      • preferred_to_keep_product: Buyer preferred to keep the product.
      • product_delivered: Verdict by a Mercado Libre representative.
      • reimbursed: Reimbursement.
      • rep_resolution: Verdict by a Mercado Libre representative.
      • respondent_timeout: Seller did not respond.
      • return_cancelled: Return canceled by the buyer.
      • return_expired: Return expired without a change in shipment status.
      • seller_asked_to_close_claim: Seller asked the buyer to close the claim.
      • seller_did_not_help: Buyer resolved the issue without seller’s help.
      • seller_explained_functions: Seller explained how the item works.
      • seller_sent_product: Seller sent the product.
      • timeout: Closure due to buyer’s action timeout.
      • warehouse_decision: Closure due to warehouse product review.
      • warehouse_timeout: Closure due to delay in warehouse product review.
      • worked_out_with_seller: Buyer resolved the issue with the seller outside of Mercado Libre.
      • low_cost: Closure because the shipping cost exceeds the product’s cost.
      • item_changed: Closure due to a successful product exchange.
      • change_expired: Exchange not completed within the allowed time.
      • change_cancelled_buyer: Proactive exchange cancellation by the buyer.
      • change_cancelled_seller: Proactive exchange cancellation by the seller.
      • change_cancelled_meli: Exchange cancellation by Mercado Libre.
      • shipment_not_stopped: Closure because the shipment could not be stopped.
      • cancel_installation: Installation service cancellation.
    • created: Date of claim resolution/closure.
    • benefited: Beneficiary/ies of the resolution.
      • respondent
    • closed_by: Actor who closed the claim.
      • mediator
      • buyer
      • respondent
      • false
    • applied_coverage: Buyer payment coverage.
    • site_id: Site ID where the claim took place.
    • date_created: Claim creation/opening date.
    • last_updated: Date of the last claim update.

Failed return review

When a return reaches the seller, they have the option to review it, indicating whether the product arrived in the expected condition or if there is a problem with it.

To check if the seller has the option to perform a failed review, we can query the resource /claims/$CLAIM_ID. Within the "players" array, we search for the player "type": "seller" and verify in their "available_actions" that there is an "action": "return_review_fail".

To perform a failed review of a return, indicating that the product arrived with an issue, three resources are used, which are described below:

Get Reasons to Create a Failed Review of a Return

To create a failed review, you will need to 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 from the resource /returns/reasons/return-fail.

Call:

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

Example:

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

Response:

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

Response fields:

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

  • id: Identifier of the reason. This value must be sent when creating a failed review.
  • name: Reason code.
  • detail: Reason for the failed return to provide context to the seller when choosing the reason.
  • position: Recommended position of the reason when showing all reasons to the seller.

Upload the Evidence to Attach in the Failed Review of a Return

As a result, you will get the file name that will be sent as evidence when creating the review. This resource must be used for each piece of evidence you wish to attach to a failed review.

Call:

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/5298903643/returns/attachments
-F 'file=@"/Users/usuer/Downloads/file.png'

Response:

{
   "user_id": 1317418851,
   "file_name": "5601f4a2-6701-4142-abaa-b111d7db22b0.jpeg"
}

Response fields:

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

  • user_id: User identifier.
  • file_name: Name of the file that can be used when creating a failed review.

Create a Failed Review

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

is available.

Parameters:

params Type Values Detalle value
claim_id Integer Unique identifier of the claim for which you want to indicate the failed review of its return (mandatory).
reson String Unique identifier of the reason why the seller indicates that the product did not arrive as expected (mandatory). The 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 (mandatory).
attachments Array[String] Names of the evidence to attach to the review.
The values for this field are obtained from the returns/attachments
resource (mandatory for reason_id SRF2 y SRF4)

Call:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' 
{
    "reason" : $REASON_ID,	
    "message": $MESSAGE,
    "attachments": [$ATTACHMENTS]
}
https://api.mercadolibre.com/marketplace/v2/claims/$CLAIM_ID/actions/return-review-fail

Example:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' 
{
   "reason" : "SRF4", 
   "message": "It wasn't the product sended",
   "attachments": ["5601f4a2-6701-4142-abaa-b111d7db22b0.jpeg"]
}
https://api.mercadolibre.com/marketplace/v2/claims/5298903643/actions/return-review-fail

Response:

{
   "id": 5298903643,
   "resource_id": 2000009256002260,
   "status": "opened",
   "type": "mediations",
   "stage": "dispute",
   "parent_id": null,
   "resource": "order",
   "reason_id": "PDD9939",
   "fulfilled": true,
   "quantity_type": "total",
   "players": [
       {
           "role": "complainant",
           "type": "buyer",
           "user_id": 1517482146,
           "available_actions": []
       },
       {
           "role": "respondent",
           "type": "seller",
           "user_id": 1317418851,
           "available_actions": [
               {
                   "action": "send_message_to_complainant",
                   "mandatory": false,
                   "due_date": null
               },
               {
                   "action": "open_dispute",
                   "mandatory": false,
                   "due_date": null
               },
               {
                   "action": "return_review_fail",
                   "mandatory": false,
                   "due_date": null
               },
               {
                   "action": "return_review_ok",
                   "mandatory": false,
                   "due_date": null
               },
               {
                   "action": "refund",
                   "mandatory": false,
                   "due_date": null
               }
           ]
       },
       {
           "role": "mediator",
           "type": "internal",
           "user_id": 46622406,
           "available_actions": []
       }
   ],
   "resolution": null,
   "site_id": "MLM",
   "date_created": "2024-09-09T18:18:38.000-04:00",
   "last_updated": "2024-09-09T18:59:39.799-04:00"
}

Response fields:

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

  • id: Claim ID
  • resource: ID of the resource the claim is created for. 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 for orders with full shipping.
    • ml_case: Purchase cancellation by the buyer due to delayed shipping.
    • 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 change.
    • service: Service cancellation for bundled orders.
  • stage: Claim stage.
    • claim: Stage where the buyer and seller are involved.
    • dispute: Mediation stage where a Mercado Libre representative is involved.
    • recontact: Stage where one party contacts after the claim/dispute is closed.
    • none: Not applicable.
    • stale: Stage where buyer and Mercado Libre are involved for ml_case-type claims.
  • parent_id: ID of another claim this one depends on.
  • resource: Resource identifier for which the claim is created. Affects the actors involved in the claim.
    • payment
    • order
    • shipment
    • purchase
  • reason_id: Reason for which the claim was created. Directly affects the possible solutions.
    • PNR: Product Not Received.
    • PDD: Product Different or Defective
    • CS: Canceled Purchase.
  • fulfilled: Indicates whether the claim is initiated for a delivered product or not
  • quantity_type: Indicates if the claim is partial or not.
    • partial: Indicates a partial claim.
    • total: Indicates a total claim.
  • players: List of actors involved in the claim with their respective available actions and time frames.
    • role: Role within the claim.
      • complainant: Person filing the claim.
      • respondent: Person to whom the claim is filed.
      • mediator: Person mediating to help solve the issue.
      • warehouse_dispatcher: Person responsible for inspecting the product in returns to the warehouse.
    • type: The role the person occupies in the operation being claimed.
      • payment: Buyer - Collector.
      • order: Buyer - Seller.
      • shipment: Receiver - Sender.
      • purchase: Buyer - Mercado Libre.
    • user_id: The user ID on Mercado Libre fulfilling the role.
    • available_actions: List of actions that each party can execute.
      • players: List of actors involved in the claim with their respective available actions and time frames.
        • action: Name of the action.
          • send_message_to_complainant: Send a message to the buyer (with or without attachments).
          • send_message_to_mediator: Send a message to the mediator (with or without attachments).
          • recontact (not yet available): Reopen an already closed claim through an interaction, like a message.
          • refund: Refund the buyer’s money. Must be done through Mercado Libre or Mercado Pago.
          • open_dispute: Start a mediation.
          • send_potential_shipping: Send a shipping promise, a date.
          • add_shipping_evidence: Submit evidence that the product was shipped.
          • send_attachments: Send a message with attachments.
          • allow_return_label: Generate a return label.
          • allow_partial_refund: Offer a partial refund to the buyer. Must be done via Mercado Libre's front-end.
          • send_tracking_number: Send the shipping tracking number.
          • mandatory: Type of action (true | false).
            • respondent: Person to whom the claim is made.
            • due_date: Deadline for performing the action.
  • resolution: List of actors involved in the claim with their respective available actions and time frames.
    • reason: Resolution/closure reason.
      • already_shipped: Product in transit.
      • buyer_claim_opened: Return closed due to another claim being opened.
      • buyer_dispute_opened: Return closed due to another claim in dispute (with Mercado Libre mediation).
      • charged_back: Closed due to chargeback.
      • coverage_decision: Dispute closed with coverage by Mercado Libre.
      • found_missing_parts: Buyer found missing parts.
      • item_returned: Product returned.
      • no_bg: Closed without coverage from Mercado Libre.
      • not_delivered: Product not delivered.
      • opened_claim_by_mistake: Buyer opened the claim by mistake.
      • other: Other case.
      • partial_refunded: Partial refund granted to the buyer.
      • payment_refunded: Payment refunded to the buyer.
      • preferred_to_keep_product: Buyer preferred to keep the product.
      • product_delivered: Judgment from a Mercado Libre representative.
      • reimbursed: Reimbursement.
      • rep_resolution: Judgment from a Mercado Libre representative.
      • respondent_timeout: Seller did not respond.
      • return_cancelled: Return canceled by the buyer.
      • return_expired: Return expired without status change in shipping.
      • seller_asked_to_close_claim: Seller asked the buyer to close the claim.
      • seller_did_not_help: Buyer solved the issue without seller’s help.
      • seller_explained_functions: Seller explained how the item worked.
      • seller_sent_product: Seller sent the product.
      • timeout: Closure due to action timeout by the buyer.
      • warehouse_decision: Closure due to product inspection at the warehouse.
      • warehouse_timeout: Closure due to delay in product inspection at the warehouse.
      • worked_out_with_seller: Buyer solved the issue with the seller outside of Mercado Libre.
      • low_cost: Closure because the shipping cost exceeds the product cost.
      • item_changed: Closure due to successful product exchange.
      • change_expired: The change was not completed within the allowed time.
      • change_cancelled_buyer: Buyer proactively canceled the change.
      • change_cancelled_seller: Seller proactively canceled the change.
      • change_cancelled_meli: Mercado Libre canceled the change.
      • shipment_not_stopped: Closure because the shipment could not be stopped.
      • cancel_installation: Cancellation of installation service.
    • created: Date of the claim resolution/closure.
    • benefited: Beneficiary(ies) of the resolution.
      • complainant
      • respondent
    • closed_by: Actor who closed the claim.
      • mediator
      • buyer
      • respondent
      • false
    • applied_coverage: Buyer compensation.
      • false
      • true
  • site_id: Site ID where the claim is developed.
  • date_created: Claim creation/opening date.
  • last_updated: Date of the last update on the claim.

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
}

go to: