Sync and moditify 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. Follow this guide to know how to achieve this actions.



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:
  • Title
  • Available_quantity
  • Price
  • Video
  • Pictures
  • Description*
  • Shipping
*It's not possible modify, just add a post. When the item has sales you won’t be allowed to change any of the following item fields:
  • Condition
  • Buying mode
  • Non MercadoPago Payment Methods
  • Warranty
  • Description*
  • *It's not possible modify, just add a post.
Also remember that:
  • Category can’t be modified via API.
  • Listing type can be modified only once.

Update your item

Let’s see a basic example of updating an item title and price. The only thing you need is the item_id of the listed product and of course, the seller’s access_token. Example:
 curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -d
  "title": "Your new title",
  "price": 1000

Nice, your item title and price has been updated and you should receive a code 200 OK response status to know everything went well. Keep in mind that it can take some time until you see the item’s information refreshed.


It’s very easy to update a description, and is something you can do whether the item has bids or not, but since there are some considerations you need to keep when adding or replacing descriptions, check our descriptions article to make sure you get it right.


You can always add or replace item pictures, refer to our working with pictures tutorial to know the best way to get through it.

Listing types

When you want more exposition on your item you need to make a listing type upgrade. Know the details and considerations and learn how to achieve an upgrade on our Listing types and Upgrades tutorial.

Changing listing status

Any item listed on our marketplace can hold different status, check the following description of each one:
closed: Finalizes your publication. Once closed, it cannot be reactivated again, but it can be relisted. Example:
curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -d

paused: Pauses your publication. Once paused, it will not be visible to other MercadoLibre’s users, but it will not be closed and it can be reactivated later on. Example:
curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -d

active: Reactivates a previously paused item. Example:
curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -d

Note: If you need to make any changes on the item status, you need to send any of these values for the “status” field, note the value is case sensitive and must be sent in lowercase. If your item is currently closed and your intention is to relist it, check our relist article to achieve it right away. Please check out the listing life-cycle article to know more about item status.

Machine Status Reference

Active: Listing is active and bids and questions can be received. You can change the listing display (upgrade listing type). Payment required: This is the case where a debtor user or a user with low credit policy makes a listing and it is automatically reactivated once the user makes the payment. Under Review: The item is under review by Mercado Libre due to the following reasons:
  • warning: item still active but pending to be corrected by the user. If it is not corrected within 2 days it will change to waiting_for_patch.
  • waiting_for_patch: item hidden until the user corrects the reported breach.
  • held: hidden item waiting for a manual moderation by Mercado Libre.
  • pending_documentation: item hidden until the user submits the requested documentation.
  • forbidden: item removed due to moderation.
Note: If you have any doubts about this state we suggest you check it with your commercial assessorr or MyML. Paused: It may be automatically (out of stock) or at the user's discretion.
  • out of stock: the item was paused for being out of stock, and it will be automatically activated upon restocking.
Note: The item will be paused in the VIP and no bids can be received. Closed: This is the final item status, and it can be due to the following reasons:
  • waiting for patch
  • held
  • expired: the listing end time was reached (end_time), and there is still stock.
  • deleted: it is added when the item is closed, and the seller decides to delete it. Or when the item expires and it is automatically re-listed.
  • suspended
  • freezed
Note: Bear in mind that, after a period of time, finished items will no longer be displayed for query. Inactive: If the relevant correction is not made to get out of the under review status, the item goes to inactive. Corrections can be found in the user's account, sales section, "review" listings tab.

Delete listing

Deleting a listing has no way back, so be careful when you call this action. Also note that there’s no need to delete closed items since they’ll be discarded automatically after some time. If you still need to delete an item, for example items in status: payment_required that won’t respond to ‘closed’ status, do as it follows: Example: First step
curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -d
"status": "closed"
Second step
curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -d
  • - If with the second PUT you get an error:
  • message: item optimistic locking error: conflict status: 409 cause: array(0) This means you should wait a few seconds until the information is updated.
  • Once the listing is removed, it will remain in the VIP for a short time as "listing finished.".
That’s it! Your item should be removed.

Update stock

Updating an item stock is quite easy. Just add the value in the “available_quantity” field taking the following into account:
  • 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.
  • An item sent with available_quantity = 0 can only be paused when its condition type = new and it is not listing_type = free.
Note: This change can be made to items and item variations.

Where is this functionality possible?

Those sites that support automatic pausing with stock 0 are MLB, MLA, MLM, MLC, MPE, MLV. Example:
curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -d
  "available_quantity": 6
Easy. You can check your listing and see stock updated. If you need to update stock or make any changes on an item with variations, you’ll find a slightly difference on how the updates are made, please follow up our variations tutorial to know how to do it right.
Next topic: Manage questions & answers.

Be part of our community