What is a claim?

A claim is a formal request that users can submit to express dissatisfaction or issues related to a specific process. These claims are essential for resolving problems, ensuring a positive user experience, and maintaining the integrity of the service. Only four types of resources can generate claims, each associated with a different aspect of the transaction on the platform. The possible resources are detailed below:

• Order This type of claim is generated from a purchase order made on the Mercado Libre platform. Users can file a claim if they experience issues with the order, such as discrepancies in the received product, errors in quantity, or any other inconvenience related to the order. This ensures that users can communicate any dissatisfaction and receive an appropriate solution, thereby maintaining trust and service integrity.
• Shipment (Shipment claims originate from the shipping process of a purchase on the Mercado Libre platform. Users can file a claim if they encounter problems with the delivery of the product, such as delays, products damaged during shipping, or logistical issues. These claims allow for quick resolution of incidents, improving the customer experience.
• Payment This type of claim is created in relation to a payment made through the Mercado Libre platform. Users can file a claim for payments related to purchases on the platform or any other type of transaction made through the Mercado Libre payment system. Issues that may prompt these claims include incorrect charges, payment processing failures, or disputes related to the transaction. This mechanism not only allows users to quickly resolve their issues but also helps the platform identify and correct potential failures in its payment system, enhancing reliability and customer satisfaction.
• Purchase Purchase claims arise from a purchase made on the Mercado Libre platform. These claims focus on the purchase transaction and address issues such as defective products, discrepancies between the product description and what was received, among other inconveniences. Allowing users to file these claims improves transparency and facilitates a quick resolution, which not only reinforces customer trust in the platform but also helps identify and resolve flaws in the purchase process.

Claims notifications

In the 'My Applications' section, edit your application and enable the 'Marketplace Claims' topic in our feed. This will allow you to receive immediate notifications whenever a claim is initiated or any related interaction occurs. Stay informed and up to date with all important claim updates.

Consult an specific claim

To consult the information of a specific claim, including its actual status, it’s necessary to consult the /claims/$CLAIM_ID resource.

Call:

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

Example:

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

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_mediator",
                   "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-09T19:00:12.000-04:00",
   "related_entities": [
       "return"
   ]
}

Response fields

The response to a GET request on the /claims/search resource will provide the following parameters:

• id: Claim id
• resource_id: ID of the resource on which the claim is created. It depends on the "resource".
• status: Status of the claim. It can take two values: opened and closed.
• type: Type of claim. It can take one of the following values:
  • meditations: Claim between buyer and seller.
  • 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.
  • cancel_purchase: Purchase cancellation by the buyer.
  • change: Product exchange. Indicates that a product exchange will take place.
  • service: Service cancellation for bundled orders.
• stage: Stage of the claim. It can take one of the following values:
  • claim: Stage where the buyer and seller are involved
  • dispute: Mediation stage involving a Mercado Libre representative.
  • recontact: Stage where one of the parties contacts after the claim/dispute is closed.
  • none: Not applicable.
  • stale: Claim stage involving the buyer and Mercado Libre for claims of type ml_case.
• parent_id: ID of another claim on which this claim depends.
• resource: Identifier of the resource on which the claim is created. It can be:
  • payment
  • order
  • shipment
  • purchase
• reason_id: Reason for which the claim was created. It directly influences the proposed solutions.
  • PNR: Product Not Received
  • PDD: Wrong or Defective Product
  • CS: Canceled Purchase
• fulfilled: Indicates whether the claim was initiated for a delivered product. It can take two values: false | true.
• quantity_type: Indicates whether the claim is a partial claim or not.
  • partial: Indicates that it is a partial claim.
  • total: Indicates that it is a complete claim.
• players: List of actors involved in the claim with their respective actions and available times.
  • role: Role within the claim. It can be:
    • complainant: The person who makes the claim.
    • respondent: The person against whom the claim is made.
    • mediator: The person who intervenes to help resolve the issue.
    • purchase: Buyer - Mercado Libre.
  • type: The role the person plays in the operation being claimed. It varies according to the resource.
    • Payment: Buyer or collector.
    • Order: Buyer or seller.
    • Shipment: Receiver or sender.
  • user_id: ID of the user in MercadoLibre who fulfills the role.
  • available_actions: List of actions that each of the intervening parties can take:
    • action: Possible actions that can be taken. For the seller, they are:
      • 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, such as a message.
      • refund: Refund the buyer's money.
      • open_dispute:Initiate a mediation.
      • send_potential_shipping: Send a shipping promise, a date.
      • add_shipping_evidence: Post evidence that the product was shipped.
      • send_attachments: Send a message with attachments.
      • allow_return: Generate a return label.
      • allow_return_label: Generate a return label.
      • allow_partial_refund : Partially refund the buyer's money for claims of the type PDD.
      • send_tracking_number: Send the tracking number.
      • return_review_fail: Perform a failed review of a return. (tracking number).
      • return_review_ok: Perform a successful review of a return.
    • mandatory: A true type field where the action is mandatory and must be completed before the deadline.
    • due_date: Deadline to perform the action.
• resolution: Resolution form of the claim.
  • reason: Resolution form of the claim.
    • 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 (with Mercado Libre mediation).
    • 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_bpp: Closure without coverage by Mercado Libre.
    • not_delivered: Product not delivered.
    • opened_claim_by_mistake: Buyer created the claim by mistake.
    • partial_refunded: Partial refund granted to the buyer.
    • payment_refunded: Payment refunded to the buyer.
    • prefered_to_keep_product: Buyer preferred to keep the product.
    • product_delivered: Decision made by a Mercado Libre representative.
    • reimbursed: Refund issued.
    • rep_resolution: Decision made by a Mercado Libre representative.
    • respondent_timeout: Seller did not respond.
    • return_canceled: Return canceled by the buyer.
    • return_expired: Return expired without a change in shipping status.
    • seller_asked_to_close_claim: Seller asked the buyer to close the claim.
    • seller_did_not_help: Buyer was able to resolve the issue without the seller's help.
    • seller_explained_functions: Seller explained how the item works.
    • seller_sent_product: Seller shipped the product.
    • timeout: Closure due to buyer action timeout.
    • warehouse_decision: Closure due to delay in product review at Warehouse.
    • warehouse_timeout: Closure due to delay in product review at Warehouse.
    • worked_out_with_seller: Buyer resolved it with the seller outside of Mercado Libre.
    • low_cost: Closure because the shipping cost is higher than the product cost.
    • item_changed: Closure because the exchange was successfully completed.
    • change_expired: The exchange was not completed, and the allowed time expired.
    • change_cancelled_buyer: Proactive closure of an exchange by the buyer.
    • change_cancelled_seller: Proactive closure of an exchange by the seller.
    • change_cancelled_meli: Closure of an exchange by Mercado Libre.
    • shipment_not_stopped: Closure because the shipment could not be stopped.
    • cancel_installation: Cancellation of installation service.
  • data_created: Date of claim resolution/closure.
  • benefited: Beneficiaries of the resolution (complainant**|respondent|**).
  • closed_by: Actor who closed the claim (mediator | buyer).
  • applied_coverage: Indicates whether the claim is covered (false | true).
  • site_id: ID of the site where the claim is being processed.
  • created_date: Date of claim creation/opening.
  • last_updated: Date of the last update on the claim.
  • related_entities: Contains a list of entities related to the claim. If there are no returns, the IDs will have a value of vda.

Claims details

To understand the reason for the claim and details on how to act in response to it, use the claims/detail resource. This resource will bring the actual status only.

Call:

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

Example:

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

Response:

{
   "due_date": "2024-09-11T22:39:00.000-04:00",
   "action_responsible": "mediator",
   "title": "Return in mediation awaiting a response from Mercado Libre",
   "description": "We will get in touch with you before Thursday, September 12.",
   "problem": "You told us the product returned is different from the one dispatched"
}

Response fields:

The response to a GET request on the /claims/detail resource will provide the following parameters:

• due_date:Deadline to resolve the claim.
• action_responsible: Party responsible for the action. It can take one of the following values: seller | buyer | mediator.
• title: Title detailing the status of the claim.
• description: Detailed description of the current status of the claim.
• problem: Problem that prompted the claim.

Customize claim search

The claim search provides you with a comprehensive view of all claims associated with a specific seller. This tool is essential for efficiently monitoring and managing reported incidents.

Parameters:

A claim can be retrieved by performing a search in the claims system using various parameters. The available search parameters are as follows:

Call:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/marketplace/v2/claims/search?status=opened&user_id=$USER_ID

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/marketplace/v2/claims/search?status=opened&user_id=1317418851

Response:

{
 {
   "paging": {
       "total": 4,
       "offset": 0,
       "limit": 30
   },
   "data": [
       {
           "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_mediator",
                           "mandatory": false,
                           "due_date": null
                       }
                   ]
               }
           ],
           "resolution": null,
           "site_id": "MLM",
           "date_created": "2024-09-09T18:18:38.000-04:00",
           "last_updated": "2024-09-09T19:00:12.000-04:00"
       },
       {
           "id": 5294651094,
           "resource_id": 2000009106789766,
           "status": "opened",
           "type": "mediations",
           "stage": "dispute",
           "parent_id": null,
           "resource": "order",
           "reason_id": "PDD9942",
           "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_mediator",
                           "mandatory": false,
                           "due_date": null
                       }
                   ]
               }
           ],
           "resolution": null,
           "site_id": "MLM",
           "date_created": "2024-08-22T18:45:22.000-04:00",
           "last_updated": "2024-08-22T18:49:44.000-04:00"
       }
       ...
   ]
}

To continue improving claim search options, we provide additional parameters that can help enhance search efficiency.

Params:

Call:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/v2/claims/search?status=opened&stage=dispute&sort=last_updated:asc

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/v2/claims/search?status=opened&stage=dispute&sort=last_updated:asc&user_id=1317418851

Response:

{
   "paging": {
       "total": 4,
       "offset": 0,
       "limit": 30
   },
   "data": [
       {
           "id": 5294651094,
           "resource_id": 2000009106789766,
           "status": "opened",
           "type": "mediations",
           "stage": "dispute",
           "parent_id": null,
           "resource": "order",
           "reason_id": "PDD9942",
           "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_mediator",
                           "mandatory": false,
                           "due_date": null
                       }
                   ]
               }
           ],
           "resolution": null,
           "site_id": "MLM",
           "date_created": "2024-08-22T18:45:22.000-04:00",
           "last_updated": "2024-08-22T18:49:44.000-04:00"
       },
       {
           "id": 5294877244,
           "resource_id": 2000009106972774,
           "status": "opened",
           "type": "mediations",
           "stage": "dispute",
           "parent_id": null,
           "resource": "order",
           "reason_id": "PDD9953",
           "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_mediator",
                           "mandatory": false,
                           "due_date": null
                       }
                   ]
               }
           ],
           "resolution": null,
           "site_id": "MLM",
           "date_created": "2024-08-23T16:13:04.000-04:00",
           "last_updated": "2024-08-28T23:42:28.000-04:00"
       },
       {
           "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_mediator",
                           "mandatory": false,
                           "due_date": null
                       }
                   ]
               }
           ],
           "resolution": null,
           "site_id": "MLM",
           "date_created": "2024-09-09T18:18:38.000-04:00",
           "last_updated": "2024-09-09T19:00:12.000-04:00"
       },
       {
           "id": 5298020007,
           "resource_id": 2000009106924564,
           "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_mediator",
                           "mandatory": false,
                           "due_date": null
                       }
                   ]
               }
           ],
           "resolution": null,
           "site_id": "MLM",
           "date_created": "2024-09-05T19:05:09.000-04:00",
           "last_updated": "2024-09-10T23:42:18.000-04:00"
       }
   ]
}

Get details on the reason of the claim

To obtain details about the reason for initiating a claim, the /claims/reasons/$REASON_ID resource should be consulted. This access provides detailed information and allows the use of specific parameters for more effective searches.

Params:

Call:

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

Example:

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

Response:

{
   "id": "PNR9502",
   "flow": "mediations_undelivered",
   "name": "respondent_unanswered",
   "detail": "El vendedor no me respondió",
   "position": 200,
   "filter": {
       "group": null,
       "site_id": [
           "MLC",
           "MCO",
           "MLU",
           "MPE",
           "MLM",
           "MLA",
           "MLB",
           "CBT",
           "MEC",
           "MPA",
           "MBO",
           "MCR",
           "MGT",
           "MLV",
           "MNI",
           "MCU",
           "MHN",
           "MPY",
           "MRD",
           "MSV",
           "MPT"
       ]
   },
   "settings": {
       "allowed_flows": [],
       "expected_resolutions": [
           "refund",
           "product"
       ],
       "rules_engine_triage": []
   },
   "parent_id": null,
   "children_title": null,
   "status": "active",
   "date_created": "2022-08-02T20:12:53.522-04:00",
   "last_updated": "2024-10-02T23:02:32.31-04:00"
}

Response fields

The response to a GET request on the /claims/reasons/$REASON_ID resource will provide the following parameters:

• id: Claim ID
• flow: Claim Flow
• name: Name of the reason
• detail: Detail of the reason
• position: Functions as sort_by but by default. Without sort_by, the system sorts the reasons by ascending position.
• group: The group indicates the item's vertical. It can take one of the following values:
  • generic
  • fashion
  • installable_autoparts
  • expiring_food
  • expiring_health
• site_id: ID of the site where the claim is processed
• settings: Can take one of the following values:
  • allowed_flows: Indicates in which flows this reason can be viewed
  • expected_resolutions: Possible resolutions expected by the claimant
    • product
    • refund
    • other
  • rules_engine_triage: This item defines the tag for triage categorization, with values such as:
    • repentant
    • defective
    • incomplete
    • different
    • not_working
• parent_id: Parent reason.
• children_title: This value is used for post-purchase typing, assigning the title to child reasons of those containing this attribute. Only reasons have this attribute.
• status: Status of the reason.
• date_created: Date the reason was created.
• last_updated: Date of the last update to the reason.

Claim action history.

The action history of a claim details the actions taken, who executed them, and when, allowing a precise and strategic tracking of the process.

Call:

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

Example:

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

Response:

[
   {
       "action_name": "close_claim",
       "player_role": "mediator",
       "action_reason_id": null,
       "claim_stage": "claim",
       "claim_status": "opened",
       "date_created": "2024-08-21T19:11:46.000-04:00"
   },
   {
       "action_name": "refund",
       "player_role": "respondent",
       "action_reason_id": null,
       "claim_stage": "claim",
       "claim_status": "opened",
       "date_created": "2024-08-21T19:11:45.000-04:00"
   },
   {
       "action_name": "send_message_to_respondent",
       "player_role": "complainant",
       "action_reason_id": null,
       "claim_stage": "claim",
       "claim_status": "opened",
       "date_created": "2024-08-21T18:41:19.000-04:00"
   },
   {
       "action_name": "open_claim",
       "player_role": "complainant",
       "action_reason_id": null,
       "claim_stage": null,
       "claim_status": null,
       "date_created": "2024-08-21T13:47:31.000-04:00"
   }
]

Response fields:

The response to a GET request on the /claims/actions-history resource will provide the following parameters:

• action_name: Name of the action performed.
• player_role: Player who performed the action.
• action_reason_id: ID of the action performed.
• claim_stage: Stage in which the action was performed.
• claim_status: Status of the stage in which the action was performed.
• date_created: Date the action was performed.

Claim status history

The claim status history provides information about the stage and status of the claim at the time of each action, enabling precise and strategic tracking of the process.

Call:

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

Example:

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

Response:

[
   {
       "stage": "claim",
       "status": "closed",
       "date": "2024-08-21T19:11:46.000-04:00",
       "change_by": "mediator"
   },
   {
       "stage": "claim",
       "status": "opened",
       "date": "2024-08-21T13:47:31.000-04:00",
       "change_by": "complainant"
   }
]

How to identify if a claim affects reputation

The /affects-reputation resource provides integrators with the ability to determine whether a specific complaint impacts the seller's reputation by executing the corresponding call

Call:

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

Example:

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

Response:

{
    "affects_reputation": "not_affected",
    "has_incentive": false,
    "due_date": null
}

Response fields

The GET response to the /claims/affects-reputation resource will provide the following parameters:

• affects_reputation: Inform if the complaint affects the seller's reputation. It can take any of the following values:
  • affected: Affects reputation.
  • not_affected: Does not affect reputation.
  • not_applies: Payments not linked to marketplace or Shops orders.
• has_incentive: When this field returns true, if the seller responds satisfactorily within the first 48 hours, it will not affect their reputation. If false, the seller still has the same 48 hours, but we do not guarantee that the seller's reputation will not be affected
• due_date: Deadline to resolve the claim

Netx: Manage claim messages