Get to know how to adapt your development to catalogue

Nowadays sellers can create catalogue publications either from their current publications or directly with no publication to be associated with via API and in this way they can compete to win the exposition on the product page. Those publications will be positioned in the first places of search results.

Before starting do not forget to read the documentation of Domains and Products; this will help you to have all of the ítems with the correct information.

Get started to prepare your development following this guide!


How does catalogue work?

Traditionally publications used to be exclusively created by sellers in Mercado Libre and they were in charge of providing both the description of the products they were selling (titles, pictures and descriptions) and the sales conditions (price, shipment, financing, among others).

From now on, apart from this traditional way of publishing, it is possible to create catalogue publications in which Mercado Libre will provide the content of such publication (titles, pictures, descriptions and the technical datasheet) and different sellers can create publications which are sold by means of a unified product page on which sales are directed towards those sellers who offer the best sales conditions and experience to purchasers.


Where can purchasers find catalogue publications?

At the moment of searching purchasers will see the catalogue products in the first places of the list and when they enter to see a product, the seller who offers the best sales conditions and price will have the opportunity to sell it. Moreover, on the product page there will be a link which shows the whole list of all the sellers who offer exacly the same product and those who offer that product in other conditions relevant for the purchaser will be highlighted (for instance: “free shipping” or “same day delivery”).
Unlike traditional publications which have their own line of lists, catalogue publications do not have an exclusive line in lists but they get their visits and achieve their sales by means of lines assigned to catalogue products that appear first in the list.
Get to know even more about catalogue.


In summary:

  • Hitherto sellers have always had to create and keep publications providing their content and setting their sales conditions.
  • From now on, apart from the traditional way of publishing, it is also possible to publish in catalogue by means of a product created and kept by Mercado Libre.
  • Sellers achieve products sales competing with others who aim to provide the best conditions of purchase and experience.
  • Products will appear in the first places of searches and in the recommendations of the website.
  • Depending on the country and on the domain where you publish, catalogue has benefits of charges per sale by up to % 23.

 

Contents

→How to publish in catalogue
    ↳Publish directly in catalogue vs. from an existing publication
       ↳What are the differences?
      ↳What happens if I modify, pause or eliminate my catalogue publication linked to a traditional one?
      ↳Is there anything else to know about the management of catalogue publications?
      ↳Is it possible to publish any item in catalogue?
      ↳What happens if I associate an item with a wrong product by mistake?
    ↳Steps to publish in catalogue from an existing publication
    ↳Steps to publish directly in catalogue with no linked publication
→Verify whether a publication is eligible for catalogue
    ↳Eligibility of an existing publication without associated catalog_product_id
    ↳Eligibility of an existing publication with associated catalog_product_id
       ↳Considerations
      ↳Description of fields
    ↳Filtering of items per seller
→Determine the precise product to be sold
       ↳Products parent and children
       ↳Selecting the specific product for my publication
→Publishing in catalogue from an existing publication
→Test in order to publish in catalogue
→Direct publication in catalogue: browser of products
→Create a catalogue publication directly
→Competing to win the sales
       ↳How to know the price to win [BETA]
      ↳How to get to know the list of publications for a product [BETA]
→More about the catalogue publications
      ↳How to identify the catalogue publication and the original one
       ↳How to know the relation between linked publications
      ↳How to manage the questions of catalogue publications
      ↳How to manage orders, visits, etc.
      ↳How to manage the sales of catalogue publications
      ↳Life cycle of linked publications
      ↳What can be modified about a catalogue publication?



How to publish in catalogue

Publish directly in catalogue vs. from an existing publication

There are two ways to create catalogue publications:

  • By creating a catalogue publication from a traditional one.
  • By publishing directly in catalogue.

 

What are the differences?

Those catalogue publications which are created from a traditional one share stock with that publication. That is to say that if, by means of the item MLA1234, we create a catalogue publication whose item is MLA1235, the sale of any of those items will lead to a decrease in the stock of the other one since it is synchronised.
Linked publications allow sellers to start selling in catalogue while they continue selling by means of their traditional publications.
Catalogue publications created directly in catalogue without being linked to a traditional publication are completely independent and they do not share stock with any current publication.


What happens if I modify, pause or eliminate my catalogue publication linked to a traditional one?

Except stock, catalogue publications are items separate from traditional publications and it is possible to modify their sales conditions and to manage their life cycle independently. In case a catalogue publication is eliminated, the link to a traditional publication gets lost and in order to publish in catalogue again the process of publishing in catalogue needs to be repeated. Bear in mind that to lose the relation, the status of the catalogue item should be “delete”.


Is there anything else to know about the management of catalogue publications?

Since the content of catalogue publications is administered by Mercado Libre, the editorial fields such as title, pictures, description and attributes of the technical datasheet of the resource/items cannot be edited in catalogue publications.


The fields corresponding to the sales conditions (for example the price) are still administered by sellers. In the following sections we will explain more about all of the resources you have in order to manage sales conditions efficiently.

No, currently the requirements are the following:

  • New products (neither reconditioned nor used).
  • Sellers with green reputation.
  • In the CELLPHONES domain it is only allowed to publish unlocked mobile phones (that is to say that they work with any telephone company).

Important:

  • In order to assign a catalog_product_id it is essential that the seller completes the technical datasheet of the item.
  • If the seller includes a universal product identifier in the publication, the possibilities of associating your item with a catalog_product_id increase.
  • Whenever you have items without associated catalog_product_id, you can search it by means of the “browser of products” which will allow you to identify the correct catalog_product_id to add it in the POST at the moment of OPTING IN.

These conditions may change over time and that is why in the following section you will find the necessary tools to know whether a publication is eligible for catalogue or not.


What happens if I associate an item with a wrong product by mistake?

In catalogue publications it is extremely important not to have any discrepancy between the catalogue product and the offer.
Taking into account that the content of the products is provided by Mercado Libre, any discrepancy between the described product and the offer published by the seller would make the purchaser receive something different from the expected.
In case a mistake is detected it is essential to remove the catalogue publication by undergoing exactly the same normal process as with a marketplace publication. Firstly, you should select PUT with status= “closed” and then, another PUT with delete= “true” on the catalogue item in order to remove it.
Both the seller and the integrator can be responsible for the mistakes in the catalogue publication and they are exposed to penalties which range from developing a poor reputation to the disqualification to operate in the platform.


Steps to publish in catalogue from an existing publication

  1. We verify that the publication is eligible for the catalogue with the resource /items/{item_id}/catalog_listing_eligibility.
  2. Depending on whether the item has a catalog_product_id associated with the resource /items/{item_id}/catalog_listing_eligibility we will verify its eligibility.
  3. If the item does not have an associated catalog_product_id, we should search in the resource /products/search the catalog_product_id which coincides exactly with the product to be sold.
  4. We check that the publication without associated catalog_product_id is eligible for catalogue with the resource /items/{item_id}/catalog_listing_eligibility?catalog_product_id={catalog_product_id}&variation_id={variation_id}.
  5. We POST with the resource /items/catalog_listings in order to create the catalogue publication linked to an existing one.


Steps to publish directly in catalogue without a linked publication

  1. Search the catalog_product_id which coincides exactly with the product to be sold in the resource /products/search.
  2. Generate the JSON of the resource /items including catalog_listing=true and the catalog_product_id validated with the resource catalog_listing_eligibility.
  3. Use the resource /items to create the catalogue publication directly.

In the next sections it is shown in detail how to follow these steps.


Verify whether a the publication is eligible for catalogue

Important:
This resource is available in Argentina, Mexico and Brazil.

As it was mentioned in the previous section, at the moment only certain publications can participate in catalogue because they meet some requirements such as being new, from sellers with good reputation and in the CELLPHONES domain it is necessary for the mobile phones to be unlocked.
In order to validate and get to know the eligibility for a publication catalogue in any domain you will have to use the API catalog_listing_eligibility. Bear in mind that the answer will be different depending on whether the publication has variations or not.
In addition, you can verify whether a publication without associated catalog_product_id is eligible to be published in catalogue by using the same resource catalog_listing_eligibility and adding the parameters of catalog_product_id and variation_id, depending on the item characteristics. Take into account that to identify the correct catalog_product_id you will have to follow the corresponding steps detailed in the section browser of products.


Eligibility of an existing publication without associated catalog_product_id

Example without variation:

curl -X GET https://api.mercadolibre.com/items/MLA123456788/catalog_listing_eligibility?catalog_product_id=MLA6352027&access_token={ACCESS_TOKEN}

Response:

{
   "id": "MLA123456788",
   "site_id": "MLA",
   "domain_id": "MLA-MICROWAVES",
   "status": "READY_FOR_OPTIN",
   "buy_box_eligible": true,
   "variations": []
}

Example with variation:

curl -X GET https://api.mercadolibre.com/items/MLA123456789/catalog_listing_eligibility?catalog_product_id=MLA9452524&variation_id=43278798243&access_token=$ACCESS_TOKEN

Response:

{
  "id": "MLA123456789",
  "site_id": "MLA",
  "domain_id": "MLA-CELLPHONES",
  "status": null,
  "buy_box_eligible": null,
  "variations": [
    {
      "id": 43278798243,
      "status": "READY_FOR_OPTIN",
      "buy_box_eligible": true
    }
  ]
}

In case the item does not have a catalog_product_id and in the resource of eligibility the parameter is not sent with a correct value of catalog_product_id, the answer will state that the catalog_product_id is “null”.


Example without parameter:

curl -X GET https://api.mercadolibre.com/items/MLA123456789/catalog_listing_eligibility?access_token={ACCESS_TOKEN}

Response:

{
   "id": "MLA123456789",
   "site_id": "MLA",
   "domain_id": "MLA-MICROWAVES",
   "status": "CATALOG_PRODUCT_ID_NULL",
   "buy_box_eligible": false,
   "variations": []
}


Eligibility of an existing publication with associated catalog_product_id

The following examples show how to validate the eligibility of an existing publication to link a new catalogue publication to synchronised stock that has an associated catalog_product_id.


Call:

curl -X GET https://api.mercadolibre.com/items/{item_id}/catalog_listing_eligibility?access_token={ACCESS_TOKEN}

Example with variations:

curl -X GET https://api.mercadolibre.com/items/MLA1234/catalog_listing_eligibility?access_token={ACCESS_TOKEN}

Response:

{
    "id": "MLA1234",
    "site_id": "MLA",
    "domain_id": "MLA-CELLPHONES",
    "status": null,
    "buy_box_eligible": null,
    "variations": [
        {
            "id": 1312323,
            "status": "READY_FOR_OPTIN",
            "buy_box_eligible": true
        },
        {
            "id": 1312444,
            "status": "READY_FOR_OPTIN",
            "buy_box_eligible": true
        }
    ]
}

Example without variations:

curl -X GET https://api.mercadolibre.com/items/MLB1234/catalog_listing_eligibility?access_token={ACCESS_TOKEN}

Response:

{
    "id": "MLB1234",
    "site_id": "MLB",
    "domain_id": "MLB-MICROWAVES",
    "status": "READY_FOR_OPTIN",
    "buy_box_eligible": true,
    "variations": []
}


Considerations:

  • If the item does not have variations, the eligibility will be expressed through the first-rate field buy_box_eligible in the JSON of the answer and the variations section will be empty.
  • If the item has variations, the eligibility of each of them will be expressed in the variations section that will have an array per variation with a field buy_box_eligible for each of them.


Description of fields:

  • id: ID of the publication we are consulting about.
  • site_id: ID of the site where the item belongs to.
  • domain_id: ID of the domain where the item belongs to.
  • buy_box_eligible: It indicates whether the item/variation is enabled to participate in catalogue or not.
  • variations: They are all of the variations that an item has. Each of them will have a status and a value associated for the field buy_box_eligible.
  • status: dIt defines the situation of the traditional item as regards catalogue. These different states could be:

Eligible:

  • READY_FOR_OPTIN: The item can be published in catalogue.
  • Not eligible:

    • ALREADY_OPTED_IN: The traditional item which is consulted about already has an associated catalogue item.
    • CLOSED: The item is in such a state that cannot be longer sold.
    • PRODUCT_INACTIVE: The item is associated with a product that has not still been enabled for catalogue or it has not got an assigned catalog_product_id yet.
    • NOT_ELIGIBLE: There is a business rule that prevents the item from applying for catalogue (for example: a used mobile phone, a locked mobile phone or a seller with poor reputation).

    Bear in mind that if you consult about a catalogue item which is competing, the state will be COMPETING.


    Filtering of items per seller

    We added a filter that will let you know which publications are of catalogue and which are traditional to the resource of browser of sellers’ publications.
    To do it you will have to enter the parameter "catalog_listing" with the value true or false in the browser depending on what you want to consult. Firstly, we identify all of the seller’s catalogue items, take into accout that you will have to enter the corresponding status parameter in case you may want to add a filter such as status=“active”.


    Call:

    curl -X GET https://api.mercadolibre.com/users/{user_id}/items/search?catalog_listing=true&access_token={ACCESS_TOKEN}
    

    Example:

    curl -X GET https://api.mercadolibre.com/users/123456789/items/search?catalog_listing=true&access_token={ACCESS_TOKEN}
    

    Delimited response of catalogue items:

    {
      "seller_id": "123456789",
      "query": null,
      "paging": {
        "limit": 50,
        "offset": 0,
        "total": 8
      },
      "results": [
        "MLA123456789",
        "MLA234567890",
        "MLA345678912",
        "MLA456789123",
        "MLA567891234",
        "MLA678912345",
        "MLA789123456",
        "MLA891234567"
      ],
      "filters": [
      ],
      "available_filters": [],
      "orders": [],
      "available_orders": []
    }
    
    

    On the other hand, you will be able to filter in exactly the same way to identify all of a seller’s items which are not of catalogue.


    Call:

    curl -X GET https://api.mercadolibre.com/users/{user_id}/items/search?catalog_listing=false&access_token={ACCESS_TOKEN}
    

    Example:

    curl -X GET https://api.mercadolibre.com/users/123456789/items/search?catalog_listing=false&access_token={ACCESS_TOKEN}
    

    Delimited response of marketplace items:

    {
      "seller_id": "123456789",
      "query": null,
      "paging": {
        "limit": 50,
        "offset": 0,
        "total": 2902
      },
      "results": [
        "MLA987654321",
        "MLA123789456",
        "MLA456789123",
        "MLA132465798",
        "MLA978645312",
        "MLA312645978",
        "MLA654987321",
        "MLA123789654",
          ],
      "filters": [
      ],
      "available_filters": [],
      "orders": [],
      "available_orders": []
    }
    


    Determine the precise product to be sold

    For an item to be published in catalogue and then to be bought, it has to be associated with a specific enough product in such a way that the purchaser may know precisely what he/she is buying and which Mercado Libre has created content for (products with status=”active” in the resource /products/{catalog_product_id}).

    Important:
    The content of the catalogue publication is provided by Mercado Libre. Therefore, the seller is responsible for confirming that the product to be associated coincides with the specific characteristics shown in the platform.
    In case there is a difference between what the user buys and the associated product, it is possible that claims and/or cancellations arise and they will impact on the seller’s reputation negatively and as a result his/her disqualification to publish in catalogue, a fact that will eventually lead him/her to the suspension of the account.


    Products parent and children

    In many domains (not all of them) there are two levels of products:

    • Products of superior level (“parents”) that group specific products together and they are not suitable to be bought. For example: Motorola Moto G6 ⇐ It has got neither the capacity nor the colour specified!
    • Products of terminal level (“children”) specified enough to be bought. For example: Motorola G6 32 GB dark indigo.

    Example of a parent product (it is not specific and it cannot be bought):

    curl -X GET https://api.mercadolibre.com/products/MLA9652753

    Response:

    {
      "id": "MLA9652753",
      "status": "inactive",
      "domain_id": "MLA-CELLPHONES",
      "permalink": "https://www.mercadolibre.com.ar/p/MLA9652753",
      "name": "Motorola Moto G6",
      "buy_box_winner": null,
      "pickers": null,
      "pictures": null,
      "main_features": null,
      "attributes": [],
      "short_description": {},
      "parent_id": "",
      "children_ids": [
        "MLA9652754",
        "MLA9652755",
        "MLA9652756",
        "MLA9652757",
        "MLA9707910",
        "MLA9707911",
        "MLA9707912",
        "MLA9707913"
      ]
    }  


    Example of a children product (it is specific and it can be used to publish and buy if it is active):

    curl -X GET https://api.mercadolibre.com/products/MLA9652754

    Response:

    {
      "id": "MLA9652754",
      "status": "active",
      "domain_id": "MLA-CELLPHONES",
      "permalink": "https://www.mercadolibre.com.ar/p/MLA9652754",
      "name": "Motorola G6 32 GB Índigo oscuro",
      "buy_box_winner": {},
      "pickers": [],
      "pictures": [],
      "main_features": [],
      "attributes": [],
      "short_description": {},
      "parent_id": "MLA9652753",
      "children_ids": [
      ]
    }
    

    What interests us with the purpose of publishing is:

    • children_ids
      • If the field is empty, it is about a children product which is specific enough to be published.
      • If this array has IDs of other products, it means that the current catalog_product_id corresponds to a parent product (not completely specified). In order to publish in catalogue we should look for a specific product among its children_ids.
    • status
      • To be able to create a catalogue publication it is necessary for the product to have status=”active”.
      • “Parent” products will never have status=”active” because they are not buyable.

    Selecting the specific product for my publication

    Your publication and/or variations eligible for catalogue will have a catalog_product_id whose adequacy for its publishing you will have to verify using the resource /products/{catalog_product_id}.


    Example of “catalog_product_id” in an item:

    curl -X GET  https://api.mercadolibre.com/items/MLA123456789?access_token={ACCESS_TOKEN}

    Delimited response:

    {
        "id": "MLA123456789",
        "site_id": "MLA",
        "title": "ITEM DE TESTEO",
        "subtitle": null,
        "seller_id": 337011113,
        "category_id": "MLA22195",
        "price": 14330,
        "available_quantity": 50,
        "catalog_product_id": "MLA14793781",
        "domain_id": "MLA-AUTOMOTIVE_TIRES"
    }

    At the moment of creating a catalogue publication from an already existing and eligible one, you will have to verify with our resource of products:

    • Si el catalog_product_id If the catalog_product_id corresponds to a product with active status, you are ready to publish in catalogue using this catalog_product_id.
    • Si el catalog_product_id Whether the catalog_product_id corresponds to a product with inactive status or not.
      • If the array children_ids is empty, it means that the publication or variation is already associated with the most specific product we have and this is not ready to be published in catalogue yet, thus you will not be able to create the catalogue publication until this product is editorialised by Mercado Libre.
      • If the array children_ids is not empty, you will have to look for the one which corresponds exactly to the one you are selling among children products.
    • If you find a children catalog_product_id active that corresponds exactly to the one you want to sell, you may use it in the following step to create your catalogue publication.
    • If you cannot find the precise product among children catalog_product_id or you find it but it is inactive, you will not be able to publish that product in catalogue in this opportunity and you will have to wait for Mercado Libre to create the product and then to editorialise it.


    Publishing in catalogue from an existing publication

    Important:
    This resource is enabled in Argentina, Mexico and Brazil for selected sellers.

    Once you have checked that your existing publication is eligible for catalogue and you have obtained the active catalog_product_id which corresponds exactly to what you are publishing, you will have to create the catalogue publication from a POST in the resource /items/catalog_listings.


    About variations

    • In the domains where catalogue now exists, the catalogue publications do not accept variations since they are already associated with a specific product. Therefore, if your original publication has variations, you will have a catalogue publication per each of them. Your variations relevant information (for example the article colour) will not get lost but it will be reflected in the attributes of the catalogue product. It is possible that in the future there will be domains in which the product never finishes specifying perfectly well what is being sold (for example clothing sizes) and it is also feasible that variations will be allowed. We will let you know that when it occurs.
    • If your existing item has variations, you will have to POST per each of them sending the field variation_id

    Example of an item with variations:

    curl -X POST https://api.mercadolibre.com/items/catalog_listings?access_token={ACCESS_TOKEN}
    {
      "item_id":"MLA1234",
      "variation_id": 4321,
      "catalog_product_id":"MLA9876"
    }

    Example of an item without variations:

    curl -X POST https://api.mercadolibre.com/items/catalog_listings?access_token={ACCESS_TOKEN}
    {
      "item_id":"MLA1234",
      "catalog_product_id":"MLA9876" 
    }

    Delimited example of an answer to the creation of an item:

    Response:

    {
        "id": "MLA1234",
        "site_id": "MLA",
        "title": "Samsung Galaxy J7 Prime 16 Gb Negro",
        "warranty": null,
        "catalog_product_id": "MLA9876",
        "domain_id": "MLA-CELLPHONES",
        "seller_custom_field": null,
        "parent_item_id": null,
        "differential_pricing": null,
        "deal_ids": [],
        "automatic_relist": false,
        "date_created": "2019-08-02T11:33:31.270Z",
        "last_updated": "2019-08-02T11:33:31.270Z",
        "total_listing_fee": null,
        "health": null,
        "catalog_listing": true,
        "item_relations": [
            {
                "id": "MLA123456789",
                "variation_id": null,
                "stock_relation": 1
            }
        ]
    }

    In addition, bear in mind that:

    • If the item is sent without variations when it actually has them, the POST will fail indicating an error 400.
    • catalog_product_id The catalog_product_id is a compulsory field in the POST regardless of whether the item has variations or not.

    Test in order to publish in catalogue

    To orient yourself and carry out tests, you will be able to use a testing user, to create an item that complies with all of the necessary conditions in order to be suitable for catalogue, to identify which the specifically active product in catalogue is that can be associated with and then POST in the resource /items/catalog_listings.
    Clarifitation: The testing publication will NOT compete in catalogue.
    Steps:

    1. Create a testing user and a testing item which will not have an associated catalog_product_id.
    2. Validate the created item with the resource of /products/search to find out which the correct catalog_product_id is for the item.
    3. Once the catalog_product_id has been identified, the eligibility will be able to be verified with the resource /items/{item_id}/catalog_listing_eligibility adding the parameter catalog_product_id and variation depending on the item characteristics. In this way it will be verified whether the item is eligible for catalogue or not.
    4. Once identified that the item together with the catalog_product_id are eligible, the next step will consist in OPTING IN to finish associating the testing item with a catalogue one.
    5. We POST with the resource /items/catalog_listings in order to create the catalogue publication associated with the testing item.


    Direct publication in catalogue: browser of products

    Important:
    This resource is available in Argentina, Mexico and Brazil.

    To publish directly in catalogue it is necessary to locate the catalog_product_id that corresponds exactly to the offer which is to be published. With this resource you will obtain a suggestion of products based on certain search parameters.

    Important:
    The content of the catalogue publication is provided by Mercado Libre. Therefore, the seller is responsible for confirming that the product to be associated with coincides with the specific characteristics shown in the platform.
    In case there is a difference between what the user buys and the associated product, it is possible that claims and/on cancellations arise and that they will impact on the seller’s reputation negatively and as a result his/her disqualification to publish in catalogue leading eventually to the suspension of the account.

    The parameters of the browser of products may be a universal code or a group of key words, for instance brand and model.

    Parameters:

    • site_id: String that represents the country. It is compulsory.
    • status: Although the product may be identified in our catalogue, it could not be eligible to be associated with a publication yet.

    -status=active: It gives back all those products that can already be selected to associate with a publication.

    -status=inactive: It gives back all those products that are not eligible to associate with a publication yet.

    Clarification: If this parameter is not sent, both active and inactive results will be automatically brought.

    • q: String with key words of search. Example: “Mobile phone Samsung Galaxy S8”. It is compulsory in case a product_identifier is not sent.
    • product_identifier: String with a universal code of the product. Example: EAN, UPC, ISBN, etc. It is compulsory in case a group of key words is not sent.
    • domain_id: String with the domain where you want to publish (optional).
    • offset: Position from which the results of search are given back (optional).
    • limit: Number of results that the search gives back (optional).

    Call with parameter “q”:

    curl -X GET https://api.mercadolibre.com/products/search?status={status_id}&site_id={site_id}&q={q}

    Example with parameter “q”:

    curl -X GET https://api.mercadolibre.com/products/search?status=active&site_id=MLA&q=Samsung%20Galaxy%20S8

    Response with parameter “q”:

    {
        "keywords": "Samsung Galaxy S8",
        "paging": {
            "total": 5,
            "limit": 10,
            "offset": 0
        },
        "results": [
            {
                "id": "MLA6408700",
                "status": "active",
                "domain_id": "MLA-CELLPHONES",
                "name": "Samsung Galaxy S8 64 GB Oro arce",
                "attributes": [
                    {
                        "id": "BRAND",
                        "name": "Marca",
                        "value_id": "206",
                        "value_name": "Samsung"
                    },
                ],
                "pictures": [
                    {
                        "id": "661005-MLA31003118709_062019",
                        "url": "https://mla-s2-p.mlstatic.com/661005-MLA31003118709_062019-F.jpg"
                    },
                    {
                        "id": "622366-MLA31003080250_062019",
                        "url": "https://mla-s2-p.mlstatic.com/622366-MLA31003080250_062019-F.jpg"
                    },
                    {
                        "id": "807399-MLA31003000897_062019",
                        "url": "https://mla-s2-p.mlstatic.com/807399-MLA31003000897_062019-F.jpg"
                    },
                    {
                        "id": "785278-MLA31003118710_062019",
                        "url": "https://mla-s1-p.mlstatic.com/785278-MLA31003118710_062019-F.jpg"
                    }
                ]
            }
        ]
    }
    

    Call with parameters “q” and “domain_id”:

    curl -X GET https://api.mercadolibre.com/products/search?status={status_id}&site_id={site_id}&q={q}&domain_id={domain_id}

    Example with parameters “q” and “domain_id”:

    curl -X GET https://api.mercadolibre.com/products/search?status=active&site_id=MLA&q=Samsung%20Galaxy%20S8&domain_id=MLA-CELLPHONES

    Answer with parameters “q” and “domain_id”:

    {
      "q": "Samsung Galaxy S8",
      "domain_id":"MLA-CELLPHONES",
      "paging": {
        "total": 10,
        "offset": 0,
        "limit": 10
      },
      "results": [
        {
          "id": "MLA6408699",
          "status": "active",
          "domain_id": "MLA-CELLPHONES",
          "name": "Samsung Galaxy S8 64 GB Gris orquídea",
          "description": "descripción",
          "attributes": [
            {
              "id": "BRAND",
              "name": "Marca",
              "value_id": "206",
              "value_name": "Samsung"
            }
          ],
          "pictures": [
            {
              "id": "924348-MLA31003000895_062019",
              "url": "https://mla-s2-p.mlstatic.com/924348-MLA31003000895_062019-F.jpg"
            }
          ]
        }
      ]
    }
    

     

    Call with parameter “product_identifier”:

    curl -X GET https://api.mercadolibre.com/products/search?status={status_id}&site_id={site_id}&product_identifier={product_identifier}

    Example with parameter “product_identifier”:

    curl -X GET https://api.mercadolibre.com/products/search?status=active&site_id=MLA&product_identifier=0123456789

    Answer with parameter “product_identifier”:

    { 
      "product_identifier": "0123456789", 
      "paging": {
          "total": 10, 
          "offset": 0, 
          "limit": 10 
       }, 
       "results": [ 
            { 
              "id": "MLA6408699", 
              "status": "active", 
              "domain_id": "MLA-CELLPHONES", 
              "name": "Samsung Galaxy S8 64 GB Gris orquídea", 
              "description": "descripción", 
              "attributes": [
                    { 
                       "id": "BRAND", 
                      "name": "Marca", 
                      "value_id": "206", 
                      "value_name": "Samsung" 
                    } 
               ], 
             "pictures": [ 
                  { 
                     "id": "924348-MLA31003000895_062019", 
                     "url": "https://mla-s2-p.mlstatic.com/924348-MLA31003000895_062019-F.jpg" 
                  } 
               ] 
            } 
         ] 
      }
    
    

    Considerations:

    • According to the parameters used for the search, we will obtain as a result one or several products as suggestions.
    • If a product_identifier is used as a parameter, only one product will be obtained.
    • If a key word is used as a parameter, either with or without a domain, one or several products that are related to the entered values may be obtained.

     

    Create a catalogue publication directly

    Apart from creating catalogue publications with an original one, you can also create catalogue items with no need to have a marketplace item to link. Bear in mind that in order to create a catalogue item you will have to consider the same requirements shown in Publish the item in catalogue.
    Important: Bear in mind that at the moment of POSTING it is necessary to send the following values in order to create the catalogue publication.

    • "catalog_product_id": This value should be confirmed with the resource of search/product.
    • "catalog_listing": true: It is necessary to send the value in true to create the catalogue item.

    • Call:

      curl -X POST https://api.mercadolibre.com/items?access_token={ACCESS_TOKEN}

      Example:

      curl -X POST -H "Content-Type: application/json" -d
      '{
          "site_id": "MLA",
          "title": "Item de test no ofertar",
          "category_id": "MLA1055",
          "price": 10000000,
          "currency_id": "ARS",
          "available_quantity": 1,
          "buying_mode": "buy_it_now",
          "listing_type_id": "gold_special",
          "pictures": [],
          "attributes": [
              {
                  "id": "CARRIER",
                  "name": "Compañía telefónica",
                  "value_id": "298335",
                  "value_name": "Liberado",
                  "value_struct": null,
                  "attribute_group_id": "OTHERS",
                  "attribute_group_name": "Otros"
              },
              {
                  "id": "ITEM_CONDITION",
                  "name": "Condición del ítem",
                  "value_id": "2230284",
                  "value_name": "Nuevo",
                  "value_struct": null,
                  "attribute_group_id": "OTHERS",
                  "attribute_group_name": "Otros"
              }
          ],
          "catalog_product_id": "MLA6005934",
          "catalog_listing": true
      }'
      https://api.mercadolibre.com/items?access_token=$ACCESS_TOKEN
      

      Response:

      {
          "id": "MLA811894603",
          "site_id": "MLA",
          "title": "Apple iPhone iPhone 3g 8 Gb Negro 128 Mb Ram",
          "subtitle": null,
          "seller_id": 464161506,
          "category_id": "MLA1055",
          "official_store_id": null,
          "price": 10000000,
          "base_price": 10000000,
          "original_price": null,
          "inventory_id": null,
          "currency_id": "ARS",
          "initial_quantity": 1,
          "available_quantity": 1,
          "sold_quantity": 0,
          "sale_terms": [],
          "buying_mode": "buy_it_now",
          "listing_type_id": "gold_special",
          "start_time": "2019-08-29T14:49:42.945Z",
          "historical_start_time": "2019-08-29T14:49:42.945Z",
          "stop_time": "2039-08-24T04:00:00.000Z",
          "end_time": "2039-08-24T04:00:00.000Z",
          "expiration_time": "2019-11-17T14:49:42.987Z",
          "condition": "new",
          "permalink": "http://articulo.mercadolibre.com.ar/MLA-811894603-apple-iphone-iphone-3g-8-gb-negro-128-mb-ram-_JM",
          "pictures": [
              {
                  "id": "675782-MLA31138875214_062019",
                  "url": "http://mla-s1-p.mlstatic.com/675782-MLA31138875214_062019-O.jpg",
                  "secure_url": "https://mla-s1-p.mlstatic.com/675782-MLA31138875214_062019-O.jpg",
                  "size": "249x500",
                  "max_size": "598x1200",
                  "quality": ""
              },
              {
                  "id": "915001-MLA31138546867_062019",
                  "url": "http://mla-s2-p.mlstatic.com/915001-MLA31138546867_062019-O.jpg",
                  "secure_url": "https://mla-s2-p.mlstatic.com/915001-MLA31138546867_062019-O.jpg",
                  "size": "250x500",
                  "max_size": "600x1200",
                  "quality": ""
              },
              {
                  "id": "881441-MLA31138332972_062019",
                  "url": "http://mla-s2-p.mlstatic.com/881441-MLA31138332972_062019-O.jpg",
                  "secure_url": "https://mla-s2-p.mlstatic.com/881441-MLA31138332972_062019-O.jpg",
                  "size": "243x500",
                  "max_size": "585x1200",
                  "quality": ""
              },
              {
                  "id": "804666-MLA31139286536_062019",
                  "url": "http://mla-s1-p.mlstatic.com/804666-MLA31139286536_062019-O.jpg",
                  "secure_url": "https://mla-s1-p.mlstatic.com/804666-MLA31139286536_062019-O.jpg",
                  "size": "405x500",
                  "max_size": "836x1030",
                  "quality": ""
              }
          ],
          "video_id": null,
          "descriptions": [
              {
                  "id": "MLA811894603-2265773390"
              }
          ],
          "accepts_mercadopago": true,
          "non_mercado_pago_payment_methods": [],
          "shipping": {
              "mode": "not_specified",
              "local_pick_up": false,
              "free_shipping": false,
              "methods": [],
              "dimensions": null,
              "tags": [],
              "logistic_type": "not_specified",
              "store_pick_up": false
          },
          "international_delivery_mode": "none",
          "seller_address": {
              "id": 1061221617,
              "comment": "",
              "address_line": "Test Address 123",
              "zip_code": "1414",
              "city": {
                  "id": "",
                  "name": "Palermo"
              },
              "state": {
                  "id": "AR-C",
                  "name": "Capital Federal"
              },
              "country": {
                  "id": "AR",
                  "name": "Argentina"
              },
              "latitude": 38.11569,
              "longitude": 13.3614868,
              "search_location": {
                  "neighborhood": {
                      "id": "TUxBQlBBTDI1MTVa",
                      "name": "Palermo"
                  },
                  "city": {
                      "id": "TUxBQ0NBUGZlZG1sYQ",
                      "name": "Capital Federal"
                  },
                  "state": {
                      "id": "TUxBUENBUGw3M2E1",
                      "name": "Capital Federal"
                  }
              }
          },
          "seller_contact": null,
          "location": {},
          "geolocation": {
              "latitude": 38.11569,
              "longitude": 13.3614868
          },
          "coverage_areas": [],
          "attributes": [
              {
                  "id": "CARRIER",
                  "name": "Compañía telefónica",
                  "value_id": "298335",
                  "value_name": "Liberado",
                  "value_struct": null,
                  "attribute_group_id": "OTHERS",
                  "attribute_group_name": "Otros"
              },
              {
                  "id": "ITEM_CONDITION",
                  "name": "Condición del ítem",
                  "value_id": "2230284",
                  "value_name": "Nuevo",
                  "value_struct": null,
                  "attribute_group_id": "OTHERS",
                  "attribute_group_name": "Otros"
              },
              {
                  "id": "BRAND",
                  "name": "Marca",
                  "value_id": "9344",
                  "value_name": "Apple",
                  "value_struct": null,
                  "attribute_group_id": "OTHERS",
                  "attribute_group_name": "Otros"
              },
              {
                  "id": "LINE",
                  "name": "Línea",
                  "value_id": "58993",
                  "value_name": "iPhone",
                  "value_struct": null,
                  "attribute_group_id": "OTHERS",
                  "attribute_group_name": "Otros"
              },
              {
                  "id": "MODEL",
                  "name": "Modelo",
                  "value_id": "14605",
                  "value_name": "iPhone 3G",
                  "value_struct": null,
                  "attribute_group_id": "OTHERS",
                  "attribute_group_name": "Otros"
              },
              {
                  "id": "IS_DUAL_SIM",
                  "name": "Es Dual SIM",
                  "value_id": "242084",
                  "value_name": "No",
                  "value_struct": null,
                  "attribute_group_id": "OTHERS",
                  "attribute_group_name": "Otros"
              },
              {
                  "id": "COLOR",
                  "name": "Color",
                  "value_id": "52049",
                  "value_name": "Negro",
                  "value_struct": null,
                  "attribute_group_id": "OTHERS",
                  "attribute_group_name": "Otros"
              },
              {
                  "id": "INTERNAL_MEMORY",
                  "name": "Memoria interna",
                  "value_id": "59566",
                  "value_name": "8 GB",
                  "value_struct": {
                      "number": 8,
                      "unit": "GB"
                  },
                  "attribute_group_id": "OTHERS",
                  "attribute_group_name": "Otros"
              },
              {
                  "id": "RAM",
                  "name": "Memoria RAM",
                  "value_id": "366239",
                  "value_name": "128 MB",
                  "value_struct": {
                      "number": 128,
                      "unit": "MB"
                  },
                  "attribute_group_id": "OTHERS",
                  "attribute_group_name": "Otros"
              },
              {
                  "id": "MAIN_COLOR",
                  "name": "Color principal",
                  "value_id": "2450295",
                  "value_name": "Negro",
                  "value_struct": null,
                  "attribute_group_id": "OTHERS",
                  "attribute_group_name": "Otros"
              },
              {
                  "id": "OPERATING_SYSTEM_NAME",
                  "name": "Nombre del sistema operativo",
                  "value_id": "7404961",
                  "value_name": "iOS",
                  "value_struct": null,
                  "attribute_group_id": "OTHERS",
                  "attribute_group_name": "Otros"
              },
              {
                  "id": "WITH_IMEI",
                  "name": "Con IMEI",
                  "value_id": "242085",
                  "value_name": "Sí",
                  "value_struct": null,
                  "attribute_group_id": "OTHERS",
                  "attribute_group_name": "Otros"
              }
          ],
          "warnings": [],
          "listing_source": "",
          "variations": [],
          "thumbnail": "http://mla-s1-p.mlstatic.com/675782-MLA31138875214_062019-I.jpg",
          "secure_thumbnail": "https://mla-s1-p.mlstatic.com/675782-MLA31138875214_062019-I.jpg",
          "status": "active",
          "sub_status": [],
          "tags": [
              "immediate_payment",
              "test_item"
          ],
          "warranty": null,
          "catalog_product_id": "MLA6005934",
          "domain_id": "MLA-CELLPHONES",
          "seller_custom_field": null,
          "parent_item_id": null,
          "differential_pricing": null,
          "deal_ids": [],
          "automatic_relist": false,
          "date_created": "2019-08-29T14:49:43.099Z",
          "last_updated": "2019-08-29T14:49:43.099Z",
          "total_listing_fee": null,
          "health": null,
          "catalog_listing": true,
          "item_relations": []
      }
      

       

      Competing to win the sales

      How to know the price to win [BETA]

      Important:
      This resource is in BETA and the answer will be changing on the following days. Bear in mind that temporarily in order to carry out tests you will have to use the current answer, however in this guide we file all the definitive answers that you will see in a few days.

      The catalogue publications compete to achieve the sales of the product page and there is an algorithm which determines who the winner of all those sales will be based on the characteristics of the publication and of the seller.
      The algorithm that assesses which publication will be the winner takes into account the following:

      • The publication price
      • Interest-free installments
      • Full delivery, free shipping and same day delivery

      Notes:

      • Some of these characteristics may only be applied to some purchasers (for example: same day delivery or discount of Mercado Puntos). In these cases we make the best effort to choose a winner considering the particular purchaser bearing also in mind what characteristics apply to him/her.
      • According to what was previously mentioned, we will talk about the “winner” in an univocal way, the seller could eventually be winning in general but not particularly for certain users (for example, if they live very far and they would never obtain a same day delivery).

      For the sellers to compete efficiently, we offer a resource that indicates which the price is with the one you would win the sales keeping the rest of the conditions unchanged (at this moment deliveries and financing).


      Call:

      curl -X GET https://api.mercadolibre.com/items/{item_id}/price_to_win?access_token={ACCESS_TOKEN}

      Example:

      curl -X GET https://api.mercadolibre.com/items/MLB1234/price_to_win?access_token={ACCESS_TOKEN}

      Response:

      {
        "item_id": "MLA1234",
        "current_price": 580.00,
        "price_to_win": 560.28,
        "boosts": {
              "fulfillment”: true,
              "free_shipping” : true,
        "same_day_shipping”: true,
        "free_installments”: false
        },
        "status": "competing"
      }
      

       

      How to read the response:

      • The field status indicates whether we are winning for the general public (we could be winning for minority segments such as those who do not benefit from the same day delivery). When we are winning the value is winning, but when we are not it is competing.
      • The field boosts indicates which characteristics of our publication are contributing to our chances of winning. The possibilities are:
        • fulfillment: for publications located in the centre of fulfillment.
        • free_shipping: when the publication offers free shipping.
        • same_day_shipping: in cases that the article can be sent on the same day.
        • free_installments: when interest free installments are offered for the publication.
      • The field price_to_win indicates what the price is (the present currency of the publication) to be the winner. That is to say that by PUTTING the suggested price in the resource/items you may surely be the winner.

      In this call you will have to use an item_id of a catalogue publication, in case you do not do it you will obtain an error code 4XX.
      Moreover, there are variables such as the reputation that are used to determine the winner. However, for a good seller, the variables used to determine the winner will be the previous ones.
      Important: Shortly, we will have a resource to receive notifications when the seller becomes the winner of a product.

      How to get to know the list of publications for a product [BETA]

      Important:
      This API is in BETA, the answer will change on the following days so temporarily you will have to use the current answer for tests. However, in this guide we file all of the definitive answers that you will come to see in a few days.

      If you need to know which articles (of all of the sellers) are the ones that compete for the sales of a particular product, you have a resource that provides you with that information.


      Call:

      curl -X GET https://api.mercadolibre.com/products/{product_id}/items

      Example:

      curl -X GET https://api.mercadolibre.com/products/MLB6309815/items

      Simplified response:

      {
        "paging": {
          "total": 3,
          "offset": 0,
          "limit": 100
        },
        "results": [
        { 
               "item_id": "MLB123456789",
               "category_id": "MLB73057",
               "seller_id": 111111111,
               "price": 560.00,
      
           },
           { 
               "item_id": "MLB345678912",
               "category_id": "MLB73057",
               "seller_id": 222222222,
               "price": 600.00,
           },
            { 
               "item_id": "MLB789123456",
               "category_id": "MLB73057",
               "seller_id": 333333333,
               "price": 650.00,
           }
        ]
        "available_filters": []
        “filters”: []
      }
      

      Take into account that “results” will firstly give the winning item back and consequently the rest of the items that are competing.

       

      Filtering [BETA]

      Soon the possibility of filtering in this API will be available. This filtering will work in exactly the same way as in the resource of Search (/sites/{site}/search) where it is possible to use the values of available_filters as a parameter in the URL, for instance:


      Example:

      curl -X GET https://api.mercadolibre.com/products/MLB6309815/items?shipping=free


      More about the catalogue publications

      Creating a catalogue publication linked to an existing one implies creating a new item of resource /items with its own and unique ID. By creating the new catalogue item, you will receive notifications both about creation and modification, in the way you already know. Delimited example of a consultation on the traditional publication.


      Call:

      curl -X GET https://api.mercadolibre.com/items/{item_id}?access_token={ACCESS_TOKEN}

      Example:

      curl -X GET https://api.mercadolibre.com/items/MLA1234?access_token={ACCESS_TOKEN}

      Response:

      { 
        "variations": [ 
           { 
            "id": 36296213011, 
            "price": 50, 
            "attribute_combinations": [
               { 
                 "id": "COLOR", 
                 "name": "Color", 
                 "value_id": "52014", 
                 "value_name": "Verde" 
               }, 
               { 
                 "id": "SIZE", 
                 "name": "Talle", 
                 "value_id": null, 
                 "value_name": "8 litros" 
              } 
           ], 
           "available_quantity": 2, 
           "sold_quantity": 0, 
           "sale_terms": [], 
           "picture_ids": [ 
              "937728-MLB26910896929_1111111", 
              "911601-MLB26910896930_1111111", 
              "762115-MLB26910896931_1111111", 
              "827037-MLB26910896928_1111111" 
           ], 
          "seller_custom_field": null, 
          "catalog_product_id": null,
          "attributes": [ 
              { 
                "id": "T_SHIRT_SIZE", 
               "name": "Talle de la remera", 
               "value_id": "5727532", 
               "value_name": "6XL" 
             } 
           ], 
          "item_relations": [ 
             { 
               "id": "MLA987654321", 
               "variation_id": null, 
               "stock_relation": 1 
             }
           ]
          } 
        ], 
          "catalog_listing": false, 
          "item_relations": [] 
      }

       

      Delimited example of a catalogue item:

      Call:

      curl -X GET https://api.mercadolibre.com/items/{item_id}/?access_token={ACCESS_TOKEN}

      Answer:

      curl -X GET https://api.mercadolibre.com/items/MLA1234?access_token={ACCESS_TOKEN}

      Response:

      {
         "variations": [], 
         "catalog_listing": true, 
         "item_relations": [
              { 
                "id": "MLA1234", 
                "variation_id": 36296213006, 
                "stock_relation": 1 
              }
          ] 
       }


      How to identify the catalogue publication and the original one

      In order to understand which the catalogue publication is and which the traditional one is you have the resource /ítems of the field catalog_listing.. If this has the value “true”, it is a catalogue publication. If it has the value “false”, it is the traditional linked item. To see the complete information about the item, you will have to use the access token.


      How to know the relation between linked publications

      The field item_relations in the resource /items (with access token) will show you which publications are linked to the current one. The only piece of information that will be shared in both publications is the stock. For this reason when the seller achieves a sale or modifies the amount in a publication the stock will be modified in both of them automatically.
      In the future there could be multiple linked publications and the relation of stock decrease could be different from 1. Bear in mind this when designing your system.


      How to manage the questions about catalogue publications

      The questions about catalogue publications are managed in the same way as the traditional publications but they are not synchronised. This means that both questions and answers that you will receive about catalogue publications will not appear in the traditional publications and vice versa.
      On the site, when a question is made on the product page, this consultation remains associated with the item that is winning only at that moment and they are not shared with other items that may win at another moment on the product page.

       

      How to manage orders, visits, etc.

      Catalogue publications are items as any others, thus the management of orders is the same as that of a traditional publication, just that these orders will have the tag catalog to differentiate them from those of Marketplace. In the answer of the resource /orders, the item_id will make reference to the one the purchase has been made.

      The linked publications do not share any other piece of information apart from the stock. For instance, visits and sales which are completely separated among publications.
      Delimited example of a catalogue order:

       

      Call:

      curl -X GET https://api.mercadolibre.com/orders/{order_id}?access_token={ACCESS_TOKEN} 

      Example:

      curl -X GET https://api.mercadolibre.com/orders/1234567890?access_token={ACCESS_TOKEN} 

      Response:

      {
        "id": 1234567890,
        "date_created": "2019-08-27T23:39:10.000-04:00",
        "date_closed": "2019-08-28T10:46:14.000-04:00",
        "last_updated": "2019-08-28T10:46:14.000-04:00",
        "manufacturing_ending_date": null,
        "feedback": {},
        "mediations": [
        ],
        "comments": null,
        "pack_id": null,
        "pickup_id": null,
        "order_request": {},
        "fulfilled": null,
        "total_amount": 16000,
        "total_amount_with_shipping": 16000,
        "paid_amount": 16000,
        "coupon": {},
        "expiration_date": "2019-09-25T10:46:14.000-04:00",
        "order_items": [
          {
            "item": {
              "id": "MLA123456789",
              "title": "Motorola G6 Plus 64 Gb",
              "category_id": "MLA1055",
              "variation_id": null,
              "seller_custom_field": "MO-CEL-N0011",
              "variation_attributes": [
              ],
              "warranty": "Garantía de fábrica: 12 meses",
              "condition": "new",
              "seller_sku": "MO-CEL-N0011"
            },
            "quantity": 1,
            "unit_price": 16000,
            "full_unit_price": 16000,
            "currency_id": "ARS",
            "manufacturing_days": null
          }
        ],
        "currency_id": "ARS",
        "payments": [],
        "shipping": {},
        "status": "paid",
        "status_detail": null,
        "tags": [
          "catalog",
          "not_delivered",
          "paid"
        ],
        "buyer": {},
        "seller": {},
        "taxes": {
          "amount": null,
          "currency_id": null
        }
      }
      

       

      How to manage the sales of catalogue publications

      The sales of catalogue publications are managed in the same way as those of traditional publications. This means that per each sale that is achieved from a catalogue item, it will be created an order with the same information that contains a sale of a traditional publication but we will only be able to identify them with the tag catalog. The order will have the catalogue item associated and notifications will be sent both when it is created and when its information gets updated.


      Life cycle of linked publications

      If you eliminate or pause a marketplace item variant related to a catalogue item, the relation between publications will get lost, but the catalogue item will not be deactivated. If you happen to eliminate the catalogue item, the traditional publication will remain active.
      Catalogue publications can be created and eliminated when necessary. Sellers with a stable behaviour of sales will not have their capacity to achieve sales of the product page affected because of the record of publication sales.


      What can be modified about a catalogue publication?

      Sales conditions such as the price, the type of delivery and the condition may be modified. At the same time these same conditions can be different from those of the original publication.
      Neither images, titles, descriptions, technical datasheets nor the product condition can be modified since they are data normalised by Mercado Libre.

Be part of our community