Documentación Mercado Libre
Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.
Documentación
Price per variation
The price per variation initiative aims to provide the seller with the ability to offer different selling conditions for variations of the same product, allowing them to implement their sales strategies in a more flexible and scalable manner.
The first meaningful change is in the array of variations in /items, which will no longer be sent in the POST and will be empty in the response of the new items. This adjustment modifies the listing logic, opening up new possibilities and strategic approaches.
Initial concepts
Before comparing and explaining the changes, it’s important to understand some concepts:
1 - Item it is the listing that the buyer views and contains information about the selling condition, price and total stock. It is represented by the item_id field and is generated when the integrator performs a POST on the /items resource.
2 - User Product: it is the logical entity that represents the physical item. The items are associated to their user product, represented by the user_product_id field, automatically generated by MELI. A user product can have more than one associated item. In the future it will be possible to work with multiple stocks.
3 - Familia: it is the variation grouping, assigned by MELI according to the attributes of the listed items. The items that represent variations of the same product will receive the family_id field with the same value in their respective user product.
Comparative of listing paths
Now
1 - The listing of variations is done through the variations array and the integrator/seller specifies only the stock and some attributes of the variations.
2 - The price is set at the root of the listing and it is the same for all variations.
3 - The grouping of the variations is done according to the item, and each variation of this item has its own variation_id.
Example:
curl --location 'https://api.mercadolibre.com/items' \
--header 'Content-Type: application/json' \
--header 'Authorization: $ACCESS_TOKEN' \
--data '{
"title": "Teste - Não ofertar",
"category_id": "MLB275575",
"price": 100,
"currency_id": "BRL",
"available_quantity": 10,
"buying_mode": "buy_it_now",
"listing_type_id": "gold_special",
"condition": "new",
"video_id": "YOUTUBE_ID_HERE",
"sale_terms":[
{
"id": "WARRANTY_TYPE",
"name": "Tipo de garantía",
"value_id": "2230280",
"value_name": "Garantía del vendedor"
},
{
"id": "WARRANTY_TIME",
"name": "Tiempo de garantía",
"value_id": null,
"value_name": "90 días"
}
],
"variations": [
{
"attribute_combinations": [
{
"id": "COLOR",
"name": "Cor",
"value_id": "52049",
"value_name": "Preto",
"value_struct": null,
"values": [
{
"id": "52049",
"name": "Preto",
"struct": null,
"source": 6808261514773724
}
],
"source": 6808261514773724,
"value_type": "string"
},
{
"id": "SIZE",
"name": "Tamanho",
"value_id": "3189128",
"value_name": "33",
"value_struct": null,
"values": [
{
"id": "3189128",
"name": "33",
"struct": null,
"source": 6808261514773724
}
],
"source": 6808261514773724,
"value_type": "string"
}
],
"picture_ids": [
"http://http2.mlstatic.com/D_690796-MLB70039699580_062023-O.jpg"
],
"price": 100,
"available_quantity": 1
},
{
"attribute_combinations": [
{
"id": "COLOR",
"name": "Cor",
"value_id": "52005",
"value_name": "Marrom",
"value_struct": null,
"values": [
{
"id": "52005",
"name": "Marrom",
"struct": null,
"source": 6808261514773724
}
],
"source": 6808261514773724,
"value_type": "string"
},
{
"id": "SIZE",
"name": "Tamanho",
"value_id": "3189128",
"value_name": "33",
"value_struct": null,
"values": [
{
"id": "3189128",
"name": "33",
"struct": null,
"source": 6808261514773724
}
],
"source": 6808261514773724,
"value_type": "string"
}
],
"picture_ids": [
"https://http2.mlstatic.com/D_769119-MLB70059370475_062023-O.jpg"
],
"price": 100,
"available_quantity": 1
}
],
"shipping": {
"mode": "me2",
"methods": [],
"tags": [],
"dimensions": null,
"local_pick_up": false,
"free_shipping": true,
"logistic_type": "drop_off",
"store_pick_up": false
},
"attributes": [
{
"id": "BRAND",
"name": "Marca",
"value_id": null,
"value_name": "Teste",
"value_struct": null,
"values": [
{
"id": null,
"name": "Teste",
"struct": null,
"source": 6808261514773724
}
],
"attribute_group_id": "OTHERS",
"attribute_group_name": "Outros",
"source": 6808261514773724,
"value_type": "string"
},
{
"id": "GENDER",
"name": "Gênero",
"value_id": "339666",
"value_name": "Masculino",
"value_struct": null,
"values": [
{
"id": "339666",
"name": "Masculino",
"struct": null,
"source": 6808261514773724
}
],
"attribute_group_id": "OTHERS",
"attribute_group_name": "Outros",
"source": 6808261514773724,
"value_type": "list"
},
{
"id": "ITEM_CONDITION",
"name": "Condição do item",
"value_id": "2230284",
"value_name": "Novo",
"value_struct": null,
"values": [
{
"id": "2230284",
"name": "Novo",
"struct": null,
"source": 6808261514773724
}
],
"attribute_group_id": "OTHERS",
"attribute_group_name": "Outros",
"source": 6808261514773724,
"value_type": "list"
},
{
"id": "MODEL",
"name": "Modelo",
"value_id": null,
"value_name": "Teste",
"value_struct": null,
"values": [
{
"id": null,
"name": "Teste",
"struct": null,
"source": 6808261514773724
}
],
"attribute_group_id": "OTHERS",
"attribute_group_name": "Outros",
"source": 6808261514773724,
"value_type": "string"
}
]
}
'After
1 - The array of variations should not be sent and each variation becomes an independent item, which implies performing a POST to /items for each variation;
Examples:
Variation 1
curl --location 'https://api.mercadolibre.com/items' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--data '
{
"title": "Teste - Não ofertar",
"category_id": "MLB275575",
"price": 100,
"currency_id": "BRL",
"available_quantity": 10,
"buying_mode": "buy_it_now",
"listing_type_id": "gold_special",
"condition": "new",
"pictures":[
{
"source":"http://mla-s2-p.mlstatic.com/968521-MLA20805195516_072016-O.jpg"
}
],
"sale_terms":[
{
"id": "WARRANTY_TYPE",
"name": "Tipo de garantía",
"value_id": "2230280",
"value_name": "Garantía del vendedor"
},
{
"id": "WARRANTY_TIME",
"name": "Tiempo de garantía",
"value_id": null,
"value_name": "90 días"
}
],
"shipping": {
"mode": "me2",
"methods": [],
"tags": [],
"dimensions": null,
"local_pick_up": false,
"free_shipping": true,
"logistic_type": "drop_off",
"store_pick_up": false
},
"attributes": [
{
"id": "BRAND",
"name": "Marca",
"value_id": null,
"value_name": "Teste",
"value_struct": null,
"values": [
{
"id": null,
"name": "Teste",
"struct": null,
"source": 6808261514773724
}
],
"attribute_group_id": "OTHERS",
"attribute_group_name": "Outros",
"source": 6808261514773724,
"value_type": "string"
},
{
"id": "GENDER",
"name": "Gênero",
"value_id": "339666",
"value_name": "Masculino",
"value_struct": null,
"values": [
{
"id": "339666",
"name": "Masculino",
"struct": null,
"source": 6808261514773724
}
],
"attribute_group_id": "OTHERS",
"attribute_group_name": "Outros",
"source": 6808261514773724,
"value_type": "list"
},
{
"id": "ITEM_CONDITION",
"name": "Condição do item",
"value_id": "2230284",
"value_name": "Novo",
"value_struct": null,
"values": [
{
"id": "2230284",
"name": "Novo",
"struct": null,
"source": 6808261514773724
}
],
"attribute_group_id": "OTHERS",
"attribute_group_name": "Outros",
"source": 6808261514773724,
"value_type": "list"
},
{
"id": "MODEL",
"name": "Modelo",
"value_id": null,
"value_name": "Teste",
"value_struct": null,
"values": [
{
"id": null,
"name": "Teste",
"struct": null,
"source": 6808261514773724
}
],
"attribute_group_id": "OTHERS",
"attribute_group_name": "Outros",
"source": 6808261514773724,
"value_type": "string"
},
{
"id": "COLOR",
"name": "Cor",
"value_id": "52049",
"value_name": "Preto",
"value_struct": null,
"values": [
{
"id": "52049",
"name": "Preto",
"struct": null,
"source": 6808261514773724
}
],
"source": 6808261514773724,
"value_type": "string"
},
{
"id": "SIZE",
"name": "Tamanho",
"value_id": "3189128",
"value_name": "33",
"value_struct": null,
"values": [
{
"id": "3189128",
"name": "33",
"struct": null,
"source": 6808261514773724
}
],
"source": 6808261514773724,
"value_type": "string"
}
]
}'Variation 2
curl --location 'https://api.mercadolibre.com/items' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--data '{
"title": "Teste - Não ofertar",
"category_id": "MLB275575",
"price": 100,
"currency_id": "BRL",
"available_quantity": 10,
"buying_mode": "buy_it_now",
"listing_type_id": "gold_special",
"condition": "new",
"pictures":[
{
"source":"https://http2.mlstatic.com/D_769119-MLB70059370475_062023-O.jpg"
}
],
"sale_terms":[
{
"id": "WARRANTY_TYPE",
"name": "Tipo de garantía",
"value_id": "2230280",
"value_name": "Garantía del vendedor"
},
{
"id": "WARRANTY_TIME",
"name": "Tiempo de garantía",
"value_id": null,
"value_name": "90 días"
}
],
"shipping": {
"mode": "me2",
"methods": [],
"tags": [],
"dimensions": null,
"local_pick_up": false,
"free_shipping": true,
"logistic_type": "drop_off",
"store_pick_up": false
},
"attributes": [
{
"id": "BRAND",
"name": "Marca",
"value_id": null,
"value_name": "Teste",
"value_struct": null,
"values": [
{
"id": null,
"name": "Teste",
"struct": null,
"source": 6808261514773724
}
],
"attribute_group_id": "OTHERS",
"attribute_group_name": "Outros",
"source": 6808261514773724,
"value_type": "string"
},
{
"id": "GENDER",
"name": "Gênero",
"value_id": "339666",
"value_name": "Masculino",
"value_struct": null,
"values": [
{
"id": "339666",
"name": "Masculino",
"struct": null,
"source": 6808261514773724
}
],
"attribute_group_id": "OTHERS",
"attribute_group_name": "Outros",
"source": 6808261514773724,
"value_type": "list"
},
{
"id": "ITEM_CONDITION",
"name": "Condição do item",
"value_id": "2230284",
"value_name": "Novo",
"value_struct": null,
"values": [
{
"id": "2230284",
"name": "Novo",
"struct": null,
"source": 6808261514773724
}
],
"attribute_group_id": "OTHERS",
"attribute_group_name": "Outros",
"source": 6808261514773724,
"value_type": "list"
},
{
"id": "MODEL",
"name": "Modelo",
"value_id": null,
"value_name": "Teste",
"value_struct": null,
"values": [
{
"id": null,
"name": "Teste",
"struct": null,
"source": 6808261514773724
}
],
"attribute_group_id": "OTHERS",
"attribute_group_name": "Outros",
"source": 6808261514773724,
"value_type": "string"
},
{
"id": "COLOR",
"name": "Cor",
"value_id": "52005",
"value_name": "Marrom",
"value_struct": null,
"values": [
{
"id": "52005",
"name": "Marrom",
"struct": null,
"source": 6808261514773724
}
],
"source": 6808261514773724,
"value_type": "string"
},
{
"id": "SIZE",
"name": "Tamanho",
"value_id": "3189128",
"value_name": "33",
"value_struct": null,
"values": [
{
"id": "3189128",
"name": "33",
"struct": null,
"source": 6808261514773724
}
],
"source": 6808261514773724,
"value_type": "string"
}
]
}
'2 - The price and commercial conditions can be determined according to each item of the family. It is important to note that each variation now corresponds to one item. For this, we recommend checking the Product's price section.
3 - Items are grouped into families according to similar attributes such as brand, model etc. These groups receive the same value in the family_id field as the grouping identifier in their user product. Please note that for Mercado Libre to consider an item as a variation, the title must be the same as in the other variations.
How to identify the families
Following the information provided in the previous topics, where we explained the new listing flow and the grouping of the new items to represent the variations according to the concept of families, we will now present how to identify the user products of a family and how to access the list of items that they represent.
There are two ways to identify the items that belong to a family.
Option 1
- The application must be subscribed to the new family notifications topic.
- To identify the user_product_id of a family, it is necessary to make the following request:
- To obtain the item_ids related to a user product you can make the following request:
When we create or change something in a family, a notification is generated indicating the family_id of the action.
{
"msg": {
“family_id”:4719173094241697799',
“site_id”:“MLA”,
“user_id”:1234
}
},This identifier allows us to consult which user products are associated to a family and thus identify their listings.
Example:
curl --location 'https://api.mercadolibre.com/sites/$SITE_ID/user-products-families/$FAMILY_ID' \
--header 'Authorization: Bearer $ACCESS_TOKEN'Request:
curl --location 'https://api.mercadolibre.com/sites/MLB/user-products-families/4719173094241697799' \
--header 'Authorization: Bearer $ACCESS_TOKEN'Response:
{
"user_products_ids": [
"MLBU205541999",
"MLBU206642488"
]
}Example
curl --location 'https://api.mercadolibre.com/users/$SELLER_ID/items/search?user_product_id=$USER_PRODUCT_ID' \
--header 'Authorization: Bearer $ACCESS_TOKEN'Request:
curl --location 'https://api.mercadolibre.com/users/1403810308/items/search?user_product_id=MLBU206642488' \
--header 'Authorization: Bearer $ACCESS_TOKEN'Response:
{
"seller_id": "1403810308",
"results": [
"MLB2012058964",
"MLB2012058757"
],
"paging": {
"limit": 50,
"offset": 0,
"total": 2
},
"query": null,
"orders": [
{
"id": "stop_time_asc",
"name": "Order by stop time ascending"
}
],
"available_orders": [...]
}Option 2
Every new item will be associated with a user product.
- It is possible to obtain this information in the POST response to /items or after listing by querying the item.
- With the user_product_id you must query the /user-products resource to identify the attributed family_id.
- In the response you will find the family_id field. You can use the information in the /user-products-families resource to identify the other user products of this family, as presented in step 2 of option 1.
Request:
curl --location 'https://api.mercadolibre.com/user-products/$USER_PRODUCT_ID' \
--header 'Authorization: Bearer $ACCESS_TOCKEN'Example:
curl --location 'https://api.mercadolibre.com/user-products/$USER_PRODUCT_ID' \
--header 'Authorization: Bearer $MLBU22012'Response:
{
"id": "MLBU22012",
"name": "iPhone 14 Pro Max",
"user_id": 1295303699,
"domain_id": "MLB-CELLPHONES",
"attributes": [
{
"id": "BRAND",
"name": "Marca",
"values": [
{
"id": "123",
"name": "Apple",
"struct": null
}
]
},
{
"id": "MODEL",
"name": "Modelo",
"values": [
{
"id": "123",
"name": "iPhone 14 Pro Max",
"struct": null
}
]
},
{
"id": "INTERNAL_MEMORY",
"name": "Internal Memory",
"values": [
{
"id": "123",
"name": "10 GB",
"struct": {
"number": 10.0,
"unit": "GB"
}
}
]
},
{
"id": "ITEM_CONDITION",
"name": "Condición del ítem",
"values": [
{
"id": "2230284",
"name": "Nuevo",
"struct": null
}
]
}
],
"pictures": [
{
"id": "856054-MLB49741387485_042022",
"secure_url": "https://http2.mlstatic.com/D_856054-MLA49741387485_042022-O.jpg"
},
{
"id": "793512-MLB51622915557_092022",
"secure_url": "https://http2.mlstatic.com/D_793512-MLA51622915557_092022-O.jpg"
}
],
"thumbnail": {
"id": "856054-MLA49741387485_042022",
"secure_url": "https://http2.mlstatic.com/D_856054-MLA49741387485_042022-O.jpg"
},
"catalog_product_id": "MLB19615318",
"family_id": 18446744000000000615,
"tags": [
"test"
],
"date_created": "2023-02-13T02:46:20.528+0000",
"last_updated": "2023-02-13T02:46:20.528+0000"
}Alterations in the items
To make alterations to the items, you must continue to execute PUT to the /items resource.
Important aspects
The item can change families:
Alterations to the attributes of items in a family may cause those items to leave the family, for example, by changing brand, model, etc. Attributes that are similar and relate the item to the family can be modified, but both the integrator and the seller must keep in mind that these items will leave the current family.
The user_product_id of the item can change:
There are very specific cases where this can happen. Changes to the item that cause it to have information related to another user product can cause it to be linked to this other user product.
Flows that are not impacted by this development
Fashion
The changes in the listing process do not affect the functioning of the fashion resources for the time being. However, it is crucial to link the Size Chart to each item of the same family. For more information, please check the "Manage size charts" section.
Promotions
The flow of promotions will not be affected by the new operation. You will be able to follow the documentation taking into account that each item of the same family will behave independently with its own promotions.
Orders and shipments
There are no impacts requiring development in this area. We will continue to send the item_id of each item sold, which may or may not be a variation. However, note that each variation will have its own item_id in addition to the user_product_id.