Listing types and item upgrades tutorial

According to the level of exposition you want your items to have, you can choose between different kinds of listing types. Each listing type has it’s own characteristics and feeds, let’s take a look of how to work with them properly.

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

Note:
In the other sites, you may use any of the API listings.

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.
or register to recieve the latest news about our API