Listing types and item upgrades tutorial
Contents
→Listings types by site →Listing type specification →Available listing types →Listing exposures →Available upgrades →Downgrades
Listings types by site
First of all, you must know each site has his own listing types. To see all available listing types on a site, you should make a GET to listing_types resources with the Site_id:
Example:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/MLC/listing_types
Response:
[
{
"site_id": "MLC",
"id": "gold_pro",
"name": "Premium"
},
{
"site_id": "MLC",
"id": "gold_premium",
"name": "Oro Premium"
},
{
"site_id": "MLC",
"id": "gold_special",
"name": "Clásica"
},
{
"site_id": "MLC",
"id": "gold",
"name": "Oro"
},
{
"site_id": "MLC",
"id": "silver",
"name": "Plata"
},
{
"site_id": "MLC",
"id": "bronze",
"name": "Bronce"
},
{
"site_id": "MLC",
"id": "free",
"name": "Gratuita"
}
]
In some sites, certain listing types underwent these changes. Anyway, the API continues listing history packages, which are automatically mapped to avoid integration errors. We suggest posting only under the following listing types, which are the active ones:
MLA, MLB, MLC, MLM, MCO
gold_pro: Premium
gold_special: Classic
free: For free
MPE, MLV, MLU
gold_special: Premium
bronze: Classic
free: For free
Listing type specification
If you want more information about an specific listing_type, include the listing_type on the GET call:
Example:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/MLA/listing_types/bronze
Response:
{
"id": "bronze",
"not_available_in_categories": [
"MLA1743",
"MLA1459"
],
"configuration": {
"name": "Bronce",
"listing_exposure": "low",
"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": 0,
"max_fee_amount": 0,
"percentage_of_fee_amount": 0,
"currency": "ARS"
},
"sale_fee_criteria": {
"min_fee_amount": 0,
"max_fee_amount": 100000000000000000,
"percentage_of_fee_amount": 11,
"currency": "ARS"
}
},
"exceptions_by_category": [
{
"category_id": "MLA1540",
"category_name": "Servicios",
"configuration": {
"name": "Básico 90",
"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": 90
},
"immediate_payment": {
"buy_it_now": false,
"auction": false,
"classified": false
},
"mercado_pago": "not_available",
"listing_fee_criteria": {
"min_fee_amount": 347,
"max_fee_amount": 347,
"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": [
]
}
]
}
Items Clásica and Premium will have unlimited duration, you could consult it from stop_time field:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MCO415406202?attributes=stop_time
Also, this listings will be paused if stock is 0, and will be activated when you add new quantity. You’ll see the item like this:
"status": "paused",
"sub_status": [
"out_of_stock"
]
If you want to add stock and active the item again, you should do it in this way:
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Accept: application/json" -d
{
"available_quantity": 1
}
https://api.mercadolibre.com/items/ITEM_ID
Don’t forget that the listing type Gratuita is going to keep the current flow. The seller could change between the listing type Clásica and Premium every time that he wishes it without any charge, and could pause and finish the items in the same way that is working now.
If you wish to change from Premium to Clásica, you will have to follow these steps:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Accept: application/json" -d
{
"id": "gold"
}
https://api.mercadolibre.com/items/$ITEM_ID/listing_type
Available listing types
You can query available listing types by user and for a given category_id.
Example:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$CUST_ID/available_listing_types?category_id={Category_id}
Response:
{
"category_id": "MLC3530",
"available": [
{
"site_id": "MLC",
"id": "gold_premium",
"name": "Oro Premium",
"remaining_listings": null
},
{
"site_id": "MLC",
"id": "gold",
"name": "Oro",
"remaining_listings": null
},
{
"site_id": "MLC",
"id": "silver",
"name": "Plata",
"remaining_listings": null
},
{
"site_id": "MLC",
"id": "bronze",
"name": "Bronce",
"remaining_listings": null
},
{
"site_id": "MLC",
"id": "free",
"name": "Gratuita",
"remaining_listings": null
}
]
}
If you can’t list under a certain listing type and you want to know why you don’t have it available, you can make this GET call to know the cause:
Example:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$CUST_ID/available_listing_type/free?category_id=$CATEGORY_ID
Response:
{
"available": false,
"cause": "You have more than 5 transactions in the last year.",
"code": "list.transactions.exceeded"
}
Listing exposures
This API returns information about the exposure levels associated to all listing types in Mercado Libre. You can query all listing exposures available by site, making a simple GET call.
Example:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/MLA/listing_exposures
Response:
{[
{
"id": "lowest",
"name": "Última",
"home_page": false,
"category_home_page": false,
"advertising_on_listing_page": true,
"priority_in_search": 4
},
{
"id": "low",
"name": "Inferior",
"home_page": false,
"category_home_page": false,
"advertising_on_listing_page": false,
"priority_in_search": 3
},
{
"id": "mid",
"name": "Media",
"home_page": false,
"category_home_page": true,
"advertising_on_listing_page": false,
"priority_in_search": 2
},
{
"id": "high",
"name": "Alta",
"home_page": false,
"category_home_page": true,
"advertising_on_listing_page": false,
"priority_in_search": 1
},
{
"id": "highest",
"name": "Superior",
"home_page": true,
"category_home_page": true,
"advertising_on_listing_page": false,
"priority_in_search": 0
}
]
And query each one by it’s Id:
Example:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/MLA/listing_exposures/high
Response:
{
"id": "high",
"name": "Alta",
"home_page": false,
"category_home_page": true,
"advertising_on_listing_page": false,
"priority_in_search": 1
}
Available upgrades
You can make upgrades to higher listing types to give your listings more exposition on our sites. If you need to make an upgrade, you can check which listing types are available for your item.
Example:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/available_upgrades
Response:
[
{
"site_id": "MLC",
"id": "gold_premium",
"name": "Oro Premium"
},
{
"site_id": "MLC",
"id": "gold",
"name": "Oro"
},
{
"site_id": "MLC",
"id": "silver",
"name": "Plata"
}
]
That’s it! Now you’re ready to get the right exposition for your products and make item upgrades. Since we know sometimes you won’t get your listing done in just one try, we offer you the possibility to check if your listing is exactly the way you want it before publishing. To know more about listing validator, please read this article.
Downgrades
A downgrade is when you reduce your item exposition by updating to a lower listing type. This is available for some particular cases:
- Listings are allowed to have downgrades between gold_pro to gold_special and back anytime.
- Listings on payment_required before they start can be downgraded.
- Downgrade a listing to free is not allowed.