Documentation Mercado Libre

Check out all the necessary information about APIs Mercado Libre.
circulos azuis em degrade

Documentation

Last update 03/10/2023

Sync and modify listings

Once you have active listings on our marketplace, you’ll probably need to update and modify those listings from time to time in order to synchronize stock with other platforms you’re working with, pause listings, improve descriptions, update prices and more.
To update the stock of products you must do it through the Global item and to update the prices in the different marketplaces you must do it through each marketplace item. Follow this guide to know how to achieve this actions.


Update ítems

Considerations

To update any item from your listings, you need to specify the item_id and the seller's access_token. Keep in mind that not every field can be updated and this will vary whether the item had sales or not, and also remember your item must be active in order to be modified. You can modify the values for: available_quantity, price, video, pictures, description, etc.


Note:
To update only the parent item, it must not have had a child item previously. Once a parent item has had a child item created, changing it only is no longer allowed.

To update title, description, price, status and to delete an item, you must do it through each marketplace item.


When the item has sales, you cannot change title, condition, buying mode. Also remember that listing_type can be modified only once.


When updating your listing variations, you can change the values from an existing variation by sending the id and the fields you want to update. Remember to send the id of the other variations or they will be deleted.


If you want to add a new variation, specify all the existing variation's id and add the required fields for the new variation without the id field.


In case you want to remove an existing variation, don't include its id in the body of the request.


Update your listing

We provide you two different ways to update your listings: you can update the global item and the changes you apply will replicate to every marketplace item listed or you can make changes to a specific marketplace item. Remember that when you list a new marketplace item, it will have a global item assigned.



Update global item

As we mention, when updating a global item, all the changes you apply will replicate to every marketplace listing associated with the global item. To do this, you need to specify the global item_id, the acces_token and the fields to modify. Keep in mind that the values of the fields must be written in english.

Example:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -d
{
  "variations": [
          {
              "id": 123,
               "available_quantity": 100
          },
          {
            "available_quantity": 200,
            "attribute_combinations": [
                     {
                         "color": "Blue"
                     } 
                 ]
          }      
      ]
}
https://api.mercadolibre.com/global/items/CBT123

In the previous example we updated the listing's title, the available quantity from an existing variation and added a new variation with the color blue.


Update marketplace item

In this case, the changes sent in the request will only impact the marketplace item that you indicated. Therefore, the values must be written in the local language per site:

  • Spanish for Mercado Libre México, Colombia and Chile.
  • Portuguese for Mercado Livre Brazil.

You can update a specific marketplace item in two different ways:

  • Specifying the marketplace item_id in the URI.

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -d
{
  "title": "Nuevo título"
}
https://api.mercadolibre.com/global/items/MLM123

  • Sending the global item_id in the URI and specifying the site_id and logistic_type in the body.

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -d
{
   "site_id": "MLM",
   "logistic_type": "remote",
   "title": "Nuevo título"
}
https://api.mercadolibre.com/global/items/CBT123

In this case, the listing MLM123 corresponds with the global item CBT123 in the site MLM with the remote logistic, so both of these requests are equivalent.

Notes:
- You can modify the logistic type only with fulfillment or remote value.

- If you want to change the price and stock of an item, it must be taken into account if the publication has variations.

- Allow changes in the titles of the items with sales achieved (sold_quantity = 0).

Description

To update the description item, check our the guide to make sure you get it right.


Pictures

You can always add or replace item pictures. Learn more our working with pictures guide to know the best way to get through it.


Listing status

The available status to global and marketplace items are active or paused and can be managed by the user (seller).


Status descriptions

Active: Listing is active and bids and questions can be received. You can change the listing display (upgrade listing type).
Paused: Listing is paused and bids and questions cant be received. It may be automatically (out of stock) or at the user's discretion.
Inactive: Listing is closed and you can't make any other action.
Under review: Listing has moderated due a problem and needs to be fixed.


Update stock

To update a marketplace item stock you have to make a PUT and add the quantity value in the “available_quantity” field taking the following into account. Remember you can update items with variations and items without variations as following examples.


So, if the seller has 10 (ten) units in stock, they must be detailed in the Global item and this amount will be in all sites where the item is listed, as well as when a sale is made, the subtraction will be reflected in the Global Selling site.


Update stock with variations

Request:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' 
{
"variations": [
       {
           "id": number,
           "available_quantity": number
       },
       {
            "id": number,
           "available_quantity": number
       }
   ]
}
https://api.mercadolibre.com/global/items/$ITEM_ID

Example:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' 
{
"variations": [
       {
           "id": 60819719795,
           "available_quantity": 100
       },
       {
            "id": 60819719802,
           "available_quantity": 150
       }
   ]
}
https://api.mercadolibre.com/global/items/CBT944238398

The response will contain the same fields and the variations that you updated in the PUT.

Update stock without variations

Request:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' 
{
   "available_quantity": number
}
https://api.mercadolibre.com/global/items/$ITEM_ID

Example:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN'
{
   "available_quantity":100
}
https://api.mercadolibre.com/global/items/CBT927817181

Response: Status Code 200



Considerations

  • When making a PUT to an available_quantity with 0, the status will change to “paused” with out_of_stock sub status.
  • When making a PUT to an available_quantity high 0 and out_of_stock status, the status will change to active without out_of_stock sub status.

Update prices

In relation to the price of the product, the seller can put a specific price for each marketplace item and if it's not defined, the price of the Global item will be replicated on marketplace items. Look at the next PUT example to modify a specific marketplace item price.

Request:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN'  
{
    "site_id": string,
    "logistic_type": string,
    "price": number
}
https://api.mercadolibre.com/global/items/$ITEM_ID

Example:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN'  
{
    "site_id": “MLM”,
    "logistic_type": “remote”, 
    "price": 30
}
https://api.mercadolibre.com/global/items/CBT939124833

Response: Status Code 200


Delete marketplace items

In order to delete marketplace items, the item to delete must be in a paused or closed state and then make the following PUT.



Fulfillment restrictions

When updating a global item with at least one of its marketplace listings using the Fulfillment logistic, and with current stock or a valid inbound, the following validations are done.

If the marketplace listing has at least one variation:

  • The edition of attribute_combinations values is not allowed, this means:

  • - The addition of attribute combinations is not allowed.


    - The modification of attribute combinations is not allowed.


    - The deletion of attribute combinations is not allowed.


  • The elimination of an existing variation is not allowed.
  • The change of status to "closed" is not allowed.

If the marketplace listing doesn't have variations:

  • The addition of a new variation is not allowed.
  • The change of status to "closed" is not allowed.

Package validations

The packages attributes of an listing must follow the requirements below:

  • The width, height and length must be greater or equal than 3 centimeters.
  • The weight must be greater or equal than 50 grams.
  • The volume calculated with the following formula must be bigger than 0.02

Width * Height * Length/5000

Rate limit locking restriction

We implemented a rate limit restriction in order to control the requests sended to the API. The rate limit is configured to 1500 requests per minute per seller, if you exceed this limit, you will receive an empty response with a 429 status code.


Errors

Error Message Solution
400 - Validation error Cannot modify CBT item from this resource. To edit global items: send the URL https://api.mercadolibre.com/global/items. To edit marketplace items: send the https://api.mercadolibre.com/global/items/CBTXXX with the marketplace item information.
400 - Validation error The item could not be updated because the item or variation you are trying to modify has inventory. The request sended doesn't pass Fulfillment validations. Please, check Fulfillment restrictions.
400 - Bad request Error processing dimensions for item The request sended doesn't contain all the packages attributes mentioned. For information about shipment dimensions and cost, visit our shipping cost calculator.
422 - bad request The submitted dimensions and/or weights do not correspond to real measurements of the package. You must use the correct dimensions of the package that you'll use to dispatch your product, as well as the net weight of the item. Check more information about How to calculate the shipping cost of your products.

Next: Fulfillment stock.