Documentation Mercado Libre

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

Documentation

Last update 16/08/2023

Complained listings

In order to reduce complaints within the framework of the Brand Protection Program, we provide the following features to consult and respond complaints made to the sellers. Remember that a report may lead to the removal of the publication and the punishment of repeat offenders may impact their reputation, restrictions on their account, suspension, temporary and/or permanent suspension. You can also use Mercado Libre's flow to respond to a complaint.


Consult reported items

With the following resource you can obtain reported items from a seller, date of the report, expiration date (deadline to respond to the report), reason for the report, the id that identifies the case and its status.


Mandatory parameters

If you do not want to filter the reports, you must send the fields, date created and status empty: ?offset=0&date_created=&status=


offset: you limit the number of results. The maximum result per page is 50. To get the first results you must send 0, then 50, 100, 150, 200 and so on.
date_created: date of creation of reports. With this parameter, you delimit the reports from one day to the day of the date (current date).
status: status of the report. The relevant statuses for vendors are: WAITING_DOCUMENTATION, DOCUMENTATION_PRESENTED, DOCUMENTATION_APPROVED, DOCUMENTATION_NOT_APPROVED, DOCUMENTATION_NOT_PRESENTED, MEMBER_NOT_RESPOND, ROLLBACK.


Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/marketplace/moderations/bpp/cases?offset=0&date_created=$aaaa-mm-dd&status=$STATUS'

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/marketplace/moderations/bpp/cases?offset=0&date_created=2023-06-14&status='

Response:

{
    "cases": [
        {
            "item_id": "MLM1855617107",
            "date_created": "2023-06-14T19:45:27Z",
            "due_date": "2023-06-20T03:59:59Z",
            "case_id": 33353725,
            "reason_text": "listing could be using personal images without permission",
            "current_status": "DOCUMENTATION_NOT_PRESENTED"
        },
        {
            "item_id": "MLM1855559571",
            "date_created": "2023-06-14T19:45:27Z",
            "due_date": "2023-06-20T03:59:59Z",
            "case_id": 33353726,
            "reason_text": "software could be piracy.",
            "current_status": "DOCUMENTATION_NOT_PRESENTED"
        },
        {
            "item_id": "MCO1267459749",
            "date_created": "2023-06-14T19:45:26Z",
            "due_date": "2023-06-20T03:59:00Z",
            "case_id": 33353723,
            "reason_text": "listing could be using personal images without permission.",
            "current_status": "MEMBER_NOT_RESPOND"
        },
        {
            "item_id": "MCO1267435359",
            "date_created": "2023-06-14T19:45:26Z",
            "due_date": "2023-06-20T03:59:59Z",
            "case_id": 33353724,
            "reason_text": "listing could be using a copy from a protected text with copyrights (example: extracted text from book).",
            "current_status": "DOCUMENTATION_NOT_PRESENTED"
        }
    ],
    "total": {
        "total": 4,
        "offset": 0,
        "limit": 50
    }
}

Response fields

item_id: item identifier.
date_created: date of creation of the complaint received.
due_date: due date to respond to the complaint. If you do not respond, the status of the report will be changed to DOCUMENTATION_NOT_PRESENTED and the item will be moderated and deleted (forbidden).
case_id: report identifier. It will allow you to know more details of the complaint received.
reason_text: reason for the report.
current_status: current status of the complaint. This will change according to the responses and resolutions. Know the different statuses:


Current_status Name Description Item status
DOCUMENTATION_APPROVED Approved documentation The complaint was answered by the seller, the member approved the documentation and removed the complaint. Active
DOCUMENTATION_NOT_APPROVED Not approved documentation The complaint was answered by the seller, but the member ratified the complaint. Removed
DOCUMENTATION_NOT_PRESENTED Not presented documentation The complaint was not answered by the seller. Removed
DOCUMENTATION_PRESENTED Presented documentation The complaint was responded by the seller and is pending a response from the member. Paused
MEMBER_NOT_RESPOND Complaint with no response from the member The complaint was answered by the seller, but the complainant did not respond in time. Active
ROLLBACK Retracted The complaint was retracted. Activo
WAITING_DOCUMENTATION Waiting for response We are waiting for a response to the complaint from the seller. Paused

Consult details of a reported item

For more information about the case and the reported item, you can make the following query:


Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/marketplace/moderations/bpp/cases/$CASE_ID'

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/marketplace/moderations/bpp/cases/33353725'

Response:

{
  "item_info": {
    "item_id": "MCO1267459749",
    "price": 82055,
    "description": "",
    "title": "Children's Backpack Preschool Dinosaur For Boys Girls",
    "pictures": [
      {
        "size": "500x493",
        "url": "https://http2.mlstatic.com/D_643888-CBT54148523182_032023-O.jpg",
        "max_size": "810x800"
      },
      {
        "size": "500x500",
        "url": "https://http2.mlstatic.com/D_771376-CBT54148523170_032023-O.jpg",
        "max_size": "800x800"
      },
      {
        "size": "445x500",
        "url": "https://http2.mlstatic.com/D_834156-CBT54148523174_032023-O.jpg",
        "max_size": "722x810"
      },
      {
        "size": "500x500",
        "url": "https://http2.mlstatic.com/D_974188-CBT54148523177_032023-O.jpg",
        "max_size": "800x800"
      },
      {
        "size": "500x500",
        "url": "https://http2.mlstatic.com/D_861302-CBT54148523167_032023-O.jpg",
        "max_size": "800x800"
      }
    ]
  },
  "last_updated": "2023-06-20T00:00:38.000-0400",
  "is_rollbackable": false,
  "date_created": "2023-06-14T15:45:26.000-0400",
  "photos_denounced": [
    {
      "src": "https://http2.mlstatic.com/D_Q_NP_643888-CBT54148523182_032023-N.jpg",
      "id": "643888-CBT54148523182_032023",
      "status": "ACTIVE"
    },
    {
      "src": "https://http2.mlstatic.com/D_Q_NP_771376-CBT54148523170_032023-N.jpg",
      "id": "771376-CBT54148523170_032023",
      "status": "ACTIVE"
    }
  ],
  "reason_text": "the listing may be using their personal image without authorization.",
  "due_date": "2023-06-19T23:59:00.000-0400",
  "photos_new": [
    {
      "src": "https://http2.mlstatic.com/D_Q_NP_638826-MLA52755553902_122022-N.jpg",
      "id": "638826-MLA52755553902_122022",
      "status": ""
    },
    {
      "src": "https://http2.mlstatic.com/D_Q_NP_638826-MLA52755553902_122023-N.jpg",
      "id": "638826-MLA52755553902_122023",
      "status": ""
    }
  ],
  "member_quittance": "",
  "reason_id": "PPPI7",
  "document_name": "33353725.jpg",
  "public_member_name": "Brand Protection Program (Nombre Publico)",
  "case_id": 33353725,
  "current_status": "MEMBER_NOT_RESPOND",
  "seller_quittance": "Prueba de responder una denuncia con variaciones",
  "document_url": ""
}

Response fields

item_info: Relevant information of the item.
last_updated: Date of the last update of the report.
date_created: Date of the report creation.
photos_denounced: Reported images.
reason_text: Received report reason.
due_date: Deadline for responding to the report.
photos_new: New images to add to the item. Once the report is responded to with this field, Mercado Libre adds the picture IDs to the listing.
member_quittance: Comment from the program member.
reason_id: Report identifier. Learn about the different types of reports:


Reason ID Name Description
PPPI1 Falsified Product It is a copy or falsification of a product that was not manufactured by the brand.
PPPI2 Brand misuse Using the brand inappropriately in the publication. For example: in the title, description, photos, etc.
PPPI3 Copyright - Software The publication offers a computer program that infringes rights.
PPPI5 Copyright - Books The publication offers a literary work that infringes rights.
PPPI6 Copyright - Images The publication contains images and/or photos that the seller is not authorized to use.
PPPI7 Copyright - Personal Image Uses the defendant's personal image.
PPPI8 Model or Industrial Design Infringes a model or industrial design.
PPPI9 Infringes patents, utility models or plant variety rights Infringes patents, utility models or plant variety rights.
PPPI10 Product not for sale E.g. free samples, products not launched in the Brazilian market, other products that were given in commodity loan.
PPPI11 Copyright - Courses The publication offers a course that infringes rights.
PPPI12 Copyright - Video Games The publication offers a video game that infringes its rights.
PPPI14 Copyright - Videos / Movies Videos / Movies. The publication offers an audiovisual work that infringes my rights.
PPPI15 Copyright - Music The publication offers musical content that infringes its rights.
PPPI16 Copyright - Character Character. The publication offers products that include unauthorized characters.
PPPI17 Copyright - Others The publication offers another type of work (design, painting, sculpture, etc.) that infringes its rights.
PPPI18 Related Rights - Illegal Reproductions Unauthorized fixations or reproductions.
PPPI19 Related Rights - Personal Image Uses personal image associated with artistic interpretation without authorization.
PPPI20 Related Rights - Audio Material Unauthorized use of audio materialRecorded music or sounds.
PPPI21 Related Rights - Audiovisual Material Movies, series, videos, recordings of concerts, shows and sports events.
PPPI22 Related Rights - Illegal Transmission Services to access signals illegally.
PPPI23 Related Rights - Illegal Device Devices that capture signals illegally.

document_name: name of the document sent by the member.
public_member_name: public name of the program member.
case_id: report identifier.
current_status: current status of the complaint.
document_url: url of the document sent by the member.


Flow for responding to complaints

1. Identify type of response

  • If the seller has rights to use the images, the seller must respond to the complaint with a comment (optional) and attach the document (required).
  • If the seller does not have rights to these images, he must upload new images and send in his response the ids of the new images and the ids of the deleted images. Use our /pictures API to work with images.
  • By documentation: the seller must respond to the complaint with a comment (required) and with the documentation (optional). Before sending the response, we recommend you to upload the document in the endpoint.


2. Upload supporting documents

Once sellers differentiate whether it is a complaint for the use of images (by sending images + documents) or documents, they must upload the document in Mercado Libre as follows:


Mandatory parameters

case_id: complaint identifier.

name: file name.

form: file or official document that proves the response to the complaint.


Note:
You can only attach a PDF, JPG or PNG file and maximum weight 5 MB.

Request:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/marketplace/moderations/bpp/cases/$CASE_ID/upload?name=$NAME_FILE.EXT' -d '@/Users/name/example/document-nike.jpg'

Example

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/marketplace/moderations/bpp/cases/33353725/upload?name=crayola.jpg' -H 'Content-Type: image/jpeg' -d '@/Users/name/example/document-nike.jpg'

Resposta

{
  "file_name":"33353725.jpg"
}

You will use this file_name for the document_name field when you want to attach evidentiary documentation to the complaint.


3. Send a response to a complaint

Note:
If the seller does not send documentation in optional cases, you can send empty string ("document_name": " ").

Request:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/marketplace/moderations/bpp/cases/$CASE_ID' -H 'Content-Type: application/json' -d '{
    "photos_new": [],
    "photos_removed": [],
    "seller_quittance":"comment",
    "document_name":"document_name.jpg",
    "variations":[]
}'

Response for use of images (without variations):

seller_quittance: seller's comment.

photos_new: new photos that the seller will send and Mercado Libre will load these images in the item.

photos_removed: id of images to be removed. Mercado Libre will delete these images.


Example:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/marketplace/moderations/bpp/cases/33353723' -H 'Content-Type: application/json' -d '{
  "seller_quittance": "comment",
  "document_name": "33353723.png",
  "photos_new": ["799744-MLA1234_112022"],
  "photos_removed": ["637858-MLA124_112022"],
  "variations": []
}'

Response by use of images (with variations)

variations: indicate the ID of the item variation along with the images you wish to remain in this one.

Example:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/marketplace/moderations/bpp/cases/33353723' -H 'Content-Type: application/json' -d '{
    "photos_new": ["638826-MLA52755553902_122022"],
    "photos_removed": ["905137-MLA52894974640_122022"],
    "seller_quittance":"Test case response with variations",
    "document_name":"33353723.jpg",
    "variations":[
        {
            "id": 176101769611,
            "picture_ids":["638826-MLA52755553902_122022"]
        },
        {
            "id": 176101769612,
            "picture_ids": ["711133-MLA52895098136_122022"]
        },
        {
            "id": 176101769613,
            "picture_ids": ["638826-MLA52755553902_122022"]
        }
    ]
}'

Learn more about working with images.


Response to complaint with document:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/marketplace/moderations/bpp/cases/33353723' -H 'Content-Type: application/json' -d '{
  "seller_quittance": "comment of seller",
  "document_name": "33353723.png"
}'

Recommendations to respond to complaints

Infraction Reason Expected response
Falsified product, copies or replicas It is illegal to sell falsifications, copies or replicas of trademarked products, and posting such products is prohibited by our Terms and Conditions. -Send pictures of the purchase invoice showing that the product is original, that you bought it legally and that justifies the stock offered in the publication.
-Send images of the labels and original packaging of the product.
- The rights holder may ask you for specific documentation that you must attach in order to respond.
Illegal use of a registered trademark A trademark is a distinctive sign (such as a word, phrase or logo) used to identify products or services. -Attach a copy of the rights holder's authorization.
-If you are the owner of the trademark you are using, send a copy of your trademark title.
Software piracy It is illegal to sell unauthorized copies of software, and posting this kind of product is prohibited by our Terms and Conditions. Send a copy of the license that authorizes you to distribute the software.
Copyright infringement They protect original intellectual property works such as films, music, photographs and books. Copyright protection prevents others from using a work without permission. -Prove that you are the owner of those rights.
-Send a copy of the authorization given by the owner to use his work.
-Send a copy of the certificate of the work deposit.
Infringement of related rights They give protection to those who, without being authors, contribute with creativity, technique or organization in the process of making a work available to the public. -Send authorizations to record your performance or interpretation.
If it is a complaint from producers of phonograms and videograms, attach:
-Invoices of acquisition of copies issued by any authorized distributor of the phonograms or videograms.
-Contracts authorizing the sale by consignment.
-Licenses to reproduce phonograms or videograms.
If it is a complaint from a broadcasting organization, send:
-License authorizing you to distribute or retransmit the signal of the complaining organization.
Infringement of a patent or utility model It is an exclusive right granted to an invention (product or process) involving a new, non-obvious and industrially applicable technical solution. -Prove that you are the owner of the patent.
-Send a copy of the authorization given by the patent holder to commercially exploit his invention.
Infringement of a model or industrial design They protect the ornamental or aesthetic aspect applied to a product. -Prove that you are the owner of those rights.
-Send a copy of the authorization given by the holder to commercially exploit them including their protected rights.
Product not for sale The trademark owner did not intend it for commercial purposes and therefore did not deliver it to be sold, e.g. free or trial samples, or products delivered on commodity.
In Brazil, it is an infringement to sell a product that was not officially launched in that market by the rights holder or with its authorization.
Send the complainant documentation proving that you bought the product without any limitation to sell it.

Test reports

If you want to test this functionality with test users, complete this form with the test_id items and choose a type of complaint (reason_id)