Last update 15/09/2022

Catalog listing

There are different ways to publish to the catalog or make OPTIN, which we detail below.


Publish from an existing publication

After validating that your existing publication is eligible for catalog and getting the catalog_product_id" enabled by the product search feature and verifying that the datasheet corresponds exactly to what you are publishing, you should create the catalog publication (do OPTIN) with a POST to /items/catalog_listings.


Variations

For catalog products, we do not allow the creation of variations because they are already associated with a specific value, for example: Apple iPad Air From 10.9 Wi-fi 256gb Rose Gold (4th Generation) where the color "rose gold" would be a variation of a marketplace publication.
So if your original publication had variations, you will have a marketplace publication for each of them. The relevant information from your variations, such as the color of the item, will not be lost, as it will be reflected in the attributes of the catalog product.
If your marketplace publication contains variations, you should make a POST for each one by sending the "variation_id" field in the body of the POST.


Example about a marketplace publication with variations:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/catalog_listings
{
   "item_id": "MLM1477978125",
   "variation_id": 174997747229,
   "catalog_product_id": "MLM15996654"

}

Example about a marketplace publication without variations:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/catalog_listings
{
   "item_id": "MLM1477978125",
   "catalog_product_id": "MLM15996654"

}

Short example of the answer creating a catalog product:

{
    "id": "MLM1477990462",
    "site_id": "MLM",
    "title": "Huawei Y6p Dual Sim 64 Gb Emerald Green 3 Gb Ram",
    "subtitle": null,
    "seller_id": 1008002397,
    "category_id": "MLM1055",
    "official_store_id": null,
    "price": 9999,
    "base_price": 9999,
    "original_price": null,
    "inventory_id": null,
    "currency_id": "MXN",
    "initial_quantity": 2,
    "available_quantity": 2,
    "sold_quantity": 0,
    "sale_terms": [
        {
            "id": "WARRANTY_TYPE",
            "name": "Tipo de garantía",
            "value_id": "2230280",
            "value_name": "Garantía del vendedor",
            "value_struct": null,
            "values": [
                {
                    "id": "2230280",
                    "name": "Garantía del vendedor",
                    "struct": null
                }
            ]
        },
        {
            "id": "WARRANTY_TIME",
            "name": "Tiempo de garantía",
            "value_id": null,
            "value_name": "3 meses",
            "value_struct": {
                "number": 3,
                "unit": "meses"
            },
            "values": [
                {
                    "id": null,
                    "name": "3 meses",
                    "struct": {
                        "number": 3,
                        "unit": "meses"
                    }
                }
            ]
        }
    ],
    "buying_mode": "buy_it_now",
    "listing_type_id": "gold_special",
    "start_time": "2022-08-10T16:28:40.141Z",
    "stop_time": "2042-08-05T04:00:00.000Z",
    "end_time": "2042-08-05T04:00:00.000Z",
    "expiration_time": "2022-10-29T16:28:40.255Z",
    "condition": "new",
    "permalink": "http://articulo.mercadolibre.com.mx/MLM-1477990462-huawei-y6p-dual-sim-64-gb-emerald-green-3-gb-ram-_JM",
    "pictures": [
        ...
    ],
    "video_id": null,
    "descriptions": [],
    "accepts_mercadopago": true,
    "non_mercado_pago_payment_methods": [],
    "shipping": {
        "mode": "me2",
        "local_pick_up": false,
        "free_shipping": true,
        "methods": [],
        "dimensions": null,
        "tags": [
            "mandatory_free_shipping"
        ],
        "logistic_type": "drop_off",
        "store_pick_up": false
    },
    "international_delivery_mode": "none",
    "seller_address": {
        ...
    },
    "seller_contact": null,
    "location": {},
    "geolocation": {
        "latitude": 20.7846638,
        "longitude": -103.4679048
    },
    "coverage_areas": [],
    "attributes": [ ... ],
    "warnings": [
      ...
    ],
    "listing_source": "",
    "variations": [],
    "thumbnail_id": "753526-MLA49391002480_032022",
    "thumbnail": "http://mlm-s1-p.mlstatic.com/753526-MLA49391002480_032022-I.jpg",
    "secure_thumbnail": "https://mlm-s1-p.mlstatic.com/753526-MLA49391002480_032022-I.jpg",
    "status": "active",
    "sub_status": [],
    "tags": [
        "cart_eligible",
        "immediate_payment",
        "test_item"
    ],
    "warranty": "Garantía del vendedor: 3 meses",
    "catalog_product_id": "MLM15996654",
    "domain_id": "MLM-CELLPHONES",
    "seller_custom_field": null,
    "parent_item_id": null,
    "differential_pricing": null,
    "deal_ids": [],
    "automatic_relist": false,
    "date_created": "2022-08-10T16:28:40.371Z",
    "last_updated": "2022-08-10T16:28:40.419Z",
    "health": null,
    "catalog_listing": true,
    "item_relations": [
        {
            "id": "MLM1477978125",
            "variation_id": 174997747229,
            "stock_relation": 1
        }
    ],
    "channels": [
        "marketplace"
    ]
}

Considerations:

  • In the marketplace product/publication information you will find the array "item_relations" which will have the information of the relationship created between the item_id of the publication, with its respective variation and the item_id of the catalog product created from it.
  • If the request to create a catalog product is sent without variations, but the publication has variations, the response will be an error:
{
   "message": "Validation error",
   "error": "validation_error",
   "status": 400,
   "cause": [
       {
           "department": "items",
           "cause_id": 216,
           "type": "error",
           "code": "item.variations.invalid",
           "references": [
               "variation_id"
           ],
           "message": "Item MLM1477978125 doesn't have a variation with id null"
       }
   ]
}
  • The "catalog_product_id" field is required in POST for marketplace publications, with or without variations:
{
   "message": "Validation error",
   "error": "validation_error",
   "status": 400,
   "cause": [
       {
           "department": "items",
           "cause_id": 369,
           "type": "error",
           "code": "body.required_fields",
           "references": [
               "body.invalid"
           ],
           "message": "The payload is missing the following properties: [catalog_product_id]"
       }
   ]
}
  • If the marketplace publication does not have the corresponding "catalog_product_id" field, the response will be an error:
{
   "message": "Validation error",
   "error": "validation_error",
   "status": 400,
   "cause": [
       {
           "department": "items",
           "cause_id": 389,
           "type": "error",
           "code": "item.catalog_listing.not_eligible",
           "references": [
               "item.catalog_listing"
           ],
           "message": "Item cannot be catalog listing"
       } 
   ]
}

Sales conditions sync

The synchronization of sales conditions (such as price, delivery, inventory, warranty, SKU and PLs) of marketplace publications associated with a catalog product will be automatic and under the following conditions:

- The seller will not be able to delete the synchronization (opt-out).
- New publications will be synchronized from the beginning.
- Existing publications associated with a catalog product are synchronized when the seller changes any of the sales conditions of the original publication.
- The sync will start when the first change is made, meaning that if the merchant first modifies the catalog publication, we will automatically update the marketplace publication and vice versa.


Note:
Changes to both marketplace and catalog publications will be notified via the item feed.

Publishing directly to the catalog

It is not necessary to have a marketplace publication to publish to the catalog, you can do direct publishing by using the "catalog_product_id" of an active catalog product.
Through a GET to the resource /products/search with the filter status:active, you will get the suggestion of products in catalog where you can publish.

Important:
- The catalog product datasheet detail is provided for by Mercado Livre. Therefore, the seller is responsible for confirming that the product to be created matches the specific characteristics (datasheet) of the "catalog_product_id".
- If there is a difference between what the user bought and the associated product, it is possible that this will generate a complaint and/or cancellation that will impact negatively on your reputation and as a consequence the inability to publish in catalog, eventually leading to account suspension.

When executing the POST you must send the following values for the catalog publication to be created:
- "catalog_product_id": this value must be confirmed with the search/product feature.
- "catalog_listing" true: you must send the value in true to generate the catalog item.

Request:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items

Short example of a direct catalog creation:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -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

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": []
}

Marketplace publications created automatically

Importante:
This feature is momentarily disabled.

Mercado Livre will evaluate the marketplace publications, if they do not meet all the requirements to make an effective optin, it will be done automatically. Consider that the original publication will be updated with the "attributes", "variations.attributes" or "variations.attribute_combinations" of the catalog product it was associated with so that both related publications are consistent.
Below you can see a catalog product with automatic optin. You will recognize these publications with the tag "catalog_boost".


Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA123456789

Short response:


{
   "id":"MLA123456789",
   "site_id":"MLA",
   "title":"Samsung Galaxy A10 32 Gb Negro 2 Gb Ram",
   "seller_id":12312345,
   "category_id":"MLA1055",
   "price":14498.49,
   "currency_id":"ARS",
   "initial_quantity":1,
   "available_quantity":1,
   "sold_quantity":0,
   "tags":[
      "brand_verified",
      "extended_warranty_eligible",
      "catalog_boost",
      "good_quality_picture",
      "good_quality_thumbnail",
      "immediate_payment",
      "cart_eligible"
   ],
   "warranty":"Garantía del vendedor: 6 meses",
   "catalog_product_id":"MLA14648964",
   "domain_id":"MLA-CELLPHONES",
   "parent_item_id":null,
   "differential_pricing":null,
   "automatic_relist":false,
   "date_created":"2020-02-25T13:30:06.000Z",
   "last_updated":"2020-02-28T16:28:14.000Z",
   "health":0.9,
   "catalog_listing":true
}

You can search by seller to identify publications that are tagged with the "catalog_boost" tag using the following feature:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/1234567/items/search?status=active&tags=catalog_boost

Validations and error messages

When performing catalog publications, you may get error messages in response, which we detail below with their respective solutions:
Code_id Reason code_name code_message Solution
4400 catalog_product_id or GTIN required (we detect product based on PKs) body.required_fileds Missing catalog_product_id or GTIN. It’s required at least one of them. Send catalog_product_id or GTIN
4402 No active product found based on catalog_product_id item.catalog_product_id The product $product_id is not active Submit an active catalog_product_id or correct GTIN
417 catalog_product_id does not match the category_id item.catalog_product_id The product $product_id does not belong to the catalog_domain of the category $category_id. Submit a correct catalog_product_id
418 catalog_product_id of different families between item and variation item.catalog_product_id Variation catalog_product_id $variation_product_id is not a child of item catalog_product_id $item_product_id. Submit a catalog_product_id at item and variation level that is of the same family

Next: Catalog required listings

banner footer

Subscribe to our Newletter

or register to recieve the latest news about our API