Sync and modify listings

Important:
As of July 1, it will be mandatory that all PUT requests to items be: https://api.mercadolibre.com/global/items. Please, start updating your endpoints.

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 items

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.


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.

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
{
  "title": "New title",
  "variations": [
          {
              "id": 123,
               "available_quantity": 100
          },
          {
            "available_quantity": 200,
            "price": 40,
            "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.

- Don't allow changes in the titles of the items with sales achieved (sold_quantity = 0).

Description

It’s very easy to update a description, and is something you can do whether the item has bids or not. Check our Guide to modify items 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 that this change can be made to items and item variations.


For example, 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 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:

{
   "id": "CBT939124833",
    "site_id": "CBT",
    "title": "Test Item - For Loadtest Tests",
    "subtitle": null,
    "seller_id": 526124693,
    "category_id": "CBT11796",
    "official_store_id": null,
    "price": 15.1,
    "base_price": 15.1,
    "original_price": null,
    "inventory_id": null,
    "currency_id": "USD",
    "initial_quantity": 1,
    "available_quantity": 100,
    "sold_quantity": 0,
    "sale_terms": [...],
    "buying_mode": "buy_it_now",
    "listing_type_id": "gold_pro",
    "start_time": "2020-06-19T19:35:57.000Z",
    "stop_time": "2040-06-14T04:00:00.000Z",
    "end_time": "2040-06-14T04:00:00.000Z",
    "expiration_time": "2020-09-07T19:37:30.837Z",
    "condition": "new",
    "permalink": "",
    "pictures": [...],
    "video_id": null,
    "descriptions": [...],
    "accepts_mercadopago": true,
    "non_mercado_pago_payment_methods": [],
    "shipping": {...},
    "international_delivery_mode": "none",
    "seller_address": {...},
    "seller_contact": null,
    "location": {},
    "geolocation": {...},
    "coverage_areas": [],
    "attributes": [...],
    "warnings": [],
    "listing_source": "",
    "variations": [],
    "thumbnail": "http://http2.mlstatic.com/resources/frontend/statics/processing-image/1.0.0/I-ES.jpg",
    "secure_thumbnail": "https://http2.mlstatic.com/resources/frontend/statics/processing-image/1.0.0/I-ES.jpg",
    "status": "active",
    "sub_status": [],
    "tags": [...],
    "warranty": "Factory warranty: 90 days",
    "catalog_product_id": null,
    "domain_id": "CBT-BABIES_FOOTWEAR",
    "seller_custom_field": null,
    "parent_item_id": null,
    "differential_pricing": null,
    "deal_ids": [],
    "automatic_relist": false,
    "date_created": "2020-06-19T19:35:57.000Z",
    "last_updated": "2020-06-19T19:37:30.882Z",
    "health": null,
    "catalog_listing": false,
    "item_relations": []
}

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.


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/marketplace/items/$ITEM_ID

Example:

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

Response:

{
    "item_id": "CBT939124833",
    "parent_id": "CBT939124833",
    "logistic_type": "remote",
    "site_id": "MLM",
    "errors": null
}

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.


Validations and restrictions

What do we validate?

In the process of updating listings, several validations are made to ensure the correct process of updating the listing. These validations are further explained below.


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 request sended doesn't pass these validations, you will receive the following message:

{
   "message": "validation_error",
   "error": "bad_request",
   "status": 400,
   "cause":[
       {
           "department": "cbt-items-wrapper",
           "cause_id": 5013,
           "type": "error",
           "code": "item.variation.invalid",
           "message": "The listing cannot be updated yet because the
                       variation you are trying to modify is still
                       being processed in inventory"
       }    
   ]
}

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.

Similarly, if the request sended doesn't pass these validations, you will receive the next message:

{
   "message": "validation_error",
   "error": "bad_request",
   "status": 400,
   "cause":[
       {
           "department": "cbt-items-wrapper",
           "cause_id": 5013,
           "type": "error",
           "code": "item.variation.invalid",
           "message": "The listing cannot be updated yet because you are
                       trying to modify is still being processed
                       in inventory"
       }    
   ]
}

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 * Length5000
If the request sended doesn't satisfy the previous requirements, the following error message will be responded:

{
   "message": "Validation error",
   "error": "bad_request",
   "status": 422,
   "cause":[
       {
           "department": "cbt-item-validation",
           "cause_id": 5125,
           "type": "error",
           "code": "item.dimensions",
           "references": [
               "https://global-selling.mercadolibre.com/help/22213"
           ],
           "message": "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.  
                                      https://global-selling.mercadolibre.com/help/22213"
       }    
   ]
}

In addition, if the request sended doesn't contain all the packages attributes mentioned, the following error message will be responded:

{
   "message": "error processing dimensions for item",
   "error": "bad_request",
   "status": 400,
   "cause":[]
}

For information about shipment dimensions and cost, visit our shipping cost calculator.


Listing locking restriction

We implemented a listing-locking restriction in order to control the requests sended to the API. When you send a request to update a listing and the API is still processing this petition, any following request to the same listing will be locked and you will receive the next error message.

{
   "message": "The items is still being processed",
   "error": "Your request requires more time to be processed. Please
            increase your timeout to process this kind of items",
   "status": 423,
   "cause":[
       {
           "cause_id": 5016,
           "type": "error",
           "code": "item.locked",
           "message": "Resource $ITEM_ID already locked"
       }    
   ]
}

This will happen more often if you are trying to update listings with large amounts of variations. For these cases, please consider increasing your timeout.


Next: Fulfillment stock.