For enhancing our search on publications related to cars and trucks parts, it will be mandatory to add the part_number attribute on the items published in the following categories (only for Argentina, Brazil and Mexico):

MLA:

All children categories under “Repuestos Autos y Camionetas” (MLA1747)

MLB:

It is important to complete this attribute for each item published so users can find your products faster and easier.

How to do that?
Simple. You just need to add the part_number attribute to your items through the following call:

EXAMPLE

curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -d "{'attributes': [{'id': 'PART_NUMBER', 'value_name': 'part number goes here'} ] }" "https://api.mercadolibre.com/items/$item_id?access=token"

IMPORTANT: In case you have to create a new item, don’t forget to add the part_number attribute.

What is a variation?

It is the possibility of choosing different attribute variations from the same product. So far, this could only be done with apparel categories, where the buyer could choose size and color of the product. Starting now, it will be possible to choose: colors in other categories, voltage in home appliances or specify if the car spare part is right or left.

If I never added variations to my integration, will it crash when this new feature is available?

No, your integration will remain unchanged since you can decide whether to use them or not. Although variations are optional, it is highly recommended to use them to add value to your listings.
It is important to point out that only variations are optional (variations for apparel are mandatory) and, as always, you can see all the information through the API.

What are the advantages of integrating variations?

Buyers will be able to choose different versions of the same product in the same listing, without having to perform a new search. This increases the convertion rate and reduces the number of questions and the account operation, as well.

How do I know which categories allow variations?

You can check this out through the API, just the same as for apparel categories:

https://api.mercadolibre.com/categories/{CATEGORY_ID}/attributes

Response:

[
    {
        "id": "PLACEMENT",
        "name": "Lado",
        "value_type": "list",
        "tags": {
            "allow_variations": true
        },
        "values": [
            {
                "id": "18b14ea",
                "name": "Derecho"
            },
            {
                "id": "6451969",
                "name": "Izquierdo"
            }
        ],
        "attribute_group_id": "DFLT",
        "attribute_group_name": "Otros"
    }
]

How can I list an item with variations?

Terminal:

curl -X POST -H "Content-Type: application/json" -d'{
    "title": "Item de testeo - variations",
    "category_id": "MPE74133",
    "price": 650,
    "currency_id": "PEN",
    "buying_mode": "buy_it_now",
    "listing_type_id": "bronze",
    "condition": "new",
    "description": "Item con variaciones publicado via API",
    "variations": [
        {
            "attribute_combinations": [
                {
                    "id": "PLACEMENT",
                    "value_id": "18b14ea"
                }
            ],
            "available_quantity": 1,
            "price": 650,
            "picture_ids": [
                "http://img2.mlstatic.com/s_MLA_v_Y_f_4903231002_082013.jpg"
            ]
        },
        {
            "attribute_combinations": [
                {
                    "id": "PLACEMENT",
                    "value_id": "6451969"
                }
            ],
            "available_quantity": 1,
            "price": 650,
            "picture_ids": [
                "http://mla-s2-p.mlstatic.com/16805-MLA20128129274_072014-Y.jpg"
            ]
        }
    ]
}’ https://api.mercadolibre.com/items?access_token={...}

For further information:

http://developers.mercadolibre.com/list-with-variation/
http://developers.mercadolibre.com/modify-items-with-variations/

Will I see the variation in the order?

Yes, indeed. For further information:

http://developers.mercadolibre.com/orders/

When printing MercadoEnvios labels, is it shown information about the variation?

If you are using MercadoEnvios 2, you will find information about the variation printed on the label. For further information:

http://developers.mercadolibre.com/listing-with-me2/

Introduction

The category prediction resource was created to help sellers and developers predict under which category a certain item should be listed and it’s currently working for Argentina, Brazil, Colombia, Chile and Mexico.

Parameters

Predicting by GET

Using the GET method it’s possible to predict one item at a time:

`curl https://api.mercadolibre.com/sites/MLB/category_predictor/predict?title=Ipod%20Touch%20Apple%2016gb%205%20Gera%C3%A7%C3%A3o`

Predicting by POST

Using the POST method it’s possible to predict multiple (up to 10K) items at a time. When multiple items needs to be predicted, this method is recommended.

`curl -X POST -H "Content-Type: application/json" -d '{"title":"Ipod Touch Apple 16gb 5 Geração", "category_from":"MLB1743"}]' "https://api.mercadolibre.com/sites/MLB/category_predictor/predict"`

Response fields

Learn how to build a good title so buyers can find your items and you can get the most accurate category prediction .

Contents

What is a variation?

A variation is a resource that allow sellers to set images and stock for each variant that a given same product may have. For example, in Fashion there may be pictures of each color or size within the same item publication. In Carparts, the same happens with right side, or left side in some accesories.

What are variations useful for?

Buyers can explore within the same listing the different versions of it, and stock available for each of them.

In addition, sellers can assign an SKU code for each variation. This will be very useful for those sellers who need to control their stock by inventory.

Standard variations

What are standard variations?

A standard variation is a default attribute which is tied to a certain category.

How to use standard variations

Each category has default variations that can be combined between them. For example: size and color (for Fashion) or only voltage (for consumer electronics). Before listing an item with variations, make sure you checked which attributes are available for that category, and the allowed values for each of them.

How to list items with standard variations

You must check the category_id of the chosen category you want to list in.

curl -X GET https://api.mercadolibre.com/categories/{Category_id}

Example:

https://api.mercadolibre.com/categories/MLA374515

Response:

{
  "id": "MLA374515",
  "name": "Polleras Largas",
  "picture": null,
  "permalink": null,
  "total_items_in_this_category": 296,
  "path_from_root": [
    {
      "id": "MLA1430",
      "name": "Ropa y Accesorios"
    },
    {
      "id": "MLA373771",
      "name": "Polleras"
    },
    {
      "id": "MLA7297",
      "name": "Mujer"
    },
    {
      "id": "MLA373876",
      "name": "Polleras Plisadas"
    },
    {
      "id": "MLA374515",
      "name": "Polleras Largas"
    }
  ],
  "children_categories": [
  ],
  "attribute_types": "variations",
  "settings": {
    "adult_content": false,
    "buying_allowed": true,
    "buying_modes": [
      "buy_it_now",
      "auction"
    ],
    "coverage_areas": "not_allowed",
    "currencies": [
      "ARS"
    ],
    "fragile": false,
    "immediate_payment": "optional",
    "item_conditions": [
      "not_specified",
      "used",
      "new"
    ],
    "items_reviews_allowed": false,
    "max_description_length": 50000,
    "max_pictures_per_item": 36,
    "max_sub_title_length": 70,
    "max_title_length": 60,
    "price": "required",
    "restrictions": [
    ],
    "rounded_address": false,
    "seller_contact": "not_allowed",
    "shipping_modes": [
      "not_specified",
      "custom",
      "me2",
      "me1"
    ],
    "shipping_options": [
      "carrier",
      "custom"
    ],
    "shipping_profile": "optional",
    "show_contact_information": false,
    "simple_shipping": "optional",
    "stock": "required",
    "tags": [
    ],
    "vip_subdomain": "articulo",
    "mirror_category": null,
    "listing_allowed": true,
    "maximum_price": null,
    "minimum_price": null
  },
  "meta_categ_id": 59801,
  "attributable": false
}

Category allows variations if the answer includes the field “attribute_types”: “variations”.

In order to know which attributes are available for the chosen category, please proceed as follows:

Call:

curl -X GET https://api.mercadolibre.com/categories/{Category_id}/attributes

Example:

https://api.mercadolibre.com/categories/MLA374515/attributes

Response:

[
  {
    "id": "GENDER",
    "name": "Género",
    "value_type": "list",
    "tags": {
      "fixed": true
    },
    "values": [
      {
        "id": "female",
        "name": "Mujer"
      }
    ],
    "attribute_group_id": "DFLT",
    "attribute_group_name": "Otros"
  },
  {
    "id": "Season",
    "name": "Season",
    "value_type": "list",
    "tags": {
      "fixed": true
    },
    "values": [
      {
        "id": "Season-All-Season",
        "name": "All-Season"
      }
    ],
    "attribute_group_id": "DFLT",
    "attribute_group_name": "Otros"
  },
  {
    "id": "93000",
    "name": "Talle",
    "type": "size",
    "value_type": "list",
    "tags": {
      "allow_variations": true,
      "required": true
    },
    "values": [
      {
        "id": "101993",
        "name": "XS"
      },
      {
        "id": "101994",
        "name": "S"
      },
      {
        "id": "101995",
        "name": "M"
      },
      {
        "id": "101996",
        "name": "L"
      },
      {
        "id": "101997",
        "name": "XL"
      },
      {
        "id": "101998",
        "name": "XXL"
      },
      {
        "id": "101999",
        "name": "XXXL"
      },
      {
        "id": "04ecc99",
        "name": "4XL"
      },
      {
        "id": "102000",
        "name": "U"
      },
      {
        "id": "102001",
        "name": "AM"
      }
    ],
    "attribute_group_id": "DFLT",
    "attribute_group_name": "Otros"
  },
  {
    "id": "83000",
    "name": "Color Primario",
    "type": "color",
    "value_type": "list",
    "tags": {
      "allow_variations": true,
      "required": true
    },
    "values": [
      {
        "id": "91993",
        "name": "Rojo",
        "metadata": {
          "rgb": "#FF0000"
        }
      },
      {
        "id": "91994",
        "name": "Rosa",
        "metadata": {
          "rgb": "#F4CCCC"
        }
      },
      {
        "id": "91995",
        "name": "Terracota",
        "metadata": {
          "rgb": "#E06666"
        }
      },
      {
        "id": "91996",
        "name": "Bordó",
        "metadata": {
          "rgb": "#990000"
        }
      },
      {
        "id": "91997",
        "name": "Naranja",
        "metadata": {
          "rgb": "#FF9900"
        }
      },
      {
        "id": "91998",
        "name": "Beige",
        "metadata": {
          "rgb": "#FCE5CD"
        }
      },
      {
        "id": "91999",
        "name": "Piel",
        "metadata": {
          "rgb": "#F6B26B"
        }
      },
      {
        "id": "92000",
        "name": "Marrón",
        "metadata": {
          "rgb": "#B45F06"
        }
      },
      {
        "id": "92001",
        "name": "Amarillo",
        "metadata": {
          "rgb": "#FFFF00"
        }
      },
      {
        "id": "92002",
        "name": "Crema",
        "metadata": {
          "rgb": "#FFF2CC"
        }
      },
      {
        "id": "92003",
        "name": "Ocre",
        "metadata": {
          "rgb": "#FFD966"
        }
      },
      {
        "id": "92004",
        "name": "Dorado",
        "metadata": {
          "rgb": "#BF9000"
        }
      },
      {
        "id": "92005",
        "name": "Verde",
        "metadata": {
          "rgb": "#0C9800"
        }
      },
      {
        "id": "92006",
        "name": "Verde claro",
        "metadata": {
          "rgb": "#D9EAD3"
        }
      },
      {
        "id": "92007",
        "name": "Esmeralda",
        "metadata": {
          "rgb": "#93C47D"
        }
      },
      {
        "id": "92008",
        "name": "Verde oscuro",
        "metadata": {
          "rgb": "#38761D"
        }
      },
      {
        "id": "92009",
        "name": "Agua",
        "metadata": {
          "rgb": "#83DDFF"
        }
      },
      {
        "id": "92010",
        "name": "Azul cielo",
        "metadata": {
          "rgb": "#D0E0E3"
        }
      },
      {
        "id": "92020",
        "name": "Azul marino",
        "metadata": {
          "rgb": "#76A5AF"
        }
      },
      {
        "id": "92012",
        "name": "Azul petróleo",
        "metadata": {
          "rgb": "#134F5C"
        }
      },
      {
        "id": "92013",
        "name": "Azul",
        "metadata": {
          "rgb": "#1717FF"
        }
      },
      {
        "id": "92014",
        "name": "Celeste",
        "metadata": {
          "rgb": "#CFE2F3"
        }
      },
      {
        "id": "92015",
        "name": "Azul acero",
        "metadata": {
          "rgb": "#6FA8DC"
        }
      },
      {
        "id": "92016",
        "name": "Azul oscuro",
        "metadata": {
          "rgb": "#0B5394"
        }
      },
      {
        "id": "92017",
        "name": "Violeta oscuro",
        "metadata": {
          "rgb": "#7600FF"
        }
      },
      {
        "id": "92018",
        "name": "Lavanda",
        "metadata": {
          "rgb": "#D9D2E9"
        }
      },
      {
        "id": "92019",
        "name": "Lila",
        "metadata": {
          "rgb": "#8E7CC3"
        }
      },
      {
        "id": "92021",
        "name": "Fucsia",
        "metadata": {
          "rgb": "#E828FF"
        }
      },
      {
        "id": "92022",
        "name": "Salmón",
        "metadata": {
          "rgb": "#EAD1DC"
        }
      },
      {
        "id": "92023",
        "name": "Fucsia oscuro",
        "metadata": {
          "rgb": "#C27BA0"
        }
      },
      {
        "id": "92024",
        "name": "Púrpura",
        "metadata": {
          "rgb": "#741B47"
        }
      },
      {
        "id": "92025",
        "name": "Negro",
        "metadata": {
          "rgb": "#000000"
        }
      },
      {
        "id": "92026",
        "name": "Plateado",
        "metadata": {
          "rgb": "#CCCCCC"
        }
      },
      {
        "id": "92027",
        "name": "Gris",
        "metadata": {
          "rgb": "#666666"
        }
      },
      {
        "id": "92028",
        "name": "Blanco",
        "metadata": {
          "rgb": "#FFFFFF"
        }
      }
    ],
    "attribute_group_id": "DFLT",
    "attribute_group_name": "Otros"
  },
  {
    "id": "73001",
    "name": "Color Secundario",
    "type": "color",
    "value_type": "list",
    "tags": {
      "allow_variations": true
    },
    "values": [
      {
        "id": "82026",
        "name": "Rojo",
        "metadata": {
          "rgb": "#FF0000"
        }
      },
      {
        "id": "82027",
        "name": "Rosa",
        "metadata": {
          "rgb": "#F4CCCC"
        }
      },
      {
        "id": "82028",
        "name": "Terracota",
        "metadata": {
          "rgb": "#E06666"
        }
      },
      {
        "id": "82029",
        "name": "Bordó",
        "metadata": {
          "rgb": "#990000"
        }
      },
      {
        "id": "82030",
        "name": "Naranja",
        "metadata": {
          "rgb": "#FF9900"
        }
      },
      {
        "id": "82031",
        "name": "Beige",
        "metadata": {
          "rgb": "#FCE5CD"
        }
      },
      {
        "id": "82032",
        "name": "Piel",
        "metadata": {
          "rgb": "#F6B26B"
        }
      },
      {
        "id": "82033",
        "name": "Marrón",
        "metadata": {
          "rgb": "#B45F06"
        }
      },
      {
        "id": "82034",
        "name": "Amarillo",
        "metadata": {
          "rgb": "#FFFF00"
        }
      },
      {
        "id": "82035",
        "name": "Crema",
        "metadata": {
          "rgb": "#FFF2CC"
        }
      },
      {
        "id": "82036",
        "name": "Ocre",
        "metadata": {
          "rgb": "#FFD966"
        }
      },
      {
        "id": "82037",
        "name": "Dorado",
        "metadata": {
          "rgb": "#BF9000"
        }
      },
      {
        "id": "82038",
        "name": "Verde",
        "metadata": {
          "rgb": "#0C9800"
        }
      },
      {
        "id": "82039",
        "name": "Verde claro",
        "metadata": {
          "rgb": "#D9EAD3"
        }
      },
      {
        "id": "82040",
        "name": "Esmeralda",
        "metadata": {
          "rgb": "#93C47D"
        }
      },
      {
        "id": "82041",
        "name": "Verde oscuro",
        "metadata": {
          "rgb": "#38761D"
        }
      },
      {
        "id": "82042",
        "name": "Agua",
        "metadata": {
          "rgb": "#83DDFF"
        }
      },
      {
        "id": "82043",
        "name": "Azul cielo",
        "metadata": {
          "rgb": "#D0E0E3"
        }
      },
      {
        "id": "82044",
        "name": "Azul marino",
        "metadata": {
          "rgb": "#76A5AF"
        }
      },
      {
        "id": "82045",
        "name": "Azul petróleo",
        "metadata": {
          "rgb": "#134F5C"
        }
      },
      {
        "id": "82046",
        "name": "Azul",
        "metadata": {
          "rgb": "#1717FF"
        }
      },
      {
        "id": "82047",
        "name": "Celeste",
        "metadata": {
          "rgb": "#CFE2F3"
        }
      },
      {
        "id": "82048",
        "name": "Azul acero",
        "metadata": {
          "rgb": "#6FA8DC"
        }
      },
      {
        "id": "82049",
        "name": "Azul oscuro",
        "metadata": {
          "rgb": "#0B5394"
        }
      },
      {
        "id": "82050",
        "name": "Violeta oscuro",
        "metadata": {
          "rgb": "#7600FF"
        }
      },
      {
        "id": "82051",
        "name": "Lavanda",
        "metadata": {
          "rgb": "#D9D2E9"
        }
      },
      {
        "id": "82052",
        "name": "Lila",
        "metadata": {
          "rgb": "#8E7CC3"
        }
      },
      {
        "id": "82054",
        "name": "Fucsia",
        "metadata": {
          "rgb": "#E828FF"
        }
      },
      {
        "id": "82055",
        "name": "Salmón",
        "metadata": {
          "rgb": "#EAD1DC"
        }
      },
      {
        "id": "82056",
        "name": "Fucsia oscuro",
        "metadata": {
          "rgb": "#C27BA0"
        }
      },
      {
        "id": "82057",
        "name": "Púrpura",
        "metadata": {
          "rgb": "#741B47"
        }
      },
      {
        "id": "82058",
        "name": "Negro",
        "metadata": {
          "rgb": "#000000"
        }
      },
      {
        "id": "82059",
        "name": "Plateado",
        "metadata": {
          "rgb": "#CCCCCC"
        }
      },
      {
        "id": "82060",
        "name": "Gris",
        "metadata": {
          "rgb": "#666666"
        }
      },
      {
        "id": "82061",
        "name": "Blanco",
        "metadata": {
          "rgb": "#FFFFFF"
        }
      }
    ],
    "attribute_group_id": "DFLT",
    "attribute_group_name": "Otros"
  }
]

You now know which attributes and values are available for your listing’s variation. Please note and remember that it is required to send those attributes that include the tag “required”:true. In addition, you can only use in your attributes combination (variation) those attributes including the tag “allow_variations”:true.

For example, you may use size and color. But you cannot use “gender” or “season” since they are tagged as “fixed:true”. This means that the item will inherit those values automatically. There is no need to send them in your post.

Check the next example to see how to list a Fashion item with size and color variations:

Example:

curl -X POST -H "Content-Type: application/json" -d '{
   "title":"Test Item - No ofertar",
   "category_id":"MLA374515",
   "price":200,
   "currency_id":"ARS",
   "buying_mode":"buy_it_now",
   "listing_type_id":"bronze",
   "condition":"new",
   "description": "Item de Test - No ofertar",
   "variations":[
    {
      "attribute_combinations":[
          {
            "id":"83000",
            "value_id":"92028"
          },
          {
            "id":"93000",
            "value_id":"101994"
          }
      ],
      "available_quantity":1,
      "price":200,
      "picture_ids":[
          "http://picture-cdn.wheretoget.it/lc6kzg-i.jpg"
      ]
    },
    {
      "attribute_combinations":[
          {
            "id":"83000",
            "value_id":"91994"
          },
          {
            "id":"93000",
            "value_id":"101995"
          }
      ],
      "available_quantity":1,
      "price":200,
      "picture_ids":[
          "https://s-media-cache-ak0.pinimg.com/736x/63/9c/a0/639ca03b5ca79e73002b4f2d4776d03b.jpg"
      ]
    }
   ]
}' 'https://api.mercadolibre.com/items?access_token=¢ACCESS_TOKEN

Response:

{  
   "id":"MLA599074368",
   "site_id":"MLA",
   "title":"Test Item - No Ofertar",
   "subtitle":null,
   "seller_id":202593498,
   "category_id":"MLA374515",
   "official_store_id":null,
   "price":200,
   "base_price":200,
   "original_price":null,
   "currency_id":"ARS",
   "initial_quantity":2,
   "available_quantity":2,
   "sold_quantity":0,
   "buying_mode":"buy_it_now",
   "listing_type_id":"bronze",
   "start_time":"2016-01-07T15:49:51.419Z",
   "stop_time":"2016-03-07T15:49:51.419Z",
   "end_time":"2016-03-07T15:49:51.419Z",
   "condition":"new",
   "permalink":"http://articulo.mercadolibre.com.ar/MLA-599074368-test-item-no-ofertar-_JM",
   "thumbnail":"http://www.mercadolibre.com/jm/img?s=STC&v=I&f=proccesing_image_es.jpg",
   "secure_thumbnail":"https://www.mercadolibre.com/jm/img?s=STC&v=I&f=proccesing_image_es.jpg",
   "pictures":[  
      {  
         "id":"749311-MLA20539854842_012016",
         "url":"http://www.mercadolibre.com/jm/img?s=STC&v=O&f=proccesing_image_es.jpg",
         "secure_url":"https://www.mercadolibre.com/jm/img?s=STC&v=O&f=proccesing_image_es.jpg",
         "size":"500x500",
         "max_size":"500x500",
         "quality":""
      },
      {  
         "id":"710411-MLA20539854841_012016",
         "url":"http://www.mercadolibre.com/jm/img?s=STC&v=O&f=proccesing_image_es.jpg",
         "secure_url":"https://www.mercadolibre.com/jm/img?s=STC&v=O&f=proccesing_image_es.jpg",
         "size":"500x500",
         "max_size":"500x500",
         "quality":""
      }
   ],
   "video_id":null,
   "descriptions":[  
      {  
         "id":"MLA599074368-1003328092"
      }
   ],
   "accepts_mercadopago":true,
   "non_mercado_pago_payment_methods":[  

   ],
   "shipping":{  
      "mode":"not_specified",
      "local_pick_up":false,
      "free_shipping":false,
      "methods":[  

      ],
      "dimensions":null,
      "tags":[  

      ]
   },
   "international_delivery_mode":"none",
   "seller_address":{  
      "id":175597910,
      "comment":"",
      "address_line":"Test Address 123",
      "zip_code":"1414",
      "city":{  
         "id":"",
         "name":"Palermo"
      },
      "state":{  
         "id":"AR-C",
         "name":"Capital Federal"
      },
      "country":{  
         "id":"AR",
         "name":"Argentina"
      },
      "latitude":-34.5711496,
      "longitude":-58.4232966,
      "search_location":{  
         "neighborhood":{  
            "id":"",
            "name":""
         },
         "city":{  
            "id":"TUxBQ0NBUGZlZG1sYQ",
            "name":"Capital Federal"
         },
         "state":{  
            "id":"TUxBUENBUGw3M2E1",
            "name":"Capital Federal"
         }
      }
   },
   "seller_contact":null,
   "location":{  

   },
   "geolocation":{  
      "latitude":-34.5711496,
      "longitude":-58.4232966
   },
   "coverage_areas":[  

   ],
   "attributes":[  
      {  
         "id":"GENDER",
         "name":"Género",
         "value_id":"female",
         "value_name":"Mujer",
         "attribute_group_id":"DFLT",
         "attribute_group_name":"Otros"
      },
      {  
         "id":"Season",
         "name":"Season",
         "value_id":"Season-All-Season",
         "value_name":"All-Season",
         "attribute_group_id":"DFLT",
         "attribute_group_name":"Otros"
      }
   ],
   "listing_source":"",
   "variations":[  
      {  
         "id":10448277573,
         "attribute_combinations":[  
            {  
               "id":"83000",
               "name":"Color Primario",
               "value_id":"92028",
               "value_name":"Blanco"
            },
            {  
               "id":"93000",
               "name":"Talle",
               "value_id":"101994",
               "value_name":"S"
            }
         ],
         "price":200,
         "available_quantity":1,
         "sold_quantity":0,
         "picture_ids":[  
            "749311-MLA20539854842_012016"
         ],
         "seller_custom_field":null,
         "attributes":[  

         ]
      },
      {  
         "id":10448277576,
         "attribute_combinations":[  
            {  
               "id":"83000",
               "name":"Color Primario",
               "value_id":"91994",
               "value_name":"Rosa"
            },
            {  
               "id":"93000",
               "name":"Talle",
               "value_id":"101995",
               "value_name":"M"
            }
         ],
         "price":200,
         "available_quantity":1,
         "sold_quantity":0,
         "picture_ids":[  
            "710411-MLA20539854841_012016"
         ],
         "seller_custom_field":null,
         "attributes":[  

         ]
      }
   ],
   "status":"not_yet_active",
   "sub_status":[  

   ],
   "tags":[  

   ],
   "warranty":null,
   "catalog_product_id":null,
   "seller_custom_field":null,
   "parent_item_id":null,
   "differential_pricing":null,
   "deal_ids":[  

   ],
   "automatic_relist":false,
   "date_created":"2016-01-07T15:49:51.753Z",
   "last_updated":"2016-01-07T15:49:51.753Z"
}

Possible errors:

Our API automatically does certain validations on the JSON you send. If you don’t include any required attribute, that post will be rejected and you will get a validation error message.

For example, if you forget including the Primary Color (which is a required attribute according to category MLA374515) in a Fashion listing, you will get the following answer:

{  
   "message":"Validation error",
   "error":"validation_error",
   "status":400,
   "cause":[  
      {  
         "code":"item.attributes.missing_required",
         "message":"The attributes [83000] are required for category MLA374515. Check the attribute is present in the attributes list or in all variation attributes combination."
      }
   ]
}

Another frequent error consists in sending an attribute with a not-accepted value according to the allowed values for that category. Check frequent errors and their meaning.
To avoid making these kind of mistakes when listing, we suggest validating your JSON before posting it, in our item validator. Learn how to validate an item before posting it.

How to modify Standard Variations

You already know how to list products with variations. You then might need to do some changes on these items, or on some particular variations like update stock, pictures, add some new variation or modify existing ones.

In order to modify items with variations, or a particular variation, you will need to know the variation_id, and get the item variations doing as follows:

Call:

curl -X GET https://api.mercadolibre.com/items/{Item_id}/variations

Example:

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

Response:

{
    "id": 10448277573,
    "attribute_combinations": [
      {
        "id": "83000",
        "name": "Color Primario",
        "value_id": "92028",
        "value_name": "Blanco"
      },
      {
        "id": "93000",
        "name": "Talle",
        "value_id": "101994",
        "value_name": "S"
      }
    ],
    "price": 200,
    "available_quantity": 1,
    "sold_quantity": 0,
    "picture_ids": [
      "749311-MLA20539854842_012016"
    ],
    "seller_custom_field": null
  },
  {
    "id": 10448277576,
    "attribute_combinations": [
      {
        "id": "83000",
        "name": "Color Primario",
        "value_id": "91994",
        "value_name": "Rosa"
      },
      {
        "id": "93000",
        "name": "Talle",
        "value_id": "101995",
        "value_name": "M"
      }
    ],
    "price": 200,
    "available_quantity": 1,
    "sold_quantity": 0,
    "picture_ids": [
      "710411-MLA20539854841_012016"
    ],
    "seller_custom_field": null
  }

Once you each variations_id, you can check one particular variation adding the variation_id at the end of the apicall:

Call:

curl -X GET https://api.mercadolibre.com/items/{Item_id}/variations/{Variation_id}

Example:

curl -X GET https://api.mercadolibre.com/items/MLA599074368/variations/10448277573

Response:

{
  "id": 10448277573,
  "attribute_combinations": [
    {
      "id": "83000",
      "name": "Color Primario",
      "value_id": "92028",
      "value_name": "Blanco"
    },
    {
      "id": "93000",
      "name": "Talle",
      "value_id": "101994",
      "value_name": "S"
    }
  ],
  "price": 200,
  "available_quantity": 1,
  "sold_quantity": 0,
  "picture_ids": [
    "749311-MLA20539854842_012016"
  ],
  "seller_custom_field": null,
  "attributes": [
  ]
}

There are several kinds of modifications you may need on an item with variations. Next, you will find an explanation for each of them.

For example, if you have new sizes in stock for a certain item, you will be able to add a new variation:

Example:

curl -X POST -d '{"attribute_combinations":[{"id":"83000","value_id":"91994"},{"id":"93000","value_id":"101996"}],"price":200,"available_quantity":3,"picture_ids":["710411-MLA20539854841_012016"]}' https://api.mercadolibre.com/items/MLA599074368/variations?access_token=¢ACCESS_TOKEN

Response:

[  
   {  
      "id":10448277573,
      "attribute_combinations":[  
         {  
            "id":"83000",
            "name":"Color Primario",
            "value_id":"92028",
            "value_name":"Blanco"
         },
         {  
            "id":"93000",
            "name":"Talle",
            "value_id":"101994",
            "value_name":"S"
         }
      ],
      "price":200,
      "available_quantity":1,
      "sold_quantity":0,
      "picture_ids":[  
         "749311-MLA20539854842_012016"
      ],
      "seller_custom_field":null,
      "attributes":[  

      ]
   },
   {  
      "id":10448277576,
      "attribute_combinations":[  
         {  
            "id":"83000",
            "name":"Color Primario",
            "value_id":"91994",
            "value_name":"Rosa"
         },
         {  
            "id":"93000",
            "name":"Talle",
            "value_id":"101995",
            "value_name":"M"
         }
      ],
      "price":200,
      "available_quantity":1,
      "sold_quantity":0,
      "picture_ids":[  
         "710411-MLA20539854841_012016"
      ],
      "seller_custom_field":null,
      "attributes":[  

      ]
   },
   {  
      "id":10448293016,
      "attribute_combinations":[  
         {  
            "id":"83000",
            "name":"Color Primario",
            "value_id":"91994",
            "value_name":"Rosa"
         },
         {  
            "id":"93000",
            "name":"Talle",
            "value_id":"101996",
            "value_name":"L"
         }
      ],
      "price":200,
      "available_quantity":3,
      "sold_quantity":0,
      "picture_ids":[  
         "710411-MLA20539854841_012016"
      ],
      "seller_custom_field":null,
      "attributes":[  

      ]
   }
]

Well done! if you check the item you will find a new size for one of the colors of your product.

It is possible that in some case you need to add a new attribute to an existing variation. Please follow the instructions below to know how to add a secondary color to one of our variations.

Example:

curl -X PUT -d '{ "attribute_combinations":[  {  "id":"83000","value_id":"91994"},{ "id":"93000","value_id":"101995"},{  "id":"73001","value_id":"82035"}]}' https://api.mercadolibre.com/items/MLA599074368/variations/10448277576?access_token=$ACCESS_TOKEN

Response:

[  
   {  
      "id":10448277573,
      "attribute_combinations":[  
         {  
            "id":"83000",
            "name":"Color Primario",
            "value_id":"92028",
            "value_name":"Blanco"
         },
         {  
            "id":"93000",
            "name":"Talle",
            "value_id":"101994",
            "value_name":"S"
         }
      ],
      "price":200,
      "available_quantity":1,
      "sold_quantity":0,
      "picture_ids":[  
         "749311-MLA20539854842_012016"
      ],
      "seller_custom_field":null,
      "attributes":[  

      ]
   },
   {  
      "id":10448277576,
      "attribute_combinations":[  
         {  
            "id":"83000",
            "name":"Color Primario",
            "value_id":"91994",
            "value_name":"Rosa"
         },
         {  
            "id":"73001",
            "name":"Color Secundario",
            "value_id":"82035",
            "value_name":"Crema"
         },
         {  
            "id":"93000",
            "name":"Talle",
            "value_id":"101995",
            "value_name":"M"
         }
      ],
      "price":200,
      "available_quantity":1,
      "sold_quantity":0,
      "picture_ids":[  
         "710411-MLA20539854841_012016"
      ],
      "seller_custom_field":null,
      "attributes":[  

      ]
   },
   {  
      "id":10448293016,
      "attribute_combinations":[  
         {  
            "id":"83000",
            "name":"Color Primario",
            "value_id":"91994",
            "value_name":"Rosa"
         },
         {  
            "id":"93000",
            "name":"Talle",
            "value_id":"101996",
            "value_name":"L"
         }
      ],
      "price":200,
      "available_quantity":3,
      "sold_quantity":0,
      "picture_ids":[  
         "710411-MLA20539854841_012016"
      ],
      "seller_custom_field":null,
      "attributes":[  

      ]
   }
]

If you need to modify the other fields within the variation, which are not attributes, you must proceed similar. In the following example, the field “seller_custom_field” will be updated:

Example:

curl -X PUT -d '{"seller_custom_field": "21000093"}' https://api.mercadolibre.com/items/MLA599074368/variations/10448277576?access_token=¢ACCESS_TOKEN

Response:

[  
   {  
      "id":10448277573,
      "attribute_combinations":[  
         {  
            "id":"83000",
            "name":"Color Primario",
            "value_id":"92028",
            "value_name":"Blanco"
         },
         {  
            "id":"93000",
            "name":"Talle",
            "value_id":"101994",
            "value_name":"S"
         }
      ],
      "price":200,
      "available_quantity":1,
      "sold_quantity":0,
      "picture_ids":[  
         "749311-MLA20539854842_012016"
      ],
      "seller_custom_field":null,
      "attributes":[  

      ]
   },
   {  
      "id":10448277576,
      "attribute_combinations":[  
         {  
            "id":"83000",
            "name":"Color Primario",
            "value_id":"91994",
            "value_name":"Rosa"
         },
         {  
            "id":"73001",
            "name":"Color Secundario",
            "value_id":"82035",
            "value_name":"Crema"
         },
         {  
            "id":"93000",
            "name":"Talle",
            "value_id":"101995",
            "value_name":"M"
         }
      ],
      "price":200,
      "available_quantity":1,
      "sold_quantity":0,
      "picture_ids":[  
         "710411-MLA20539854841_012016"
      ],
      "seller_custom_field":"21000093",
      "attributes":[  

      ]
   },
   {  
      "id":10448293016,
      "attribute_combinations":[  
         {  
            "id":"83000",
            "name":"Color Primario",
            "value_id":"91994",
            "value_name":"Rosa"
         },
         {  
            "id":"93000",
            "name":"Talle",
            "value_id":"101996",
            "value_name":"L"
         }
      ],
      "price":200,
      "available_quantity":3,
      "sold_quantity":0,
      "picture_ids":[  
         "710411-MLA20539854841_012016"
      ],
      "seller_custom_field":null,
      "attributes":[  

      ]
   }
]

If you need to add an image to an existing variation, you must send the image URL in both: in the item images array, and in the variation images array. In addition, since update will be done on items resource, it is important to also send each existing variation ID in the JSON. If you don’t, the API will consider you are willing to delete those variations.

Example:

curl -XPUT -H "Content-type: application/json" -d '{
  "pictures":[  
    { "id":"749311-MLA20539854842_012016" },
    { "id":"710411-MLA20539854841_012016" },
    { "source": "https://s-media-cache-ak0.pinimg.com/236x/16/d0/29/16d0294482674bb2ddefd06f49896ef1.jpg" }
  ],
  "variations":[  
    { "id":10448277573 },
    { "id":10448277576,
       "picture_ids":[  
          "710411-MLA20539854841_012016",
          "https://s-media-cache-ak0.pinimg.com/236x/16/d0/29/16d0294482674bb2ddefd06f49896ef1.jpg"
       ]
    },
    { "id":10448293016 }
  ]
}' https://api.mercadolibre.com/items/MLA599074368?access_token=$ACCESS_TOKEN

Response:

{
    "accepts_mercadopago": true,
    "attributes": [
        {
            "attribute_group_id": "DFLT",
            "attribute_group_name": "Otros",
            "id": "GENDER",
            "name": "Género",
            "value_id": "female",
            "value_name": "Mujer"
        },
        {
            "attribute_group_id": "DFLT",
            "attribute_group_name": "Otros",
            "id": "Season",
            "name": "Season",
            "value_id": "Season-All-Season",
            "value_name": "All-Season"
        }
    ],
    "automatic_relist": false,
    "available_quantity": 5,
    "base_price": 200,
    "buying_mode": "buy_it_now",
    "catalog_product_id": null,
    "category_id": "MLA374515",
    "condition": "new",
    "coverage_areas": [],
    "currency_id": "ARS",
    "date_created": "2016-01-07T15:49:51.000Z",
    "deal_ids": [],
    "descriptions": [
        {
            "id": "MLA599074368-1003328092"
        }
    ],
    "differential_pricing": null,
    "end_time": "2016-03-07T15:49:51.000Z",
    "geolocation": {
        "latitude": -34.571149599999998,
        "longitude": -58.4232966
    },
    "id": "MLA599074368",
    "initial_quantity": 5,
    "international_delivery_mode": "none",
    "last_updated": "2016-01-07T17:37:08.164Z",
    "listing_source": "",
    "listing_type_id": "bronze",
    "location": {},
    "non_mercado_pago_payment_methods": [],
    "official_store_id": null,
    "original_price": null,
    "parent_item_id": null,
    "permalink": "http://articulo.mercadolibre.com.ar/MLA-599074368-test-item-no-ofertar-_JM",
    "pictures": [
        {
            "id": "749311-MLA20539854842_012016",
            "max_size": "300x300",
            "quality": "",
            "secure_url": "https://a248.e.akamai.net/mla-s2-p.mlstatic.com/749311-MLA20539854842_012016-O.jpg",
            "size": "300x300",
            "url": "http://mla-s2-p.mlstatic.com/749311-MLA20539854842_012016-O.jpg"
        },
        {
            "id": "710411-MLA20539854841_012016",
            "max_size": "500x622",
            "quality": "",
            "secure_url": "https://a248.e.akamai.net/mla-s1-p.mlstatic.com/710411-MLA20539854841_012016-O.jpg",
            "size": "401x500",
            "url": "http://mla-s1-p.mlstatic.com/710411-MLA20539854841_012016-O.jpg"
        },
        {
            "id": "230411-MLA20540036877_012016",
            "max_size": "236x455",
            "quality": "",
            "secure_url": "https://a248.e.akamai.net/mla-s2-p.mlstatic.com/230411-MLA20540036877_012016-O.jpg",
            "size": "236x455",
            "url": "http://mla-s2-p.mlstatic.com/230411-MLA20540036877_012016-O.jpg"
        }
    ],
    "price": 200,
    "secure_thumbnail": "https://a248.e.akamai.net/mla-s2-p.mlstatic.com/749311-MLA20539854842_012016-I.jpg",
    "seller_address": {
        "address_line": "Test Address 123",
        "city": {
            "id": "",
            "name": "Palermo"
        },
        "comment": "",
        "country": {
            "id": "AR",
            "name": "Argentina"
        },
        "id": 175597910,
        "latitude": -34.571149599999998,
        "longitude": -58.4232966,
        "search_location": {
            "city": {
                "id": "TUxBQ0NBUGZlZG1sYQ",
                "name": "Capital Federal"
            },
            "neighborhood": {
                "id": "",
                "name": ""
            },
            "state": {
                "id": "TUxBUENBUGw3M2E1",
                "name": "Capital Federal"
            }
        },
        "state": {
            "id": "AR-C",
            "name": "Capital Federal"
        },
        "zip_code": "1414"
    },
    "seller_contact": null,
    "seller_custom_field": null,
    "seller_id": 202593498,
    "shipping": {
        "dimensions": null,
        "free_shipping": false,
        "local_pick_up": false,
        "methods": [],
        "mode": "not_specified",
        "tags": []
    },
    "site_id": "MLA",
    "sold_quantity": 0,
    "start_time": "2016-01-07T15:49:51.000Z",
    "status": "active",
    "stop_time": "2016-03-07T15:49:51.000Z",
    "sub_status": [],
    "subtitle": null,
    "tags": [],
    "thumbnail": "http://mla-s2-p.mlstatic.com/749311-MLA20539854842_012016-I.jpg",
    "title": "Test Item - No Ofertar",
    "variations": [
        {
            "attribute_combinations": [
                {
                    "id": "83000",
                    "name": "Color Primario",
                    "value_id": "92028",
                    "value_name": "Blanco"
                },
                {
                    "id": "93000",
                    "name": "Talle",
                    "value_id": "101994",
                    "value_name": "S"
                }
            ],
            "attributes": [],
            "available_quantity": 1,
            "id": 10448277573,
            "picture_ids": [
                "749311-MLA20539854842_012016"
            ],
            "price": 200,
            "seller_custom_field": null,
            "sold_quantity": 0
        },
        {
            "attribute_combinations": [
                {
                    "id": "83000",
                    "name": "Color Primario",
                    "value_id": "91994",
                    "value_name": "Rosa"
                },
                {
                    "id": "73001",
                    "name": "Color Secundario",
                    "value_id": "82035",
                    "value_name": "Crema"
                },
                {
                    "id": "93000",
                    "name": "Talle",
                    "value_id": "101995",
                    "value_name": "M"
                }
            ],
            "attributes": [],
            "available_quantity": 1,
            "id": 10448277576,
            "picture_ids": [
                "710411-MLA20539854841_012016",
                "230411-MLA20540036877_012016"
            ],
            "price": 200,
            "seller_custom_field": "21000093",
            "sold_quantity": 0
        },
        {
            "attribute_combinations": [
                {
                    "id": "83000",
                    "name": "Color Primario",
                    "value_id": "91994",
                    "value_name": "Rosa"
                },
                {
                    "id": "93000",
                    "name": "Talle",
                    "value_id": "101996",
                    "value_name": "L"
                }
            ],
            "attributes": [],
            "available_quantity": 3,
            "id": 10448293016,
            "picture_ids": [
                "710411-MLA20539854841_012016"
            ],
            "price": 200,
            "seller_custom_field": null,
            "sold_quantity": 0
        }
    ],
    "video_id": null,
    "warranty": null
}

In case you do not need to keep previous images, just avoid sending them in the JSON and they will be deleted automatically.

If you paid attention through this tutorial, you are now able to modify items with variations. If you need to modify not-variation-related aspects, please refer to the tutorial Listings Sync-up.

How to relist standard variations

If your listing finished, but you still have stock available in some of the variations, you can relist sending only those variations with stock. Remember to indicate quantity and price in each of them.

Example:

curl -X POST -H "Content-Type: application/json" -d'{
    "listing_type_id": "bronze",
    "variations": [
        {
            "id": 10448277573,
            "price": 1,
            "quantity": 200
        },
        {
            "id": 10448277576,
            "price": 4,
            "quantity": 200
        },
        {
            "id": 10448293016,
            "price": 2,
            "quantity": 200
        }
    ] }' https://api.mercadolibre.com/items/MLA599074368/relist?access_token=$ACCESS_TOKEN

Response:

{  
   "id":"MLA599099879",
   "site_id":"MLA",
   "title":"Test Item - No Ofertar",
   "subtitle":null,
   "seller_id":202593498,
   "category_id":"MLA374515",
   "official_store_id":null,
   "price":4,
   "base_price":4,
   "original_price":null,
   "currency_id":"ARS",
   "initial_quantity":600,
   "available_quantity":600,
   "sold_quantity":0,
   "buying_mode":"buy_it_now",
   "listing_type_id":"bronze",
   "start_time":"2016-01-07T18:00:38.518Z",
   "stop_time":"2016-03-07T18:00:38.518Z",
   "end_time":"2016-03-07T18:00:38.518Z",
   "condition":"new",
   "permalink":"http://articulo.mercadolibre.com.ar/MLA-599099879-test-item-no-ofertar-_JM",
   "thumbnail":"http://mla-s2-p.mlstatic.com/749311-MLA20539854842_012016-I.jpg",
   "secure_thumbnail":"https://a248.e.akamai.net/mla-s2-p.mlstatic.com/749311-MLA20539854842_012016-I.jpg",
   "pictures":[  
      {  
         "id":"749311-MLA20539854842_012016",
         "url":"http://mla-s2-p.mlstatic.com/749311-MLA20539854842_012016-O.jpg",
         "secure_url":"https://a248.e.akamai.net/mla-s2-p.mlstatic.com/749311-MLA20539854842_012016-O.jpg",
         "size":"300x300",
         "max_size":"300x300",
         "quality":""
      },
      {  
         "id":"710411-MLA20539854841_012016",
         "url":"http://mla-s1-p.mlstatic.com/710411-MLA20539854841_012016-O.jpg",
         "secure_url":"https://a248.e.akamai.net/mla-s1-p.mlstatic.com/710411-MLA20539854841_012016-O.jpg",
         "size":"401x500",
         "max_size":"500x622",
         "quality":""
      },
      {  
         "id":"230411-MLA20540036877_012016",
         "url":"http://mla-s2-p.mlstatic.com/230411-MLA20540036877_012016-O.jpg",
         "secure_url":"https://a248.e.akamai.net/mla-s2-p.mlstatic.com/230411-MLA20540036877_012016-O.jpg",
         "size":"236x455",
         "max_size":"236x455",
         "quality":""
      }
   ],
   "video_id":null,
   "descriptions":[  
      {  
         "id":"MLA599099879-1003435516"
      }
   ],
   "accepts_mercadopago":true,
   "non_mercado_pago_payment_methods":[  

   ],
   "shipping":{  
      "mode":"not_specified",
      "local_pick_up":false,
      "free_shipping":false,
      "methods":[  

      ],
      "dimensions":null,
      "tags":[  

      ]
   },
   "international_delivery_mode":"none",
   "seller_address":{  
      "id":175597910,
      "comment":"",
      "address_line":"Test Address 123",
      "zip_code":"1414",
      "city":{  
         "id":"",
         "name":"Palermo"
      },
      "state":{  
         "id":"AR-C",
         "name":"Capital Federal"
      },
      "country":{  
         "id":"AR",
         "name":"Argentina"
      },
      "latitude":-34.5711496,
      "longitude":-58.4232966,
      "search_location":{  
         "neighborhood":{  
            "id":"",
            "name":""
         },
         "city":{  
            "id":"TUxBQ0NBUGZlZG1sYQ",
            "name":"Capital Federal"
         },
         "state":{  
            "id":"TUxBUENBUGw3M2E1",
            "name":"Capital Federal"
         }
      }
   },
   "seller_contact":null,
   "location":{  

   },
   "geolocation":{  
      "latitude":-34.5711496,
      "longitude":-58.4232966
   },
   "coverage_areas":[  

   ],
   "attributes":[  
      {  
         "id":"GENDER",
         "name":"Género",
         "value_id":"female",
         "value_name":"Mujer",
         "attribute_group_id":"DFLT",
         "attribute_group_name":"Otros"
      },
      {  
         "id":"Season",
         "name":"Season",
         "value_id":"Season-All-Season",
         "value_name":"All-Season",
         "attribute_group_id":"DFLT",
         "attribute_group_name":"Otros"
      }
   ],
   "listing_source":"",
   "variations":[  
      {  
         "id":10449631060,
         "attribute_combinations":[  
            {  
               "id":"83000",
               "name":"Color Primario",
               "value_id":"92028",
               "value_name":"Blanco"
            },
            {  
               "id":"93000",
               "name":"Talle",
               "value_id":"101994",
               "value_name":"S"
            }
         ],
         "price":1,
         "available_quantity":200,
         "sold_quantity":0,
         "picture_ids":[  
            "749311-MLA20539854842_012016"
         ],
         "seller_custom_field":null,
         "attributes":[  

         ]
      },
      {  
         "id":10449631063,
         "attribute_combinations":[  
            {  
               "id":"83000",
               "name":"Color Primario",
               "value_id":"91994",
               "value_name":"Rosa"
            },
            {  
               "id":"73001",
               "name":"Color Secundario",
               "value_id":"82035",
               "value_name":"Crema"
            },
            {  
               "id":"93000",
               "name":"Talle",
               "value_id":"101995",
               "value_name":"M"
            }
         ],
         "price":4,
         "available_quantity":200,
         "sold_quantity":0,
         "picture_ids":[  
            "710411-MLA20539854841_012016",
            "230411-MLA20540036877_012016"
         ],
         "seller_custom_field":"21000093",
         "attributes":[  

         ]
      },
      {  
         "id":10449631067,
         "attribute_combinations":[  
            {  
               "id":"83000",
               "name":"Color Primario",
               "value_id":"91994",
               "value_name":"Rosa"
            },
            {  
               "id":"93000",
               "name":"Talle",
               "value_id":"101996",
               "value_name":"L"
            }
         ],
         "price":2,
         "available_quantity":200,
         "sold_quantity":0,
         "picture_ids":[  
            "710411-MLA20539854841_012016"
         ],
         "seller_custom_field":null,
         "attributes":[  

         ]
      }
   ],
   "status":"not_yet_active",
   "sub_status":[  

   ],
   "tags":[  
      "dragged_bids_and_visits"
   ],
   "warranty":null,
   "catalog_product_id":null,
   "seller_custom_field":null,
   "parent_item_id":"MLA599074368",
   "differential_pricing":null,
   "deal_ids":[  

   ],
   "automatic_relist":false,
   "date_created":"2016-01-07T18:00:38.701Z",
   "last_updated":"2016-01-07T18:00:38.701Z"
}

As we can see in the answer, when you relist an item a new listing is generated. Therefore, item_id and variation_id’s must be renewed.

Delete standard variations

Now that you know each variation ID, deleting one or more variations will be an easy task.

Example:

curl -X DELETE 'https://api.mercadolibre.com/items/MLA599099879/variations/10449631060?access_token=¢ACCESS_TOKEN'

Response:

[  
   {  
      "id":10449631063,
      "attribute_combinations":[  
         {  
            "id":"83000",
            "name":"Color Primario",
            "value_id":"91994",
            "value_name":"Rosa"
         },
         {  
            "id":"73001",
            "name":"Color Secundario",
            "value_id":"82035",
            "value_name":"Crema"
         },
         {  
            "id":"93000",
            "name":"Talle",
            "value_id":"101995",
            "value_name":"M"
         }
      ],
      "price":4,
      "available_quantity":200,
      "sold_quantity":0,
      "picture_ids":[  
         "710411-MLA20539854841_012016",
         "230411-MLA20540036877_012016"
      ],
      "seller_custom_field":"21000093",
      "attributes":[  

      ]
   },
   {  
      "id":10449631067,
      "attribute_combinations":[  
         {  
            "id":"83000",
            "name":"Color Primario",
            "value_id":"91994",
            "value_name":"Rosa"
         },
         {  
            "id":"93000",
            "name":"Talle",
            "value_id":"101996",
            "value_name":"L"
         }
      ],
      "price":2,
      "available_quantity":200,
      "sold_quantity":0,
      "picture_ids":[  
         "710411-MLA20539854841_012016"
      ],
      "seller_custom_field":null,
      "attributes":[  

      ]
   }
]

As you can see, variation 10449631060 was deleted, and variations 10449631063 and 10449631067 were kept

Introduction

We are working to improve the publications in “ceramicas” and “porcelanatos” categories (only MLA for now). To accomplish that now we allow Bulk sale in those categories.

¿What we change?

Those attributes will be NOT REQUIRED! You can publish normally without them but we recommend you to use those attributes to improve the functionality of bulk sale inside your items.

Before to continue check the new attribute type number_unit which is mostly used in bulk sale.

¿How to create or update an item with those attributes?

Simply, you have to add the attributes into a common POST or PUT call. Here some examples:

Possible values to bulk feature

Possible values are displayed into category through the following call:

curl https://api.mercadolibre.com/categories/$category_id/attributes

Example:

curl https://api.mercadolibre.com/categories/MLA321215/attributes

Response:

[
  …
{
    "id": "SALES_UNIT",
    "name": "Unidad de venta",
    "value_type": "list",
    "tags": {
    },
    "values": [
      {
        "id": "121602",
        "name": "Unidad"
      },
      {
        "id": "121604",
        "name": "Caja"
      },
      {
        "id": "121605",
        "name": "Pallet"
      },
      {
        "id": "145190",
        "name": "m²"
      }
    ],
    "attribute_group_id": "DFLT",
    "attribute_group_name": "Otros"
  },
  {
    "id": "YIELD_OF_SALES_UNIT",
    "name": "Rendimiento",
    "value_type": "number_unit",
    "tags": {
    },
    "allowed_units": [
      {
        "id": "m²",
        "name": "m²"
      }
    ],
    "attribute_group_id": "DFLT",
    "attribute_group_name": "Otros"
  },
  {
    "id": "WEIGHT_OF_SALES_UNIT",
    "name": "Peso",
    "value_type": "number_unit",
    "tags": {
    },
    "allowed_units": [
      {
        "id": "g",
        "name": "g"
      },
      {
        "id": "kg",
        "name": "kg"
      }
    ],
    "attribute_group_id": "DFLT",
    "attribute_group_name": "Otros"
  },
    ...
]

Attribute example – POST item with bulk attributes

curl -X POST 'https://api.mercadolibre.com/items?access_token=$access_token' -d '
{
	"site_id": "MLA",
	"title": "test bulk item",
	"seller_custom_field": null,
	"category_id": "MLA14559",
	"price": 100,
	"currency_id": "ARS",
	"buying_mode": "buy_it_now",
	"listing_type_id": "free",
	"condition": "new",
	"warranty": null,
	"available_quantity": 1,
	"video_id": null,
	"pictures": [],
	"accepts_mercadopago": false,
	"official_store_id": null,
	"non_mercado_pago_payment_methods": [],
	"shipping": {
		"local_pick_up": true,
		"free_shipping": false,
		"costs": []
	},
	"attributes": [{
		"id": "SALES_UNIT",
		"value_id": "121604"
	}, {
		"id": "YIELD_OF_SALES_UNIT",
		"value_name": "4 m²"
	}, {
		"id": "SIDE_A",
		"value_name": "12 cm"
	}, {
		"id": "SIDE_B",
		"value_name": "12 cm"
	}, {
		"id": "THICKNESS",
		"value_name": "2 mm"
	}, {
		"id": "WEIGHT_OF_SALES_UNIT",
		"value_name": "3 kg"
	}, {
		"id": "FINISH",
		"value_name": "bicelado"
	}],
	"automatic_relist": false,
	"description": {
		"text": "
item de test<\/p>",
		"plain_text": null
	}
}'

There is a new attribute called “number_unit”. The “value_name” of the attribute must be a number followed by the corresponding unit. For example “1.33 cm”.
This attribute type has the field “allowed_units” which enumerate the units that are allowed.

Examples:

Attribute example – PUT item

curl -X PUT 'https://api.mercadolibre.com/items/$item_id?access_token=$access_token' -d '
{"attributes" : [{"id": "YIELD_OF_SALES_UNIT", "value_name": "5.34 cm"}]}'

Add invalid attribute example – PUT item

In case we add an invalid “value_name” the attribute is discarded and a error message is shown inside “warnings” but doesn’t interrupt the creation or modification of the item.

Example:

curl -X PUT 'https://api.mercadolibre.com/items/$item_id?access_token=$access_token' -d '{"attributes" : [{"id": "YIELD_OF_SALES_UNIT", "value_name": "2.22 z"}, {"id": "SALES_UNIT", "value_id": "121604"}]}'

Response:

{
	"id": "MLA604016753",
	...
	"attributes": [{ "id": "SALES_UNIT", "name": "Unidad de venta", "value_id": "121604", "value_name": "Caja", "attribute_group_id": "DFLT", "attribute_group_name": "Otros" }],
	"warnings": [{
		"code": "item.attributes.omitted",
		"message": "Attribute YIELD_OF_SALES_UNIT with value 2.22 z was omitted. You can use a number followed by one of these valid units: [m2]."
	}],
	...
}

Empty value example – PUT item

curl -X PUT 'https://api.mercadolibre.com/items/$item_id?access_token=$access_token' -d '{"attributes" : [{"id": "YIELD_OF_SALES_UNIT", "value_name": ""}]}'

Contents

What are custom variations?

When users do not find the attributes they need for a certain variation, they will be able to create a “custom variation” that better fits or describe their products.

For example, a cell-phones covers seller need to add the “design” attribute for a variation. Doing so, he will be able to create 1 listing with the different design variations.

Sellers will also be able to add custom values to existing standard variations.

Using custom variations

When using custom variations, make sure the category in which you want to list products has attributes. Also, attributes and existing values in that category are different to which you are intending to add. Take into account that only is possible to add one type of variation per product.

Listing products with custom variations

First of all, you need to check on the Categories API if the selected category accepts the type of variation you are intending to add:

Call:

curl -X GET https://api.mercadolibre.com/categories/{Category_id}

Example:

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

Response:

{
  "id": "MLA70400",
  "name": "Silicona",
  "picture": null,
  "permalink": null,
  "total_items_in_this_category": 1693,
  "path_from_root": [
    {
      "id": "MLA1051",
      "name": "Celulares y Teléfonos"
    },
    {
      "id": "MLA3502",
      "name": "Accesorios para Celulares"
    },
    {
      "id": "MLA5337",
      "name": "Holders y Fundas"
    },
    {
      "id": "MLA39387",
      "name": "iPhone"
    },
    {
      "id": "MLA70400",
      "name": "Silicona"
    }
  ],
  "children_categories": [
  ],
  "attribute_types": "none",
  "settings": {
    "adult_content": false,
    "buying_allowed": true,
    "buying_modes": [
      "auction",
      "buy_it_now"
    ],
    "coverage_areas": "not_allowed",
    "currencies": [
      "ARS"
    ],
    "fragile": false,
    "immediate_payment": "optional",
    "item_conditions": [
      "used",
      "new",
      "not_specified"
    ],
    "items_reviews_allowed": false,
    "max_description_length": 50000,
    "max_pictures_per_item": 12,
    "max_sub_title_length": 70,
    "max_title_length": 60,
    "price": "required",
    "restrictions": [
    ],
    "rounded_address": false,
    "seller_contact": "not_allowed",
    "shipping_modes": [
      "me1",
      "me2",
      "not_specified",
      "custom"
    ],
    "shipping_options": [
      "custom",
      "carrier"
    ],
    "shipping_profile": "optional",
    "show_contact_information": false,
    "simple_shipping": "optional",
    "stock": "required",
    "tags": [
    ],
    "vip_subdomain": "articulo",
    "mirror_category": null,
    "listing_allowed": true,
    "maximum_price": null,
    "minimum_price": null
  },
  "meta_categ_id": 22340,
  "attributable": false
}

The next step is to perform a call to the attributes resource to find out if the category has fixed attributes.

curl -X GET https://api.mercadolibre.com/categories/{Category_id}/attributes

Example:

curl -X GET https://api.mercadolibre.com/categories/MLA90105/attributes

In this case, the category does not have attributes, therefore the variation will be added under no restrictions. You can encode your Json as the following example.

Example:

curl -XPOST -H "Content-type: application/json" -d '{
    "site_id": "MLA",
    "title": "Item de Test - No Ofertar",
    "category_id": "MLA70400",
    "price": 1000,
    "currency_id": "ARS",
    "available_quantity": 9,
    "buying_mode": "buy_it_now",
    "listing_type_id": "bronze",
    "condition": "new",
    "video_id": null,
    "description": "item de test",
    "variations": [
        {
            "price": 1000,
            "available_quantity": 3,
            "picture_ids": [
                "21150-MLA20204290696_112014"
            ],
            "attribute_combinations": [
                {
                    "name": "Diseño",
                    "value_name": "Bulldog"
                }
            ]
        },
        {
            "price": 1000,
            "available_quantity": 3,
            "picture_ids": [
                "21124-MLA20204291671_112014"
            ],
            "attribute_combinations": [
                {
                    "name": "Diseño",
                    "value_name": "Búho"
                }
            ]
        }
    ]
}' https://api.mercadolibre.com/items?access_token={$ACCESS_TOKEN}

Response:

{  
   "id":"MLA601053403",
   "site_id":"MLA",
   "title":"Item De Test - No Ofertar",
   "subtitle":null,
   "seller_id":202593498,
   "category_id":"MLA70400",
   "official_store_id":null,
   "price":1000,
   "base_price":1000,
   "original_price":null,
   "currency_id":"ARS",
   "initial_quantity":6,
   "available_quantity":6,
   "sold_quantity":0,
   "buying_mode":"buy_it_now",
   "listing_type_id":"bronze",
   "start_time":"2016-01-18T18:01:14.422Z",
   "stop_time":"2016-03-18T18:01:14.422Z",
   "end_time":"2016-03-18T18:01:14.422Z",
   "condition":"new",
   "permalink":"http://articulo.mercadolibre.com.ar/MLA-601053403-item-de-test-no-ofertar-_JM",
   "thumbnail":"http://mla-s1-p.mlstatic.com/21150-MLA20204290696_112014-I.jpg",
   "secure_thumbnail":"https://a248.e.akamai.net/mla-s1-p.mlstatic.com/21150-MLA20204290696_112014-I.jpg",
   "pictures":[  
      {  
         "id":"21150-MLA20204290696_112014",
         "url":"http://mla-s1-p.mlstatic.com/21150-MLA20204290696_112014-O.jpg",
         "secure_url":"https://a248.e.akamai.net/mla-s1-p.mlstatic.com/21150-MLA20204290696_112014-O.jpg",
         "size":"281x500",
         "max_size":"336x596",
         "quality":""
      },
      {  
         "id":"21124-MLA20204291671_112014",
         "url":"http://mla-s1-p.mlstatic.com/21124-MLA20204291671_112014-O.jpg",
         "secure_url":"https://a248.e.akamai.net/mla-s1-p.mlstatic.com/21124-MLA20204291671_112014-O.jpg",
         "size":"500x500",
         "max_size":"700x700",
         "quality":""
      }
   ],
   "video_id":null,
   "descriptions":[  
      {  
         "id":"MLA601053403-1011616345"
      }
   ],
   "accepts_mercadopago":true,
   "non_mercado_pago_payment_methods":[  

   ],
   "shipping":{  
      "mode":"not_specified",
      "local_pick_up":false,
      "free_shipping":false,
      "methods":[  

      ],
      "dimensions":null,
      "tags":[  

      ]
   },
   "international_delivery_mode":"none",
   "seller_address":{  
      "id":175597910,
      "comment":"",
      "address_line":"Test Address 123",
      "zip_code":"1414",
      "city":{  
         "id":"",
         "name":"Palermo"
      },
      "state":{  
         "id":"AR-C",
         "name":"Capital Federal"
      },
      "country":{  
         "id":"AR",
         "name":"Argentina"
      },
      "latitude":-34.5711496,
      "longitude":-58.4232966,
      "search_location":{  
         "neighborhood":{  
            "id":"",
            "name":""
         },
         "city":{  
            "id":"TUxBQ0NBUGZlZG1sYQ",
            "name":"Capital Federal"
         },
         "state":{  
            "id":"TUxBUENBUGw3M2E1",
            "name":"Capital Federal"
         }
      }
   },
   "seller_contact":null,
   "location":{  

   },
   "geolocation":{  
      "latitude":-34.5711496,
      "longitude":-58.4232966
   },
   "coverage_areas":[  

   ],
   "attributes":[  

   ],
   "warnings":[  

   ],
   "listing_source":"",
   "variations":[  
      {  
         "id":10541993184,
         "attribute_combinations":[  
            {  
               "id":null,
               "name":"Diseño",
               "value_id":null,
               "value_name":"Bulldog"
            }
         ],
         "price":1000,
         "available_quantity":3,
         "sold_quantity":0,
         "picture_ids":[  
            "21150-MLA20204290696_112014"
         ],
         "seller_custom_field":null,
         "attributes":[  

         ]
      },
      {  
         "id":10541993186,
         "attribute_combinations":[  
            {  
               "id":null,
               "name":"Diseño",
               "value_id":null,
               "value_name":"Búho"
            }
         ],
         "price":1000,
         "available_quantity":3,
         "sold_quantity":0,
         "picture_ids":[  
            "21124-MLA20204291671_112014"
         ],
         "seller_custom_field":null,
         "attributes":[  

         ]
      }
   ],
   "status":"not_yet_active",
   "sub_status":[  

   ],
   "tags":[  

   ],
   "warranty":null,
   "catalog_product_id":null,
   "seller_custom_field":null,
   "parent_item_id":null,
   "differential_pricing":null,
   "deal_ids":[  

   ],
   "automatic_relist":false,
   "date_created":"2016-01-18T18:01:14.574Z",
   "last_updated":"2016-01-18T18:01:14.574Z"
}

Awesome! You have just listed a product with custom variation. Go to the listing through the permalink to check how your product with design variation is shown in our Marketplace.

How to update custom variations

You have already learned to publish with custom variations and, most probably, you will need to update them when updating prices, adding variations or modifying the values of some published attribute.
For example, let’s suppose you listed.

To perform changes on a product with variations or a particular variation, you will have to get the variation_id by looking the product variations up as follows:

Call:

curl -X GET https://api.mercadolibre.com/items/{Item_id}/variations

Example:

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

Response:

{
    "id": 10541993184,
    "attribute_combinations": [
      {
        "id": null,
        "name": "Diseño",
        "value_id": null,
        "value_name": "Bulldog"
      }
    ],
    "price": 1000,
    "available_quantity": 3,
    "sold_quantity": 0,
    "picture_ids": [
      "21150-MLA20204290696_112014"
    ],
    "seller_custom_field": null
  },
  {
    "id": 10541993186,
    "attribute_combinations": [
      {
        "id": null,
        "name": "Diseño",
        "value_id": null,
        "value_name": "Búho"
      }
    ],
    "price": 1000,
    "available_quantity": 3,
    "sold_quantity": 0,
    "picture_ids": [
      "21124-MLA20204291671_112014"
    ],
    "seller_custom_field": null
  }

Once you have the Ids for each variation, you can look up for each of them by adding the variaton_id at the end of the GET.

Call:

curl -X GET https://api.mercadolibre.com/items/{Item_id}/variations/{Variation_id}

Example:

curl -X GET https://api.mercadolibre.com/items/MLA601053403/variations/10541993184

Response:

{
  "id": 10541993184,
  "attribute_combinations": [
    {
      "id": null,
      "name": "Diseño",
      "value_id": null,
      "value_name": "Bulldog"
    }
  ],
  "price": 1000,
  "available_quantity": 3,
  "sold_quantity": 0,
  "picture_ids": [
    "21150-MLA20204290696_112014"
  ],
  "seller_custom_field": null,
  "attributes": [
  ]
}

Different types of changes can be performed on a listing with variations. The following guideline shows how to work in each particular case.

If you need to add an image to an existing variation, the image URL will have to be added to the product general pictures array and to the variation’s, as well. Also, since the update will be performed on the items resource, it is necessary to add the Ids for each existing variation on the Json, otherwise, the API will interpret you do not want to keep them on the product listing.

Example:

curl -XPUT -H "Content-type: application/json" -d '{
  "pictures":[  
    { "id":"21124-MLA20204291671_112014" },
    { "id":"21150-MLA20204290696_112014" },
    { "source": "http://mla-s1-p.mlstatic.com/funda-marc-jacobs-3d-iphone-5-5s-5c-bulldog-cebra-buho-732301-MLA20299187840_052015-F.jpg" }
  ],
  "variations":[  
    { "id":10541993184},
    { "id":10541993186,
       "picture_ids":[  
          "21124-MLA20204291671_112014",
          "http://mla-s1-p.mlstatic.com/funda-marc-jacobs-3d-iphone-5-5s-5c-bulldog-cebra-buho-732301-MLA20299187840_052015-F.jpg"
       ]
    }
  ]
}' https://api.mercadolibre.com/items/MLA601053403?access_token=$ACCESS_TOKEN

If you do not want to keep the previous images, do not add them to the Json and they will be automatically detached.

Let’s say now it is available a new design for your product. You can add a new variation on the same listing.

Example:

curl -X POST -d '{
	"attribute_combinations": [{
		"name": "Diseño",
		"value_name": "Cebra"
	}],
	"price": 1000,
	"available_quantity": 3,
	"picture_ids": ["209411-MLA20552996931_012016"]
}' https://api.mercadolibre.com/items/MLA601053403/variations?access_token=$ACCESS_TOKEN

OK. Now the listing has three design variations: Bulldog, Búho and Cebra.

If you want to modify a non-attibute type variation field, you will have to do something similar. In this case, you will have to replace the value of “seller_custom_field” field, which previously was set to null, with a String with the product SKU:

Example:

curl -X PUT -d '{"seller_custom_field": "123456789000"}' https://api.mercadolibre.com/items/MLA601053403/variations/10541993184?access_token=$ACCESS_TOKEN

If you need to change other listing aspects non-related to variations, follow the tutorials for Synchronizing listings (Link).

Relisting custom variations

If your listing is closed but yet there are some variations with stock, you can relist it by setting the variations you wish to keep, the available quantity and the price for each.

Example:

curl -X POST -H "Content-Type: application/json" -d'{
    "listing_type_id": "bronze",
    "variations": [
        {
            "id": 10541993184,
            "price": 1000,
            "quantity": 2
        },
        {
            "id": 10541993186,
            "price": 1000,
            "quantity": 2
        },
                {
            "id": 10542199553,
            "price": 1000,
            "quantity": 1
        }
    ] }' https://api.mercadolibre.com/items/MLA601053403/relist?access_token=$ACCESS_TOKEN

As you can see, when an item is relisted, a new listing is created, therefore there will be created a new “Item_id” and a new variation “Id”, as well.

Deleting custom variations

Now that you know how get the Id of each variation, deleting one or more variations of an item will be a simple task.

Example:

curl -X DELETE 'https://api.mercadolibre.com/items/MLA601053403/variations/10542199553?access_token=$ACCESS_TOKEN'

Well done! You have already learned how to delete variations for an item.

We’re making changes on our free shippings options by country: From now on seller’s will have a country flat rate for the items they free ship. This rate is going to be calculated basing on dimensions.

By now it’s only available on MercadoLibre México (MLM), but soon it’s going to work for all sites where our MercadoEnvios unit is active: Argentina, Brazil & Colombia as well. Follow this guide to know what options you have available for free shipping your items on MLM.

Sites

Calculate free shipping costs by site & item dimensions

Example:

curl -X GET https://api.mercadolibre.com/sites/MLM/shipping_options/free?dimensions=2x11x25,500

Response:

{
    "coverage": {
        "all_country": {
            "list_cost": 97,
            "currency_id": "MXN"
        }
    }
}

Users & items

On México we offer seller’s a single flat rate option. When dimensions aren’t specified on the item, calculate is done basing on standard category dimensions.

Know standard dimensions for a given category

Example:

curl -X GET https://api.mercadolibre.com/categories/MLM165702/shipping

Response:

{
    "category_id": "MLM1055",
    "height": 10,
    "width": 10,
    "length": 15,
    "weight": 500
}

Calculate free shipping costs by user & item dimensions

Example:

curl -X GET https://api.mercadolibre.com/users/4422224/shipping_options/free?dimensions=10x10x10,500

Response:

{
    "coverage": {
        "all_country": {
            "list_cost": 97,
            "currency_id": "MXN"
        }
    }
}

Calculate free shipping costs by user & item_id

Example:

curl -X GET https://api.mercadolibre.com/users/4422224/shipping_options/free?item_id=MLM531425223

{
    "coverage": {
        "all_country": {
            "list_cost": 97,
            "currency_id": "MXN"
        }
    }
}

Calculate free shipping costs by item

Example:

curl -X GET https://api.mercadolibre.com/items/MLM540832430/shipping_options/free

Response:

{
  "coverage": {
    "all_country": {
      "list_cost": 105,
      "currency_id": "MXN"
    }
  }
}

Use multiget to calculate the cost of free shipping up to 50 items on one API call:

Example:

curl -X GET curl -X GET https://api.mercadolibre.com/items/shipping_options/free?ids=MLM531425223,MLM537956425,MLM537955922

Response:

{
    "MLM537955922": {
        "coverage": {
            "all_country": {
                "list_cost": 140,
                "currency_id": "MXN"
            }
        }
    },
    "MLM531425223": {
        "coverage": {
            "all_country": {
                "list_cost": 97,
                "currency_id": "MXN"
            }
        }
    },
    "MLM537956425": {
        "coverage": {
            "all_country": {
                "list_cost": 105,
                "currency_id": "MXN"
            }
        }
    }
}

The new publishing model is available from today for MercadoLibre Argentina. During this week we will also be doing in Mexico.
And remember that in a few days, in April, will be the turn of Chile. Little by little we are improving the experience of all our vendors.

You won’t have to pay any cost for list products. You are going to pay just the sales charge. Besides, there will be only three types of listings to choose:

Argentina

México

Chile

In both cases (Argentina and Mexico) ^*, the items location on search lists will depend on:

• – Offer installments without interests
• – Use MercadoEnvios
• – Offer free shipping
• – Ship products on time
• – Answer buyer’s questions on time
• – Reputation

_{* no apply for Chile}

Take a look at the current version of JSON and the new one, which will be available starting in March:

curl -X GET 'https://api.mercadolibre.com/sites/MLA/listing_types'

[
  {
    "site_id": "MLA",
    "id": "gold_pro",
    "name": "Oro Premium Full"
  },
  {
    "site_id": "MLA",
    "id": "gold_premium",
    "name": "Oro Premium"
  },
  {
    "site_id": "MLA",
    "id": "gold_special",
    "name": "Oro Profesional"
  },
  {
    "site_id": "MLA",
    "id": "gold",
    "name": "Oro"
  },
  {
    "site_id": "MLA",
    "id": "silver",
    "name": "Plata"
  },
  {
    "site_id": "MLA",
    "id": "bronze",
    "name": "Bronce"
  },
  {
    "site_id": "MLA",
    "id": "free",
    "name": "Gratuita"
  }
]

[
    {
        "site_id": "MLA",
        "id": "gold_pro",
        "name": "Premium"
    },
    {
        "site_id": "MLA",
        "id": "gold_special",
        "name": "Clásica"
    },
    {
        "site_id": "MLA",
        "id": "gold_premium",
        "name": "Oro Premium"
    },
    {
        "site_id": "MLA",
        "id": "gold",
        "name": "Oro"
    },
    {
        "site_id": "MLA",
        "id": "silver",
        "name": "Plata"
    },
    {
        "site_id": "MLA",
        "id": "bronze",
        "name": "Bronce"
    },
    {
        "site_id": "MLA",
        "id": "free",
        "name": "Gratuita"
    }
]

Items Clásica and Premium will have unlimited duration, you could consult it from stop_time field:

curl -X GET https://api.mercadolibre.com/items/MCO415406202?attributes=stop_time

Also, this listings will be paused if stock is 0, and will be activated when you add new quantity. You’ll see the item like this:

"status": "paused",
  "sub_status": [
    "out_of_stock"
  ]

If you want to add stock and active the item again, you should do it in this way:

curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -d
{
  "quantity": 1
}
https://api.mercadolibre.com/items/ITEM_ID?access_token=YOUR_ACCESS_TOKEN

Don’t forget that the listing type Gratuita is going to keep the current flow.

The seller could change between the listing type Clásica and Premium every time that he wishes it without any charge, and could pause and finish the items in the same way that is working now.

If you wish to change from Premium to Clásica, you will have to follow these steps:

 curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -d
{
  "id": "gold"
}
https://api.mercadolibre.com/items/{Item_id}/listing_type?access_token=$ACCESS_TOKEN

To conclude, we want to tell you that we are creating a test environment because we want to give you all the resources to develop the feature and introduce the changes before they become effective. Soon we will contact you to share more news.

What is a notification?

Some events occur on MercadoLibre’s side, and the only way to know that they happened is listen to notifications MercadoLibre sends when they occurs.
Listening to Notifications enables you to have a real-time feed of the changes that occur on the different resources of the MercadoLibre API.
For example, if you listed an item and later it was paused, someone asked you a question, purchased your item or even paid for it and requested shipment, you will receive a Notification of a change on the resource.
Notifications are a very convenient way to stay up-to-date with everything important, in the most efficient way without having to query our API constantly. You only get notified of the resource that changes.

Contents:

• Subscribe to notifications
• Available Topics
• Considerations
• Structure of Notifications
• Order topic
• Questions topic
• Items topic

Subscribe to Notifications

If you want to start receiving notifications you need to go to our application manager, where you first created your app, and edit the details and specify the topics you will listen to. If you haven’t created your App yet, go to the Creating your app section.

– Notifications callback URL:
Configure the public URL of your domain where you want to receive notifications for the different topics. E.g.: “http://myshoes-app.com/callbacks”.
– Topics: Select among different topics to receive their notifications

Available Topics:

• orders – To get notified of any change on one of your orders. E.g.: you received an order from a purchase, the buyer added shipping instructions or the buyer added a payment to an order.
• items – To get notified of any changes on an item you have published. E.g.: Due to MercadoLibre’s rules, your item is set to “under_review” the seller changes an item’s attribute (price, title, description) and all the applications subscribed to that seller’s feed get notified of the change.
• questions – To get notified of every question asked or answered.
• payments – To get notified when the payment status changes.

Considerations

• Messages will be sent out and retried for a period of 12 hours. After that period, if not accepted by the app, they will be discarded.
• Since we will send a POST to your URL, your application must acknowledge the reception with an HTTP status code 200, otherwise the message will be considered undelivered and it will be retried.
• Your application must send a response within 20 seconds, otherwise it will timeout and be considered undelivered and will retry.

What events trigger notifications?

Orders

• Payment: The buyer adds a payment to the order.
• Shipping: There is new shipping information associated to the order or the status of the shipping is changed to: pending, handling, active, delivered, not_delivered.
• Feedback: The buyer rates you as a seller or you send feedback to the buyer. A feed is received on the order.

Items

• Stock decrement: Somebody purchases one of your items and the stock is decremented. A new order is created.
• Changes on any of the attributes.
• Changes on the status: The listing has to be reviewed by an operator and the status is changed to “under_review” or it is paused and the status is changed to “paused”
• 60 days passed and the listing expired: The status changes to “closed”

Questions

• You receive a new question.
• You answer a question.
• You delete a question that you considered inappropriate.

Get the details

After receiving a notification of one topic, you’ll need to make a GET to the resource to get the details and then, if you stored the previous Json, compare both.

Orders

Example:

curl -X GET https://api.mercadolibre.com/orders/{Order_id}?access_token=ACCESS_TOKEN

Response:

{
    "user_id": 1234,
    "resource": "/orders/139876",
    "topic": "orders",
    "received": "2011-10-19T16:38:34.425Z",
    "sent" : "2011-10-19T16:40:34.425Z",
}

Items

Example:

curl -X GET https://api.mercadolibre.com/items/{Item_id}?access_token=ACCESS_TOKEN

Response:

{
  "user_id": 1234,
  "resource": "/items/MLB139876",
  "topic": "items",
  "received": "2011-10-19T16:38:34.425Z",
  "sent" : "2011-10-19T16:40:34.425Z",
}

Questions

Example:

curl -X GET https://api.mercadolibre.com/questions/{Question_id}?access_token=ACCESS_TOKEN

Response:

{
  "user_id": 1234,
  "resource": "/questions/139876",
  "topic": "questions",
  "received": "2011-10-19T16:38:34.425Z",
  "sent" : "2011-10-19T16:40:34.425Z",
}

Payments

Example:

curl -X GET https://api.mercadolibre.com/payments/{Payment_id}?access_token=ACCESS_TOKEN

Resonse:

{
	"resource ": "/orders/1049220880",
	"user_id ": "149218964",
	"topic ": "orders",
	"application_id": 2470,
	"attempts": 1,
	"sent": "2016 - 01 - 15 T18: 12: 31.313 Z ",
	"received": "2016 - 01 - 15 T18: 12: 31.299 Z "
}

Feed History API

We keep a track of your notifications history and you can get it anytime by calling our feeds resource.

Example:

curl -X GET https://api.mercadolibre.com/myfeeds?app_id={App_id}

Response:

{
  "messages": [
    {
      "_id": "123aaa456bbb789ccc",
      "application_id": "1234",
      "user_id": "123456789",
      "resource": "/orders/12345678",
      "topic": "orders",
      "sent": "2014-10-24T11:00:00.836Z",
      "received": "2014-10-24T11:00:00.836Z",
      "attempts": "2",
      "http_code": "400",
      "created_at": "2014-10-24T11:00:00.836Z"
    }
}
}

Next topic: Searches and advanced features.

La entrada Subscribe to our feeds aparece primero en MercadoLibre Developers.

What is a notification?

Some events occur on MercadoLibre’s side, and the only way to know that they happened is listen to notifications MercadoLibre sends when they occurs.
Listening to Notifications enables you to have a real-time feed of the changes that occur on the different resources of the MercadoLibre API.
For example, if you listed an item and later it was paused, someone asked you a question, purchased your item or even paid for it and requested shipment, you will receive a Notification of a change on the resource.
Notifications are a very convenient way to stay up-to-date with everything important, in the most efficient way without having to query our API constantly. You only get notified of the resource that changes.

Contents:

• Subscribe to notifications
• Available Topics
• Considerations
• Structure of Notifications
• Order topic
• Questions topic
• Items topic

Subscribe to Notifications

If you want to start receiving notifications you need to go to our application manager, where you first created your app, and edit the details and specify the topics you will listen to. If you haven’t created your App yet, go to the Creating your app section.

– Notifications callback URL:
Configure the public URL of your domain where you want to receive notifications for the different topics. E.g.: “http://myshoes-app.com/callbacks”.
– Topics: Select among different topics to receive their notifications

Available Topics:

• orders – To get notified of any change on one of your orders. E.g.: you received an order from a purchase, the buyer added shipping instructions or the buyer added a payment to an order.
• items – To get notified of any changes on an item you have published. E.g.: Due to MercadoLibre’s rules, your item is set to “under_review” the seller changes an item’s attribute (price, title, description) and all the applications subscribed to that seller’s feed get notified of the change.
• questions – To get notified of every question asked or answered.
• payments – To get notified when the payment status changes.

Considerations

• Messages will be sent out and retried for a period of 12 hours. After that period, if not accepted by the app, they will be discarded.
• Since we will send a POST to your URL, your application must acknowledge the reception with an HTTP status code 200, otherwise the message will be considered undelivered and it will be retried.
• Your application must send a response within 20 seconds, otherwise it will timeout and be considered undelivered and will retry.

What events trigger notifications?

Orders

• Payment: The buyer adds a payment to the order.
• Shipping: There is new shipping information associated to the order or the status of the shipping is changed to: pending, handling, active, delivered, not_delivered.
• Feedback: The buyer rates you as a seller or you send feedback to the buyer. A feed is received on the order.

Items

• Stock decrement: Somebody purchases one of your items and the stock is decremented. A new order is created.
• Changes on any of the attributes.
• Changes on the status: The listing has to be reviewed by an operator and the status is changed to “under_review” or it is paused and the status is changed to “paused”
• 60 days passed and the listing expired: The status changes to “closed”

Questions

• You receive a new question.
• You answer a question.
• You delete a question that you considered inappropriate.

Get the details

After receiving a notification of one topic, you’ll need to make a GET to the resource to get the details and then, if you stored the previous Json, compare both.

Orders

Example:

curl -X GET https://api.mercadolibre.com/orders/{Order_id}?access_token=ACCESS_TOKEN

Response:

{
    "user_id": 1234,
    "resource": "/orders/139876",
    "topic": "orders",
    "received": "2011-10-19T16:38:34.425Z",
    "sent" : "2011-10-19T16:40:34.425Z",
}

Items

Example:

curl -X GET https://api.mercadolibre.com/items/{Item_id}?access_token=ACCESS_TOKEN

Response:

{
  "user_id": 1234,
  "resource": "/items/MLB139876",
  "topic": "items",
  "received": "2011-10-19T16:38:34.425Z",
  "sent" : "2011-10-19T16:40:34.425Z",
}

Questions

Example:

curl -X GET https://api.mercadolibre.com/questions/{Question_id}?access_token=ACCESS_TOKEN

Response:

{
  "user_id": 1234,
  "resource": "/questions/139876",
  "topic": "questions",
  "received": "2011-10-19T16:38:34.425Z",
  "sent" : "2011-10-19T16:40:34.425Z",
}

Payments

Example:

curl -X GET https://api.mercadolibre.com/payments/{Payment_id}?access_token=ACCESS_TOKEN

Resonse:

{
	"resource ": "/orders/1049220880",
	"user_id ": "149218964",
	"topic ": "orders",
	"application_id": 2470,
	"attempts": 1,
	"sent": "2016 - 01 - 15 T18: 12: 31.313 Z ",
	"received": "2016 - 01 - 15 T18: 12: 31.299 Z "
}

Feed History API

We keep a track of your notifications history and you can get it anytime by calling our feeds resource.

Example:

curl -X GET https://api.mercadolibre.com/myfeeds?app_id={App_id}

Response:

{
  "messages": [
    {
      "_id": "123aaa456bbb789ccc",
      "application_id": "1234",
      "user_id": "123456789",
      "resource": "/orders/12345678",
      "topic": "orders",
      "sent": "2014-10-24T11:00:00.836Z",
      "received": "2014-10-24T11:00:00.836Z",
      "attempts": "2",
      "http_code": "400",
      "created_at": "2014-10-24T11:00:00.836Z"
    }
}
}

Next topic: Searches and advanced features.

La entrada Subscribe to our feeds aparece primero en MercadoLibre Developers.

Official stores

Some selected users are part of MercadoLibre Official Stores, and have one or more brands under the same user. If you want to become part of MercadoLibre Official Stores, you’ll have to communicate with a commercial adviser. If you’re part of Official Stores already, follow this tutorial to learn the basic of how to work with this user type.

Contents:

• Obtain your brands Ids
• Obtain all information about a specific brand

Obtain your brands Ids

This resource retrieves brands associated to an user_id. There can be more than one per user. The official_store_id attribute identifies a store.
Example:

curl -X GET https://api.mercadolibre.com/users/{User_id}/brands

Response:

{
  "cust_id": 12345678,
  "tags": [
	"large_seller",
	"user_info_verified",
	"brand"
  ],
  "brands": [
	{
  	"tags": [
    	"girls",
    	"female"
  	],
  	"official_store_id": 16,
  	"categories_ids": [
    	"MLA1430"
  	],
  	"fantasy_name": "47 Street",
  	"site_id": "MLA",
  	"status": "active",
  	"name": "47 Street",
  	"pictures": [
    	{
      	"id": 104,
      	"name": "big_logo",
      	"secure_url": null,
      	"url": "http://static.mlstatic.com/org-img/apparel/images/47street/149254178-logo-g2.jpg",
      	"size": "174x164"
    	},
    	{},
    	{},
    	{},
    	{},
    	{}
  	],
  	"relevance_position": 50
	},
	{},
	{},
	{},
	{}
  ],
  "site_id": "MLA",
  "user_type": "brand"
}

Obtain all information about a specific brand

To get information about a specific brand, you can make the call to the brand_id you want to know about like in the example that follows:
Example:

curl -X GET https://api.mercadolibre.com/users/58715193/brands/133

Response:

{
  "tags": [
	"home",
	"standout"
  ],
  "official_store_id": 133,
  "categories_ids": [
	"MLA1403"
  ],
  "fantasy_name": "Bodega Lanzarini",
  "users": [
	{
  	"cust_id": 58715193,
  	"tags": [
    	"eshop",
    	"large_seller",
    	"user_info_verified",
    	"brand"
  	],
  	"site_id": "MLA",
  	"user_type": "brand"
	}
  ],
  "site_id": "MLA",
  "status": "active",
  "name": "Bodega Lanzarini",
  "date_created": "2014-08-04T04:00:00.000Z",
  "pictures": [
	{
  	"id": 632,
  	"name": "big_logo",
  	"secure_url": null,
  	"url": "http://static.mlstatic.com/org-img/apparel/images/bodegalanzarini/58715193-logo-g.jpg",
  	"size": "174x164"
	},
	{
  	"id": 2474,
  	"name": "facebook_logo",
  	"secure_url": null,
  	"url": "http://static.mlstatic.com/org-img/apparel/images/mla-fb/58715193-logo-fb.jpg",
  	"size": "1600x750"
	},
	{
  	"id": 9428,
      "name": "home_app",
  	"secure_url": null,
  	"url": "http://static.mlstatic.com/org-img/apparel/bkg_apps/58715193-bkg.jpg",
  	"size": "270x155"
	},
	{
  	"id": 634,
  	"name": "logo",
  	"secure_url": null,
  	"url": "http://static.mlstatic.com/org-img/apparel/images/bodegalanzarini/58715193-logo-home.jpg",
  	"size": "160x80"
	},
	{
      "id": 633,
  	"name": "logo_landing",
  	"secure_url": null,
  	"url": "http://static.mlstatic.com/org-img/apparel/images/bodegalanzarini/58715193-logo-home.jpg",
  	"size": "160x80"
	},
	{
  	"id": 631,
  	"name": "background",
  	"secure_url": null,
  	"url": "http://static.mlstatic.com/org-img/apparel/images/bodegalanzarini/58715193-bkg.jpg",
  	"size": "1600x750"
	},
	{
  	"id": 635,
  	"name": "small_logo",
  	"secure_url": null,
  	"url": "http://static.mlstatic.com/org-img/apparel/images/bodegalanzarini/58715193-logo-ch2.jpg",
  	"size": "96x70"
	}
  ],
  "boost": {
	"is_active": false,
	"last_update": "2015-08-17T20:55:12.000Z"
  },
  "relevance_position": 69
}

Great! You already know the brand_id associated to your user to send every time you want to list an item.

Next topic: Set categories for your products

La entrada Manage Official Stores aparece primero en MercadoLibre Developers.

User’s addresses

Overview

The purpose of the following document is to introduce the Address API, specifying the fields listed in the response to your query, along with the potential responses to those fields.

Contents:

• Get user’s addresses
• Response fields description

Get user’s addresses

To make a call to this API, you will need an access token.

Example:

curl -X GET https://api.mercadolibre.com/users/{User_id}/addresses?access_token=$ACCESS_TOKEN

Response:

{
	"id": 145834937,
	"user_id": "160252486",
	"contact": null,
	"phone": null,
	"address_line": "Guatemala 5100",
	"floor": null,
	"apartment": null,
	"street_number": "5100",
	"street_name": "Guatemala",
	"zip_code": "1000",
	"city": -{
    	"id": "TUxBQlBBTDI1MTVa",
    	"name": "Palermo",
	},
	"state": -{
    	"id": "AR-C",
    	"name": "Capital Federal",
    	
	},
	"country": -{
    	"id": "AR",
    	"name": "Argentina",
	},
	"neighborhood": -{
    	"id": null,
    	"name": null,
	},
	"municipality": -{
    	"id": null,
    	"name": null,
	},
	"search_location": -{
    	"state": -{
        	"id": "TUxBUENBUGw3M2E1",
        	"name": "Capital Federal",
    	},
    	"city": -{
        	"id": "TUxBQ0NBUGZlZG1sYQ",
        	"name": "Capital Federal",
    	},
    	"neighborhood": -{
        	"id": "TUxBQlBBTDI1MTVa",
        	"name": "Palermo",
    	},
	},
	"types": -[
        "default_selling_address",
    	"shipping",
	],
	"comment": "",
	"geolocation_type": "RANGE_INTERPOLATED",
	"latitude": -34.5834729,
	"longitude": -58.4281022,
	"status": "active",
	"date_created": "2014-06-05T12:26:54.000-04:00",
	"normalized": true,
	"open_hours": -{
    	"on_holidays": -{
        	"hours": [
        	],
        	"status": "closed",
    	},
	},
}

Response fields description

Next topic: Add and manage user’s bookmarks.

La entrada User’s addresess aparece primero en MercadoLibre Developers.

Bookmarks

Overview

The Bookmarks feature explains itself, being a way to keep the items you’re interested associated to a user.
You can manage bookmarks through the Bookmarks API Resource, adding or removing references, which are synchronized with mobile apps.

Contents:

• Get your bookmarks
• Bookmark an item
• Remove a bookmark
• Response

Get your bookmarks

Use the following url In order to retrieve your bookmarks:
Example:

curl -X GET https://api.mercadolibre.com/users/me/bookmarks?access_token=...

Response:

[
  ....
  {
	"bookmarked_date": "2012-07-20T10:22:04.736-04:00",
	"item_id": "MLA428108770",
  },
  {
	"bookmarked_date": "2012-07-17T16:46:46.079-04:00",
	"item_id": "MLA428424006",
  },
  {
	"bookmarked_date": "2012-07-13T16:41:43.937-04:00",
	"item_id": "MLA428112474",
  },
  ....
]

Bookmark an item

To bookmark an item, do as it follows:

Example:

curl -X POST -H "Content-Type: application/json" -d
'{
   	"item_id":"MLA5529"
 }'

https://api.mercadolibre.com/users/me/bookmarks?access_token=$ACCESS_TOKE

Remove a bookmark

Bookmarks can be removed any time you want by simply deleting the reference.

Example:

curl -X DELETE "https://api.mercadolibre.com/users/me/bookmarks/MLA605670642?access_token=$ACCESS_TOKEN

Next topic: Check account balance.

La entrada Bookmarks aparece primero en MercadoLibre Developers.

Account balance

Contents:

• Overview
• Check account balance
• Reasons of amount unavailavilty
• Response

When you have money on your account, you can check your balance with the MercadoPago Account resource.
Example:

curl -X GET https://api.mercadolibre.com/users/{User_id}/mercadopago_account/balance?access_token=$ACCESS_TOKEN

You will notice that you’ll find various amounts separated by status and availability in the response.

The parameter “unavailable_balance_by_reason” shows the amounts ​​unavailable and it will tell you the reason why it’s unavailable.
You can also see amounts available for transfer, withdrawal, and payment (credit in MercadoPago) in the parameter “available_balance_by_transaction_type.”

Reasons of amount unavailavilty

• dispute – Amount blocked while the order is in dispute.
• fraud – Amount blocked due to suspected fraud.
• ml_debt – Amount destined only to MercadoLibre cost.
• time_period – Amount blocked by default time processing MercadoPago.
• restriction – Amount blocked for other reasons.

That’s all you need to know about it. If you want to know further about working with MercadoPago, check the MercadoPago Developers Site.

La entrada Account balance aparece primero en MercadoLibre Developers.

Manage packages

Promotions Packs are listing packages for Car Dealers and Real State Agency Classifieds listings. In this tutorial you’ll learn how to get information about packages and also engage and activate a package.

Contents:

• Obtain packages by category
• Get packages engaged by an user
• Resource description
• Calling packages
• Obtain listing Packages and upgrades
• Hired packages by user
• Calling packages with parameters
• Hire a package
• Activate a hired package
• End a hired package
• Calls to upgrades
• GET upgrades by user
• Check item available upgrades
• Upgrade the item
• Downgrade an item
• End Package
• FAQ

Obtain packages by category

The possible values for classifieds_promotion_packs categories are different each site. Possible values are:
{site_id}1743: Car Dealer.
{site_id}1459: Real Estate Agency.
For example, on Argentina, Car Dealer package category it’s MLA1743 while in Brazil it’s MLB1743
Make a GET to look for packages in an specific category:

curl -X GET https://api.mercadolibre.com/categories/{category_id}/classifieds_promotion_packs

Response:

[
  {
    "id": "IPAA",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 15 Básico",
    "price": 350,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCAA",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 15
      }
    ]
  },
  {
    "id": "IPAR",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 15 Premium",
    "price": 600,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCAR",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "gold",
        "available_listings": 6
      },
      {
        "listing_type_id": "gold_premium",
        "available_listings": 1
      },
      {
        "listing_type_id": "silver",
        "available_listings": 8
      }
    ]
  },
  {
    "id": "IPAS",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 15 Especial",
    "price": 410,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCAS",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 10
      },
      {
        "listing_type_id": "gold",
        "available_listings": 5
      }
    ]
  },
  {
    "id": "IPBA",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 30 Básico",
    "price": 480,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCBA",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 30
      }
    ]
  },
  {
    "id": "IPBR",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 30 Premium",
    "price": 880,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCBR",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 16
      },
      {
        "listing_type_id": "gold_premium",
        "available_listings": 2
      },
      {
        "listing_type_id": "gold",
        "available_listings": 12
      }
    ]
  },
  {
    "id": "IPBS",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 30 Especial",
    "price": 560,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCBS",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 20
      },
      {
        "listing_type_id": "gold",
        "available_listings": 10
      }
    ]
  },
  {
    "id": "IPCA",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 60 Básico",
    "price": 570,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCCA",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 60
      }
    ]
  },
  {
    "id": "IPCR",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 60 Premium",
    "price": 910,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCCR",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 32
      },
      {
        "listing_type_id": "gold",
        "available_listings": 24
      },
      {
        "listing_type_id": "gold_premium",
        "available_listings": 4
      }
    ]
  },
  {
    "id": "IPCS",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 60 Especial",
    "price": 650,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCCS",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "gold",
        "available_listings": 20
      },
      {
        "listing_type_id": "silver",
        "available_listings": 40
      }
    ]
  },
  {
    "id": "IPDA",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 100 Básico",
    "price": 750,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCDA",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 100
      }
    ]
  },
  {
    "id": "IPDR",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 100 Premium",
    "price": 1180,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCDR",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "gold_premium",
        "available_listings": 5
      },
      {
        "listing_type_id": "gold",
        "available_listings": 35
      },
      {
        "listing_type_id": "silver",
        "available_listings": 60
      }
    ]
  },
  {
    "id": "IPDS",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 100 Especial",
    "price": 820,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCDS",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "gold",
        "available_listings": 25
      },
      {
        "listing_type_id": "silver",
        "available_listings": 75
      }
    ]
  },
  {
    "id": "IPEA",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 500 Básico",
    "price": 850,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCEA",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 500
      }
    ]
  },
  {
    "id": "IPER",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 500 Premium",
    "price": 1900,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCER",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "gold",
        "available_listings": 100
      },
      {
        "listing_type_id": "gold_premium",
        "available_listings": 15
      },
      {
        "listing_type_id": "silver",
        "available_listings": 385
      }
    ]
  },
  {
    "id": "IPES",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 500 Especial",
    "price": 1000,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCES",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "gold",
        "available_listings": 70
      },
      {
        "listing_type_id": "silver",
        "available_listings": 430
      }
    ]
  }
]

Get packages engaged by an user

curl -X GET https://api.mercadolibre.com/users/{user_id}/classifieds_promotion_packs?access_token=$ACCESS_TOKEN;

Response:

[
	{
    	"id": 754985,
    	"user_id": "135146148",
    	"promotion_pack_id": "MPAB",
    	"category_id": "MLU1743",
    	"description": "Paquete 15 Básico",
    	"package_type": "rotary",
    	"status": "active",
    	"date_created": "2013-05-23T15:34:48.498-04:00",
    	"date_start": "2013-05-23T15:34:47.544-04:00",
    	"date_expires": "2013-06-22T15:34:47.544-04:00",
    	"date_stopped": null,
    	"last_updated": "2013-05-23T15:35:48.211-04:00",
    	"engagement_type": "none",
    	"charge_id": 822129921,
    	"remaining_listings": 15,
    	"used_listings": 0,
    	"listing_details": [
        	{
            	"listing_type_id": "silver",
            	"available_listings": 15,
            	"used_listings": 0,
            	"remaining_listings": 15
        	}
    	]
	}
]

Resource description

Check if an user has an specific listing_type available

curl -X GET https://api.mercadolibre.com/users/{user_id}/classifieds_promotion_packs/{listing_type}ilver& categoryId={Category_id}?access_token=$ACCESS_TOKEN

Response:

{
  "has_available_listings": true
}

Engage and activate a package

You can engage a package and activate it by making a POST to the API like in the following example:

curl -X POST "Content-type:application/json" -d '{
"categ_id":"MLA1459", "promotion_pack_id":"IPIN", "engagement_type":"none", "status":"active"
}' http://api.mercadolibre.com/users/{user_id}/classifieds_promotion_packs&access_token=$ACCESS_TOKEN

The current documentation focusses on the new logic for upgrades packages currently working only for real estate agencies for Argentina, Brazil, Mexico and Uruguay. The new upgrade packages logic consists in migrating the actual model where charges are being generated for individual upgrades, to an analog logic on listings packages where the client hires an upgrade package and then every upgrade done occupies a place or quota in the package.

Calling packages

There’s retro compatibility between the existing packages logic and the new one, adding an extra optional filter on the call: “package_content” that makes possible to differentiate between listing packages and upgrade packages.

Obtain listing Packages and upgrades

curl -X GET https://api.mercadolibre.com/categories/{category_id}/classifieds_promotion_packs

Example:

https://api.mercadolibre.com/categories/MLA1459/classifieds_promotion_packs?package_content=upgrades,publications
[
    {
        "id": "IPUA",
        "category_id": "MLA1459",
        "brand": "MLREALESTATE",
        "description": "Paquete Unico Ilimitado 15",
        "price": 600,
        "package_type": "unlimited",
        "package_content": "publications",
        "duration": 30,
        "status": "active",
        "charge_type_id": "CCBA",
        "max_upgrades": 12,
        "listing_details": [
            {
                "listing_type_id": "silver",
                "available_listings": 15
            }
        ],
        "visibility": "private"
    },
    {
        "id": "IPUB",
        "category_id": "MLA1459",
        "brand": "MLREALESTATE",
        "description": "Paquete Unico Ilimitado 50",
        "price": 600,
        "package_type": "unlimited",
        "package_content": "publications",
        "duration": 30,
        "status": "active",
        "charge_type_id": "CCBA",
        "max_upgrades": 30,
        "listing_details": [
            {
                "listing_type_id": "silver",
                "available_listings": 50
            }
        ],
        "visibility": "private"
    },
    {
        "id": "IPUC",
        "category_id": "MLA1459",
        "brand": "MLREALESTATE",
        "description": "Paquete Unico Ilimitado 100",
        "price": 600,
        "package_type": "unlimited",
        "package_content": "publications",
        "duration": 30,
        "status": "active",
        "charge_type_id": "CCBA",
        "max_upgrades": 50,
        "listing_details": [
            {
                "listing_type_id": "silver",
                "available_listings": 100
            }
        ],
        "visibility": "private"
    },
    {
        "id": "IPUD",
        "category_id": "MLA1459",
        "brand": "MLREALESTATE",
        "description": "Paquete Unico Ilimitado 500",
        "price": 600,
        "package_type": "unlimited",
        "package_content": "publications",
        "duration": 30,
        "status": "active",
        "charge_type_id": "CCBA",
        "max_upgrades": 100,
        "listing_details": [
            {
                "listing_type_id": "silver",
                "available_listings": 500
            }
        ],
        "visibility": "private"
    },
    {
        "id": "IPUPGG1",
        "category_id": "MLA1459",
        "brand": "MLREALESTATE",
        "description": "Paquete Upgrades Gold Individual",
        "price": 150,
        "package_type": "rotary",
        "package_content": "upgrades",
        "duration": 30,
        "status": "active",
        "charge_type_id": "free",
        "max_upgrades": 1,
        "listing_details": [
            {
                "listing_type_id": "gold",
                "available_listings": 1
            }
        ],
        "visibility": "private"
    },
    {
        "id": "IPUPGGP1",
        "category_id": "MLA1459",
        "brand": "MLREALESTATE",
        "description": "Paquete Upgrades Gold Premium Individual",
        "price": 220,
        "package_type": "rotary",
        "package_content": "upgrades",
        "duration": 30,
        "status": "active",
        "charge_type_id": "free",
        "max_upgrades": 1,
        "listing_details": [
            {
                "listing_type_id": "gold_premium",
                "available_listings": 1
            }
        ],
        "visibility": "private"
    },
    {
        "id": "IPUPGGP10",
        "category_id": "MLA1459",
        "brand": "MLREALESTATE",
        "description": "Paquete Upgrades 10 Destaques Gold Premium",
        "price": 1650,
        "package_type": "rotary",
        "package_content": "upgrades",
        "duration": 30,
        "status": "active",
        "charge_type_id": "free",
        "max_upgrades": 1,
        "listing_details": [
            {
                "listing_type_id": "gold_premium",
                "available_listings": 10
            }
        ],
        "visibility": "private"
    }
]

As you see, we got the listing packages and upgrade packages for the specified category.

Hired packages by user

GET https://api.mercadolibre.com/users/{user_id}/classifieds_promotion_packs?access_token=

Example:

https://api.mercadolibre.com/users/184179005/classifieds_promotion_packs?access_token=$ACCESS_TOKEN&status=active,finished&package_content=upgrades,publications
[
    {
        "id": 1024029,
        "user_id": "184179005",
        "promotion_pack_id": "PPUGOLDPREMIUMTEST02",
        "category_id": "MLA1459",
        "brand": "MLREALESTATE",
        "description": "Paquete de upgrades gold premium",
        "package_type": "rotary",
        "status": "active",
        "date_created": "2015-05-27T14:26:37.790-04:00",
        "date_start": "2015-05-27T14:26:37.692-04:00",
        "date_expires": "2015-06-27T14:26:37.692-04:00",
        "date_stopped": null,
        "last_updated": "2015-05-27T14:26:37.790-04:00",
        "engagement_type": "re-engagement",
        "package_content": "upgrades",
        "charge_id": 0,
        "remaining_listings": 9999,
        "used_listings": 1,
        "listing_details": [
            {
                "listing_type_id": "gold_premium",
                "available_listings": 10000,
                "used_listings": 1,
                "remaining_listings": 9999
            }
        ]
    },
    {
        "id": 1023654,
        "user_id": "184179005",
        "promotion_pack_id": "IPUE",
        "category_id": "MLA1459",
        "brand": "MLREALESTATE",
        "description": "Paquete Unico Ilimitado 1000",
        "package_type": "unlimited",
        "status": "active",
        "date_created": "2015-05-26T14:37:12.540-04:00",
        "date_start": "2015-05-26T14:37:12.475-04:00",
        "date_expires": "2015-06-26T14:37:12.475-04:00",
        "date_stopped": null,
        "last_updated": "2015-05-27T14:23:02.951-04:00",
        "engagement_type": "none",
        "package_content": "publications",
        "charge_id": 1725523903,
        "remaining_listings": 999,
        "used_listings": 1,
        "listing_details": [
            {
                "listing_type_id": "silver",
                "available_listings": 1000,
                "used_listings": 1,
                "remaining_listings": 999
            }
        ]
    }
]

As you see we got a upgrade package and a listing package. You can see the difference in the package_content attribute.
Note: Due to retro-compatibility, if package_content parameter is not provided in the request, it will be equal to provide package_content =publications. This means, that every time you want to obtain upgrade packages, you need to include “upgrades” in the package_content parameter.

Calling packages with parameters

Example:

https://api.mercadolibre.com/users/184179005/classifieds_promotion_packs?access_token=$ACCESS_TOKEN&status=active,finished&package_content=upgrades,publications

Response in case there’s no package:

[
    {
"message":"User promotion packs not found for user 184179005",
"error":"not_found",
"status":404,
"cause":[]
     }

]

Hire a package

Example:

POST https://api.mercadolibre.com/users/{user_id}/classifieds_promotion_packs?access_token=$ACCESS_TOKEN

BODY WITHOUT AUTOMATIC RE-ENGAGEMENT:

{ 
“status”:”active”,
“engagement_type”:”none”,
“promotion_pack_id”:”IPIN”,
“categ_id”:”MLA1743” 
}

Example:

 curl -X POST --header "Content-type:application/json" -d 
'{"promotion_pack_id":"PPUGOLDPREMIUMTEST02","categ_id":"MLA1459","engagement_type":"re-engagement","status":"active"}' 'http://api.mercadolibre.com/users/184179005/classifieds_promotion_packs?access_token=$ACCESS_TOKEN'


   "id": 1026038,
    "user_id": "184179005",
    "promotion_pack_id": "PPUGOLDPREMIUMTEST02",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete de upgrades gold premium",
    "package_type": "rotary",
    "status": "active",
    "date_created": "2015-06-03T16:37:31.646-04:00",
    "date_start": "2015-06-03T16:37:31.497-04:00",
    "date_expires": "2015-07-03T16:37:31.497-04:00",
    "date_stopped": null,
    "last_updated": "2015-06-03T16:37:31.646-04:00",
    "engagement_type": "re-engagement",
    "package_content": "upgrades",
    "charge_id": 0,
    "remaining_listings": 10000,
    "used_listings": 0,
    "listing_details": [
        {
            "listing_type_id": "gold_premium",
            "available_listings": 10000,
            "used_listings": 0,
            "remaining_listings": 10000
        }
    ]
}

As you can see, it returns the hired package. In this case is an upgrade packages.
NOTE: On contrary of listing packages, upgrade packages does not accept “pending” as inicial status.
Example:

 curl -X POST --header "Content-type:application/json" -d '{"promotion_pack_id":"PPUGOLDPREMIUMTEST02","categ_id":"MLA1459","engagement_type":"re-engagement","status":"active"}' 'http://api.mercadolibre.com/users/184179005/classifieds_promotion_packs?access_token=$ACCESS_TOKEN'

Response in case you can’t hire the package:

 {
    "message": "Promotion pack not found for categ MLA1459 and id PPUGOLDPREMIUMTEST02",
    "error": "not_found",
    "status": 404,
    "cause": []
}

Activate a hired package

Example:

PUT http://api.mercadolibre.com/users/{user_id}/classifieds_promotion_packs/{user_promotion_pack_id}?access_token=$ACCESS_TOKEN
BODY
{ “status”:”active” }

To obtain the package_id we’ll make the following GET:

GET http://api.mercadolibre.com/users/{user_id}/classifieds_promotion_packs?status=pending

End a hired package

Example:

PUT http://api.mercadolibre.com/users/{user_id}/classifieds_promotion_packs/{user_promotion_pack_id}?acces_token=$ACCESS_TOKEN
BODY
{ “status”:”finished” }

Calls to upgrades

If the user doesn’t have hired any upgrade package, the upgrade is not going to be done.

GET upgrades by user

Example:

GET http://api.mercadolibre.com/users/{user_id}/classifieds_promotion_packs/user_item_upgrade
?acces_token=$ACCESS_TOKEN

Response:

curl -X GET 'http://api.mercadolibre.com/users/184179005/classifieds_promotion_packs/user_item_upgrade?status=finished,active&access_token=$ACCESS_TOKEN'
{
    "paging": {
        "total": 4,
        "offset": 0,
        "limit": 50
    },
    "results": [
        {
            "item_id": "MLA562766164",
            "listing_type_from": "silver",
            "listing_type_to": "gold_premium",
            "engagement_type": "none",
            "status": "active",
            "date_start": "2015-06-03T08:28:32.000-04:00",
            "date_stop": null,
            "date_expires": "2015-06-27T14:26:37.000-04:00",
            "charge_id": null
        },
        {
            "item_id": "MLA562083882",
            "listing_type_from": "silver",
            "listing_type_to": "gold_premium",
            "engagement_type": "none",
            "status": "active",
            "date_start": "2015-05-29T12:20:39.000-04:00",
            "date_stop": null,
            "date_expires": "2015-06-27T14:26:37.000-04:00",
            "charge_id": null
        },
        {
            "item_id": "MLA562083882",
            "listing_type_from": "silver",
            "listing_type_to": "gold_premium",
            "engagement_type": "none",
            "status": "finished",
            "date_start": "2015-04-29T11:49:06.000-04:00",
            "date_stop": "2015-05-29T11:50:41.000-04:00",
            "date_expires": "2015-06-27T14:26:37.000-04:00",
            "charge_id": null
        },
        {
            "item_id": "MLA561761811",
            "listing_type_from": "silver",
            "listing_type_to": "gold_premium",
            "engagement_type": "none",
            "status": "finished",
            "date_start": "2015-05-27T16:05:48.000-04:00",
            "date_stop": "2015-05-28T08:09:58.000-04:00",
            "date_expires": "2015-06-26T16:05:48.000-04:00",
            "charge_id": null
        }
    ]
}

As you see, this user hired 4 upgrades, 3 of them already ended. You can also see upgrades hired for the same item.
NOTE: According to this new logic, charge_id attribute will no longer be in use. The charges will apply to the package.

Check item available upgrades

GET https://api.mercadolibre.com/items/{item_id}/available_upgrades?access_token=$ACCESS_TOKEN

Example:

curl 'https://api.mercadolibre.com/items/MLA563672820/available_upgrades?&access_token=$ACCESS_TOKEN'
[
    {
        "site_id": "MLA",
        "id": "gold_premium",
        "name": "Oro Premium"
    },
    {
        "site_id": "MLA",
        "id": "gold",
        "name": "Oro"
    }
]

Upgrade the item

POST https://api.mercadolibre.com/items/{item_id}/listing_type?acces_token=$ACCESS_TOKEN
BODY
{ “id”:”{listing_type}” }

The response is the item updated.
Example:

curl -X POST --header "Content-type:application/json" -d '{"id":"gold"}' 'https://api.mercadolibre.com/items/MLA563940625/listing_type?access_token=$ACCESS_TOKEN'
{
    "id": "MLA563940625",
    "site_id": "MLA",
    "title": "Test 10 No Ofertar",
    "subtitle": null,
    "seller_id": 184854440,
    "category_id": "MLA50543",
    "official_store_id": null,
    "price": 2928282,
    "base_price": 2928282,
    "original_price": null,
    "currency_id": "ARS",
    "initial_quantity": 1,
    "available_quantity": 1,
    "sold_quantity": 0,
    "buying_mode": "classified",
    "listing_type_id": "gold",
    "start_time": "2015-06-09T20:25:50.000Z",
    "stop_time": "2015-07-05T19:51:17.587Z",
    "end_time": "2015-07-05T19:51:17.587Z",
    "condition": "not_specified",
    "permalink": "http://inmueble.mercadolibre.com.ar/MLA-563940625-test-10-no-ofertar-_JM",
    "thumbnail": "http://mla-s1-p.mlstatic.com/302401-MLA20317818801_062015-I.jpg",
    "secure_thumbnail": "https://mla-s1-p.mlstatic.com/302401-MLA20317818801_062015-I.jpg",
    "pictures": [
        {
            "id": "302401-MLA20317818801_062015",
            "url": "http://mla-s1-p.mlstatic.com/302401-MLA20317818801_062015-O.jpg",
            "secure_url": "https://mla-s1-p.mlstatic.com/302401-MLA20317818801_062015-O.jpg",
            "size": "500x281",
            "max_size": "1200x675",
            "quality": ""
        }
    ],
    "video_id": null,
    "descriptions": [],
    "accepts_mercadopago": false,
    "non_mercado_pago_payment_methods": [],
    "shipping": {
        "mode": "not_specified",
        "local_pick_up": false,
        "free_shipping": false,
        "methods": [],
        "dimensions": null,
        "tags": []
    },
    "international_delivery_mode": "none",
    "seller_address": {
        "id": 163310864,
        "comment": "",
        "address_line": "Test Address 123",
        "zip_code": "1414",
        "city": {
            "id": "",
            "name": "Palermo"
        },
        "state": {
            "id": "AR-C",
            "name": "Capital Federal"
        },
        "country": {
            "id": "AR",
            "name": "Argentina"
        },
        "latitude": "",
        "longitude": "",
        "search_location": {
            "neighborhood": {
                "id": "TUxBQlBBTDI1MTVa",
                "name": "Palermo"
            },
            "city": {
                "id": "TUxBQ0NBUGZlZG1sYQ",
                "name": "Capital Federal"
            },
            "state": {
                "id": "TUxBUENBUGw3M2E1",
                "name": "Capital Federal"
            }
        }
    },
    "seller_contact": {
        "contact": "",
        "other_info": "",
        "area_code": "",
        "phone": "",
        "area_code2": "",
        "phone2": "",
        "email": "",
        "webpage": ""
    },
    "location": {
        "address_line": "falsa 123 123",
        "zip_code": "",
        "neighborhood": {
            "id": "TUxBQkVTUDYyODRa",
            "name": "Espartillar"
        },
        "city": {
            "id": "TUxBQ0FETzQ2Nzc",
            "name": "Adolfo Alsina"
        },
        "state": {
            "id": "TUxBUFpPTmFpbnRl",
            "name": "Buenos Aires Interior"
        },
        "country": {
            "id": "AR",
            "name": "Argentina"
        },
        "latitude": -34.6635266,
        "longitude": -58.3654707,
        "open_hours": ""
    },
    "geolocation": {
        "latitude": -34.6635266,
        "longitude": -58.3654707
    },
    "coverage_areas": [],
    "attributes": [
        {
            "id": "MLA1459-HORPREF",
            "name": "Horario de contacto",
            "value_id": "",
            "value_name": "",
            "attribute_group_id": "ADICIONALES",
            "attribute_group_name": "Adicionales"
        },
        {
            "id": "MLA50541-ACCESO",
            "name": "Acceso",
            "value_id": "",
            "value_name": "",
            "attribute_group_id": "ADICIONALES",
            "attribute_group_name": "Adicionales"
        },
        {
            "id": "MLA50541-ANTIG",
            "name": "Antigüedad",
            "value_id": "",
            "value_name": "",
            "attribute_group_id": "ADICIONALES",
            "attribute_group_name": "Adicionales"
        },
        {
            "id": "MLA50541-EXPENCEM",
            "name": "Expensas ($)",
            "value_id": "",
            "value_name": "",
            "attribute_group_id": "ADICIONALES",
            "attribute_group_name": "Adicionales"
        },
        {
            "id": "MLA50541-SEGUR",
            "name": "Seguridad",
            "value_id": "",
            "value_name": "",
            "attribute_group_id": "ADICIONALES",
            "attribute_group_name": "Adicionales"
        },
        {
            "id": "MLA1459-INMUEBLE",
            "name": "Inmueble",
            "value_id": "MLA1459-INMUEBLE-COCHERA",
            "value_name": "Cochera",
            "attribute_group_id": "FIND",
            "attribute_group_name": "Ficha técnica"
        },
        {
            "id": "MLA1459-OPERACION",
            "name": "Operación",
            "value_id": "MLA1459-OPERACION-VENTA",
            "value_name": "Venta",
            "attribute_group_id": "FIND",
            "attribute_group_name": "Ficha técnica"
        },
        {
            "id": "MLA50541-MTRSTOTAL",
            "name": "Superficie total (m²)",
            "value_id": "",
            "value_name": "24",
            "attribute_group_id": "FIND",
            "attribute_group_name": "Ficha técnica"
        },
        {
            "id": "MLA50541-TIPCOB",
            "name": "Tipo de cobertura",
            "value_id": "MLA50541-TIPCOB-CUBIERTA",
            "value_name": "Cubierta",
            "attribute_group_id": "FIND",
            "attribute_group_name": "Ficha técnica"
        },
        {
            "id": "MLA50541-TIPOCOCH",
            "name": "Tipo de cochera",
            "value_id": "MLA50541-TIPOCOCH-FIJA",
            "value_name": "Fija",
            "attribute_group_id": "FIND",
            "attribute_group_name": "Ficha técnica"
        }
    ],
    "listing_source": "",
    "variations": [],
    "status": "active",
    "sub_status": [],
    "tags": [],
    "warranty": null,
    "catalog_product_id": null,
    "seller_custom_field": null,
    "parent_item_id": null,
    "differential_pricing": null,
    "deal_ids": [],
    "automatic_relist": false,
    "date_created": "2015-06-09T20:25:50.000Z",
    "last_updated": "2015-06-10T12:20:32.418Z"
}

Downgrade an item

POST https://api.mercadolibre.com/items/{item_id}/listing_type?acces_token=$ACCESS_TOKEN
BODY
{ “id”:”{listing_type}” }

The difference is the that the value for the “id” on the JSON is going to be the one for the original listing_type. For example, if you made an upgrade from “silver” to “gold”, the id you’re sending on the call (downgrade) is going to be “silver”.
Example:

curl -X POST --header "Content-type:application/json" -d '{"id":"silver"}' 'https://api.mercadolibre.com/items/MLA563940625/listing_type?access_token=$ACCESS_TOKEN'
{
    "id": "MLA563940625",
    "site_id": "MLA",
    "title": "Test 10 No Ofertar",
    "subtitle": null,
    "seller_id": 184854440,
    "category_id": "MLA50543",
    "official_store_id": null,
    "price": 2928282,
    "base_price": 2928282,
    "original_price": null,
    "currency_id": "ARS",
    "initial_quantity": 1,
    "available_quantity": 1,
    "sold_quantity": 0,
    "buying_mode": "classified",
    "listing_type_id": "silver",
    "start_time": "2015-06-09T20:25:50.000Z",
    "stop_time": "2015-07-05T19:51:17.587Z",
    "end_time": "2015-07-05T19:51:17.587Z",
    "condition": "not_specified",
    "permalink": "http://inmueble.mercadolibre.com.ar/MLA-563940625-test-10-no-ofertar-_JM",
    "thumbnail": "http://mla-s1-p.mlstatic.com/302401-MLA20317818801_062015-I.jpg",
    "secure_thumbnail": "https://mla-s1-p.mlstatic.com/302401-MLA20317818801_062015-I.jpg",
    "pictures": [
        {
            "id": "302401-MLA20317818801_062015",
            "url": "http://mla-s1-p.mlstatic.com/302401-MLA20317818801_062015-O.jpg",
            "secure_url": "https://mla-s1-p.mlstatic.com/302401-MLA20317818801_062015-O.jpg",
            "size": "500x281",
            "max_size": "1200x675",
            "quality": ""
        }
    ],
    "video_id": null,
    "descriptions": [],
    "accepts_mercadopago": false,
    "non_mercado_pago_payment_methods": [],
    "shipping": {
        "mode": "not_specified",
        "local_pick_up": false,
        "free_shipping": false,
        "methods": [],
        "dimensions": null,
        "tags": []
    },
    "international_delivery_mode": "none",
    "seller_address": {
        "id": 163310864,
        "comment": "",
        "address_line": "Test Address 123",
        "zip_code": "1414",
        "city": {
            "id": "",
            "name": "Palermo"
        },
        "state": {
            "id": "AR-C",
            "name": "Capital Federal"
        },
        "country": {
            "id": "AR",
            "name": "Argentina"
        },
        "latitude": "",
        "longitude": "",
        "search_location": {
            "neighborhood": {
                "id": "TUxBQlBBTDI1MTVa",
                "name": "Palermo"
            },
            "city": {
                "id": "TUxBQ0NBUGZlZG1sYQ",
                "name": "Capital Federal"
            },
            "state": {
                "id": "TUxBUENBUGw3M2E1",
                "name": "Capital Federal"
            }
        }
    },
    "seller_contact": {
        "contact": "",
        "other_info": "",
        "area_code": "",
        "phone": "",
        "area_code2": "",
        "phone2": "",
        "email": "",
        "webpage": ""
    },
    "location": {
        "address_line": "falsa 123 123",
        "zip_code": "",
        "neighborhood": {
            "id": "TUxBQkVTUDYyODRa",
            "name": "Espartillar"
        },
        "city": {
            "id": "TUxBQ0FETzQ2Nzc",
            "name": "Adolfo Alsina"
        },
        "state": {
            "id": "TUxBUFpPTmFpbnRl",
            "name": "Buenos Aires Interior"
        },
        "country": {
            "id": "AR",
            "name": "Argentina"
        },
        "latitude": -34.6635266,
        "longitude": -58.3654707,
        "open_hours": ""
    },
    "geolocation": {
        "latitude": -34.6635266,
        "longitude": -58.3654707
    },
    "coverage_areas": [],
    "attributes": [
        {
            "id": "MLA1459-HORPREF",
            "name": "Horario de contacto",
            "value_id": "",
            "value_name": "",
            "attribute_group_id": "ADICIONALES",
            "attribute_group_name": "Adicionales"
        },
        {
            "id": "MLA50541-ACCESO",
            "name": "Acceso",
            "value_id": "",
            "value_name": "",
            "attribute_group_id": "ADICIONALES",
            "attribute_group_name": "Adicionales"
        },
        {
            "id": "MLA50541-ANTIG",
            "name": "Antigüedad",
            "value_id": "",
            "value_name": "",
            "attribute_group_id": "ADICIONALES",
            "attribute_group_name": "Adicionales"
        },
        {
            "id": "MLA50541-EXPENCEM",
            "name": "Expensas ($)",
            "value_id": "",
            "value_name": "",
            "attribute_group_id": "ADICIONALES",
            "attribute_group_name": "Adicionales"
        },
        {
            "id": "MLA50541-SEGUR",
            "name": "Seguridad",
            "value_id": "",
            "value_name": "",
            "attribute_group_id": "ADICIONALES",
            "attribute_group_name": "Adicionales"
        },
        {
            "id": "MLA1459-INMUEBLE",
            "name": "Inmueble",
            "value_id": "MLA1459-INMUEBLE-COCHERA",
            "value_name": "Cochera",
            "attribute_group_id": "FIND",
            "attribute_group_name": "Ficha técnica"
        },
        {
            "id": "MLA1459-OPERACION",
            "name": "Operación",
            "value_id": "MLA1459-OPERACION-VENTA",
            "value_name": "Venta",
            "attribute_group_id": "FIND",
            "attribute_group_name": "Ficha técnica"
        },
        {
            "id": "MLA50541-MTRSTOTAL",
            "name": "Superficie total (m²)",
            "value_id": "",
            "value_name": "24",
            "attribute_group_id": "FIND",
            "attribute_group_name": "Ficha técnica"
        },
        {
            "id": "MLA50541-TIPCOB",
            "name": "Tipo de cobertura",
            "value_id": "MLA50541-TIPCOB-CUBIERTA",
            "value_name": "Cubierta",
            "attribute_group_id": "FIND",
            "attribute_group_name": "Ficha técnica"
        },
        {
            "id": "MLA50541-TIPOCOCH",
            "name": "Tipo de cochera",
            "value_id": "MLA50541-TIPOCOCH-FIJA",
            "value_name": "Fija",
            "attribute_group_id": "FIND",
            "attribute_group_name": "Ficha técnica"
        }
    ],
    "listing_source": "",
    "variations": [],
    "status": "active",
    "sub_status": [],
    "tags": [],
    "warranty": null,
    "catalog_product_id": null,
    "seller_custom_field": null,
    "parent_item_id": null,
    "differential_pricing": null,
    "deal_ids": [],
    "automatic_relist": false,
    "date_created": "2015-06-09T20:25:50.000Z",
    "last_updated": "2015-06-10T12:20:32.418Z"
}

End Package

PUT https://api.mercadolibre.com/users/186704185/classifieds_promotion_packs/1047628?access_token=$ACCESS_TOKEN
BODY
{ “status”:”{finished}” }

Example:

curl -X PUT -H "Content-Type: application/json" -d'{
> "status":"finished"
> }' https://api.mercadolibre.com/users/186704185/classifieds_promotion_packs/1047628?access_token=$ACCESS_TOKEN

FAQ

Is it possible to make an upgrade without an upgrade package?
No, is not possible.
Does hiring a package generates a charge?
No, the charge is only generated when you hire a upgrade package.
I have an upgrade packages hires, why can’t I upgrade my item?
Upgrade packages are for specific listing types and they have counted quota. Make sure you’re making an upgrade for the listing type of your hired package and that you still have available cuotas.
Is it possible to hire more than an upgrade package?
Yes, you can have multiple upgrade packages, on contrary you can’t have multiple listing packages.
Is it possible for a client to see of which package belongs an upgrade?
No, it’s not.
If I make a downgrade, does the quota becomes available?
Yes, the quotas can be re-used when you end an upgrade or an upgraded item.
How long does an upgrade lasts?
Each upgrade shares the ending date of it’s package.

Next topic: Categories & attributes.

La entrada Manage packages aparece primero en MercadoLibre Developers.

Variations

Contents:

• What is a variation?
• What are variations useful for?

What is a variation?

A variation is a resource that allow sellers to set images and stock for each variant that a given same product may have. For example, in Fashion there may be pictures of each color or size within the same item publication. In Car parts, the same happens with right side, or left side in some accessories.

What are variations useful for?

Buyers can explore within the same listing the different versions of it, and stock available for each of them.

• Reduces Q&A between buyer and seller
• Allows a better control on items stock
• Increases conversion

In addition, sellers can assign an SKU code for each variation. This will be very useful for those sellers who need to control their stock by inventory.

Variations can be standard, with pre-established ids you’ll found on our API, or custom, which you can create if there isn’t a standard one to match up.

Learn more about standard variations.

Learn more about custom variations.

La entrada Variations aparece primero en MercadoLibre Developers.

Manage your project & apps

As explained before, you need to register an application to communicate with our API. Since many developers have more than one applications, we offer you the possibility of creating a project as a way to link all the apps you own so that way you, and us, can keep track of them.
The only way to create or update an application is through our Applications Manager, but there are some really useful and important features you can work via API like creating and managing your project, get all your apps, link them to your project, know how many apps a user has authorized – as long as you have a valid access_token for that user -, and revoke authorization from user’s you don’t want to use your app or be notified anymore via API.

Related articles:

Create and manage a project.

Manage your applications.

La entrada Manage your project & apps aparece primero en MercadoLibre Developers.

Overview

Our platform allows you to use our resources by calling our API through HTTP methods. Public resources can be accessed anonymously, such as sites, and categories, while private resources and some other features require authentication, like listing an item, giving feedback or being able to see the user contact information.

As we have described above, the first step to work with our resources is to create an application. This is the way to get the Client_id and Secret_key for your authentication. If you have not registered your application yet, follow our guide to learn how to do it.

Contents:

• Overview
• Authentication flow
• Use our SDKs
• Considerations
• Error Codes Reference

Authentication flow

Mercadolibre supports two Authorization types: Client-side and Server-side.

Client-side

The Client-side flow helps you get an access token by sending your application’s Client ID and Secret key. In this flow, when the token expires, the user will be required to get authenticated again to continue working with our private resources on his/her behalf.
Client side authentication flow

Server-side

The Server-side flow generates a secret code that you will later exchange for an access token. For this exchange you will need your application’s Client ID and Secret key, which will go on the server side to preserve key integrity. This flow also helps you get a refresh token to grant user permissions.
Server side authentication flow

Use our SDKs

We already provide SDKs for
Java
.NET
PHP
Javascript (client-side)
Python
Ruby
All of them implement OAuth flows. We encourage to use our SDKs and have it simple with authentication.
Using our saves you from coding the whole OAuth protocol from scratch and you benefit from using code that has been tested by the community. [3] [4] Go to our Tools section to know and download any of our SDKs.

Considerations

Token validity and expiration

When you get an access token, it will be valid immediately and usable to make requests to the API for a limited period of 6 hours. After that period has elapsed, the access token is considered to have expired and the user will need to be authenticated again in order for your app to obtain a fresh access token. If you’re coding the authentication through server side, you can avoid this scenario by setting offline_access scopes and getting a refresh token. We’ll go further on this on the Server side authentication guide.
There are also events which may cause an access token to become invalid before the expiration time. Such events include the user changing his password, an application refreshing its App Secret and, of course, the user revoking permissions to your app. Dealing with access token expiration times, and handling the case when an access token becomes invalid before its expected expiration time is essential for building a robust application so it doesn’t takes you by surprise.
As we stated before, if you’re configuration is right and the user has provided you with offline access, then by using the server-side authentication flow you will have a refresh token who will automatically refresh user permissions. Note that a refresh token can be used only once.

Error Codes Reference

Next topic: Start testing.

La entrada Authenticate aparece primero en MercadoLibre Developers.

Application Manager

To create an App, you must use the Application Manager. You need to choose your country to create a new one.

Application Data

There are three groups of information in this form: Basic Application Info, Authentication & Security and Notification Settings.

Basic Application Info

• ID: This is your client_id. It must be used to retrieve an access token.
• Secret Key: This is used to retrieve an access token, too. Don’t share this secret with anyone.
• Name: Name of your application. It must be unique.
• Short Name: Name that Meli uses to generate your application’s URL.
• Description: This description (up to 150 characters) will be shown when the application requests an authorization.

Authentication & Security

• Callback URL: Redirect URI. URL to return users to your app after they grant access.
• Domains: Authorized Javascript Origins. Comma-separated list of fully-qualified domain name of all pages that will use the client-side authentication. Only needed if using Javascript API. Don’t include protocol, port or “localhost”.

Both of these attributes are further explained in the Authentication and authorization guide.

• Scopes:

Read: Allows to use API GET HTTP methods.
Write: Allows to use API PUT, POST and DELETE HTTP methods.
Offline Access: Allows to make request server side and refresh token.

Some comments about scopes

There are several types of applications. However, we will divide them in three groups to explain the required scopes.

• Read-Only apps: An application that allows an anonymous or authenticated user to get customized information from MELI. In this case an anonymous user might search for items, look at descriptions, etc, and an authenticated user may look at personal information. If no modification is made to the data on MELI (no user information update, no item listing, no item buying), all you need is a read scope. Note that any attempt to modify data through MELI APIs would get an error.
• Read/Write online apps: This kind of app allows an anonymous user to carry out certain read-only operations on MELI, as well as an authenticated user to modify data, list new items (sell), post orders (buy), and so on. In this case the application requires a write scope so that the user can grant write permissions for the app to act on his behalf. The application will be able to modify data on behalf of the user while the access token remains valid. Once it has expired, the user needs to renew the token to regain access.
• Read/Write offline apps: If your app needs to act on behalf of the user even when the user is offline, it will require offline-access permission by the user. By requesting this scope, upon acceptance by the user, the app will have both the access token to act on behalf of the user and a refresh token to get a new valid access token once the previous one has expired.

Notification Settings

• Notifications callback URL: Configure the public URL of your domain where you want to receive the notifications on the different topics.
• Topics: List of topics you want to subscribe to. There are four possible topics: orders, items, questions, payments.

La entrada Application Manager aparece primero en MercadoLibre Developers.