Sync and moditify listings

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

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

Stock of items

Update stock

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.

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").

Availability time (MANUFACTURING TIME)

Add stock availability time

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.

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

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

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