Documentação do Mercado Livre

Confira todas as informações necessárias sobre as APIs Mercado Livre.
circulos azuis em degrade

Documentação do

Última atualização em 02/11/2023

Listing types

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.

Important:
Currently, for MLU Marketplace there are Classic combos as listing_type 'bronze' and Premium as 'gold_special'. As of November 15, 2023, we will unify both combos and only the listing_type: free and gold_special (Premium) will be available for MLU . See example.
Learn more about the change in MLU publications .
Nota:
- Remember that the listing_types available for Marketplace and Mshops are free, gold_special, gold_pro (may vary by site).
- Learn more about the costs to sell for a particular listing_type by site, category, currency, logistics and more.

Now your publications are differentiated by the fees you add

Important:
This feature applies only to the Argentina site.

So that you can identify more clearly what your publications offer, we stop calling them Classic or Premium (applies only at frontend level, at backend level we will continue using the listing_type gold_special and gold_pro) and you can differentiate them as follows:

  • Publications in which you choose not to add quotas
    They apply to gold_special publications, they only have the quotas with interest offered by the banks. That's why you only pay the selling charge and, if applicable, also the fixed cost.
  • Publications where you choose to add quotas
    In gold_pro publications, when offering more convenient installments to buyers, you pay the selling fee plus a cost for offering quotas, and the fixed cost if applicable.

Learn more about costs and commissions.


Note the relationship between the listing_type (required attribute) and the campaign tags. Learn more about Quota Campaigns for Marketplace .



Listings types by site

Learn about the different types of publication per Mercado Libre site. To know the available IDs, execute the following request.


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_special",
    "name": "Clásica"
  },
  {
    "site_id": "MLA",
    "id": "free",
    "name": "Gratuita"
  }
]

Example MLU site:

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

Response:

  • Starting November 15, 2023.
[
  {
    "site_id": "MLU",
    "id": "gold_special",
    "name": "Premium"
  },
  {
    "site_id": "MLU",
    "id": "free",
    "name": "Gratuita"
  }
]

Listing type specification

If you want more information about an specific listing_type per site, include the ID in the request:


Request:

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

Example:

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

Response:

{
  "id": "gold_special",
  "not_available_in_categories": [
    "MLA1743",
    "MLA1459",
    "MLA1540"
  ],
  "configuration": {
    "name": "Clásica",
    "listing_exposure": "highest",
    "requires_picture": true,
    "max_stock_per_item": 99999,
    "deduction_profile_id": null,
    "differential_pricing_id": null,
    "duration_days": {
      "buy_it_now": 7300,
      "auction": null,
      "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": 750000,
      "percentage_of_fee_amount": 13,
      "currency": "ARS"
    }
  },
  "exceptions_by_category": []
}

The gold_special and gold_pro publications will have an unlimited duration; you can check this in /items, filtering by the stop_time attribute:


Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$TIEM_ID?attributes=stop_time

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' hh¡ttps://api.mercadolibre.com/items/MLA1389403099?attributes=stop_time

Remember that the publications will be paused if the stock is at 0 and will be activated when you add a new quantity. Learn more about how to update the stock of your publications.


Available listing types

You can check the types of publication available for a given user and category.


Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/available_listing_types?category_id=$CATEGORY_ID

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/1160561786/available_listing_types?category_id=MLA1055

Respuesta:

{
  "category_id": "MLA1055",
  "available": [
    {
      "site_id": "MLA",
      "id": "gold_pro",
      "name": "Premium",
      "remaining_listings": null
    },
    {
      "site_id": "MLA",
      "id": "gold_special",
      "name": "Clásica",
      "remaining_listings": null
    },
    {
      "site_id": "MLA",
      "id": "free",
      "name": "Gratuita",
      "remaining_listings": 10
    }
  ]
}

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:


Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_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

Podrás consultar la información sobre los niveles de exposición asociados a todos los tipos de publicaciones en Mercado Libre por site.


Request:

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

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
  }
]

You can also consult each exposure level separately with its respective ID.


Request:

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

Example:

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

Resposte:

{
  "id": "high",
  "name": "Alta",
  "home_page": false,
  "category_home_page": true,
  "advertising_on_listing_page": false,
  "priority_in_search": 1
}

Transactions available for a publication

You can check the listing_types available for a specific publication, it may vary from site to site.


Request:

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

Example:

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

Response:

[
  {
    "site_id": "MLA",
    "id": "gold_pro",
    "name": "Premium"
  },
  {
    "site_id": "MLA",
    "id": "gold_premium",
    "name": "Oro Premium"
  }
]

Available upgrades

You can make upgrades to higher listing types to give your listings more exposition (upgrade) on our sites. If you need to make an upgrade, you can check which listing types are available for your item, may vary by site. If no upgrades are available, it returns an empty list.


Request:

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

Example:

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

Response:

[
  {
    "site_id": "MLA",
    "id": "gold_pro",
    "name": "Premium"
  }
]

Downgrades available for publication

Downgrade is to reduce the exposure of your publication by upgrading it to a lower type. It is available for some particular cases:

  • It is allowed to downgrade publications from gold_pro to gold_special and vice versa at any time (depends on the site).
  • You can downgrade a publication with status PAYMENT_REQUIED. In addition, in MLA you can also downgrade publications with status ACTIVE, NOT_YET_ACTIVE, UNDER_REVIEW and PAUSED.
  • It is not allowed to downgrade a publication to free.
  • If no downgrades are available, an empty list is returned.

Request:

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

Example:

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

Response:

 [ ]


Update Post Type

Remember that you can switch between gold_special and gold_pro listing types (depends on the site) whenever you want free of charge.
If you want to update the listing_type of a publication, you must make a POST to the following resource:


Request:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Accept: application/json" -d
{
  "id": "gold_special"
}
https://api.mercadolibre.com/items/$TIEM_ID/listing_type

Example:

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/MLA1389403099/listing_type

Response:

{
  "id": "MLA1389403099",
  "site_id": "MLA",
  "title": " Moto Z3 Play 64 Gb  Índigo Oscuro 4 Gb Ram",
  "subtitle": null,
  "seller_id": 1160561786,
  "category_id": "MLA1055",
  "user_product_id": "MLAU10645855",
  "official_store_id": null,
  "price": 18008976,
  "base_price": 18008976,
  "original_price": null,
  "inventory_id": null,
  "currency_id": "ARS",
  "initial_quantity": 6,
  "available_quantity": 6,
  "sold_quantity": 0,
  "sale_terms": []
  "buying_mode": "buy_it_now",
  "listing_type_id": "gold_special"
[...]
}

That's it! You are now ready to access the right exposure for your products and make article updates. As we know that sometimes you need more than one try to make your post, we offer you the possibility to check if your post was exactly how you wanted it before publishing it. Read more about the publication validator.


Learn more about: