User Products

Conceptual framework

The User Products model is based on three main concepts:

• 1. Product (UP Siteless): Your product with all its attributes, images, and descriptions. This is what you create and manage.
• 2. Sales conditions (Items): Price, listing type, and shipping options. You can customize them for each destination marketplace.
• 3. Stock: Inventory management is handled at the product level through fulfillment logistics.

Transitional Model and Backward Compatibility

The current User Products model coexists with historical publishing structures for backward compatibility reasons. Although conceptually the product should be directly related to site-specific offers, intermediate entities and local representations are currently necessary to maintain compatibility with existing items, languages, site-specific sellers, and legacy workflows. These entities are not part of the model's target design and should not be considered as stable contracts for future integrations.

General description

The User Products model represents a new way to manage your listings in Latin American marketplaces. Instead of creating and managing individual items for each country, you define a single UP Siteless containing all product information, and Mercado Libre automatically creates the corresponding items in each destination marketplace.

• UP Siteless: Represents the product itself, without being tied to a specific marketplace. It centralizes attributes, images, and stock, and allows for defining multiple independent sales conditions per site. It doesn't model a hierarchy, but rather a single point of product definition decoupled from its offers.
• Stock Locations: Inventory management entities associated with the UP Siteless.
• Items: Sales conditions (price, listing type, shipping) that are automatically created in each marketplace.

Figure 1: Architecture of User Products - Each site gets its own item with customizable sales conditions.

How it works

Publishing a product

When you publish a product, you create a UP Siteless with all the product information and specify which marketplaces you want to sell in. Mercado Libre automatically generates the corresponding items in each destination site.

You send:

• Product information (attributes, images, family name)
• Destination marketplaces (sites_to_sell)
• Sales conditions per site (price, listing type)

Modifying a product

To modify your product, you work with the UP Siteless ID and/or the item IDs depending on what you want to change:

CBT UP Siteless structure

• The seller_id for Siteless UPs will be the merchant_id.
• The seller_id for items in each site will be different (each site has its unique sellers).
• Items can no longer be created traditionally under this new scheme.
• Stock/inventory is only associated with the UP Siteless.
• All items in the tree will have the same inventory_id.

Site-specific attributes

While most product information is defined at the UP Siteless level and shared across all marketplaces, certain attributes can be customized for each destination site:

Differences with traditional variations

Model changes

Titles and Family Name

• New required field: family_name - a generic description of your product (e.g., "Apple iPhone 256GB").
• Mercado Libre may generate optimized titles for each marketplace based on family_name and product attributes.

Images

Images must be sent only by id, as the source field is no longer supported. Check working with pictures section out for more details on how to upload pictures.

{
  "pictures": [
    {
      "id": "701198-CBT79185512197_092024"
    }
  ]
}

Variations

Do not send variations in the body. If it contains values, the API will return 400 Bad Request. Each variation becomes a separate User Product with its own sales conditions.

Item Condition

Item condition is defined by the ITEM_CONDITION attribute. Currently, only items with "New" status are allowed:

{
  "id": "ITEM_CONDITION",
  "values": [
    {
      "id": "2230284",
      "name": "New"
    }
  ]
}

Identifying sellers and items from User Products

Verify if a seller uses User Products

Sellers enabled for User Products have the user_product_seller tag:

curl -X GET 'https://api.mercadolibre.com/users/{user_id}' \
  --header 'Authorization: Bearer $TOKEN'

Response Example:

{
  "user_type": "normal",
  "tags": [
    "user_product_seller",
    "normal"
  ]
}

Verify if an item uses User Products

Items under the User Product model have family_name different from null and the user_product_listing tag.

User Products Model Evaluation

The evolution of the User Products model aims to simplify the current architecture by gradually eliminating dependencies on CBT structures and the traditional item model. In the target state, the product will be defined only once and directly associated with marketplace sales conditions, without intermediate entities. Integrations should be designed with this objective in mind to minimize future changes.

FAQ

How can I identify sellers under the new User Product model?
Through the user_product_seller tag in the /users API response.

How can I identify items under the User Product model?
By validating if the item has family_name different from null and if it has the user_product_listing tag.

Are catalog items tagged with user_product_listing = true?
No.

Can I still send the variations array?
No, each variation becomes a separate User Product. Check the Price per Variation documentation.

Is there an endpoint to list all of a seller's families?
No, there is currently no such endpoint.

How can I get all items belonging to the same family?

• GET /items/{item_id} to get the user_product_id
• GET /user-products/{user_product_id} to get the family_id
• GET /sites/{site_id}/user-products-families/{family_id} to get all UPs in that family

What if I only want to sell in some marketplaces?
Specify only the marketplaces you want in the sites_to_sell array. You can add more marketplaces later by updating your UP Siteless.

Can the family_name be updated?
Yes, only when none of the sales conditions associated with the User Product have sales.