Documentação do Mercado Livre
Confira todas as informações necessárias sobre as APIs Mercado Livre.
Documentação do
User Products
In the previous seller listing model, it was possible to create variants that grouped different options of the same product, for example, a shirt in various colors or sizes. These variants allow offering related products within the same listing. However, this model has several limitations:
- Different prices per variant cannot be set.
- Different delivery options per variant cannot be configured.
- Promotions or specific payment installments cannot be applied to one variant and not to others.
Our goal is to adapt a new model that addresses these issues and unifies the experience by decoupling sales conditions to allow differences for each variant and thus scale listings.
From this, the idea to create "User Products" arises, where the initiatives to work on will include:
This approach will offer greater flexibility in configuring listings, allowing specific prices and stock management for each variant, thereby improving the buyer's experience and sales operation efficiency.
Important Concepts
To understand the User Product (UP) model, it is essential to consider the following concepts:
- Item:
- It is the representation of a product listing that a buyer views on the platform.
- It contains information related to sales conditions (price, installments, etc.).
- Each item has a unique identifier (item_id) associated with it.
- User Product (UP):
- Represents a physical product that a seller owns and offers through the platform.
- A UP describes the product as specifically as possible (at the variation level).
- Each UP has a unique identifier (user_product_id) automatically assigned by the system.
- It can be associated with one or more items, e.g., a red iPhone (the UP) can be in item1 with 3 installments and in item2 with a different price.
- Each UP can be viewed on Mercado Libre through a User Products Page (UPP).
- Family:
- It is auto-generated based on product information.
- Each UP belongs to a family (family_id), and each family groups several UPs.
- Items belonging to the same family will have the same family_name and will be represented as different pickers on the UPP. Pickers are the options offered to a buyer to purchase a product, including different sales conditions and attributes, e.g., color.
- Modification of the items via a PUT to the /items resource referring to User Product characteristics will be asynchronously replicated by Mercado Libre across all items associated with the same User Product. The fields of the item that are synchronized are:
- For fashion items, the size guide will be shared by the variation (User products) and its sales conditions (items).
Below, to exemplify the aforementioned concepts, we present a comparison between a listing in the previous model vs. the endgame with User Products.
Based on the new model, we present an example for a family and its composition in both UP and its items and sales conditions:
FAQs
Price per variation
What type of integrators need to adapt their developments to this initiative?
The Price per Variation and UPtin initiative applies to all integrators who publish, synchronize, or even display a list of publications for sellers. The Distributed and Multi-Origin Stock initiative applies to all sellers who publish, synchronize, or take information on orders and shipments.
What impact will I have if I do not implement the initiative?
Once sellers are enabled to start listing under the new User Products model, if the integrator is not adapted to the changes, it will not be possible to publish with the previous model (informing title and variations array).
For integrators who synchronize items, update stock, price, or safeguard information about items in their databases, they must consider the new stock modification structure (at the UP level) and also receive notifications of changes due to item migration to maintain data consistency in their databases.
Finally, for integrators who list publications, they should consider updating their front to adapt to the value proposition that Mercado Libre will provide with this initiative. That is, grouping items by family, by user product, and also (in cases of publication or modification) allowing different sales conditions for each variation.
How can I identify items that are already under the new UP model?
Items under the new User Products model can be identified through 2 things: with the tag "user_product_listing" or identified in the item with the attribute family_name different from null.
How can I test the User Products flow?
If it is necessary to test User Products flows, we request you do so through this form. Every 15 days, these new users will be activated. Remember that the testing scenario is only available for Argentina (you must create test accounts on this site).
Will all sellers be enabled to work with the new UP model?
In the endgame, all sellers will be enabled to publish under the new User Products model. Starting in October, sellers will be progressively enabled until reaching 100% of sellers.
How can I identify sellers that are already under the new UP model?
Through the tag "user_product_seller."
Will all items have user_product_id, family_id, and family_name?
- Prior to activating the "user_product_seller" tag: Live Listing will have a user_product_id and will not have a family_name. The relationship of user_product_id and item_id will be 1:1.
- After activating the "user_product_seller" tag: a unification process will be carried out for single-variant and non-variant items, to group items that should belong to the same user_product_id, allowing a user_product_id to be associated with one or more items. After unification, items will have the family_name attribute.
- When the seller decides to migrate a multi-variant item to the new model (UPtin). In this case, the new items generated will be associated with the same user_product_id and will also have family_name.
Until when can sellers publish in the old model?
Until the activation of the "user_product_seller" tag. After activation, new items must be created under the new model.
Is there any endpoint to list all the families of a seller?
No, there isn't currently one.
How can I get all items that belong to the same family?
By making the following requests:
- GET to /items to obtain the user_product_id
- GET to /user-products/$USER_PRODUCT_ID to obtain the family_id
- GET to /sites/$SITE_ID/user-products-families/$FAMILY_ID to obtain all User Products associated with a family
What size should the family_name entered by the seller during publishing be?
The family_name that can be entered should be less than or equal to the domain's "max_title_length".
Is it possible to update the family_name?
Yes, only when the item has no sales. Note that if an item is associated with a UP with several items, the family_name can be updated and will be synchronized across all items of the UP.
When altering the sales condition of a family, will its family_name also change?
It should not be altered, as the family_name is not related to sales conditions (e.g., price, listing type).
Will the family_name be managed by the integrator, correct? That is, will Meli not change this field value?
Yes, it is the responsibility of the seller/integrator. Only in the case of UPtin, Mercado Libre will create the family_name for the item.
Can I publish with custom type attributes in User products?
Yes, you can publish by adding the attribute, for example:
{
"attributes": [
{
"name": "my-custom-attribute-name",
"value_name":"my-custom-attribute-value"
}
]
}
Will the /categories resource continue to function the same so that we can consult attributes and their tags? For example, allow_variations and variation_attribute.
Yes, additionally, you can use these attributes as a reference (not a rule) to understand which attribute will be taken for the completion of the family_name of the listing.
Will it be possible to send the variations array after activating a seller to the new UP model?
No, the array cannot be sent because each variation will be a different user product.
What attributes can be synchronized at the UP level?
Name (item's title)
Family Name (item's family_name)
Site Id (item's site_id)
User Id (item's seller_id)
Domain Id (item's domain_id)
Catalog Product Id (item's catalog_product_id)
Family Id (user_product's own)
Date Created (user_product's own)
Last Updated (user_product's own)
Attributes (item's attributes + attributes_combination in case the user product is generated from an item variation)
Pictures (item's pictures)
Thumbnail (item's thumbnail)
Tags (user_product's own)
UPtin
Will items in the previous model migrate automatically to the new model?
No, items can only be migrated at the seller's request, either from Mercado Libre's front end or from their integrator.
When a seller migrates a listing with 3 variants from the current model to the User Products model, how will the creation notification be sent?
You will receive a notification for each item created via the item topic. Moreover, the old item will have a closed status, and each new listing created will have the tag "variations_migration_uptin".
What will happen to the sales information of old listings?
The sales information will remain the same; they will not lose the history.
Distributed and Multi-origin Stock
Will it be possible to send stock for all sales conditions at once?
Yes, you must use the distributed stock resource, which allows you to send stock directly to UP, which will synchronize with all sales conditions.
Can the same listing be in more than one warehouse?
Yes, it can be in more than one warehouse. The new POST allows you to specify the stock the listing has in each warehouse or store. The stock will be at the UP level, and the UP may have different stock per store, meaning the listings/sales conditions associated with that UP will have the same stock.
Will it be possible to distribute stock for listings in the old model?
Yes, once a listing has a user_product_id, it is possible to manage the stock through the user product. Additionally, sellers with the "warehouse_management" tag can distribute stock by store.
Help Us Improve
We recommend complementing this reading with the documentation on our Devsite, as well as the following documentation. However, if you have more questions about User Products, you can submit your questions through this form to help us complement this document.
Next: Price per variation.