Last update 07/06/2022

List products

On MercadoLibre's API, listings are items that contains products and other attributes you can sell or buy. Users can’t exchange contact information right away on them, so every time there’s an intention of buying a product, potential buyers are able to make as many questions they want on the item and when they’re ready, an order is created for both seller and buyer detailing the transaction as a sale or a purchase for each one, and that’s when contact information is visible automatically between those users.



Item details page

When a user chooses an item from the result, this page displays the following item details:

  • Item_id
  • Title
  • Category
  • Pictures
  • Price
  • City
  • Sold quantity
  • Questions
  • Seller’s reputation

Consult items

Nota:
From June 20, 2022 it will be possible to obtain a new parameter "value_type" within the detail of the attributes of the items. This field provides information on the type of data that is expected. example: string, number, etc.

Request:

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

Example:

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

Response:

{
"id": "MLA1136716168",
   "site_id": "MLA",
   "title": "Zapatillas Avid Fof - Test Item",
   "subtitle": null,
   "seller_id": 1108966308,
   "category_id": "MLA109027",
   "official_store_id": null,
   "price": 15000,
   "base_price": 15000,
   "original_price": null,
   "currency_id": "ARS",
   "initial_quantity": 2,
   "available_quantity": 2,
   "sold_quantity": 0,
   "sale_terms": [],
   "buying_mode": "buy_it_now",
   "listing_type_id": "gold_pro",
   "start_time": "2022-05-10T21:55:46.000Z",
   "historical_start_time": "2022-05-10T21:55:46.000Z",
   "stop_time": "2042-05-05T04:00:00.000Z",
   "condition": "new",
   "permalink": "https://articulo.mercadolibre.com.ar/MLA-1136716168-zapatillas-avid-fof-test-item-_JM",
   "thumbnail_id": "963513-MLA49868862376_052022",
   "thumbnail": "http://http2.mlstatic.com/D_963513-MLA49868862376_052022-I.jpg",
   "secure_thumbnail": "https://http2.mlstatic.com/D_963513-MLA49868862376_052022-I.jpg",
   "pictures": [
       {
           "id": "963513-MLA49868862376_052022",
           "url": "http://http2.mlstatic.com/D_963513-MLA49868862376_052022-O.jpg",
           "secure_url": "https://http2.mlstatic.com/D_963513-MLA49868862376_052022-O.jpg",
           "size": "500x411",
           "max_size": "898x739",
           "quality": ""
       }
   ],
   "video_id": null,
   "descriptions": [],
   "accepts_mercadopago": true,
   "non_mercado_pago_payment_methods": [],
   "shipping": {
       "mode": "not_specified",
       "methods": [],
       "tags": [
           "adoption_required"
       ],
       "dimensions": null,
       "local_pick_up": false,
       "free_shipping": false,
       "logistic_type": "not_specified",
       "store_pick_up": false
   },
   "international_delivery_mode": "none",
   "seller_address": {
       "id": 0
   },
   "seller_contact": null,
   "location": {},
   "coverage_areas": [],
   "attributes": [
       {
           "id": "AGE_GROUP",
           "name": "Edad",
           "value_id": "6725189",
           "value_name": "Adultos",
           "value_struct": null,
           "values": [
               {
                   "id": "6725189",
                   "name": "Adultos",
                   "struct": null
               }
           ],
           "attribute_group_id": "OTHERS",
           "attribute_group_name": "Otros",
           "value_type": "string"
       },
       {
           "id": "BRAND",
           "name": "Marca",
           "value_id": "11823494",
           "value_name": "Propia",
           "value_struct": null,
           "values": [
               {
                   "id": "11823494",
                   "name": "Propia",
                   "struct": null
               }
           ],
           "attribute_group_id": "OTHERS",
           "attribute_group_name": "Otros",
           "value_type": "string"
       },
       {
           "id": "EXCLUSIVE_CHANNEL",
           "name": "Canal exclusivo",
           "value_id": "7865259",
           "value_name": "Mercado Libre",
           "value_struct": null,
           "values": [
               {
                   "id": "7865259",
                   "name": "Mercado Libre",
                   "struct": null
               }
           ],
           "attribute_group_id": "OTHERS",
           "attribute_group_name": "Otros",
           "value_type": "string"
       },
       {
           "id": "FOOTWEAR_TYPE",
           "name": "Tipo de calzado",
           "value_id": "517583",
           "value_name": "Zapatilla",
           "value_struct": null,
           "values": [
               {
                   "id": "517583",
                   "name": "Zapatilla",
                   "struct": null
               }
           ],
           "attribute_group_id": "OTHERS",
           "attribute_group_name": "Otros",
           "value_type": "string"
       },
       {
           "id": "GENDER",
           "name": "Género",
           "value_id": "339666",
           "value_name": "Hombre",
           "value_struct": null,
           "values": [
               {
                   "id": "339666",
                   "name": "Hombre",
                   "struct": null
               }
           ],
           "attribute_group_id": "OTHERS",
           "attribute_group_name": "Otros",
           "value_type": "string"
       },
       {
           "id": "ITEM_CONDITION",
           "name": "Condición del ítem",
           "value_id": "2230284",
           "value_name": "Nuevo",
           "value_struct": null,
           "values": [
               {
                   "id": "2230284",
                   "name": "Nuevo",
                   "struct": null
               }
           ],
           "attribute_group_id": "OTHERS",
           "attribute_group_name": "Otros",
           "value_type": "string"
       },
       {
           "id": "MODEL",
           "name": "Modelo",
           "value_id": null,
           "value_name": "EQ2122",
           "value_struct": null,
           "values": [
               {
                   "id": null,
                   "name": "EQ2122",
                   "struct": null
               }
           ],
           "attribute_group_id": "OTHERS",
           "attribute_group_name": "Otros",
           "value_type": "string"
       },
       {
           "id": "SIZE_GRID_ID",
           "name": "ID de la guía de talles",
           "value_id": null,
           "value_name": "210052",
           "value_struct": null,
           "values": [
               {
                   "id": null,
                   "name": "210052",
                   "struct": null
               }
           ],
           "attribute_group_id": "OTHERS",
           "attribute_group_name": "Otros",
           "value_type": "string"
       },
       {
           "id": "STYLE",
           "name": "Estilo",
           "value_id": "6694773",
           "value_name": "Urbano",
           "value_struct": null,
           "values": [
               {
                   "id": "6694773",
                   "name": "Urbano",
                   "struct": null
               }
           ],
           "attribute_group_id": "OTHERS",
           "attribute_group_name": "Otros",
           "value_type": "string"
       }
   ],
   "warnings": [],
   "listing_source": "",
   "variations": [
       {
           "id": 174497701554,
           "price": 15000.00,
           "attribute_combinations": [
               {
                   "id": "COLOR",
                   "name": "Color",
                   "value_id": "52049",
                   "value_name": "Negro",
                   "value_struct": null,
                   "values": [
                       {
                           "id": "52049",
                           "name": "Negro",
                           "struct": null
                       }
                   ],
                   "value_type": "string"
               },
               {
                   "id": "SIZE",
                   "name": "Talle",
                   "value_id": "11505183",
                   "value_name": "45,0 AR",
                   "value_struct": null,
                   "values": [
                       {
                           "id": "11505183",
                           "name": "45,0 AR",
                           "struct": null
                       }
                   ],
                   "value_type": "string"
               }
           ],
           "available_quantity": 1,
           "sold_quantity": 0,
           "sale_terms": [],
           "picture_ids": [
               "963513-MLA49868862376_052022"
           ],
           "catalog_product_id": null
       },
       {
           "id": 174497701555,
           "price": 15000.00,
           "attribute_combinations": [
               {
                   "id": "COLOR",
                   "name": "Color",
                   "value_id": "52049",
                   "value_name": "Negro",
                   "value_struct": null,
                   "values": [
                       {
                           "id": "52049",
                           "name": "Negro",
                           "struct": null
                       }
                   ],
                   "value_type": "string"
               },
               {
                   "id": "SIZE",
                   "name": "Talle",
                   "value_id": "11505178",
                   "value_name": "44,0 AR",
                   "value_struct": null,
                   "values": [
                       {
                           "id": "11505178",
                           "name": "44,0 AR",
                           "struct": null
                       }
                   ],
                   "value_type": "string"
               }
           ],
           "available_quantity": 1,
           "sold_quantity": 0,
           "sale_terms": [],
           "picture_ids": [
               "963513-MLA49868862376_052022"
           ],
           "catalog_product_id": null
       }
   ],
   "status": "active",
   "sub_status": [],
   "tags": [
       "test_item",
       "good_quality_picture",
       "good_quality_thumbnail",
       "immediate_payment"
   ],
   "warranty": null,
   "catalog_product_id": null,
   "domain_id": "MLA-SNEAKERS",
   "parent_item_id": null,
   "differential_pricing": null,
   "deal_ids": [],
   "automatic_relist": false,
   "date_created": "2022-05-10T21:55:46.000Z",
   "last_updated": "2022-05-22T09:49:16.725Z",
   "total_listing_fee": null,
   "health": 0.85,
   "catalog_listing": false,
   "channels": [
       "marketplace"
   ],
   "bundle": null   
}

Attributes

Some of the fields are mandatory when you create an item, while some others can be skipped or will be automatically added to the item. They will define how the item is displayed, how buyers can purchase it and the position on search results among other variables.


Title

The title is the key for buyers to find your product. Therefore, it should be as explicit as possible.

  • Generate the title with Product + Brand + product model + some specifications that help identify the product.
  • Avoid in the title information of other services, such as returns, free shipping or installment payments because your information will be seen by your buyers next to the product, without having to enter the publication.
  • If your product is new, used or refurbished, do not include it in the title, upload it in the features and we will show it in the detail of the publication.
  • If you sell the same product but with different colors, do not put the color in the title. Better create variants, so everything will be in a single publication.
  • If you only have stock of a certain color, load the color when publishing or in the characteristics section so that your buyers read the complete technical sheet, but you can add it in the title since it would be a publication that only sells a variant.
  • If you make a discount we will also indicate it showing the percentage of the promotion, we also have a special label to call attention. No need to add it in the title.
  • Separate words with spaces, do not use punctuation or symbols.
  • Check have no spelling errors.
  • It is not allowed to mention stock if you do it your publication will be moderated. The limit of the publication title is set by the category to which it belongs ("max_title_length").

For example: HP Dual Core 425 LED 14 320 GB 4 GB Wifi HDMI Notebook

Note:
You can always make all the changes you need making a PUT on an item's resource modifying the tittle field when sold_quantity be 0.

Description

Note:
As of September 1, 2021 the content of the "descriptions" field will be deactivated. When doing a GET to / items, this field will show an empty array.
To create the description, you must first create the publication without a description and then submit the description via a POST to /items/$ITEM_ID/description resource.

A detailed description will improve your chances to sell a product and will save time from answering questions. Check our item descriptions guide.


Condition

When listing an item you need to declare if the condition is new, used or not_specified. This attribute is mandatory to complete a list operation.

Nota:
From June 28th for items used in the moda/sports category you can only create items with available quantit = 1, and when making the sale, the item will change to status: closed. This functionality only applies to Argentina, Brazil, Mexico and Colombia.

Available quantity

This attribute defines the stock, that's the number of products available for selling on this item. The highest value is defined by the chosen to list type. See more details in the listing type section.


Also, when you want to publish Fulfillment products you can specify the available quantity to zero, modifying the available_quantity field to 0. In this way, the publication will be created with a paused status and out_of_stock sub-status. This will allow you to not have sales and cannot deliver them due to lack of logistics. What happens when you PUT items and have no stock? It supports the same operations as an item paused due to lack of stock, that is, you will not be able to activate it and you must add units so that it is activated automatically.

Example:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d

'{
    ...
    "available_quantity": 0,
    ...
}'
 
https://api.mercadolibre.com/items

Response:

{
    "id": "MLB1374737433",
    "site_id": "MLB",
    "title": "Item De Teste - Não Comprar",
    "base_price": 10,
    ...
    "initial_quantity": 0,
    "available_quantity": 0,
    "sold_quantity": 0,
    ...
    "status": "paused",
    "sub_status": [
        "out_of_stock"
    ],
    ...
}
Important:
This possibility applies only to Argentina, Mexico and Brazil where we operate Fulfillment.

Pictures

Nice pictures can make an item more appealing and give buyers a better idea of the item’s appearance. Basically, you should add an array of up to six URL pictures on the Json.

{
 ....
 "pictures":[
  {"source":"http://yourServer/path/to/your/picture.jpg"},
  {"source":"http://yourServer/path/to/your/otherPicture.gif"},
  {"source":"http://yourServer/path/to/your/anotherPicture.png"}
 ]
 ...
}

We highly recommend you don’t use slow servers to host your pictures, since this can lead to disadvantages when listing. You can also add or change pictures to your item here later on. Please read more about this topic to know which kind of pictures are allowed and how to work with them here.


Category

Sellers must define a category in MercadoLibre site. This attribute is mandatory and only accepts pre-established ids. For more information read categories guide. To get a category suggestion read this article.

Request:

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

Example:

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

Response:

{
  "id": "MLA1055",
  "name": "Celulares y Smartphones",
  "picture": "http://resources.mlstatic.com/category/images/fdca1620-3b63-4af2-bc0b-aeed17048d5d.png",
  "permalink": null,
  "total_items_in_this_category": 79627,
  "path_from_root": [
    {
      "id": "MLA1051",
      "name": "Celulares y Teléfonos"
    },
    {
      "id": "MLA1055",
      "name": "Celulares y Smartphones"
    }
  ],
  "children_categories": [
  ],
  "attribute_types": "variations",
  "settings": {
    "adult_content": false,
    "buying_allowed": true,
    "buying_modes": [
      "buy_it_now",
      "auction"
    ],
    "catalog_domain": "MLA-CELLPHONES",
    "coverage_areas": "not_allowed",
    "currencies": [
      "ARS"
    ],
    "fragile": false,
    "immediate_payment": "required",
    "item_conditions": [
      "not_specified",
      "used",
      "new"
    ],
    "items_reviews_allowed": false,
    "listing_allowed": true,
    "max_description_length": 50000,
    "max_pictures_per_item": 12,
    "max_pictures_per_item_var": 10,
    "max_sub_title_length": 70,
    "max_title_length": 60,
    "maximum_price": null,
    "minimum_price": 22,
    "mirror_category": null,
    "mirror_master_category": null,
    "mirror_slave_categories": [
    ],
    "price": "required",
    "reservation_allowed": "not_allowed",
    "restrictions": [
    ],
    "rounded_address": false,
    "seller_contact": "not_allowed",
    "shipping_modes": [
      "me1",
      "custom",
      "me2",
      "not_specified"
    ],
    "shipping_options": [
      "custom",
      "carrier"
    ],
    "shipping_profile": "optional",
    "show_contact_information": false,
    "simple_shipping": "optional",
    "stock": "required",
    "sub_vertical": "smartphones",
    "subscribable": false,
    "tags": [
    ],
    "vertical": "consumer_electronics",
    "vip_subdomain": "articulo",
    "buyer_protection_programs": [
      "delivered",
      "undelivered"
    ],
    "status": "enabled"
  },
  "meta_categ_id": null,
  "attributable": false,
  "date_created": "2018-04-25T08:12:56.000Z"
}

Considerations
With the /categories resource, you will be able to recognize whether the category is enabled on the site you want to publish.
With listing_allowed and status fields you can identify whether the categories are enabled for publication on the site. To identify those that are enabled, the listing_allowed field should have true value and the status field, enabled value.


Purchase method

The bidding modality ("buying_mode"="auction") will still appear in the APIs of some categories, but you will not be able to use it. As we carry out a constant review of categories, in short, all the APIs will already be updated.
We eliminated this type of advertisement, because almost 100% of our publications have a "Fixed price" and we saw that the experience for the seller and the buyer was being affected when the negotiation was due to bid.
Since then, only the immediate purchase mode ("buying_mode"="buy_it_now") is available, which guarantees that an order will only appear to the seller when the payment is approved, guaranteeing more security in transactions.


Price

This is a mandatory attribute, when you define a new item it must have a price. We suggest you search similar items on our marketplace to know the best price for your products and increase your competitively. If you defined a price and then you’re not happy with it, you can change it later on, learn to modify items.


Currency

Besides price, you need to define a currency. This one is also a mandatory attribute. You need to define it using a pre-established id. Calling our Currencies resource you will know which Id to send.


Payment methods

It’s important that you have in consideration which payment methods you have available to work with. This will vary depending on the country you are currently working. Check this guide to know more about it.


Shipping

Shipping details are not mandatory, but there are many options to choose, and shipping the products you sell is a competitive advantage. Know more about Mercado Envíos.


Product Identifiers

The identifiers are specific codes that help to locate a product.


SKU

This information will help your sellers to identify, locate and internally track a product. We only take into account the information loaded in the SELLER_SKU attribute. Learn more about variations considerations.

Variations

With Variations you can count in the same publication all the variants of the item, maintaining even differential stock for each one. In this way, when you receive a purchase, you will see in the purchase order the color and size chosen by the buyer, thus facilitating the after-sales process. Lear more about Variations.


Listing type

This is another case of a mandatory attribute that only accepts pre-defined values and is very important for you to understand about it. There are different listing types available for each country. You should make a mixed call through sites and listing_types resources to know which listing_types are supported.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/{Site_id}/listing_types

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/MLA/listing_types

Response:

[
  {
    "site_id": "MLA",
    "id": "gold_pro",
    "name": "Premium"
  },
  {
    "site_id": "MLA",
    "id": "gold_premium",
    "name": "Oro Premium"
  },
  {
    "site_id": "MLA",
    "id": "gold_special",
    "name": "Clásica"
  },
  {
    "site_id": "MLA",
    "id": "gold",
    "name": "Oro"
  },
  {
    "site_id": "MLA",
    "id": "silver",
    "name": "Plata"
  },
  {
    "site_id": "MLA",
    "id": "bronze",
    "name": "Bronce"
  },
  {
    "site_id": "MLA",
    "id": "free",
    "name": "Gratuita"
  }
]

The fees for selling your item, as well as how it ranks on search results, will vary according to the chosen listing type. You will find information about each listing type feeds and characteristics on each country marketplace FAQs, or you can make an API call like this:

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/{Site_id}/listing_types/{Listing_type}

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/MLA/listing_types/silver

Response:

{
  "id": "silver",
  "not_available_in_categories": [
  ],
  "configuration": {
  "name": "Plata",
  "listing_exposure": "mid",
  "requires_picture": false,
  "max_stock_per_item": 9999,
  "deduction_profile_id": null,
  "differential_pricing_id": null,
  "duration_days": {
    "buy_it_now": 60,
    "auction": 7,
    "classified": null
  },
  "immediate_payment": {
    "buy_it_now": false,
    "auction": false,
    "classified": false
  },
  "mercado_pago": "mandatory",
  "listing_fee_criteria": {
   "min_fee_amount": 5,
    "max_fee_amount": 160,
    "percentage_of_fee_amount": 1,
    "currency": "ARS"
  },
  "sale_fee_criteria": {
    "min_fee_amount": 0,
    "max_fee_amount": 100000000000000000,
    "percentage_of_fee_amount": 7.5,
    "currency": "ARS"
  }
  },
  "exceptions_by_category": [
  {
    "category_id": "MLA1743",
    "category_name": "Autos, Motos y Otros",
    "configuration": {
      "name": "Plata",
      "listing_exposure": "mid",
      "requires_picture": false,
      "max_stock_per_item": 1,
      "deduction_profile_id": null,
      "differential_pricing_id": null,
      "duration_days": {
        "buy_it_now": null,
        "auction": null,
        "classified": 60
      },
      "immediate_payment": {
        "buy_it_now": false,
        "auction": false,
        "classified": false
      },
      "mercado_pago": "not_available",
      "listing_fee_criteria": {
        "min_fee_amount": 147,
        "max_fee_amount": 147,
        "percentage_of_fee_amount": 0,
        "currency": "ARS"
      },
      "sale_fee_criteria": {
        "min_fee_amount": 0,
        "max_fee_amount": 0,
        "percentage_of_fee_amount": 0,
        "currency": null
      }
   },
    "exceptions_by_category": [
    ]
  },
  {
    "category_id": "MLA1459",
    "category_name": "Inmuebles",
    "configuration": {
      "name": "Plata",
      "listing_exposure": "mid",
      "requires_picture": false,
      "max_stock_per_item": 1,
      "deduction_profile_id": null,
      "differential_pricing_id": null,
      "duration_days": {
        "buy_it_now": null,
        "auction": null,
        "classified": 60
      },
      "immediate_payment": {
        "buy_it_now": false,
        "auction": false,
        "classified": false
      },
      "mercado_pago": "not_available",
      "listing_fee_criteria": {
        "min_fee_amount": 147,
        "max_fee_amount": 147,
        "percentage_of_fee_amount": 0,
        "currency": "ARS"
      },
      "sale_fee_criteria": {
        "min_fee_amount": 0,
        "max_fee_amount": 0,
        "percentage_of_fee_amount": 0,
        "currency": null
      }
    },
    "exceptions_by_category": [
    ]
  },
  {
    "category_id": "MLA1540",
    "category_name": "Servicios",
    "configuration": {
      "name": "Básico 365",
      "listing_exposure": "mid",
      "requires_picture": false,
      "max_stock_per_item": 999,
      "deduction_profile_id": null,
      "differential_pricing_id": null,
      "duration_days": {
          "buy_it_now": null,
        "auction": null,
        "classified": 365
      },
      "immediate_payment": {
        "buy_it_now": false,
        "auction": false,
        "classified": false
      },
      "mercado_pago": "not_available",
      "listing_fee_criteria": {
        "min_fee_amount": 727,
        "max_fee_amount": 727,
        "percentage_of_fee_amount": 0,
        "currency": "ARS"
      },
      "sale_fee_criteria": {
        "min_fee_amount": 0,
        "max_fee_amount": 0,
        "percentage_of_fee_amount": 0,
        "currency": null
      }
    },
    "exceptions_by_category": [
    ]
  }
  ]
}

An item condition

To define if a product is new, used or refurbished, you will need to send the “item_condition” attribute with the value you intend to give. We recommend you to review the Attribute documentation to learn about category attributes and supported values. 

Note:
While today it is allowed to send if an item is new or used in the “condition” field, it should be placed as attribute in the case of “reacondicionado”.

Example:

 curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/categories/MLA30835/attributes

Response:

{
    "id": "ITEM_CONDITION",
    "name": "Condición del ítem",
    "tags": {
      "hidden": true
    },
    "hierarchy": "ITEM",
    "relevance": 2,
    "value_type": "list",
    "values": [
      {
        "id": "2230284",
        "name": "Nuevo"
      },
      {
        "id": "2230581",
        "name": "Usado"
      },
      {
        "id": "2230582",
        "name": "Reacondicionado"
      }
    ],
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },

Important:
When the listing has “reacondicionado” condition, you need to load the Product Warranty in "sale_terms".

Product warranty

Within an item “sale_terms” section, define the warranty of the listed product. For this, the information should have a combination of attributes:
Warranty Type: represents the forms that warranty can take. For example, seller or factory warranty, etc.
Warranty Time: represents the time that warranty will be in force.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/categories/$CATEGORY_ID/sale_terms

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/categories/MLA1642/sale_terms

Response:

{
    "id": "WARRANTY_TYPE",
    "name": "Tipo de garantía",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "list",
    "values": [
      {
        "id": "2230279",
        "name": "Garantía de fábrica"
      },
      {
        "id": "2230280",
        "name": "Garantía del vendedor"
      }
    ],
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "WARRANTY_TIME",
    "name": "Tiempo de garantía",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "number_unit",
    "value_max_length": 255,
    "allowed_units": [
      {
        "id": "días",
        "name": "días"
      },
      {
        "id": "años",
        "name": "años"
      },
      {
        "id": "meses",
        "name": "meses"
      }
    ],
    "default_unit": "días",
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },

Note:
Keep in mind that when setting an item as reconditioned it should be done with a minimum 90-day guarantee. Look more about Publication Policies.

Listing an item

You’re ready to list your first item. Notice you’ll need an access_token to make it. If you have questions regarding how to get your access token, please go back to the Authenticate tutorial. We also recommend using test users to publish test articles. If you don't have your user test yet, see how to perform tests and get yours. You can create a Json for your item basing on the following example, or send it as it is, and you’ll be listing a sample product on the site:

Request:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -d '{
  "title":"Item de test - No Ofertar",
  "category_id":"MLA3530",
  "price":350,
  "currency_id":"ARS",
  "available_quantity":10,
  "buying_mode":"buy_it_now",
  "condition":"new",
  "listing_type_id":"gold_special",
  "sale_terms":[
     {
        "id":"WARRANTY_TYPE",
        "value_name":"Garantía del vendedor"
     },
     {
        "id":"WARRANTY_TIME",
        "value_name":"90 días"
     }
  ],
  "pictures":[
     {
        "source":"http://mla-s2-p.mlstatic.com/968521-MLA20805195516_072016-O.jpg"
     }
  ],
  "attributes":[
     {
        "id":"BRAND",
        "value_name":"Marca del producto"
     },
     {
        "id":"EAN",
        "value_name":"7898095297749"
     }
  ]
}' 'https://api.mercadolibre.com/items

Example:

{
    "title": "Item de test - No Ofertar",
    "category_id": "MLA3530",
    "price": 350,
    "currency_id": "ARS",
    "available_quantity": 10,
    "buying_mode": "buy_it_now",
    "condition": "new",
    "listing_type_id": "gold_special",
    "description": {
        "plain_text": "Descripción con Texto Plano  \n"
    },
    "video_id": "YOUTUBE_ID_HERE",
    "sale_terms": [
        {
            "id": "WARRANTY_TYPE",
            "vale_name": "Garantía del vendedor"
        },
        {
            "id": "WARRANTY_TIME",
            "value_name": "90 días"
        }
    ],
    "pictures": [
        {
            "source": "http://mla-s2-p.mlstatic.com/968521-MLA20805195516_072016-O.jpg"
        }
    ],
    "attributes": [
        {
            "id": "BRAND",
            "value_name": "Marca del producto"
        },
        {
            "id": "EAN",
            "value_name": "7898095297749"
        }
    ]
}

Note:
If you have any trouble when trying to list, check the API Error Codes Reference chart at the end of this guide.

Items with mandatory Mercado Pago

Just as a user or a category can be marked with immediate payment, so can an item. This scenario occurs when:


List an item with immediate payment

If you want to get your item paid only with Mercado Pago, you may set that choice when you create a new item, or when you change an active one. To that end, use the tag “inmediate_payment”.

Request:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
'{
    "title": "Item de teste - Não Comprar",
    "category_id": "MLB437616",
    "price": 10,
    "currency_id": "BRL",
    "available_quantity": 1,
    "buying_mode": "buy_it_now",
    "listing_type_id": "gold_special",
    "condition": "new",
    "description": "Publicação de teste, não comprar",
    "video_id": "YOUTUBE_ID_HERE",
    "tags": [
        "immediate_payment"
    ],
   "sale_terms":[
      {
         "id":"WARRANTY_TYPE",
         "value_name":"Garantia do vendedor"
      },
      {
         "id":"WARRANTY_TIME",
         "value_name":"90 días"
      }
   ],

    "pictures": [
         {
    "source": "https://www.motorino.com.br/site/wp-content/uploads/2018/01/produto_de_teste_amarelo_4_2_20171020224326-400x400.jpg"}

    ]
}
 
'
 
https://api.mercadolibre.com/items

Response:

{
    "id": "MLB1548991737",
    "site_id": "MLB",
    "title": "Item De Teste - Não Comprar",
    "subtitle": null,
    "seller_id": 419059118,
    "category_id": "MLB437616",
    "official_store_id": null,
    "price": 10,
    "base_price": 10,
    "original_price": null,
    "inventory_id": null,
    "currency_id": "BRL",
    "initial_quantity": 1,
    "available_quantity": 1,
    "sold_quantity": 0,
    "sale_terms": [
        {
            "id": "WARRANTY_TYPE",
            "name": "Tipo de garantia",
            "value_id": "2230280",
            "value_name": "Garantia do vendedor",
            "value_struct": null,
            "values": [
                {
                    "id": "2230280",
                    "name": "Garantia do vendedor",
                    "struct": null
                }
            ]
        },
        {
            "id": "WARRANTY_TIME",
            "name": "Tempo de garantia",
            "value_id": null,
            "value_name": "90 días",
            "value_struct": {
                "number": 90,
                "unit": "dias"
            },
            "values": [
                {
                    "id": null,
                    "name": "90 días",
                    "struct": {
                        "number": 90,
                        "unit": "dias"
                    }
                }
            ]
        }
    ],
    "buying_mode": "buy_it_now",
    "listing_type_id": "gold_special",
    "start_time": "2020-06-05T13:48:44.964Z",
    "stop_time": "2040-05-31T04:00:00.000Z",
    "end_time": "2040-05-31T04:00:00.000Z",
    "expiration_time": "2020-08-24T13:48:45.039Z",
    "condition": "new",
    "permalink": "http://produto.mercadolivre.com.br/MLB-1548991737-item-de-teste-no-comprar-_JM",
    "pictures": [
        {
            "id": "830983-MLB42088778762_062020",
            "url": "http://http2.mlstatic.com/resources/frontend/statics/processing-image/1.0.0/O-PT.jpg",
            "secure_url": "https://http2.mlstatic.com/resources/frontend/statics/processing-image/1.0.0/O-PT.jpg",
            "size": "500x500",
            "max_size": "500x500",
            "quality": ""
        }
    ],
    "video_id": null,
    "descriptions": [ ],
    "accepts_mercadopago": true,
    "non_mercado_pago_payment_methods": [],
    "shipping": {
        "mode": "me1",
        "local_pick_up": false,
        "free_shipping": false,
        "methods": [],
        "dimensions": null,
        "tags": [],
        "logistic_type": "default",
        "store_pick_up": false
    },
    "international_delivery_mode": "none",
    "seller_address": {
        "id": 1032937241,
        "comment": "",
        "address_line": "Rua Exemplo 123",
        "zip_code": "01234100",
        "city": {
            "id": "BR-SP-44",
            "name": "São Paulo"
        },
        "state": {
            "id": "BR-SP",
            "name": "São Paulo"
        },
        "country": {
            "id": "BR",
            "name": "Brasil"
        },
        "latitude": -23.6251244,
        "longitude": -46.7441422,
        "search_location": {
            "neighborhood": {
                "id": "TUxCQlZJTDI1OTI",
                "name": "Vila Andrade"
            },
            "city": {
                "id": "TUxCQ1NQLTkxMjE",
                "name": "São Paulo Zona Sul"
            },
            "state": {
                "id": "TUxCUFNBT085N2E4",
                "name": "São Paulo"
            }
        }
    },
    "seller_contact": null,
    "location": {},
    "geolocation": {
        "latitude": -23.6251244,
        "longitude": -46.7441422
    },
    "coverage_areas": [],
    "attributes": [
        {
            "id": "ITEM_CONDITION",
            "name": "Condição do item",
            "value_id": "2230284",
            "value_name": "Novo",
            "value_struct": null,
            "values": [
                {
                    "id": "2230284",
                    "name": "Novo",
                    "struct": null
                }
            ],
            "attribute_group_id": "",
            "attribute_group_name": ""
        }
    ],
    "warnings": [],
    "listing_source": "",
    "variations": [],
    "thumbnail": "http://http2.mlstatic.com/resources/frontend/statics/processing-image/1.0.0/I-PT.jpg",
    "secure_thumbnail": "https://http2.mlstatic.com/resources/frontend/statics/processing-image/1.0.0/I-PT.jpg",
    "status": "active",
    "sub_status": [],
    "tags": [
        "cart_eligible",
        "immediate_payment",
        "test_item"
    ],
    "warranty": "Garantia do vendedor: 90 días",
    "catalog_product_id": null,
    "domain_id": null,
    "seller_custom_field": null,
    "parent_item_id": null,
    "differential_pricing": null,
    "deal_ids": [],
    "automatic_relist": false,
    "date_created": "2020-06-05T13:48:45.176Z",
    "last_updated": "2020-06-05T13:48:45.176Z",
    "health": null,
    "catalog_listing": false,
    "item_relations": []
}

Categories with immediate payment

Some categories within MercadoLibre require Mercado Pago as the only choice. To find out if the category where you wish to list is one of them, check the following:

curl - X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/categories/$CATEGORY_ID

"immediate_payment": "required",
    "item_conditions": [
      "new",
      "not_specified",
      "used"
    ],

If the "immediate_payment" field is set as "required," Mercado Pago is mandatory. If it reads "optional,” it also accepts “As agreed with the seller”.



List an official store item

Listing an official store item is just like listing any other item, except that you also need to add the official_store_id attribute on the JSON.


Important:
The limited listing brands may only be offered by official stores and sellers certified by the brands. . This measure applies in the following countries:
- In Argentina:Adidas, Reebok and Nike
- In Brasil: Adidas, Reebok and Nike
- In Colômbia: Adidas, Reebok and Nike
- In México: Adidas, Reebok and Nike
- In Peru: Adidas and Reebok
- In Chile: Adidas and Rebook


Example:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
'{
   "title":"Item de Test -No Ofertar",
   "category_id":"MLA5529",
   "price":10,
   "official_store_id":1,
   "currency_id":"ARS",
   "available_quantity":1,
   "buying_mode":"buy_it_now",
   "listing_type_id":"bronze",
   "condition":"new",
   "description":{
      "plain_text":"Item:, Ray-Ban WAYFARER Gloss Black RB2140 901 Model: RB2140. Size: 50mm. Name: WAYFARER. Color: Gloss Black. Includes Ray-Ban Carrying Case and Cleaning Cloth. New in Box"
   },
   "video_id":"YOUTUBE_ID_HERE",
   "sale_terms":[
      {
         "id":"WARRANTY_TYPE",
         "value_name":"Garantia do vendedor"
      },
      {
         "id":"WARRANTY_TIME",
         "value_name":"90 días"
      }
   ],

   "pictures":[
      {
         "source":"http://upload.wikimedia.org/wikipedia/commons/f/fd/Ray_Ban_Original_Wayfarer.jpg"
      },
      {
         "source":"http://en.wikipedia.org/wiki/File:Teashades.gif"
      }
   ]
}'https://api.mercadolibre.com/items

Note:
If your store is multi-brand you need to specify the official_store_id of the brand where you want to list that item. Check our Official Stores guide to know more about this topic.

Select the channel where you want to offer products

Important:
This functionality is available only for Argentina, Brazil and Mexico, that is, where Mercado Shops is active.

Using the exclusive_channel attribute you can choose where to publish an article, either only in Mercado Libre, in Mercado Shops or on both channels. Possible values are: 
- Mercado Libre
- Mercado Shops

The presence of this attribute determines in which channel the item is visible exclusively and its absence indicates that the item is visible in both channels. An item with the exclusive_channel attribute with value_id field in null, behaves as if the attribute did not exist.  Below you can see an example of an Item published exclusively in Mercado Shops:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
'{
... 
"attributes": [
  	{
		"id": "EXCLUSIVE_CHANNEL",
		"value_name": "Mercado Shops"
	}]
...
}' https://api.mercadolibre.com/items

The following example corresponds to an item offered exclusively in Mercado Libre:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
'{
... 
"attributes": [
  	{
		"id": "EXCLUSIVE_CHANNEL",
		"value_name": "Mercado Libre"
	}]
...
}' https://api.mercadolibre.com/items

Learn more about Mercado Shops.


Error codes reference

Error Error message Description Possible solution
moderations.seller_id.not_authorized Seller is not authorized for this brand and category This is a limited publication mark. To be able to offer your products in Mercado Libre you must be an accredited seller. The product will not be published. This restriction is active in Argentina, Brazil, Colombia and Mexico.
item.start_time.invalid La hora de inicio $startTime solo se puede actualizar en artículos NOT_YET_ACTIVE item.start_time.invalid Start time $startTime is only updateable in NOT_YET_ACTIVE items. Field start time cannot be updated. The parameter start_time can only be updated if the item status is NOT_YET_ACTIVE
item.category_id.invalid Category $categoryId does not exist. Category not found. To see the available categories check the page/sites/$siteId (Check $sideId).
item.category_id.invalid Is not allowed to post in category $categoryId. Make sure you’re posting in a leaf category. $category.listing_allowed false. Before post an item, make sure it is allowed to post in the chosen category, see the parameter listing_allowed on /categories/$categoryId.
item.buying_mode.invalid Category $categoryId only supports listing modes: $category.buyingModes. $item.buying_modes is invalid. To see the available listing modes in category check the page /categories/$categoryId in parameter settings:{buying_modes:[…]}.
item.attributes.missing_required The attributes $requiredAttributeIds are required for category $item.categoryId. Check the attribute is present in the attributes list or in all variation attributes combination. Category is required attribute. To see the attributes mandatory on this category check the page /categories/$categoryId/attributes in parameter {tags:{required:{true}}}.
item.listing_type_id.invalid Invalid listing_type_id. $item.listing_type_id is invalid. To see the available listing types in category check the page /categories/$categoryId/listing_types.
item.listing_type_id.requiresPictures Pictures are mandatory for listing type $item.listingTypeId. Pictures is required. To see if the pictures is mandatory in category check the page /categories/$categoryId/listing_types/silver in parameter requires_picture:{}.
item.site_id.invalid Site $item.siteId doesn’t exist. $item.site_id is invalid. To the available sites, see the page /sites.
item.description.max The description field is too long. More than $maxSize characters is not allowed. Number of characters exceeded. The number of characters in description must be less then 50000 characters.
item.pictures.max Items in category $item.categoryId cannot exceeds $maxPicturesPerItem pictures. Number of images exceeded. To see the quantity of pictures per item in category check the page /categories/$categoryId in parametermax_pictures_per_item:{}.
item.attributes.invalid_length Invalid value length for attribute $it.attributeId. Maximum length is ${attribute.value_max_length}. To see the attributes max_length on this attribute check the page /categories/$categoryId/attributes in parameter value_max_length for attributes with .value_type string or number.
seller.unable_to_list The seller cannot post. The seller cannot post for certain cause. Identify the “cause” field in the response. - Find out the meaning of “cause” under /users#options, set the status to list, and you will see the meaning.
- Try to make the first manual posting from My Account in Mercado Libre to see the warnings in the flow.
moderations.seller_id.not_authorized Seller is not authorized for this brand and category. The Nike, Adidas and Reebok brands have authorized sellers to sell their products on Mercado Libre. If the seller does not have that relationship, they will not be able to publish the item. The item was moderated and you will not be able to publish. This moderation is active in Mexico and Argentina.

Warnings

Warning code Error message Description Possible solution
moderations.seller_id.not_authorized Seller is not authorized for this brand and category This is a brand that must be accredited, that is, to demonstrate that the products are acquired through distributors or retailers authorized by the brand in the country. Access to Mercado Libre section Ventas > Preferencias de ventas > Acreditaciones, select “Acreditar marca”, enter the brand to be credited, attach purchase invoices and that's it!

HTTP response code references

If any information could not be obtained, items can return the http code 206. Keep in mind that in most cases the information you receive will be enough to continue working.
In the response header X-Content-Missing you will find the name of the fields without information, which could be “location”, “geolocation” and/or “seller_address”.

Request:

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

Response http 200 OK:

{
    "id": "",
    "seller_id": ,
    ...
    "seller_address": {
        "id": 1011241361,
        "address_line": "Evaristo Lillo 112",
        "zip_code": "7200",
        "comment": "this is a comment",
        "city": {
            "id": "TUxDQ0xBUzU2MTEz",
            "name": "Las Condes"
        },
        "state": {
            "id": "CL-RM",
            "name": "RM (Metropolitana)"
        },
        "country": {
            "id": "CL",
            "name": "Chile"
        },
        "search_location": {
            "neighborhood": {
                "id": "",
                "name": ""
            },
            "city": {
                "id": "TUxDQ0xBUzU2MTEz",
                "name": "Las Condes"
            },
            "state": {
                "id": "TUxDUE1FVEExM2JlYg",
                "name": "RM (Metropolitana)"
            }
        },
        "latitude": -33.4140509,
        "longitude": -70.5814078
    },
    "location": {},
    "geolocation": {
        "latitude": -33.4140509,
        "longitude": -70.5814078
    },
    ...
}

Request:

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

Response :

{
    "id": "",
    "seller_id": ,
    ...
    "seller_address": {
        "id": 1011241361
    },
    "location": {},
    "geolocation": {},
    ...
}

Related articles: Add and configure shipping options for your products and Know listing prices and exposures.


Next topic: Ship products

banner footer

Subscribe to our Newletter

or register to recieve the latest news about our API