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.

Contents

→Considerations
→Update your item
→Description
→Pictures
→Listing types
→Changing listing status
→Machine Status Reference
→Delete listing
→Update stock
    ↳Where is this functionality possible?
→Add stock availability time
    ↳Considerations
    ↳Create an item with stock availability
    ↳Modify stock availability
    ↳Delete stock availability
→Maximum purchase quantity
→Competitive prices (only available in Mexico and Brazil)


Considerations

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
  • Shipping

When the item has sales, you cannot change any of the following fields:

  • Title
  • Condition
  • Buying mode

Also remember that:

  • 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.

Note:
We do not allow changes in the titles of the items with sales achieved (sold_quantity = 0). Remember this to restrict this in your tool and avoid errors in this type of update.
Example:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Accept: application/json" -d
{
  "title": "Your new title",
  "price": 1000
}
https://api.mercadolibre.com/items/ITEM_ID

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.


Description

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.


Pictures

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 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Accept: application/json" -d
{
  "status":"closed"
}
https://api.mercadolibre.com/items/ITEM_ID
  • 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 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Accept: application/json" -d
{
  "status":"paused"
}
https://api.mercadolibre.com/items/ITEM_ID
  • active: Reactivates a previously paused item.

Example:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Accept: application/json" -d
{
  "status":"active"
}
https://api.mercadolibre.com/items/ITEM_ID
Nota:
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.
Nota:
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 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Accept: application/json" -d
{
"status": "closed"
}
https://api.mercadolibre.com/items/ITEM_ID
  • Second step
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Accept: application/json" -d
{
"deleted":"true"
}
https://api.mercadolibre.com/items/ITEM_ID
Notes:
- 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 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Accept: application/json" -d
{
  "available_quantity": 6
}
https://api.mercadolibre.com/items/ITEM_ID

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.


Add stock availability time

In this section, we will show you how to use the feature that allows you to tell the buyers how much time it takes for the products to be ready to sell.

It can be used in the following cases:

  • Custom-made orders.
  • Product manufacture.
  • Product customization for sale.
  • When you receive stock from a supplier on a regular basis.

This way, the listing will remain active even though the products are not ready for sale and the buyers will be able to buy them knowing the exact date when they will arrive.

Keep in mind that if you extend the period, the listings will have less exposure. We will always show first the listings with available stock, therefore make sure to use it only when necessary.

Important:
As of January 29, you can specify the time of stock availability for ads in Brazil. In Argentina, Uruguay, Colombia, Chile and Mexico it is already available.

Within the section sale_terms of an item, you can specify the stock availability time of your listing using the sale_term MANUFACTURING_TIME.


Call:

curl -X GET https://api.mercadolibre.com/categories/$CATEGORY_ID/sale_terms

Example:

curl -X GET https://api.mercadolibre.com/categories/MLA1577/sale_terms

Response:

[
  {
    "id": "INVOICE",
    "name": "Facturación",
    "tags": {
      "hidden": true,
      "multivalued": true
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 1,
    "value_type": "list",
    "values": [
      {
        "id": "6891885",
        "name": "Factura A"
      },
      {
        "id": "6891886",
        "name": "Factura B"
      },
      {
        "id": "6891887",
        "name": "Factura C"
      },
      {
        "id": "6891888",
        "name": "No factura"
      }
    ],
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "SUBSCRIBABLE",
    "name": "Suscribible",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "boolean",
    "values": [
      {
        "id": "242084",
        "name": "No",
        "metadata": {
          "value": false
        }
      },
      {
        "id": "242085",
        "name": "Sí",
        "metadata": {
          "value": true
        }
      }
    ],
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "PRICE_SUBSCRIPTION",
    "name": "Precio por suscripción",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "number_unit",
    "value_max_length": 255,
    "allowed_units": [
      {
        "id": "USD",
        "name": "USD"
      },
      {
        "id": "UVA",
        "name": "UVA"
      },
      {
        "id": "ARS",
        "name": "ARS"
      }
    ],
    "default_unit": "USD",
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "SUBSCRIPTION_FREE_SHIPPING",
    "name": "Envío gratis por suscripciones",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "boolean",
    "values": [
      {
        "id": "242084",
        "name": "No",
        "metadata": {
          "value": false
        }
      },
      {
        "id": "242085",
        "name": "Sí",
        "metadata": {
          "value": true
        }
      }
    ],
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "LOYALTY_LEVEL_1",
    "name": "Precio por nivel 1 de loyalty",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "number_unit",
    "value_max_length": 255,
    "allowed_units": [
      {
        "id": "USD",
        "name": "USD"
      },
      {
        "id": "UVA",
        "name": "UVA"
      },
      {
        "id": "ARS",
        "name": "ARS"
      }
    ],
    "default_unit": "USD",
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "LOYALTY_LEVEL_2",
    "name": "Precio por nivel 2 de loyalty",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "number_unit",
    "value_max_length": 255,
    "allowed_units": [
      {
        "id": "USD",
        "name": "USD"
      },
      {
        "id": "UVA",
        "name": "UVA"
      },
      {
        "id": "ARS",
        "name": "ARS"
      }
    ],
    "default_unit": "USD",
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "LOYALTY_LEVEL_3",
    "name": "Precio por nivel 3 de loyalty",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "number_unit",
    "value_max_length": 255,
    "allowed_units": [
      {
        "id": "USD",
        "name": "USD"
      },
      {
        "id": "UVA",
        "name": "UVA"
      },
      {
        "id": "ARS",
        "name": "ARS"
      }
    ],
    "default_unit": "USD",
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "LOYALTY_LEVEL_4",
    "name": "Precio por nivel 4 de loyalty",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "number_unit",
    "value_max_length": 255,
    "allowed_units": [
      {
        "id": "USD",
        "name": "USD"
      },
      {
        "id": "UVA",
        "name": "UVA"
      },
      {
        "id": "ARS",
        "name": "ARS"
      }
    ],
    "default_unit": "USD",
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "LOYALTY_LEVEL_5",
    "name": "Precio por nivel 5 de loyalty",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "number_unit",
    "value_max_length": 255,
    "allowed_units": [
      {
        "id": "USD",
        "name": "USD"
      },
      {
        "id": "UVA",
        "name": "UVA"
      },
      {
        "id": "ARS",
        "name": "ARS"
      }
    ],
    "default_unit": "USD",
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "LOYALTY_LEVEL_6",
    "name": "Precio por nivel 6 de loyalty",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "number_unit",
    "value_max_length": 255,
    "allowed_units": [
      {
        "id": "USD",
        "name": "USD"
      },
      {
        "id": "UVA",
        "name": "UVA"
      },
      {
        "id": "ARS",
        "name": "ARS"
      }
    ],
    "default_unit": "USD",
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "CHECKOUT_EXCHANGE_RATE",
    "name": "Tipo de cambio para checkout",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "number_unit",
    "value_max_length": 255,
    "allowed_units": [
      {
        "id": "ARS/USD",
        "name": "ARS/USD"
      }
    ],
    "default_unit": "ARS/USD",
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "DISCOUNT_SUBSCRIPTION",
    "name": "Descuento por suscripciones",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "number_unit",
    "value_max_length": 255,
    "allowed_units": [
      {
        "id": "%",
        "name": "%"
      }
    ],
    "default_unit": "%",
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "WARRANTY_TYPE",
    "name": "Tipo de garantía",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "list",
    "values": [
      {
        "id": "2230280",
        "name": "Garantía del vendedor"
      },
      {
        "id": "2230279",
        "name": "Garantía de fábrica"
      },
      {
        "id": "6150835",
        "name": "Sin garantía"
      }
    ],
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "WARRANTY_TIME",
    "name": "Tiempo de garantía",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "number_unit",
    "value_max_length": 255,
    "allowed_units": [
      {
        "id": "días",
        "name": "días"
      },
      {
        "id": "meses",
        "name": "meses"
      },
      {
        "id": "años",
        "name": "años"
      }
    ],
    "default_unit": "meses",
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "MANUFACTURING_TIME",
    "name": "Tiempo de elaboración",
    "tags": {
      "hidden": true
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "number_unit",
    "value_max_length": 255,
    "allowed_units": [
      {
        "id": "días",
        "name": "días"
      }
    ],
    "default_unit": "días",
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  }
]

Considerations

  • When setting stock availability you cannot set values higher than 45 days.
  • You cannot specify this information in listings related to the verticals Real Estate, Automoviles and Services.
  • It is not allowed to set stock availability time in items that allow flex delivery or that belong to Fulfillment.
  • When adding or modifying the sale term, always use one of the available units. You will find them in the section allowed_units. Following the example above, you can observe that only the unit “days” is available to use within the category MLA1577.
Note:
The previous validations won’t be applied in real time while interacting with the items resource. If one of the requirements is not met a warning will be returned -with cause_id: 2110 and code: delete.item.sale_terms.manufacturing_time- specifying the action that will run in the background on the sale_term.

Create an item with stock availability

To create a listing, first you must determine which categories you wish to publish, then you must check that MANUFACTURING_TIME is available for said category. To do this, you must make a GET to the resource sale_terms and check that it appears on the list.


Call:

curl -X GET https://api.mercadolibre.com/categories/$CATEGORY_ID/sale_terms

Example:

curl -X GET https://api.mercadolibre.com/categories/MLA1577/sale_terms

Response:

[
  {
    "id": "INVOICE",
    "name": "Facturación",
    "tags": {
      "hidden": true,
      "multivalued": true
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 1,
    "value_type": "list",
    "values": [
      {
        "id": "6891885",
        "name": "Factura A"
      },
      {
        "id": "6891886",
        "name": "Factura B"
      },
      {
        "id": "6891887",
        "name": "Factura C"
      },
      {
        "id": "6891888",
        "name": "No factura"
      }
    ],
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "SUBSCRIBABLE",
    "name": "Suscribible",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "boolean",
    "values": [
      {
        "id": "242084",
        "name": "No",
        "metadata": {
          "value": false
        }
      },
      {
        "id": "242085",
        "name": "Sí",
        "metadata": {
          "value": true
        }
      }
    ],
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "PRICE_SUBSCRIPTION",
    "name": "Precio por suscripción",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "number_unit",
    "value_max_length": 255,
    "allowed_units": [
      {
        "id": "USD",
        "name": "USD"
      },
      {
        "id": "UVA",
        "name": "UVA"
      },
      {
        "id": "ARS",
        "name": "ARS"
      }
    ],
    "default_unit": "USD",
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "SUBSCRIPTION_FREE_SHIPPING",
    "name": "Envío gratis por suscripciones",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "boolean",
    "values": [
      {
        "id": "242084",
        "name": "No",
        "metadata": {
          "value": false
        }
      },
      {
        "id": "242085",
        "name": "Sí",
        "metadata": {
          "value": true
        }
      }
    ],
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "LOYALTY_LEVEL_1",
    "name": "Precio por nivel 1 de loyalty",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "number_unit",
    "value_max_length": 255,
    "allowed_units": [
      {
        "id": "USD",
        "name": "USD"
      },
      {
        "id": "UVA",
        "name": "UVA"
      },
      {
        "id": "ARS",
        "name": "ARS"
      }
    ],
    "default_unit": "USD",
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "LOYALTY_LEVEL_2",
    "name": "Precio por nivel 2 de loyalty",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "number_unit",
    "value_max_length": 255,
    "allowed_units": [
      {
        "id": "USD",
        "name": "USD"
      },
      {
        "id": "UVA",
        "name": "UVA"
      },
      {
        "id": "ARS",
        "name": "ARS"
      }
    ],
    "default_unit": "USD",
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "LOYALTY_LEVEL_3",
    "name": "Precio por nivel 3 de loyalty",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "number_unit",
    "value_max_length": 255,
    "allowed_units": [
      {
        "id": "USD",
        "name": "USD"
      },
      {
        "id": "UVA",
        "name": "UVA"
      },
      {
        "id": "ARS",
        "name": "ARS"
      }
    ],
    "default_unit": "USD",
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "LOYALTY_LEVEL_4",
    "name": "Precio por nivel 4 de loyalty",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "number_unit",
    "value_max_length": 255,
    "allowed_units": [
      {
        "id": "USD",
        "name": "USD"
      },
      {
        "id": "UVA",
        "name": "UVA"
      },
      {
        "id": "ARS",
        "name": "ARS"
      }
    ],
    "default_unit": "USD",
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "LOYALTY_LEVEL_5",
    "name": "Precio por nivel 5 de loyalty",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "number_unit",
    "value_max_length": 255,
    "allowed_units": [
      {
        "id": "USD",
        "name": "USD"
      },
      {
        "id": "UVA",
        "name": "UVA"
      },
      {
        "id": "ARS",
        "name": "ARS"
      }
    ],
    "default_unit": "USD",
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "LOYALTY_LEVEL_6",
    "name": "Precio por nivel 6 de loyalty",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "number_unit",
    "value_max_length": 255,
    "allowed_units": [
      {
        "id": "USD",
        "name": "USD"
      },
      {
        "id": "UVA",
        "name": "UVA"
      },
      {
        "id": "ARS",
        "name": "ARS"
      }
    ],
    "default_unit": "USD",
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "CHECKOUT_EXCHANGE_RATE",
    "name": "Tipo de cambio para checkout",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "number_unit",
    "value_max_length": 255,
    "allowed_units": [
      {
        "id": "ARS/USD",
        "name": "ARS/USD"
      }
    ],
    "default_unit": "ARS/USD",
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "DISCOUNT_SUBSCRIPTION",
    "name": "Descuento por suscripciones",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "number_unit",
    "value_max_length": 255,
    "allowed_units": [
      {
        "id": "%",
        "name": "%"
      }
    ],
    "default_unit": "%",
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "WARRANTY_TYPE",
    "name": "Tipo de garantía",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "list",
    "values": [
      {
        "id": "2230280",
        "name": "Garantía del vendedor"
      },
      {
        "id": "2230279",
        "name": "Garantía de fábrica"
      },
      {
        "id": "6150835",
        "name": "Sin garantía"
      }
    ],
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "WARRANTY_TIME",
    "name": "Tiempo de garantía",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "number_unit",
    "value_max_length": 255,
    "allowed_units": [
      {
        "id": "días",
        "name": "días"
      },
      {
        "id": "meses",
        "name": "meses"
      },
      {
        "id": "años",
        "name": "años"
      }
    ],
    "default_unit": "meses",
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "MANUFACTURING_TIME",
    "name": "Tiempo de elaboración",
    "tags": {
      "hidden": true
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "number_unit",
    "value_max_length": 255,
    "allowed_units": [
      {
        "id": "días",
        "name": "días"
      }
    ],
    "default_unit": "días",
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  }
]

Finally, create the JSON to generate the listing. Below you can see how to do this:


Call:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" https://api.mercadolibre.com/items  -d

Example:

{
 "site_id":"MLA",
 "title":"Item de testeo, por favor no contactar --kc:off",
 "category_id":"MLA1577",
 "price":4000,
 "currency_id":"ARS",
"pictures": [
      {
        "source": "http://mla-s2-p.mlstatic.com/777099-MLA26466460545_112017-O.jpg"   
 }
  ],
 "buying_mode":"buy_it_now",
 "listing_type_id":"gold_special",
 "condition":"new",
 "available_quantity":10,
 "sale_terms":[
   {
     "id":"MANUFACTURING_TIME",
     "value_name":"20 días"
   } 
]
}

Modify stock availability

Once the listing is created, you can add the MANUFACTURING_TIME if there isn’t one, or modify its value if there is one.

If you want to add MANUFACTURING_TIME to a listing, first check that the corresponding category allows it. How? Make a GET to the resource sale_terms and validate that the stock availability is available to use.


Example:

curl -X GET https://api.mercadolibre.com/categories/MLA1577/sale_terms

Response:

[
  {
    "id": "INVOICE",
    "name": "Facturación",
    "tags": {
      "hidden": true,
      "multivalued": true
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 1,
    "value_type": "list",
    "values": [
      {
        "id": "6891885",
        "name": "Factura A"
      },
      {
        "id": "6891886",
        "name": "Factura B"
      },
      {
        "id": "6891887",
        "name": "Factura C"
      },
      {
        "id": "6891888",
        "name": "No factura"
      }
    ],
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "SUBSCRIBABLE",
    "name": "Suscribible",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "boolean",
    "values": [
      {
        "id": "242084",
        "name": "No",
        "metadata": {
          "value": false
        }
      },
      {
        "id": "242085",
        "name": "Sí",
        "metadata": {
          "value": true
        }
      }
    ],
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "PRICE_SUBSCRIPTION",
    "name": "Precio por suscripción",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "number_unit",
    "value_max_length": 255,
    "allowed_units": [
      {
        "id": "USD",
        "name": "USD"
      },
      {
        "id": "UVA",
        "name": "UVA"
      },
      {
        "id": "ARS",
        "name": "ARS"
      }
    ],
    "default_unit": "USD",
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "SUBSCRIPTION_FREE_SHIPPING",
    "name": "Envío gratis por suscripciones",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "boolean",
    "values": [
      {
        "id": "242084",
        "name": "No",
        "metadata": {
          "value": false
        }
      },
      {
        "id": "242085",
        "name": "Sí",
        "metadata": {
          "value": true
        }
      }
    ],
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "LOYALTY_LEVEL_1",
    "name": "Precio por nivel 1 de loyalty",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "number_unit",
    "value_max_length": 255,
    "allowed_units": [
      {
        "id": "USD",
        "name": "USD"
      },
      {
        "id": "UVA",
        "name": "UVA"
      },
      {
        "id": "ARS",
        "name": "ARS"
      }
    ],
    "default_unit": "USD",
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "LOYALTY_LEVEL_2",
    "name": "Precio por nivel 2 de loyalty",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "number_unit",
    "value_max_length": 255,
    "allowed_units": [
      {
        "id": "USD",
        "name": "USD"
      },
      {
        "id": "UVA",
        "name": "UVA"
      },
      {
        "id": "ARS",
        "name": "ARS"
      }
    ],
    "default_unit": "USD",
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "LOYALTY_LEVEL_3",
    "name": "Precio por nivel 3 de loyalty",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "number_unit",
    "value_max_length": 255,
    "allowed_units": [
      {
        "id": "USD",
        "name": "USD"
      },
      {
        "id": "UVA",
        "name": "UVA"
      },
      {
        "id": "ARS",
        "name": "ARS"
      }
    ],
    "default_unit": "USD",
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "LOYALTY_LEVEL_4",
    "name": "Precio por nivel 4 de loyalty",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "number_unit",
    "value_max_length": 255,
    "allowed_units": [
      {
        "id": "USD",
        "name": "USD"
      },
      {
        "id": "UVA",
        "name": "UVA"
      },
      {
        "id": "ARS",
        "name": "ARS"
      }
    ],
    "default_unit": "USD",
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "LOYALTY_LEVEL_5",
    "name": "Precio por nivel 5 de loyalty",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "number_unit",
    "value_max_length": 255,
    "allowed_units": [
      {
        "id": "USD",
        "name": "USD"
      },
      {
        "id": "UVA",
        "name": "UVA"
      },
      {
        "id": "ARS",
        "name": "ARS"
      }
    ],
    "default_unit": "USD",
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "LOYALTY_LEVEL_6",
    "name": "Precio por nivel 6 de loyalty",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "number_unit",
    "value_max_length": 255,
    "allowed_units": [
      {
        "id": "USD",
        "name": "USD"
      },
      {
        "id": "UVA",
        "name": "UVA"
      },
      {
        "id": "ARS",
        "name": "ARS"
      }
    ],
    "default_unit": "USD",
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "CHECKOUT_EXCHANGE_RATE",
    "name": "Tipo de cambio para checkout",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "number_unit",
    "value_max_length": 255,
    "allowed_units": [
      {
        "id": "ARS/USD",
        "name": "ARS/USD"
      }
    ],
    "default_unit": "ARS/USD",
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "DISCOUNT_SUBSCRIPTION",
    "name": "Descuento por suscripciones",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "number_unit",
    "value_max_length": 255,
    "allowed_units": [
      {
        "id": "%",
        "name": "%"
      }
    ],
    "default_unit": "%",
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "WARRANTY_TYPE",
    "name": "Tipo de garantía",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "list",
    "values": [
      {
        "id": "2230280",
        "name": "Garantía del vendedor"
      },
      {
        "id": "2230279",
        "name": "Garantía de fábrica"
      },
      {
        "id": "6150835",
        "name": "Sin garantía"
      }
    ],
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "WARRANTY_TIME",
    "name": "Tiempo de garantía",
    "tags": {
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "number_unit",
    "value_max_length": 255,
    "allowed_units": [
      {
        "id": "días",
        "name": "días"
      },
      {
        "id": "meses",
        "name": "meses"
      },
      {
        "id": "años",
        "name": "años"
      }
    ],
    "default_unit": "meses",
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "MANUFACTURING_TIME",
    "name": "Tiempo de elaboración",
    "tags": {
      "hidden": true
    },
    "hierarchy": "SALE_TERMS",
    "relevance": 2,
    "value_type": "number_unit",
    "value_max_length": 255,
    "allowed_units": [
      {
        "id": "días",
        "name": "días"
      }
    ],
    "default_unit": "días",
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  }
]

Once checked, create the JSON to modify the listing and add MANUFACTURING_TIME. See how to do this:


Call:

curl -H 'Content-Type: application/json' -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID  -d

Example:

{
   "sale_terms": [{
       "id": "MANUFACTURING_TIME",
       "value_name": "20 días"
   }]
}

If the listing already has MANUFACTURING_TIME and you only want to modify its value, make a similar PUT specifying the new sale_term value in value_name.


Call:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' -X PUT https://api.mercadolibre.com/items/$ITEM_ID  -d

Example:

{
   "sale_terms": [{
       "id": "MANUFACTURING_TIME",
       "value_name": "30 días"
   }]
}

Delete stock availability

To delete the sale term MANUFACTURING_TIME, send null in the fields value_id and value_name.


Call:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' -X PUT https://api.mercadolibre.com/items/$ITEM_ID  -d

Example:

{
  "sale_terms": [
    {
      "id": "MANUFACTURING_TIME",
      "value_id": null
      "value_name": null
    }
  ]
}

Maximum purchase quantity

In the responsible consumption context by Covid-19, we limit the number of items per purchase to avoid abuse and shortages in critical products in the Supermercaado category. Check if the category has the maximum sale quantity condition with the $ CATEGORY_ID.

Example:

curl -X GET https://api.mercadolibre.com/categories/MLM167991/sale_terms

Response:

[
...
{
        "id": "PURCHASE_MAX_QUANTITY",
        "name": "Cantidad máxima de compra",
        "tags": {
            "hidden": true,
            "read_only": true
        },
        "hierarchy": "SALE_TERMS",
        "relevance": 2,
        "value_type": "number",
        "value_max_length": 18,
        "attribute_group_id": "OTHERS",
        "attribute_group_name": "Otros"
    }
...
]

Example of a product with this condition:

Request:

curl -X GET https://api.mercadolibre.com/items/$ITEM_ID

Example:

curl -X GET https://api.mercadolibre.com/items/MLA847983293

Response:

"title": "Alcohol En Gel 500 Ml Botella Pet",
...
"sale_terms": [
        {
            "id": "PURCHASE_MAX_QUANTITY",
            "name": "Cantidad máxima de compra",
            "value_id": null,
            "value_name": "10",
            "value_struct": null,
            "values": [
                {
                    "id": null,
                    "name": "10",
                    "struct": null
                }
            ]
        }
]
...

In this case, the maximum quantity to buy is 10 units.


Competitive prices (only available in Mexico and Brazil)

We want Mercado Libre to be the site for buyers to find the most attractive market prices. For this reason, we will now tag those publications with poor competitive prices so that sellers can easily change them. Their price range will be set based on our market analysis, and a due date. Thereafter, they will not be listed anymore.
To recognize them, just look for those tagged as "not_market_price". See below how to do it. Example:

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

Response:

{
  "id": "MLM600190449",
  "site_id": "MLM",
  "title": "Item de test - Por favor no ofertar",
  "subtitle": null,
  "seller_id": 118617934,
  "category_id": "MLM352543",
  "tags": [
“not_market_price”
    ],
}

You will be able to search your own items with the assigned tag like this:Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/USER_ID/items/search?tags=not_market_price

Once you have recognized the items tagged as “not_market_price”, make a GET to /items/${item_id}/policies/market_price and find the price range to change them and the due date. If you don't adjust them by that due date, your publications will not be listed anymore.Example:

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

Respuesta:

{
   "item_id":"MLB10000",
   "suggested_price_range": {
       "currency": "BRL",
       "min_amount": 648.93,
       "max_amount": 689.07
   },
   "deadline": "2018-09-13T00:00:00.000Z"
}
Important:
Tag “not_market_price” will be removed in 24 hours following the price adjustment; provided that, such price becomes competitive. If you are not listed anymore, you can recover it in 48 hours.

Next topic: Manage questions & answers.

or register to recieve the latest news about our API