Sync and modify listings

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.

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.

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

Next: Fulfillment stock.