Catalog required listings

From July 23 some products must be published in a catalog or have an associated catalog publication to continue selling in Mercado Libre. Before knowing if a product is part of the catalog, we recommend you consult the /products/search resource and identify if you have to publish it in the catalog. In case you cannot publish or associate the publication due to not finding the product in the catalog, you can create better quality publications by following our recommendations. Thus, sellers avoid moderate (paused) posts, and compete to gain exposure and offer the best selling experience.

Contents

→Recognize products before listing
→Identify existing posts to associate (optin)
→Deadline to list in catalog
→Create higher quality posts
→Validate listings quality
    ↳Product Identifiers (PIs)
    ↳Pictures
    ↳Title and description
→Consult moderations


Recognize products before listing

Before creating new publications, you must recognize if the product exists and is active in the catalog. To do this, GET the resource /products/search with the status filter and check through the listing_strategy: catalog_required if the product should be published in the catalog. In this case, you can:

In this way, you will prevent your publication from being moderated (paused) by Mercado Libre.

Note:
The seller will be able to recognize the required publications in the catalog by product family, that is, if he decides to sell an “Apple iPhone 3G 8 GB Black 128 MB RAM” he must associate it with a catalog publication because the family of that product (iPhone 3) is active in catalog. In the event that your product is within a family of products required in the catalog but its specific characteristics are not in the catalog, you must create a higher quality publication.

Example of product required to catalog:

{
    "keywords": " Apple iphone 3g",
    "domain_id": "MLA-CELLPHONES",
    "paging": {
        "total": 3,
        "limit": 10,
        "offset": 0
    },
    "results": [
        {
            "id": "MLA6005934",
            "status": "active",
            "domain_id": "MLA-CELLPHONES",
            "settings": {
                "listing_strategy": "catalog_required"
            },
            "name": "Apple iPhone iPhone 3G 8 GB Negro 128 MB RAM",
            "attributes": [
                {
                    "id": "BRAND",
                    "name": "Marca",
                    "value_id": "9344",
                    "value_name": "Apple"
                },
                {
                    "id": "LINE",
                    "name": "Línea",
                    "value_id": "58993",
                    "value_name": "iPhone"
                },
                {
                    "id": "MODEL",
                    "name": "Modelo",
                    "value_id": "14605",
                    "value_name": "iPhone 3G"
                },
                {
                    "id": "IS_DUAL_SIM",
                    "name": "Es Dual SIM",
                    "value_id": "242084",
                    "value_name": "No"
                },
                {
                    "id": "COLOR",
                    "name": "Color",
                    "value_id": "52049",
                    "value_name": "Negro"
                },
                {
                    "id": "INTERNAL_MEMORY",
                    "name": "Memoria interna",
                    "value_id": "59566",
                    "value_name": "8 GB"
                },
                {
                    "id": "RAM",
                    "name": "Memoria RAM",
                    "value_id": "579543",
                    "value_name": "128 MB"
                },
                {
                    "id": "MAIN_COLOR",
                    "name": "Color principal",
                    "value_id": "2450295",
                    "value_name": "Negro"
                },
                {
                    "id": "OPERATING_SYSTEM_NAME",
                    "name": "Nombre del sistema operativo",
                    "value_id": "7404961",
                    "value_name": "iOS"
                }
            ],
            "pictures": [
                {
                    "id": "675782-MLA31138875214_062019",
                    "url": "https://mla-s1-p.mlstatic.com/675782-MLA31138875214_062019-F.jpg"
                },
                {
                    "id": "915001-MLA31138546867_062019",
                    "url": "https://mla-s1-p.mlstatic.com/915001-MLA31138546867_062019-F.jpg"
                },
                {
                    "id": "881441-MLA31138332972_062019",
                    "url": "https://mla-s1-p.mlstatic.com/881441-MLA31138332972_062019-F.jpg"
                },
                {
                    "id": "804666-MLA31139286536_062019",
                    "url": "https://mla-s2-p.mlstatic.com/804666-MLA31139286536_062019-F.jpg"
                }
            ]
        },
        {
            "id": "MLA6007403",
            "status": "active",
            "domain_id": "MLA-CELLPHONES",
            "settings": {
                "listing_strategy": "catalog_required"
            },
            "name": "Apple iPhone iPhone 3G 16 GB Negro 128 MB RAM",
            "attributes": [
                {
                    "id": "BRAND",
                    "name": "Marca",
                    "value_id": "9344",
                    "value_name": "Apple"
                },
                {
                    "id": "LINE",
                    "name": "Línea",
                    "value_id": "58993",
                    "value_name": "iPhone"
                },
                {
                    "id": "MODEL",
                    "name": "Modelo",
                    "value_id": "14605",
                    "value_name": "iPhone 3G"
                },
                {
                    "id": "IS_DUAL_SIM",
                    "name": "Es Dual SIM",
                    "value_id": "242084",
                    "value_name": "No"
                },
                {
                    "id": "COLOR",
                    "name": "Color",
                    "value_id": "52049",
                    "value_name": "Negro"
                },
                {
                    "id": "INTERNAL_MEMORY",
                    "name": "Memoria interna",
                    "value_id": "59561",
                    "value_name": "16 GB"
                },
                {
                    "id": "RAM",
                    "name": "Memoria RAM",
                    "value_id": "579543",
                    "value_name": "128 MB"
                },
                {
                    "id": "MAIN_COLOR",
                    "name": "Color principal",
                    "value_id": "2450295",
                    "value_name": "Negro"
                },
                {
                    "id": "OPERATING_SYSTEM_NAME",
                    "name": "Nombre del sistema operativo",
                    "value_id": "7404961",
                    "value_name": "iOS"
                }
            ],
            "pictures": [
                {
                    "id": "675782-MLA31138875214_062019",
                    "url": "https://mla-s1-p.mlstatic.com/675782-MLA31138875214_062019-F.jpg"
                },
                {
                    "id": "915001-MLA31138546867_062019",
                    "url": "https://mla-s1-p.mlstatic.com/915001-MLA31138546867_062019-F.jpg"
                },
                {
                    "id": "881441-MLA31138332972_062019",
                    "url": "https://mla-s1-p.mlstatic.com/881441-MLA31138332972_062019-F.jpg"
                },
                {
                    "id": "804666-MLA31139286536_062019",
                    "url": "https://mla-s2-p.mlstatic.com/804666-MLA31139286536_062019-F.jpg"
                }
            ]
        },
        {
            "id": "MLA6007404",
            "status": "active",
            "domain_id": "MLA-CELLPHONES",
            "settings": {
                "listing_strategy": "catalog_required"
            },
            "name": "Apple iPhone iPhone 3G 16 GB Blanco 128 MB RAM",
            "attributes": [
                {
                    "id": "BRAND",
                    "name": "Marca",
                    "value_id": "9344",
                    "value_name": "Apple"
                },
                {
                    "id": "LINE",
                    "name": "Línea",
                    "value_id": "58993",
                    "value_name": "iPhone"
                },
                {
                    "id": "MODEL",
                    "name": "Modelo",
                    "value_id": "14605",
                    "value_name": "iPhone 3G"
                },
                {
                    "id": "IS_DUAL_SIM",
                    "name": "Es Dual SIM",
                    "value_id": "242084",
                    "value_name": "No"
                },
                {
                    "id": "COLOR",
                    "name": "Color",
                    "value_id": "52055",
                    "value_name": "Blanco"
                },
                {
                    "id": "INTERNAL_MEMORY",
                    "name": "Memoria interna",
                    "value_id": "59561",
                    "value_name": "16 GB"
                },
                {
                    "id": "RAM",
                    "name": "Memoria RAM",
                    "value_id": "579543",
                    "value_name": "128 MB"
                },
                {
                    "id": "MAIN_COLOR",
                    "name": "Color principal",
                    "value_id": "2450308",
                    "value_name": "Blanco"
                },
                {
                    "id": "OPERATING_SYSTEM_NAME",
                    "name": "Nombre del sistema operativo",
                    "value_id": "7404961",
                    "value_name": "iOS"
                }
            ],
            "pictures": [
                {
                    "id": "675782-MLA31138875214_062019",
                    "url": "https://mla-s1-p.mlstatic.com/675782-MLA31138875214_062019-F.jpg"
                },
                {
                    "id": "915001-MLA31138546867_062019",
                    "url": "https://mla-s1-p.mlstatic.com/915001-MLA31138546867_062019-F.jpg"
                },
                {
                    "id": "881441-MLA31138332972_062019",
                    "url": "https://mla-s1-p.mlstatic.com/881441-MLA31138332972_062019-F.jpg"
                },
                {
                    "id": "804666-MLA31139286536_062019",
                    "url": "https://mla-s2-p.mlstatic.com/804666-MLA31139286536_062019-F.jpg"
                }
            ]
        }
    ]
}

Identify existing posts to associate

To recognize the current marketplace publications that should be published in a catalog, consult recurso search with the catalog_forewarning parameter the search resource and filter this type of listings. Once identified, we recommend that you associate each publication with a catalog (optin) and avoid moderations.

Request:

curl -X GET https://api.mercadolibre.com/users/$USER_ID/items/search?tags=catalog_forewarning&access_token=$ACCESS_TOKEN

Example:

curl -X GET https://api.mercadolibre.com/users/123456987/items/search?tags=catalog_forewarning&access_token=$ACCESS_TOKEN

Short response:

{
    "seller_id": "123456987",
    "query": null,
    "paging": {
        "limit": 50,
        "offset": 0,
        "total": 1
    },
    "results": [
        "MLA123456789"
    ],
    "filters": [],
    "available_filters": [
            ]
}
Note:
The search response will show in results all the items of the seller marked with the catalog_forewarning tag.

Deadline to list in catalog

Recognizing these publications, check the deadline that you will have as the deadline to publish the product in catalog by consulting the resource /catalog_forewarning/date.

Request:

curl -X GET https://api.mercadolibre.com/items/$ITEM_ID/catalog_forewarning/date?access_token=$ACCESS_TOKEN

Example:

curl -X GET https://api.mercadolibre.com/items/MLA123456789/catalog_forewarning/date?access_token=$ACCESS_TOKEN

List response with assigned date:

{
   "status":"date_defined",
   "moderation_date":"2020-08-20T13:00:00Z"
}

List response without the catalog_forewarning tag:

{
   "status":"date_not_defined",
   "moderation_date": null
}

List response with expired date:

{
   "status":"date_expired",
   "moderation_date":"2020-06-10T13:00:00Z"
}
Note:
Remember to filter and notify the catalog publication deadlines to your sellers to avoid pausing their publications and improving the sales experience.

To prevent existing posts from being moderated (paused) because they weren't published in the catalog on time, you can:


Create higher quality posts

This type of publication will be available in the event that the product family that is required in the catalog does not have the specific product that you want to publish. For this, you must adequately complete the following product requirements:

  • GTIN mandatory
  • Required attributes
  • Title and description with product information (coming soon)
  • Optimal quality pictures (coming soon)

  • To recognize this type of publication, request the /items resource and check the catalog_product_candidate tag of each item.
    Remember that although the publication has the mentioned tag it could be paused if it does not meet the quality requirements described. With the status: under_review you can identify the paused items of this type of publications that do not meet the requirements.
    Example of a higher quality item:

    {
      "id": "MLA123456789",
      "site_id": "MLA",
      "title": "Item De Testeo, Por Favor No Ofertar --kc:off",
      "subtitle": null,
      "seller_id": 123456987,
      "category_id": "MLA3530",
      "official_store_id": null,
      "price": 50,
      "base_price": 50,
      "original_price": null,
      "currency_id": "ARS",
      "initial_quantity": 1,
      "available_quantity": 1,
      "sold_quantity": 0,
      "sale_terms": [ ],
      "buying_mode": "buy_it_now",
      "listing_type_id": "free",
      "start_time": "2020-02-17T16:30:39.000Z",
      "stop_time": "2020-04-17T04:00:00.000Z",
      "condition": "new",
      "permalink": "https://articulo.mercadolibre.com.ar/MLA-839616438-item-de-testeo-por-favor-no-ofertar-kcoff-_JM",
      "thumbnail": "http://mla-s1-p.mlstatic.com/951410-MLA40807113659_022020-I.jpg",
      "secure_thumbnail": "https://mla-s1-p.mlstatic.com/951410-MLA40807113659_022020-I.jpg",
      "pictures": [ ],
      "video_id": null,
      "descriptions": [ ],
      "accepts_mercadopago": true,
      "non_mercado_pago_payment_methods": [ ],
      "shipping": { },
      "international_delivery_mode": "none",
      "seller_address": { },
      "seller_contact": null,
      "location": { },
      "geolocation": { },
      "coverage_areas": [ ],
      "attributes": [ ],
      "warnings": [ ],
      "listing_source": "",
      "variations": [ ],
      "status": "active",
      "sub_status": [ ],
      "tags": [
        "catalog_product_candidate",
        "good_quality_picture",
        "test_item",
        "immediate_payment"
      ],
      "warranty": null,
      "catalog_product_id": null,
      "domain_id": "MLA-UNCLASSIFIED_PRODUCTS",
      "parent_item_id": null,
      "differential_pricing": null,
      "deal_ids": [],
      "automatic_relist": false,
      "date_created": "2020-02-17T16:30:40.000Z",
      "last_updated": "2020-02-17T16:34:12.000Z",
      "health": 0.4,
      "catalog_listing": false
    }

    Validate listings quality

    This validation resource will allow you to verify if an item meets the required quality parameters. Remember that a publication can be moderate in case any quality requirement of this type of publication is not correct or is not complete.

    Request:

    curl -X POST https://api.mercadolibre.com/catalog_product_candidate/validate?access_token=$ACCESS_TOKEN
    Note:
    Modify the title, description, pictures, category_id, domain_id and attributes parameters according to the validation you want to obtain.

    Example of validation that meets the required quality parameters:

    curl -X POST https://api.mercadolibre.com/catalog_product_candidate/validate?access_token=$ACCESS_TOKEN
    
    {
      "site_id":"MLA",
      "title": "ok",
      "description":"ok",
      "category_id": "MLA538565",
      "pictures":[
        "967960-MLA41175135696_032020"
        ],
      "domain_id":"MLA-CELLPHONES",
      "attributes":[
        {
                "id": "BRAND",
                "name": "Marca",
                "value_id": "995",
                "value_name": "Apple"
            },
          {
           "id": "GTIN",
           "value_name": "0190198457012"
          }
      ]
    }
    Note:
    If the answer returns the empty arrays [] it means that what was sent in the POST to validate meets the quality requirements.

    Example of validation that does not meet the required quality parameters:

    curl -X POST https://api.mercadolibre.com/catalog_product_candidate/validate?access_token=$ACCESS_TOKEN
    
    {
      "site_id":"MLA",
      "title": "Test title",
      "description":"Test title",
      "category_id": "MLA438566",
      "pictures":[
        "967960-MLA41175135696_032020"
        ],
      "domain_id":"MLA-CELLPHONES",
      "attributes":[
        {
                "id": "BRAND",
                "name": "Marca",
                "value_id": "995",
                "value_name": "Apple"
            },
          {
           "id": "GTIN",
           "value_name": "0190198457011"
          }
      ]
    }

    Response with incorrect information consulted:

    {
        "message": "Validation error",
        "error": "validation_error",
        "status": 400,
        "cause": [
            {
                "cause_id": 6004,
                "code": "item.product_identifier.invalid",
                "message": "El código no corresponde a tu producto.",
                "references": [
                    "0190198457011",
                    "PI_INCORRECT"
                ],
                "type": "error"
            },
            {
                "cause_id": 6001,
                "code": "item.title.invalid",
                "message": "Title has invalid topics",
                "references": [
                    "LOCATION"
                ],
                "type": "error"
            },
            {
                "cause_id": 6002,
                "code": "item.description.invalid",
                "message": "Description has invalid topics",
                "references": [
                    "LINK_TO_STORE",
                    "LOCATION",
                    "STOCK"
                ],
                "type": "error"
            },
            {
                "cause_id": 6003,
                "code": "item.picture.invalid",
                "message": "Picture quality is not good",
                "references": [
                    "967960-MLA41175135696_032020",
                    "logo_text_watermark",
                    "blur"
                ],
                "type": "error"
            }
        ]
    }

    Response fields

    status: can have 400 values when some of the parameters you validate do not meet the required quality and 204 value when the parameters meet the required quality.
    cause: it will have the multiple causes that generate the validation error depending on the ones that have been sent in the POST. They can be by GTIN, title, description and/or pictures.

    • cause_id: refers to the validations sent and they are not of quality.
    • code: is the descriptive code by which the error occurs.
    • message: this is the reason for the error for which the validation fails.
    • references: are the validations that failed. In the case of images and PIs we refer to the id that does not pass the validation.

    Validate Product Identifiers (PIs)

    To correctly validate PIs, we recommend you send site_id, domain_id and the BRAND (optional), MODEL (optional) and GTIN attributes with their respective value_name.

    Product Identifiers validation example:

    curl -X POST https://api.mercadolibre.com/catalog_product_candidate/validate?access_token=$ACCESS_TOKEN
    {
       "site_id":"MLA",
       "domain_id":"MLA-CELLPHONES",
       "attributes":[
          {
             "id":"BRAND",
             "name":"Marca",
             "value_id":"995",
             "value_name":"Apple"
          },
          {
             "id":"MODEL",
             "value_name":"iPhone X"
          },
          {
             "id":"GTIN",
             "value_name":"0190198457011"
          }
       ]
    }
    Note:
    If a product has more than one PI, they can be sent comma separated and without spaces within the value_name of GTIN.

    Response with PI errors:

    {
       "message":"Validation error",
       "error":"validation_error",
       "status":400,
       "cause":[
          {
             "cause_id":6004,
             "code":"item.product_identifier.invalid",
             "message":"El código no corresponde a tu producto.",
             "references":[
                "0190198457011",
                "PI_INCORRECT"
             ],
             "type":"error"
          }
       ]
    }
    Note:
    En el campo references In the references field, the id of the PI or the PIs that were sent in the POST but did not pass the validation will be indicated first, and secondly the error for which it failed.

    Possible error messages

    • The code does not correspond to your product.
    • The code does not belong to the category.
    • The code does not belong to the brand.

    Validate pictures

    Important:
    The moderation of the images is not yet in force, but now you can start to carry out validations.

    To validate images of higher quality publications you must perform a POST by sending site_id and id of the picture to analyze. For this, you must upload the images to our servers and the “category_id” in which you are going to publish. Know the category to publish using the category predictor.

    Picture validation example:

    curl -X POST https://api.mercadolibre.com/catalog_product_candidate/validate?access_token=$ACCESS_TOKEN
    {
        "site_id": "MLA",
        "category_id": "MLA438566",
        "pictures": [
            "967960-MLA41175135696_032020",
            "967961-MLA41175135696_032020"
        ]
    }

    Image error response:

    {
       "message":"Validation error",
       "error":"validation_error",
       "status":400,
       "cause":[
          {
             "cause_id":6003,
             "code":"item.picture.invalid",
             "message":"Picture quality is not good",
             "references":[
                "967960-MLA41175135696_032020",
                "logo_text_watermark",
                "blur"
             ],
             "type":"error"
          }
       ]
    }
    Note:
    In the references field you can see the id of the images sent in the POST but they did not pass the validation, and secondly the error for the reason or reasons why it failed.

    Possible pictures errors

    minimum_size: evaluate if any of the images in the publication exceed the minimum 500 x 500 px.
    logo_text_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.



    Validate title and description

    Important:
    The titles and descriptions moderation is not yet effective, but you can start validations now.

    With this validation you can recognize if the title and description of the product is not of quality. Take into account topics or information that we seek that is not found in the title or description of a product, each topic has a scope description indicating what it covers.
    To make the POST validation of title and description you must send site_id, title and description.

    Example of title and description validation:

    curl -X POST https://api.mercadolibre.com/catalog_product_candidate/validate?access_token=$ACCESS_TOKEN
    
    {
      "site_id":"MLA",
      "title": "Apple Iphone X Rose",
      "description":"Fotos amplias y perfectas de día y de noche. Un color rosado perfecto."
    }

    Response with title and description errors:

     {
       "message":"Validation error",
       "error":"validation_error",
       "status":400,
       "cause":[
          {
             "cause_id":6001,
             "code":"item.title.invalid",
             "message":"Title has invalid topics",
             "references":[
                "LOCATION"
             ],
             "type":"error"
          },
          {
             "cause_id":6002,
             "code":"item.description.invalid",
             "message":"Description has invalid topics",
             "references":[
                "LINK_TO_STORE",
                "LOCATION",
                "STOCK"
             ],
             "type":"error"
          }
       ]
    }

    Possible title and description errors

    In the response you will be able to recognize the different topics for which the listing does not meet the quality requirements in its title or description. In the first instance, we will validate:

    Topics Details
    SHIPPING Contains shipping information, such as product shipping process, how the product is shipped, shipping cost, shipping detail, or shipping delay
    METHOD_OF_PAYMENT Contains payment information, such as accepted forms of payment or financing
    BILLING Contains billing information and billing delivery methods (by email, mail)
    WARRANTY Contains product warranty information, duration or terms of this
    LOCATION Contains information of the physical store, location, delivery points, origin of the product

    Soon, we will add the following topics to the validations:

    Topics Details
    PICKUP Contains information about the product delivery process, such as post office
    TECHNICAL_SUPPORT Contains information on the technical service offered after sales
    ABOUT_US Contains seller information
    FAQ Contains information about frequently asked questions (FAQs)
    STOCK Contains stock information
    LEGAL Contains legal information such as Terms and Conditions
    OFFICE_HOURS Contains customer support information
    LINK_TO_STORE Contains links to Mercado Libre listings or external links

    Consult moderations

    Important:
    Any change or modification that alters the quality of the publication may generate its moderation (paused).

    You can then query /moderations/infractions recognize if a post was moderated (paused) by not associating it in time with a catalog post, recognizing it with the reason: OPT_OBEY.

    Request:

    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/1234567?access_token=$ACCESS_TOKEN

    Response:

    {
       "message":"1 item with infractions since March 2020",
       "seller":{
          "id":1234567,
          "nickname":"TESTDD9J81ZY"
       },
       "paging":{
          "limit":20,
          "offset":0,
          "total":1
       },
       "results":[
          {
             "element_id":"MLA123456789",
             "element_type":"ITM",
             "infraction_date":"2020-05-07T18:21:13.748-04:00",
             "type":"infraction",
             "reason":"OPT_OBEY",
             "current_status":"under_review",
             "sub_status":[
                "waiting_for_patch"
             ]
          }
       ]
    }

    To reactivate your publication you must associate the publication with the catalog (optin) o create higher quality listings. Learn more about notifying the deadline to publish in catalog and avoid this type of moderation.

    You can also consult the same resource and identify the reasons for moderation of a higher quality publication and improve the required quality parameters.

    Example:

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

    Response:

    {
       "message":"1 item with infractions since March 2020",
       "seller":{
          "id":1234567,
          "nickname":"TESTDD9J81ZY"
       },
       "paging":{
          "limit":20,
          "offset":0,
          "total":1
       },
       "results":[
          {
             "element_id":"MLA123456798",
             "element_type":"ITM",
             "infraction_date":"2020-05-07T18:21:13.748-04:00",
             "type":"infraction",
             "reason":"ITEM_PLUS",
             "current_status":"under_review",
             "sub_status":[
                "waiting_for_patch"
             ]
          }
       ]
    }

    To reactivate a higher quality publication, we recommend that you validate the quality parameters of these publications.


    Back to: Catalog required listings.

or register to recieve the latest news about our API