List products

Now that you went through authentication, users and categories, we think you are ready to list your first listing. Follow this tutorial to learn how to do it.

Contents:

 

Basics

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, they need to make an offer on the seller’s product, so 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.

Listing Results

Each item you list will appear in the listing results of a given product search. For example, when a user search for the query “ipod”, as a result he will get a list of all items related. Your item can be in that list.
When someone clicks on an item, the item details page is displayed, showing all the information about the item that was provided at the time of listing, keep reading to know more about it.

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
  • Detailed description

Item Fields

Let’s see a regular item in detail. This is easy since you only need to know the item_id associated to the product, and since it’s public you can get it from the item’s details page on the top of the page, like in the example picture. You just need to add the site_id before the number and that’s it. Now you can call the Items resource to get all the related information:

Call:

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

Example:

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

Response:

{
  "id": "MLA600190449",
  "site_id": "MLA",
  "title": "Iphone 6 64gb Space Gray Liberado",
  "subtitle": null,
  "seller_id": 118617944,
  "category_id": "MLA352543",
  "official_store_id": null,
  "price": 16550,
  "base_price": 16550,
  "original_price": null,
  "currency_id": "ARS",
  "initial_quantity": 2,
  "available_quantity": 2,
  "sold_quantity": 0,
  "buying_mode": "buy_it_now",
  "listing_type_id": "bronze",
  "start_time": "2016-01-13T18:10:29.000Z",
  "stop_time": "2016-03-13T18:10:29.000Z",
  "condition": "new",
  "permalink": "http://articulo.mercadolibre.com.ar/MLA-600190449-iphone-6-64gb-space-gray-liberado-_JM",
  "thumbnail": "http://mla-s1-p.mlstatic.com/873411-MLA20547233702_012016-I.jpg",
  "secure_thumbnail": "https://a248.e.akamai.net/mla-s1-p.mlstatic.com/873411-MLA20547233702_012016-I.jpg",
  "pictures": [
    {
      "id": "873411-MLA20547233702_012016",
      "url": "http://mla-s1-p.mlstatic.com/873411-MLA20547233702_012016-O.jpg",
      "secure_url": "https://a248.e.akamai.net/mla-s1-p.mlstatic.com/873411-MLA20547233702_012016-O.jpg",
      "size": "225x225",
      "max_size": "225x225",
      "quality": ""
    },
    {
      "id": "234411-MLA20547233720_012016",
      "url": "http://mla-s1-p.mlstatic.com/234411-MLA20547233720_012016-O.jpg",
      "secure_url": "https://a248.e.akamai.net/mla-s1-p.mlstatic.com/234411-MLA20547233720_012016-O.jpg",
      "size": "259x194",
      "max_size": "259x194",
      "quality": ""
    },
    {
      "id": "768311-MLA20547233735_012016",
      "url": "http://mla-s1-p.mlstatic.com/768311-MLA20547233735_012016-O.jpg",
      "secure_url": "https://a248.e.akamai.net/mla-s1-p.mlstatic.com/768311-MLA20547233735_012016-O.jpg",
      "size": "300x168",
      "max_size": "300x168",
      "quality": ""
    }
  ],
  "video_id": null,
  "descriptions": [
    {
      "id": "MLA600190449-1007729488"
    }
  ],
  "accepts_mercadopago": true,
  "non_mercado_pago_payment_methods": [
  ],
  "shipping": {
    "mode": "me2",
    "local_pick_up": true,
    "free_shipping": true,
    "free_methods": [
      {
        "id": 73328,
        "rule": {
          "free_mode": "country",
          "value": null
        }
      }
    ],
    "dimensions": null,
    "tags": [
    ]
  },
  "international_delivery_mode": "none",
  "seller_address": {
    "id": 138834162,
    "comment": "",
    "address_line": "",
    "zip_code": "",
    "city": {
      "id": "TUxBQ05FVXF1ZW4",
      "name": "Neuquén"
    },
    "state": {
      "id": "AR-Q",
      "name": "Neuquén"
    },
    "country": {
      "id": "AR",
      "name": "Argentina"
    },
    "latitude": -38.95628353,
    "longitude": -68.12749595,
    "search_location": {
      "neighborhood": {
        "id": "",
        "name": ""
      },
      "city": {
        "id": "TUxBQ05FVXF1ZW4",
        "name": "Neuquén"
      },
      "state": {
        "id": "TUxBUE5FVW4xMzMzNQ",
        "name": "Neuquén"
      }
    }
  },
  "seller_contact": null,
  "location": {
  },
  "geolocation": {
    "latitude": -38.96055205,
    "longitude": -68.12525497
  },
  "coverage_areas": [
  ],
  "attributes": [
  ],
  "listing_source": "",
  "variations": [
  ],
  "status": "active",
  "sub_status": [
  ],
  "tags": [
  ],
  "warranty": null,
  "catalog_product_id": null,
  "parent_item_id": null,
  "differential_pricing": null,
  "deal_ids": [
  ],
  "automatic_relist": false,
  "date_created": "2016-01-13T18:10:29.000Z",
  "last_updated": "2016-01-13T18:26:54.000Z"
}

Defining 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

Title is a mandatory attribute and is the key for buyers to find your product, for this reason you should be as specific as possible.
The best way to build a title is name + brand + model + technical specifications and characteristics + additional services. Separate words with spaces, don’t use symbols or punctuation signs. Check you are not misspelling any words. For example: Ipod Touch Apple 16gb 5 Geração.

Description

A detailed description will improve your chances to sell a product and will save time from answering questions. It can be a text-only description or you can add your own personalized HTML. There are some considerations when working with descriptions, for example, it’s not allowed posting a description with contact information. If you are interested in increasing your knowledge about this topic, check our 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.

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 listing type. See more details in the listing type section.

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.

{
 ....
  "category_id":"MLA12683",
 ...
}

 

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 competitivity. 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 the shipping options you have here.

Product Identifiers

Not a mandatory attribute either and only available for some countries and user types. Know more about it.

Seller Custom Field

The seller custom field is not mandatory but is very useful since there aren’t any pre-established values and you can send anything as a String. Most sellers use this field to associate their own SKUs to their products, to identify the product sold on the order.
Example:

curl -X PUT -d '{"seller_custom_field": "21000093"}' https://api.mercadolibre.com/items/MLA599074368?access_token=¢ACCESS_TOKEN

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.

Call:

curl https://api.mercadolibre.com/sites/{Site_id}/listing_types

Example:

curl https://api.mercadolibre.com/sites/MLA/listing_types

Response:

[
  {
    "site_id": "MLA",
    "id": "gold_pro",
    "name": "Oro Premium Full"
  },
  {
    "site_id": "MLA",
    "id": "gold_premium",
    "name": "Oro Premium"
  },
  {
    "site_id": "MLA",
    "id": "gold_special",
    "name": "Oro Profesional"
  },
  {
    "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:

Call:

curl https://api.mercadolibre.com/sites/{Site_id}/listing_types/{Listing_type}

Example:

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

 

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. Also we recommend using test users to post test items, if you are not familiar with that, please check the generating test users sections here. In addition, we highly recommended you validate the Json you’re sending before making the POST, so you better check out this easy and quick item validation tutorial.
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:

curl -X POST -H "Content-Type: application/json" -d
'{
"title":"Item de test - No Ofertar",
"category_id":"MLA3530",
"price":10,
"currency_id":"ARS",
"available_quantity":1,
"buying_mode":"buy_it_now",
"listing_type_id":"gold_special",
"condition":"new",
"description": "Item de test - No Ofertar",
"video_id": "YOUTUBE_ID_HERE",
"warranty": "12 months",
"pictures":[
{"source":"http://mla-s2-p.mlstatic.com/968521-MLA20805195516_072016-O.jpg"}
]
}'
https://api.mercadolibre.com/items?access_token=$ACCESS_TOKEN

Note that this example works for MLA (Argentina), if you’re working on any other country you’ll need to replace values for category_id, currency_id and maybe listing_type_id.

Items with mandatory Mercado Pago

Items with mandatory Mercado Pago
Mercado Pago as the only payment method may be referred to as “Mandatory Mercado Pago” or “Immediate Payment.” Therefore, we exclude the “As agreed with the seller” payment choice.
An item may be marked with immediate payment just like a user or category.
This scenario applies to:

  • All MLB listings.
  • All MLA and MLM listings from the sale of products with “condition: new”.
  • Official Store listings in every country with Mercado Pago.
  • There are categories with Mercado Pago as the only choice. (For more information, visit: “Categories with immediate payment”)
  • User automatically marked to have transactions routed through this flow with the mark “immediate_payment” in the users API.
  • Seller “auto” marked to have sales routed through this flow.

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”.

Example:

POST
curl -X POST -H "Content-Type: application/json" -d
'{
    "title": "Item de test - No Ofertar",
    "category_id": "MLA47392",
    "price": 10,
    "currency_id": "ARS",
    "available_quantity": 1,
    "buying_mode": "buy_it_now",
    "listing_type_id": "gold_special",
    "condition": "new",
    "description": "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",
    "tags": [
        "immediate_payment"
    ],
    "warranty": "12 months by Ray Ban",
    "pictures": [
        {
            "source": "https://upload.wikimedia.org/wikipedia/commons/f/fd/Ray_Ban_Original_Wayfarer.jpg"
        },
        {
            "source": "https://en.wikipedia.org/wiki/File:Teashades.gif"
        }
    ]
}'

https://api.mercadolibre.com/items?access_token=$ACCESS_TOKEN
PUT
curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -d 

‘{
  "tags": [
        "immediate_payment"
    ],
}’


https://api.mercadolibre.com/items/MLA626369506?access_token=$ACCESS_TOKEN

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 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.
Example:

curl -X POST -H "Content-Type: application/json" -d '{
  "title":"Item de Test -No Ofertar",
  "category_id":"MLA34323",
  "price":10,
  "official_store_id": 60,
  "currency_id":"ARS",
  "available_quantity":1,
  "buying_mode":"buy_it_now",
  "listing_type_id":"bronze",
  "condition":"new",
  "description": "Escultura de cerámica",
  "pictures":[
    {"source":"http://mla-s2-p.mlstatic.com/estatuas-femeninas-130-mts-cemento-gris-21185-MLA20205509642_122014-O.jpg"}
  ]
}' https://api.mercadolibre.com/items?access_token=$ACCESS_TOKEN

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 .

Common errors in the API response while listing on multi-brand Official Stores

If you don’t send the official_store_id of the item for a multi-brand Official Store, you’ll get as response the possible IDs you could send with your user:

"message": "Validation error",
   "error": "validation_error",
   "status": 400,
   "cause": [{
       "code": "item.official_store_id.invalid",
       "message": "Users type brand have to provide one of this [60, 274, 257] official store id"
If you send an invalid official_store_id for a multibrand Official Store you’ll get:
{
   "message": "body.invalid_official_store_id",
   "error": "The seller 148829068 is not allowed to use official_store_id 315 on site MLA.",
   "status": 403,
   "cause": []
}

If you send an invalid official_store_id for a multibrand Official Store you’ll get:

{
   "message": "body.invalid_official_store_id",
   "error": "The seller 148829068 is not allowed to use official_store_id 315 on site MLA.",
   "status": 403,
   "cause": []
}

 

Error Codes Reference

Error Description Possible solution
Item.start_time.invalid

Start time $startTime is only updateable in NOT_YET_ACTIVE ítems.

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 atribute. 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.requiresPicturesItem

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.



Next topic: Ship products



Related articles:
Add and configure shipping options for your products.

Know listing prices and exposures.

Learn how to add variations for your products.

Send product identifiers and feature your products on Google Shopping.

Please rate this