Moderations

We developed an API that helps the integrator query the elements affected by some type of moderation, i.e., which have not passed some platform filters. For example, listings which -for some reason- were pending review due to price, description, etc., or questions including contents which do not pass the filter. In this way, the integrator will be able to see certain situations which will be only viewed by the seller on the platform.

Contents

→Query infractions
→Query infractions with filter
→Considerations
→Status list
→Picture Quality
    ↳How to identify errors
    ↳Parameter description
    ↳Possible Condition IDs
    ↳Error handling


Query infractions

With the GET, you can query the elements affected by some type of moderation.

curl -X GET https://api.mercadolibre.com/moderations/infractions/$USER_ID?access_token=$ACCESS_TOKEN

Example:

curl -X GET https://api.mercadolibre.com/moderations/infractions/305860144?access_token=$ACCESS_TOKEN
Note:
Keep in mind that in the response you will not see the items written out in duplicates and only the items in which the states can be final (forbidden) or temporary (waiting_for_patch, held, pending_documentation) appear. If you want to check if a user is suspended you can check the status => list => allow through the api of users (https://api.mercadolibre.com/users/$USER_ID). In case that field is false, it means that it is suspended.
Important:
In case the user be suspended, should check the account configuration in Help site.

Query infractions with filter

You can make the same query with some filters, such as, year and limit of records to be displayed by the API.

curl -X GET https://api.mercadolibre.com/moderations/infractions/$USER_ID?year_month=201711&limit=50&offset=0&access_token=$ACCESS_TOKEN

Example:

curl -X GET https://api.mercadolibre.com/moderations/infractions/305860144?year_month=201711&limit=50&offset=0&access_token=$ACCESS_TOKEN

Response:

{
    "message": "1 items with infractions since December 2017",
    "seller": {
        "id": 305860144,
        "nickname": "TESTDD9J81ZY"
    },
    "paging": {
        "limit": 20,
        "offset": 0,
        "total": 1
    },
    "results": [
        {
            "element_id": "MLB997546581",
            "element_type": "ITM",
            "infraction_date": "2018-03-21T09:59:30.480-04:00",
            "type": "infraction",
            "reason": "Mal categorizado - Categoría - Titulo",
            "current_status": "under_review",
            "sub_status": [
                "waiting_for_patch"
            ]
        }
    ]
}

Considerations

limit Paging limit (Default = 20, <= 50)
offset Paging offset (Default = 0, <=50)
year_month Starting year and month to get infractions (Example: 201711 (year and month))


Status list

  • element_type: Type of element

- ITM (item): means that the element is a listing.
-QUE (question/response): means that the element can be a question or a response to the listing.

  • type: type of infraction.

- At this point, only the "infraction" type will be displayed.

  • current_status: element current status.

- The possible statuses to be displayed are: under_review, paused, active.

  • sub_status: list of current element sub-statuses. The sub-status can be displayed empty and the following can also be displayed.

-Current status under_review: waiting_for_patch, suspended, held, banned, pending_documentation, forbidden, suspended_for_prevention.

- Current status paused: freezes, suspended.


Picture Quality

The /quality/pictures resource will help identify the reasons why an item is losing visibility on listings, i.e., it does not meet picture requirements. Below we explain how to identify whether an item is being moderated or has picture issues.

Besides, you can use the /items resources to see items that are losing visibility, provided that they have a "good_quality_thumbnail" or “poor_quality_thumbnail” tag. Learn more in our Item and search guide.


How to identify errors

To identify whether or not there are items with errors, make this request:

curl -X GET https://api.mercadolibre.com/quality/pictures/$ITEM_ID?access_token=$ACCESS_TOKEN

Response:

{
    "itemID": "MLA0111111",
    "quality": "good",
    "thumbnail": "344725-MLA25503040734_042017",
    "conditions": [
        {
            "id": "white_background",
            "passed": true
        },
        {
            "id": "minimum_size",
            "passed": true
        },
        {
            "id": "text_logo_watermark",
            "passed": true
        },
        {
            "id": "unprofessional_photo",
            "passed": true
        }
    ],
    "taggedDate": "2019-05-02T07:27:40Z"
}

Parameter description

itemID: Listing ID.
quality: Picture quality may take “good” or “poor” values to define a “good picture” or “bad picture” status, respectively.
thumbnail: Picture with which the item was processed corresponds to the item thumbnail.
conditions: Set of conditions to be met by an item to determine picture quality. A condition consists of an ID (with a brief definition of the analyzed aspects) and a passed attribute, a Boolean value that defines whether or not the picture meets the condition.
taggedDate: Date of latest item processing.


Possible Condition IDs

minimum_size: evaluate if any of the images in the publication exceed the minimum 500 x 500 px.
text_logo_watermark: evaluate whether the first image of the publication contains logos, text, promotional banners or watermarks.
white_background: evaluate if the first image of the publication has a pure white background. In other words, a white background created with an image editor, instead of a product photo in front of a wall or other element.
multiproduct: evaluate if the first image contains more than one product. For example, we do not allow the first image of the publication to contain several pairs of shoes.
blur: evaluate that the images in the publication are not blurry.
unprofessional_photo: it is executed when the rest of the validations are negative and evaluates three conditions at the same time: multiproduct, white background and logos. It does not mean that the image meets all three, but may not be complying with any of the three.
rollbacked: this validation is reserved for the customer service team. We use it when a seller contacts to claim for incorrect detections (false positive). Once applied, the photo is not re-moderated, unless the seller changes the image.


Error handling

Error structure

{
"error": Error Type,
"code": Error code,
"message": error message,
"cause": list of error cause
}

Invalid access_token example

{
  "message": "access_token is missing",
  "error": "Forbidden",
  "status": 403,
  "cause": "Couldn't validate authentication"
}

Item no tagged with thumbnail example

{
 "message": "No picture tagged for item (Item_id)",
 "error": "Not Found",
 "status": 404,
 "cause": "Element not found"
}

Use the resource below to query the actions to make if the main picture of your listing fails to meet any of the above validations:

Request:

curl -X GET https://api.mercadolibre.com/tagging/quality/message/$ITEM_ID

Response:

{
  "reason": "Para recuperar tu exposición, corregí tus fotos
  • Asegurate de que la primera imagen de tu producto tenga como mínimo 500 píxeles en uno de los lados. Te recomendamos usar 1200 x 1200, para que puedan hacer zoom.
", "conditions": [ { "id": "sizePictures", "message": "Asegurate de que la primera imagen de tu producto tenga como mínimo 500 píxeles en uno de los lados. Te recomendamos usar 1200 x 1200, para que puedan hacer zoom." } ] }

Learn more about how work with pictures.