Working with claims

The new resource /claims will help you get the claim details and start actions via API to settle them properly by adding this feature to your integration.

Contents

What actions can you start?

You can start the following actions:
  • See message details
  • Get all the messages of a claim
  • See, answer, and attach files to messages
  • Send messages without attachments
  • Request mediation
  • See participants' expected resolutions
  • Accept the player's resolution
  • Load a new resolution
  • Get claim evidence
  • Load shipping evidence
  • History of claim status and scenario
  • See the claim history of actions taken
  • Get the details of the reason why the claim was filed

Parameters description

The response to a resource /claims GET results in the following parameters:
  • id:Claim ID
  • type: Type of claim. It may take one of the following values: - mediations: claim between buyer and seller - cancel_purchase: purchase cancelled by buyer - return: product return
  • stage: Claim stage It may take one of the following values: - claim: claim stage involving both buyer and seller - dispute: mediation stage involving a representative of Mercado Libre - recontact: stage in which one of the parties contacts the other after the claim/dispute is settled
  • - none: not applicable
  • status: Claim status It may take two values: opened and closed
  • parent_id: ID of a parent claim
  • resource: Identifier of the resource on which the claim is created. It may be: - payment - order - shipment
  • resource_id: ID of the resource on which the claim is created, depending on the above parameter.
  • players: List of players involved in the claim with their relevant actions and available times. - role: role within the claim. It may be: complainant: person who starts the claim respondent: person the claim is filed against mediator: person who intervenes to help solve the problem - type: role filled by the person regarding the claimed transaction. It may be: buyer seller internal carrier - user_id: Type ID of the above parameter - available_actions: list of actions that the involved parties may take action: action that may be taken. It may be: send_message_to_complainant send_message_to_respondent send_message_to_mediator refund send_shipping_evidence open_dispute send_potential_shipping close_claim close_dispute load_resolution accept_resolution due_date: deadline to take action mandatory: when this field is true, it means a mandatory action to be taken within the indicated time
  • resolution: Form of claim resolution
  • labels: Claim labels, e.g., a label that shows whether the claim affects reputation or not
  • site_id: ID of the site on which the claim is conducted
  • date_created: Claim creation date
  • last_updated:Time when the claim was last updated
The response to a resource /claim message GET results in a list with the following parameters:
  • sender_role: player who sent the message
  • receiver_role: player who will receive the message
  • attachments: list of message attachments - filename: named hashed attached file - original_filename: actual name of the attachment - size: file size in Bytes - type: file type - date_created: date when the attachment was uploaded
  • stage: Stage in which the message was sent
  • date_created: Date when the message was sent
  • date_read: This value will be null until a new resource version is available
  • message: message text

Using resources - Step by step

SEE MESSAGE DETAILS Call
curl -X GET “https://api.mercadolibre.com/v1/claims/{claim_id}?access_token=$ACCESS_TOKEN”
Example
curl -X GET “https://api.mercadolibre.com/v1/claims/950700111?access_token=$ACCESS_TOKEN”
Response
{
    "id": 950700111,
    "type": "mediations",
    "stage": "claim",
    "status": "closed",
    "parent_id": null,
    "client_id": null,
    "resource_id": 1656223086,
    "resource": "order",
    "reason_id": "PDD-0",
    "players": [
        {
            "role": "complainant",
            "type": "buyer",
            "user_id": 271942703,
            "available_actions": [
                {
                    "action": "recontact",
                    "due_date": "2018-04-07T10:35:29.000-0400",
                    "mandatory": false
                }
            ]
        },
        {
            "role": "respondent",
            "type": "seller",
            "user_id": 271959653,
            "available_actions": [
                {
                    "action": "recontact",
                    "due_date": "2018-04-07T10:35:29.000-0400",
                    "mandatory": false
                }
            ]
        }
    ],
    "resolution": {
        "reason": "item_returned",
        "date_created": "2018-03-08T10:35:29.269-0400",
        "decision": [
            "complainant",
            "respondent"
        ],
        "closed_by": "mediator"
    },
    "coverages": [
        {
            "type": "bpp",
            "benefited": "complainant",
            "amount": 194.99,
            "resource": "bpp",
            "resource_id": 224635193,
            "date_created": "2018-03-08T10:35:30.000-0400",
            "costs": [
                {
                    "role": "respondent",
                    "amount": 194.99,
                    "date_created": "2018-03-08T10:35:30.000-0400"
                }
            ]
        },
        {
            "type": "return_label",
            "benefited": "complainant",
            "amount": 144.99,
            "resource": "bpp",
            "resource_id": 224635218,
            "date_created": "2018-03-08T10:38:28.000-0400",
            "costs": [
                {
                    "role": "mediator",
                    "amount": 144.99,
                    "date_created": "2018-03-08T10:38:28.000-0400"
                },
                {
                    "role": "respondent",
                    "amount": 0,
                    "date_created": "2018-03-08T10:38:28.000-0400"
                }
            ]
        }
    ],
    "labels": [
        {
            "name": "reputation",
            "value": "avoid",
            "comments": null,
            "admin_id": null,
            "date_created": "2018-03-08T09:56:00.078-0400"
        },
        {
            "name": null,
            "value": null,
            "comments": null,
            "admin_id": null,
            "date_created": "2018-03-08T09:56:00.078-0400"
        },
        {
            "name": null,
            "value": null,
            "comments": null,
            "admin_id": null,
            "date_created": "2018-03-08T09:56:00.078-0400"
        },
        {
            "name": "return_label",
            "value": "charged",
            "comments": null,
            "admin_id": null,
            "date_created": "2018-03-08T09:56:00.078-0400"
        }
    ],
    "site_id": "MLA",
    "date_created": "2018-03-08T09:56:00.078-0400",
    "last_updated": "2018-03-08T10:38:27.999-0400"
}

GET ALL THE MESSAGES OF A CLAIM Call
curl -X GET “https://api.mercadolibre.com/v1/claims/{claim_id}/messages?access_token=$ACCESS_TOKEN”
Example
curl -X GET http://api.internal.ml.com/v1/claims/950463475/messages?access_token=$ACCESS_TOKEN -H 'Content-Type:application/json'
Response
[
    {
        "sender_role": "respondent",
        "receiver_role": "complainant",
        "attachments": [
            {
                "filename": "fa8d559e-b6c9-4a9d-9824-aba4607bd869_271959653.jpg",
                "original_filename": "camiseta promocional 6555 rosa.jpg",
                "size": 5434,
                "type": "image/jpeg",
                "date_created": "2018-03-08T16:59:25.936-0400"
            }
        ],
        "stage": "claim",
        "internal_data": {
            "solution_id": null,
            "edited": false,
            "action_id": null,
            "author": null
        },
        "date_created": "2018-03-08T16:59:25.936-0400",
        "message": "Este es un mensaje de test del respondant al complainant",
        "date_read": null
    },
    {
        "sender_role": "complainant",
        "receiver_role": "respondent",
        "attachments": [],
        "stage": "claim",
        "internal_data": {
            "solution_id": null,
            "edited": false,
            "action_id": null,
            "author": null
        },
        "date_created": "2018-03-08T10:40:02.602-0400",
        "message": "Test pdd ",
        "date_read": null
    }
]

SEE, ANSWER, AND ATTACH FILES TO MESSAGES

ATTACHMENT POST

Call
curl -X POST “https://api.mercadolibre.com/v1/claims/attachments?access_token=$ACCESS_TOKEN” -F file={file_path}
NOTES
  • The POST should be made as form.data with file = file location.
  • The file needs to have a maximum 5 MB size.
  • You can exchange pictures, instruction manuals, invoices, and any other attachments of up to 5 MB in JPG, PNG, PDF and TXT format.
Example
curl -X POST “https://api.mercadolibre.com/v1/claims/attachments?access_token=$ACCESS_TOKEN” -H 'content-type: multipart/form-data;  -F 'file=@/Users/user/Desktop/file.jpg'
Response
{
    "user_id": 271959653,
    "filename": "fa8d559e-b6c9-4a9d-9824-aba4607bd869_271959653.jpg",
    "render_url": "https://api.mercadolibre.com/mediations/claims/attachments/render/fa8d559e-b6c9-4a9d-9824-aba4607bd869_271959653.jpg"
}

MESSAGE POST with the above attachment

Call
POST “https://api.mercadolibre.com/v1/claims/{claim_id}/messages?access_token=$ACCESS_TOKEN&application_id=$APPLICATION_ID”
NOTE:The attachment list will display all the attachments retrieved in the previous POST and associated to the message, separated by comma. Example
curl -X POST “https://api.mercadolibre.com/v1/claims/950463475/messages?access_token=$ACCESS_TOKEN&application_id=$APPLICATION_ID” -H 'Content-Type: application/json'  \
 -d '{ \
  "receiver_role": "complainant", \
  "message": "Este es un mensaje de test del respondent al complainant", \
  "attachments": [ \
    "fa8d559e-b6c9-4a9d-9824-aba4607bd869_271959653.jpg" \
  ] \
}'
Response
{"id":1817133310}

SEND MESSAGES WITHOUT ATTACHMENTS Call
POST “https://api.mercadolibre.com/v1/claims/{claim_id}/messages?access_token=$ACCESS_TOKEN”
Example
curl -X POST “https://api.mercadolibre.com/v1/claims/950463475/messages?access_token=$ACCESS_TOKEN” -H 'Content-Type: application/json'  \
 -d '{ \
  "receiver_role": "complainant", \
  "message": "Este es un mensaje de test del respondent al complainant", \
}'
Response
{"id":1817133310}

REQUEST MEDIATION Response
PUT “https://api.mercadolibre.com/v1/claims/{claim_id}?access_token=$ACCESS_TOKEN”
Example
curl -X PUT “https://api.mercadolibre.com/v1/claims/950463475?access_token=$ACCESS_TOKEN”  -H 'Content-Type: application/json' -d '{"stage":"dispute"}'
Response

{
    "id": 950463475,
    "type": "mediations",
    "stage": "dispute",
    "status": "opened",
    "parent_id": null,
    "client_id": null,
    "resource_id": 1656273684,
    "resource": "order",
    "reason_id": "PDD-0",
    "players": [
        {
            "role": "complainant",
            "type": "buyer",
            "id": 271942703,
            "available_actions": []
        }
    ],
    "resolution": null,
    "coverages": [],
    "labels": [
        {
            "name": null,
            "value": null,
            "comments": null,
            "admin_id": null,
            "date_created": "2018-03-08T10:40:02.390-0400"
        },
        {
            "name": null,
            "value": null,
            "comments": null,
            "admin_id": null,
            "date_created": "2018-03-08T10:40:02.390-0400"
        }
    ],
    "site_id": "MLA",
    "date_created": "2018-03-08T10:40:02.390-0400",
    "last_updated": "2018-03-12T09:17:56.844-0400"
}

SEE PARTICIPANTS' EXPECTED RESOLUTIONS Call
GET “https://api.mercadolibre.com/v1/claims/{claim_id}/expected_resolutions'?access_token=$ACCESS_TOKEN”
Example
curl -X GET “https://api.mercadolibre.com/v1/claims/950463475/expected_resolutions?access_token=$ACCESS_TOKEN”
Response
[
    {
        "player_role": "complainant",
        "user_id": 271942703,
        "expected_resolution": "return",
        "date_created": "2018-03-08T11:40:02.489-0300",
        "last_updated": "2018-03-08T11:40:02.489-0300",
        "status": "pending"
    }
]

Parameters description:

  • player_role: claim player role
  • user_id: claim player ID
  • expected_resolution: claim resolution loaded by the player specified in the above parameter. Possible values are: refund: the player expects a money refund product: the player expects to receive the product change_product: the player expects to change the product return_product: the player expects to have the product returned with the subsequent money refund
  • date_created: expected resolution creation date
  • date_created: time when the expected resolution was last updated
  • status: expected resolution status. It may take one of the following values: pending: the player loaded the expected resolution, but its counterparty has not accepted it yet accepted: the resolution loaded by the player was accepted by its counterparty or, otherwise, by Mercado Libre's mediator rejected: the resolution loaded by the player was rejected by its counterparty or, otherwise, a new resolution alternative was loaded
NOTA: Regardless of the resolutions loaded by the parties involved, in certain cases the final resolution is defined by a representative of Mercado Libre, if the parties fail to come to an agreement.
ACCEPT THE PLAYER'S RESOLUTION Call
PUT “https://api.mercadolibre.com/v1/claims/{claim_id}/expected_resolutions'?access_token=$ACCESS_TOKEN”
Example
curl -X PUT “https://api.mercadolibre.com/v1/claims/950463475/expected_resolutions?access_token=$ACCESS_TOKEN” d '{"status":"accepted"}'
Response
[
    {
        "player_role": "complainant",
        "user_id": 271942703,
        "expected_resolution": "change_product",
        "date_created": "2018-03-08T11:40:02.489-0300",
        "last_updated": "2018-03-08T11:40:02.489-0300",
        "status": "accepted"
    }
]
NOTAS
  • In the event the respondent accepts the complainant's resolution.
  • If applicable, Mercado Libre will give the buyer a label to return the product.
  • The resolution to be accepted is always depending on the counterparty's decision.

LOAD A NEW RESOLUTION Call
POST “https://api.mercadolibre.com/v1/claims/{claim_id}/expected_resolutions'?access_token=$ACCESS_TOKEN”
Example
curl -X POST “https://api.mercadolibre.com/v1/claims/950463475/expected_resolutions?access_token=$ACCESS_TOKEN” d '{"expected_resolution":"return_product"}'
Response
[
    {
        "player_role": "complainant",
        "user_id": 271942703,
        "expected_resolution": "change_product",
        "date_created": "2018-03-07T11:40:02.489-0300",
        "last_updated": "2018-03-08T11:40:02.489-0300",
        "status": "rejected"
    },
{
        "player_role": "respondent",
        "user_id": 271944560,
        "expected_resolution": "return_product",
        "date_created": "2018-03-08T11:40:02.489-0300",
        "last_updated": "2018-03-08T11:40:02.489-0300",
        "status": "accepted"
    }
]
NOTE: In the example, the seller rejects the buyer's requested change of product, but accepts the product return and, alternatively, grants a money refund to the buyer.
GET CLAIM EVIDENCE Call
GET “https://api.mercadolibre.com/v1/claims/{claim_id}/evidences?access_token=$ACCESS_TOKEN”
Example
curl -X GET “https://api.mercadolibre.com/v1/claims/949903015/evidences?access_token=$ACCESS_TOKEN”  
NOTE: At present, there is only the shipping evidence load by the seller. Response
[
    {
        "attachments": [],
        "type": "shipping_evidence",
        "date_shipped": "2018-03-07T05:00:00Z",
        "date_delivered": null,
        "destination_agency": null,
        "receiver_email": null,
        "receiver_id": null,
        "receiver_name": null,
        "shipping_company_name": "servientrega",
        "shipping_method": "mail",
        "tracking_number": "132456787"
    }
]

LOAD SHIPPING EVIDENCE Call
POST “https://api.mercadolibre.com/v1/claims/{claim_id}/evidences?access_token=$ACCESS_TOKEN”
Example
curl -X POST “https://api.mercadolibre.com/v1/claims/949903015/evidences?access_token=$ACCESS_TOKEN” -d {"attachments": [],"type": "shipping_evidence", "date_shipped": "2018-03-07T05:00:01.858-03:00", "shipping_company_name": "servientrega", "shipping_method": "mail" }  
Response
[
    {
        "attachments": [],
        "type": "shipping_evidence",
        "date_shipped": "2018-03-07T05:00:00Z",
        "date_delivered": null,
        "destination_agency": null,
        "receiver_email": null,
        "receiver_id": null,
        "receiver_name": null,
        "shipping_company_name": "servientrega",
        "shipping_method": "mail",
        "tracking_number": "132456787"
    }
]

HISTORY OF CLAIM STATUS AND SCENARIO Call
GET “https://api.mercadolibre.com/v1/claims/{claim_id}/status_history?access_token=$ACCESS_TOKEN”
Example
curl -X GET “https://api.mercadolibre.com/v1/claims/950463475/status_history?access_token=$ACCESS_TOKEN”
Response
[
    {
        "stage": "dispute",
        "status": "closed",
        "date": "2018-03-12T10:33:01.858-03:00",
        "change_by": "mediator"
    },
    {
        "stage": "dispute",
        "status": "opened",
        "date": "2018-03-12T10:17:56.844-03:00",
        "change_by": "respondent"
    },
    {
        "stage": "claim",
        "status": "opened",
        "date": "2018-03-08T11:40:02.390-03:00",
        "change_by": "complainant"
    }
]

SEE THE CLAIM HISTORY OF ACTIONS TAKEN Call
GET “https://api.mercadolibre.com/v1/claims/{claim_id}/actions_history?access_token=$ACCESS_TOKEN”
Example
curl -X GET “https://api.mercadolibre.com/v1/claims/950463475/actions_history?access_token=$ACCESS_TOKEN”
Response
[
    {
        “action_id”: 3454323247,
        “action_name”: “open_dispute”,
        “role”: ”mediator”,  
        "claim_stage": "claim",
        "claim_status": "opened",
       "date_created": "2018-03-12T10:33:01.858-03:00"
    },
    {
        “action_id”: 3454323245,
        “action_name”: “send_message_to_complainant”,
        “role”: ”respondent”,  
        "claim_stage": "claim",
        "claim_status": "opened",
       "date_created": "2018-03-10T11:33:01.858-03:00"
    },
    {
        “action_id”: 3454323243,
        “action_name”: “send_message_to_respondent”,
        “role”: ”complainant”,  
        "claim_stage": "claim",
        "claim_status": "opened",
       "date_created": "2018-03-10T10:33:01.858-03:00"
    }
]

Parameters description:

  • action_id: ID of action taken
  • action_name: action taken
  • role: player who took the action
  • claim_stage: stage in which the action was taken
  • claim_status: status of the stage in which the action was taken
  • date_created: date on which the action was taken

GET DETAILS OF THE REASON WHY THE CLAIM WAS FILED Call
GET “https://api.mercadolibre.com/v1/reasons/{reason_id}/children”
Example
curl -X GET “https://api.mercadolibre.com/v1/reasons/PDD2/children”
Response
{
    "id": "PDD2",
    "name": "damaged_item",
    "detail": "El paquete llegó dañado y afectó al producto",
    "flow": "mediations",
    "position": 10,
    "site_id": "MLA",
    "parent_id": "PDD1",
    "status": "active",
    "categories": [],
    "expected_resolutions": [
        "product",
        "refund",
        "other"
    ],
    "date_created": "2018-03-14T19:22:11Z",
    "last_updated": "2018-03-14T19:22:10Z"
}

Be part of our community