Documentação do Mercado Livre

Confira todas as informações necessárias sobre as APIs Mercado Livre.
circulos azuis em degrade

Documentação do

Última atualização em 02/07/2024

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.

Considerations to update items

- Identify the channel of listing (Mercado Libre or Mercado Shops). If it is a mshops listing, modify mshops listings.

- When item is active you can modify:

  • Available_quantity
  • Price
  • Video
  • Pictures
  • Description
  • Shipping

When the item has sales, you can´t change any:

  • Title
  • Condition
  • Buying mode

When the item has not sales ("sold_quantity" = 0), you can change:

  • Title

- The listing type can be modified only once
- Consider if the listing has variations
- Verify if item has active promotions

Update your item

Request:

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


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.


Listings status and flow


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. In this condition the item can only be deleted directly.

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.
  • picture downloading pending: the item has been paused until the picture is downloaded correctly and will be activated when this happens.

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

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.


Item can hold different status:

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

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:

  • 1. Update status item to closed:
  • 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
  • 2. Delete the item:
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.".
- For items with status "under_review" and subsatus "forbidden" only the second delete PUT should be executed.

Stock of items

Update stock

Important:
Auto pause with 0 stock is available on MLB, MLA, MLM, MLC, MPE, MLV.

To update item stock just add the value in the “available_quantity” field:

  • When making a PUT to an available_quantity = 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.

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

Stock of used items

Know the categories and countries with a limit of 1 (one) item with condition used ("condition":"used").

References MLA MLM MLC MPE
Category_id Category
Category ID Category name
Category_id Categoría
MLA1322 Tenis, Padel y Squash
MLA3114 Accesorios de Moda
MLA47786 Montañismo y Trekking
MLA430281 Trajes de Baño
Category_id Categoría
MLM1456 Accesorios de Moda - Lentes
MLM5529 Accesorios de Moda - Otros
MLM438426 Deportes y Fitness - Esqui y Snowboard - Accesorios
Category_id Category
MLC3724 Zapatillas
MLC1339 Ropa Deportiva
MLC158467 Poleras
MLC7022 Bolsos, Carteras y Mochilas
MLC158340 Chaquetas
MLC158425 Vestidos
MLC158583 Pantalones y Jeans
MLC158350 Zapatillas
MLC3111 Calzados
MLC158335 Camisas
MLC158382 Polerones
MLC158342 Blusas
MLC158340 Chaquetas, Parkas y Blazers
MLC158457 Faldas
MLC440323 Ropa Interior y de Dormir
MLC158416 Chalecos
MLC158307 Bermudas y Shorts
MLC440434 Uniformes y Ropa de Trabajo
MLC1455 Vestuario para Bebés
MLC455528 Abrigos
MLC413460 Lotes de Ropa
MLC3111 Calzado
MLC440371 Chalecos, Sweaters y Cardigans
MLC158422 Sweaters
MLC158473 Trajes
MLC440654 Calzas
MLC440371 Cardigans, Sweaters y Chalecos
MLC440687 Ropa Deportiva
MLC158340 Chaquetas y Parkas
MLC158473 Ternos
MLC1455 Ropa para Bebés
MLC440714 Enteritos
MLC440679 Trajes de Baño
Category_id Category
MPE3724 Zapatillas Deportivas
MPE3724 Zapatillas
MPE417397 Ropa Deportiva
MPE6585 Zapatillas
MPE127832 Vestidos
MPE127835 Casacas
MPE127808 Calzado
MPE127752 Bolsos, Carteras y Billeteras
MPE127828 Pantalones y Jeans
MPE127835 Casacas, Sacos y Blazers
MPE127752 Equipaje, Bolsos y Carteras
MPE127828 Pantalones, Jeans y Joggers
MPE127827 Shorts
MPE431499 Polos
MPE127831 Polos
MPE127894 Chompas
MPE431500 Blusas
MPE455528 Abrigos
MPE431498 Camisas
MPE443832 Cardigans, Chompas y Chalecos
MPE127833 Chalecos
MPE443907 Poleras
MPE443830 Ropa Deportiva
MPE443973 Ternos
MPE443920 Ropa Interior y de Dormir
MPE443969 Enterizos y Overoles
MPE413460 Lotes de Ropa
MPE127826 Poleras
MPE127834 Cardigans
MPE443975 Ropa y Calzado de Bebé
MPE430281 Ropa de Baño
MPE443953 Uniformes y Ropa de Trabajo
MPE443951 Leggings
MPE127830 Ropa Interior
MPE417479 Ropa de Danza y Patinaje

Availability time (MANUFACTURING TIME)

Add stock availability time

Important:
It is available only in Argentina, Brasil, Uruguay, Colombia and México.

You can use the functionality to show buyers how long it takes to make products available for sale, in situations such as:

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

Get category with manufacturing time

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


Request:

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.


Request:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" https://api.mercadolibre.com/items -d
{
 "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.


Request:

curl -H 'Content-Type: application/json' -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID -d
{ "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.


Request:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' -X PUT https://api.mercadolibre.com/items/$ITEM_ID  -d
{
   "sale_terms": [{
       "id": "MANUFACTURING_TIME",
       "value_name": "30 días"
   }]
}

Delete stock availability

Send null in the value_id and value_name fields.


Request:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' -X PUT https://api.mercadolibre.com/items/$ITEM_ID  -d
{
  "sale_terms": [
    {
      "id": "MANUFACTURING_TIME",
      "value_id": null
      "value_name": null
    }
  ]
}

Maximum purchase quantity

Importante:
We will soon disable the "PURCHASE_MAX_QUANTITY" option in "sale_terms" for /items in the flooring, coatings, and other domains. Active items with this sales condition will automatically be updated to "null", so the maximum purchase quantity cannot be limited in your listings. Check the domains that will be impacted.

It allows you to limit the available purchase units. Check if the category has the maximum purchase quantity per transaction condition with the $CATEGORY_ID.


Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 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"
    }
[...]
]

Load maximum purchase quantity on listing

From Mercado Libre, we will review those entered values that are below the minimum allowed value of “1” in an offline process, removing the sale_term from cases that do not meet the requirement.


Request:

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

Example:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' -H 'Accept: application/json' -d
{
   "sale_terms":[
      {
         "id":"PURCHASE_MAX_QUANTITY",
         "value_name":"10"
      }
   ]
}
https://api.mercadolibre.com/items/11122233

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


Learn more about Synchronizing your listings..