Products search

Contents

→Search products
→Determine the exact product to sell
→Product by ID
→Parents and children products
→Choose the specific product to list


Search products

Before list a product in the catalog, you must confirm, using the product search engine, the correct product that you will sell, if it is active and its characteristics. This resource allows you to identify the products to publish directly in the catalog and/or through associated publications .
The products search parameters of the product finder can be the universal code or a set of keywords, for example brand and model. Adding to the options the possibility of performing a POST with a combination of catalog attributes.


Parameters

site_id: (required) string that represents the country.
status: It may be that although the product is identified within our catalog, it isn´t yet eligible to associate with a publication.

  • status=active: returns those products that can already be chosen to associate with a publication.
  • status=inactive: returns those products that aren´t yet eligible to associate with a publication.
Note:
If you don't send this parameter, by default it will bring all the results, both active and inactive.

q: string with search keywords. Example: "Samsung Galaxy S8 cellphone". Mandatory in case a product_identifier isn´t sent.
product_identifier: (required) string with the universal product code. Example: GTIN which includes the different PIs (EAN, UPC, ISBN, etc). Mandatory in case a string of keywords isn´t sent.
domain_id: (optional) string with the domain in which you want to publish.
offset: (optional) position from which the search results are returned.
limit: (optional) number of results returned by the search.


Request with “q” parameter:

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

Example with “q” parameter:

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

Response with “q” parameter:

{
    "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"
                }
            ]
        }
    ]
}

Request with “q” and “domain_id” parameters:

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

Example with “q” and “domain_id” parameters:

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

Response with “q” and “domain_id” parameters:

{
  "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"
        }
      ]
    }
  ]
}

Request with “product_identifier” parameter:

curl -X GET https://api.mercadolibre.com/products/search?status=$STATUS_ID&site_id=$SITE_ID&product_identifier=$PRODUCT_IDENTIFIER

Example with “product_identifier” parameter:

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

Response with “product_identifier”vparameter:

{ 
  "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" 
              } 
           ] 
        } 
     ] 
  }

Example with catalog attributes:

curl -X POST https://api.mercadolibre.com/products/search?access_token=$ACCESS_TOKEN
{
   "domain_id":"MLA-CELLPHONES",
   "site_id":"MLA",
   "status":"active",
   "attributes":  [
        {
         "id": "BRAND",
         "value_id": "206"
        },
        {
         "id": "LINE",
         "value_name": "Galaxy"
        },
        {
         "id": "IS_DUAL_SIM",
         "value_name": "Si"
        }
   ]
}

Short response with catalog attributes:

{
    "domain_id": "MLA-CELLPHONES",
    "paging": {
        "total": 9,
        "limit": 10,
        "offset": 0
    },
    "results": [
        {
            "id": "MLA13316403",
            "status": "active",
            "domain_id": "MLA-CELLPHONES",
            "settings": {
                "listing_strategy": "open"
            },
            "name": "Samsung Galaxy Folder 2 Dual SIM 16 GB Negro 2 GB RAM",
            "attributes": [
                {
                    "id": "BRAND",
                    "name": "Marca",
                    "value_id": "206",
                    "value_name": "Samsung"
                },
                {
                    "id": "LINE",
                    "name": "Línea",
                    "value_id": "43675",
                    "value_name": "Galaxy"
                },
                {
                    "id": "MODEL",
                    "name": "Modelo",
                    "value_id": "8212554",
                    "value_name": "Folder 2 Duos"
                },
                {
                    "id": "IS_DUAL_SIM",
                    "name": "Es Dual SIM",
                    "value_id": "242085",
                    "value_name": "Sí"
                },
                {
                    "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": "445970",
                    "value_name": "2 GB"
                },
                {
                    "id": "MAIN_COLOR",
                    "name": "Color principal",
                    "value_id": "2450295",
                    "value_name": "Negro"
                },
                {
                    "id": "OPERATING_SYSTEM_NAME",
                    "name": "Nombre del sistema operativo",
                    "value_id": "7403813",
                    "value_name": "Android"
                },
                {
                    "id": "OPERATING_SYSTEM_VERSION",
                    "name": "Versión del sistema operativo",
                    "value_id": "7206970",
                    "value_name": "6.0 Marshmallow"
                },
                {
                    "id": "DISPLAY_SIZE",
                    "name": "Tamaño de la pantalla",
                    "value_id": "7762087",
                    "value_name": "3.8 \""
                },
                {
                    "id": "DISPLAY_RESOLUTION",
                    "name": "Resolución de la pantalla",
                    "value_id": "7222488",
                    "value_name": "480 px x 800 px"
                },
                {
                    "id": "MAIN_REAR_CAMERA_RESOLUTION",
                    "name": "Resolución de la cámara trasera principal",
                    "value_id": "7199614",
                    "value_name": "8 Mpx"
                },
                {
                    "id": "REAR_CAMERA_RECORDING_RESOLUTION",
                    "name": "Resolución de video de la cámara trasera",
                    "value_id": "7199621",
                    "value_name": "1920 px x 1080 px"
                },
                {
                    "id": "MAIN_FRONT_CAMERA_RESOLUTION",
                    "name": "Resolución de la cámara frontal principal",
                    "value_id": "7199627",
                    "value_name": "5 Mpx"
                },
                {
                    "id": "WITH_FINGERPRINT_READER",
                    "name": "Con lector de huella digital",
                    "value_id": "242084",
                    "value_name": "No"
                },
                {
                    "id": "BATTERY_CAPACITY",
                    "name": "Capacidad de la batería",
                    "value_id": "8212557",
                    "value_name": "1950 mAh"
                },
                {
                    "id": "NUMBER_OF_SIM_CARD_SLOTS",
                    "name": "Cantidad de ranuras para tarjeta SIM",
                    "value_id": "2087802",
                    "value_name": "2"
                },
                {
                    "id": "SIM_SIZES",
                    "name": "Tamaños de tarjeta SIM compatibles",
                    "value_id": "80453",
                    "value_name": "Nano-SIM"
                },
                {
                    "id": "WITH_ESIM",
                    "name": "Con eSIM",
                    "value_id": "242084",
                    "value_name": "No"
                },
                {
                    "id": "WEIGHT",
                    "name": "Peso",
                    "value_id": "2087854",
                    "value_name": "165 g"
                },
                {
                    "id": "HEIGHT",
                    "name": "Altura",
                    "value_id": "4369069",
                    "value_name": "122 mm"
                },
                {
                    "id": "WIDTH",
                    "name": "Ancho",
                    "value_id": "7936922",
                    "value_name": "60.2 mm"
                },
                {
                    "id": "DEPTH",
                    "name": "Profundidad",
                    "value_id": "8212558",
                    "value_name": "16.1 mm"
                },
                {
                    "id": "PIXELS_PER_INCH",
                    "name": "Píxeles por pulgada",
                    "value_id": "8212555",
                    "value_name": "246 ppi"
                },
                {
                    "id": "SCREEN_TECHNOLOGY",
                    "name": "Tecnología de pantalla",
                    "value_id": "80489",
                    "value_name": "TFT"
                },
                {
                    "id": "WITH_TOUCH_SCREEN",
                    "name": "Con pantalla táctil",
                    "value_id": "242085",
                    "value_name": "Sí"
                },
                {
                    "id": "WITH_PHYSICAL_QWERTY_KEYBOARD",
                    "name": "Con teclado QWERTY físico",
                    "value_id": "242084",
                    "value_name": "No"
                },
                {
                    "id": "WITH_CAMERA",
                    "name": "Con cámara",
                    "value_id": "242085",
                    "value_name": "Sí"
                },
                {
                    "id": "REAR_CAMERAS_NUMBER",
                    "name": "Cantidad de cámaras traseras",
                    "value_id": "7477198",
                    "value_name": "1"
                },
                {
                    "id": "REAR_CAMERA_APERTURE",
                    "name": "Apertura del diafragma de la cámara trasera",
                    "value_id": "7441410",
                    "value_name": "f 1.9"
                },
                {
                    "id": "FRONT_CAMERAS_NUMBER",
                    "name": "Cantidad de cámaras frontales",
                    "value_id": "7477216",
                    "value_name": "1"
                },
                {
                    "id": "FRONT_CAMERA_RECORDING_RESOLUTION",
                    "name": "Resolución de video de la cámara frontal",
                    "value_id": "7180687",
                    "value_name": "1280 px x 720 px"
                },
                {
                    "id": "FRONT_CAMERA_APERTURE",
                    "name": "Apertura del diafragma de la cámara frontal",
                    "value_id": "7439050",
                    "value_name": "f 1.9"
                },
                {
                    "id": "WITH_FRONT_CAMERA_FLASH",
                    "name": "Con flash en la cámara frontal",
                    "value_id": "242084",
                    "value_name": "No"
                },
                {
                    "id": "MOBILE_NETWORK",
                    "name": "Red",
                    "value_id": "367876",
                    "value_name": "4G/LTE"
                },
                {
                    "id": "MEMORY_CARD_TYPES",
                    "name": "Tipos de tarjeta de memoria",
                    "value_id": "7199655",
                    "value_name": "MicroSD"
                },
                {
                    "id": "MAX_MEMORY_CARD_CAPACITY",
                    "name": "Capacidad máxima de la tarjeta de memoria",
                    "value_id": "2087792",
                    "value_name": "256 GB"
                },
                {
                    "id": "PROCESSOR_MODEL",
                    "name": "Modelo del procesador",
                    "value_id": "2087879",
                    "value_name": "Snapdragon 425"
                },
                {
                    "id": "CPU_MODELS",
                    "name": "Modelos de CPU",
                    "value_id": "7657686",
                    "value_name": "4x1.4 GHz Cortex-A53"
                },
                {
                    "id": "PROCESSOR_CORES_NUMBER",
                    "name": "Cantidad de núcleos del procesador",
                    "value_id": "7206949",
                    "value_name": "4"
                },
                {
                    "id": "PROCESSOR_SPEED",
                    "name": "Velocidad del procesador",
                    "value_id": "1151166",
                    "value_name": "1.4 GHz"
                },
                {
                    "id": "GPU_MODEL",
                    "name": "Modelo de GPU",
                    "value_id": "7531831",
                    "value_name": "Adreno 308"
                },
                {
                    "id": "WITH_USB_CONNECTOR",
                    "name": "Con conector USB",
                    "value_id": "242085",
                    "value_name": "Sí"
                },
                {
                    "id": "WITH_WIFI",
                    "name": "Con Wi-Fi",
                    "value_id": "242085",
                    "value_name": "Sí"
                },
                {
                    "id": "WITH_GPS",
                    "name": "Con GPS",
                    "value_id": "242085",
                    "value_name": "Sí"
                },
                {
                    "id": "WITH_BLUETOOTH",
                    "name": "Con Bluetooth",
                    "value_id": "242085",
                    "value_name": "Sí"
                },
                {
                    "id": "WITH_MINI_HDMI",
                    "name": "Con mini HDMI",
                    "value_id": "242084",
                    "value_name": "No"
                },
                {
                    "id": "WITH_RADIO",
                    "name": "Con radio",
                    "value_id": "242084",
                    "value_name": "No"
                },
                {
                    "id": "WITH_TV_TUNER",
                    "name": "Con sintonizador de TV",
                    "value_id": "242084",
                    "value_name": "No"
                },
                {
                    "id": "WITH_ACCELEROMETER",
                    "name": "Con acelerómetro",
                    "value_id": "242085",
                    "value_name": "Sí"
                },
                {
                    "id": "WITH_PROXIMITY_SENSOR",
                    "name": "Con sensor de proximidad",
                    "value_id": "242085",
                    "value_name": "Sí"
                },
                {
                    "id": "WITH_GYROSCOPE",
                    "name": "Con giroscopio",
                    "value_id": "242084",
                    "value_name": "No"
                },
                {
                    "id": "IS_SPLASH_RESISTANT",
                    "name": "Es resistente a salpicaduras",
                    "value_id": "242084",
                    "value_name": "No"
                },
                {
                    "id": "IS_WATER_RESISTANT",
                    "name": "Es resistente al agua",
                    "value_id": "242084",
                    "value_name": "No"
                },
                {
                    "id": "IS_WATERPROOF",
                    "name": "Es a prueba de agua",
                    "value_id": "242084",
                    "value_name": "No"
                },
                {
                    "id": "BATTERY_TYPE",
                    "name": "Tipo de batería",
                    "value_id": "95013",
                    "value_name": "Ion de litio"
                },
                {
                    "id": "WITH_REMOVABLE_BATTERY",
                    "name": "Con batería removible",
                    "value_id": "242085",
                    "value_name": "Sí"
                },
                {
                    "id": "STANDBY_TIME",
                    "name": "Duración de la batería en espera",
                    "value_id": "7835954",
                    "value_name": "318 h"
                }
            ],
            "pictures": [
                {
                    "id": "636253-MLA41570339037_042020",
                    "url": "https://mla-s2-p.mlstatic.com/636253-MLA41570339037_042020-F.jpg"
                },
                {
                    "id": "819635-MLA41570339038_042020",
                    "url": "https://mla-s2-p.mlstatic.com/819635-MLA41570339038_042020-F.jpg"
                },
                {
                    "id": "690923-MLA41569811814_042020",
                    "url": "https://mla-s2-p.mlstatic.com/690923-MLA41569811814_042020-F.jpg"
                },
                {
                    "id": "976286-MLA41569811805_042020",
                    "url": "https://mla-s1-p.mlstatic.com/976286-MLA41569811805_042020-F.jpg"
                }
            ]
        }
}
Notes:
- The domain_id, site_id and attributes parameters are required.
- Depending on the parameters used for the search, we will get one or more products as a suggestion.
- If use a product_identifier as a parameter, you get only a product.
- If use a keyword as a parameter, either with or without a domain, it is possible to get one or more products that are related to the entered values.
-If you use a POST with attributes, the search is more specific and can return several but specific results about the attributes sent in the POST.
* You must add at least 3 different attributes in the attributes field.
* All attributes within the attribute list must have an "id" (attribute id) and a value_id (attribute value id) or value_name (attribute value).

Determine the exact product to sell

For an item to be published in the catalog and purchased, it must be associated with a sufficiently specific product such that the buyer can know precisely what they are buying and for which Mercado Libre has created the content (products with status="active” in the resource/products/{product_id}).


Product by ID

Once the product has been identified within the domain, you can find out its main characteristics with the/products/$PRODUCT_ID resource. In this way, it will be possible to create a better quality item.

Request:

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

Example:

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

Response:

{
  "id": "MLA10025564",
  "status": "active",
  "domain_id": "MLA-CELLPHONES",
  "permalink": "https://www.mercadolibre.com.ar/p/MLA10025564",
  "name": "Samsung Galaxy J4 Dual SIM 32 GB Púrpura",
  "buy_box_winner": null,
  "pickers": [
    {
      "picker_id": "INTERNAL_MEMORY",
      "picker_name": "Memoria interna",
      "products": [
        {
          "product_id": "MLA10025565",
          "picker_label": "16 GB",
          "picture_id": "",
          "thumbnail": "",
          "tags": [
            "disabled"
          ],
          "permalink": "https://www.mercadolibre.com.ar/p/MLA10025565"
        }
      ]
    }
  ],
  "pictures": [
    {
      "id": "877438-MLA31001589974_062019",
      "url": "https://mla-s1-p.mlstatic.com/877438-MLA31001589974_062019-F.jpg",
      "suggested_for_picker": [
      ],
      "max_width": 589,
      "max_height": 1118
    }
  ],
  "main_features": [
    {
      "text": "Procesador Exynos 7570 Quad-core - 2 GB",
      "type": "key_value",
      "metadata": {
        "key": "",
        "value": ""
      }
    }
  ],
  "attributes": [
    {
      "id": "BRAND",
      "name": "Marca",
      "value_id": "206",
      "value_name": "Samsung"
    },
    {
      "id": "LINE",
      "name": "Línea",
      "value_id": "195973",
      "value_name": "Galaxy J"
    },
    {
      "id": "MODEL",
      "name": "Modelo",
      "value_id": "5640181",
      "value_name": "J4 Duos"
    }
  ],
  "short_description": {
    "type": "plaintext",
    "content": "El Galaxy J4 cuenta con una pantalla HD de 5.5” que te da un excelente radio de contraste con imágenes realistas...
  },
  "parent_id": "MLA9928419",
  "children_ids": [
  ]
}

Special behaviors

  • When the product has "status":"inactive" the "pictures", "pickers" and "main_features" fields will come with null. And the fields inside "short_description" come empty.
  • The "buy_box_winner" field indicates the catalog item that currently has the "won" buybox. When there are no catalog items competing for the buybox for this product, this field is null.
Important:
The catalog publication content is provided by Mercado Libre. Therefore, the seller is responsible for confirming that the product to be associated matches the specific characteristics displayed on the platform.
In the event that there is a difference between what the user buys and the associated product, it is possible that claims and/or cancellations are generated that will negatively impact their reputation and as a consequence of this the disqualification to publish in the catalog, eventually leading to account suspension.

Parents and children products

In many domains there are two levels of products:

Superior level products (“parents”) that group specific products and are not in themselves suitable to be purchased. Example: Motorola Moto G6. This doesn´t have the capacity or color specified.
Terminal level products (“children”) sufficiently specified to be purchased. Example: Motorola G6 32GB índigo oscuro.

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

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 (specific and can be used to publish and buy if 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 for the purposes of publishing is:

children_ids

  • If the field is empty it is a children product which is specific enough to publish.
  • If this array contains IDs of other products, it means that the current catalog_product_id corresponds to a parent product (not fully specified). To list in the catalog we must look for the specific product among its children_ids.

status

  • In order to create a catalog publication, the product must have status="active".
  • The "parent" productos never will have status="active" because they are not comparable.

Choose the specific product to list

Your publication and/or your catalog-eligible variations will have a catalog_product_id that you must verify that it is suitable for publishing using the /products/$CATALOG_PRODUCT_ID resource.

Item “catalog_product_id” example:

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

Short 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"
}

Creating a catalog post from an existing eligible post, you need to verify with our Products resource:

  • If the catalog_product_id corresponds to a product with active status, you are ready to publish to catalog using that catalog_product_id.
  • If the catalog_product_id corresponds to a product with inactive status.
  • If the children_ids array is empty, the publication or variation is already associated with the most specific product we have and it isn´t yet ready to be published in the catalog, so you will not be able to create the catalog publication until the product is edited by Mercado Libre.
  • If the children_ids array is not empty, you will have to search among the children products for the one that corresponds exactly to what you are selling.
  • If you find an active catalog_product_id children that corresponds exactly to what you want to sell, you can use it in the next step to create your catalog publication.
  • If among the catalog_product_id children you cannot find your exact product or you find it but it is not active, you will not be able to publish that product in the catalog at this time and you will have to wait for Mercado Libre to create the product and publish it.

Next: Catalog listing.

or register to recieve the latest news about our API