Price by Variation

The price by variation initiative aims to provide sellers with the ability to offer different sales conditions for variations of the same product, allowing them to apply their sales strategies more flexibly and scalably.

Publish an Item

We will have 2 types of users: those who can publish with the previous model and those who can start publishing with the new User Products model (both models will coexist). These sellers can be identified through the tag "user_product_seller" in the users API.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/{User_id}

Response:

{
    "id": 206946886,
    "nickname": "TETE6838590",
    "registration_date": "2016-02-24T15:18:42.000-04:00",
    "first_name": "Pedro",
    "last_name": "Picapiedras",
    "tags": [
        "normal",
        "test_user",
        "user_info_verified",
        "user_product_seller"
    ]
}

Considerations

Here are some considerations you should keep in mind when publishing an item under the new UP model.

The new field family_name is a required field that the seller must complete. This field will be a generic description of the item that covers the different User Products of the same family. It is recommended to use generic and representative text for the items, for example:

Family name: "Apple iPhone 256GB"
Item_1: "Apple iPhone 256GB Red"
Item_2: "Apple iPhone 256GB Blue"

Additionally, the title field should not be sent by the seller as Mercado Libre will complete it automatically with the specific item or product information. This is done to standardize items more, using the domain, attributes, family_name, among others, as a base.

As an example, we will be publishing two items of the same family that share: family_name, domain, condition, seller_id, and GTIN.

First item, in blue:

curl -X POST https://api.mercadolibre.com/items -H 'Content-Type: application/json' -H 'Authorization: Bearer $ACCESS_TOKEN' -d '{
   "family_name": "Apple iPhone 256GB",
   "category_id": "MLM1055",
   "price": 17616,
   "currency_id": "MXN",
   "available_quantity": 6,
   "sale_terms": [
       {
           "id": "WARRANTY_TIME",
           "value_name": "3 months"
       },
       {
           "id": "WARRANTY_TYPE",
           "value_name": "Seller's warranty"
       }
   ],
   "buying_mode": "buy_it_now",
   "listing_type_id": "gold_special",
   "condition": "new",
   "pictures": [ … ],
   "attributes": [
       {
           "id": "BRAND",
           "value_name": "Apple"
       },
       {
           "id": "COLOR",
           "value_name": "Blue"
       },
       {
           "id": "GTIN",
           "value_name": "195949034862"
       },
       {
           "id": "RAM",
           "value_name": "6 GB"
       },
       {
           "id": "IS_DUAL_SIM",
           "value_name": "Yes"
       },
       {
           "id": "MODEL",
           "value_name": "iPhone 15"
       },
       {
           "id": "CARRIER",
           "value_name": "Unlocked"
       }
   ]
}'

Second item, in red:

curl -X POST https://api.mercadolibre.com/items -H 'Content-Type: application/json' -H 'Authorization: Bearer $ACCESS_TOKEN' -d '{
   "family_name": "Apple iPhone 256GB",
   "category_id": "MLM1055",
   "price": 19800,
   "currency_id": "MXN",
   "available_quantity": 8,
   "sale_terms": [
       {
           "id": "WARRANTY_TIME",
           "value_name": "3 months"
       },
       {
           "id": "WARRANTY_TYPE",
           "value_name": "Seller's warranty"
       }
   ],
   "buying_mode": "buy_it_now",
   "listing_type_id": "gold_special",
   "condition": "new",
   "pictures": [ … ],
   "attributes": [
       {
           "id": "BRAND",
           "value_name": "Apple"
       },
       {
           "id": "COLOR",
           "value_name": "Red"
       },
       {
           "id": "GTIN",
           "value_name": "195949034862"
       },
       {
           "id": "RAM",
           "value_name": "6 GB"
       },
       {
           "id": "IS_DUAL_SIM",
           "value_name": "Yes"
       },
       {
           "id": "MODEL",
           "value_name": "iPhone 15"
       },
       {
           "id": "CARRIER",
           "value_name": "Unlocked"
       }
   ]
}'

Example of a response for creating an item:

{
   "id": "MLM2061397137",
   "site_id": "MLM",
   "title": "Apple iPhone 256GB Red",
   "family_name": "Apple iPhone 256GB",
   "seller_id": 1008002397,
   "category_id": "MLM1055",
   "user_product_id": "MLMU367467963",
   "official_store_id": null,
   "price": 19800,
   "base_price": 19800,
   "original_price": null,
   "inventory_id": null,
   "currency_id": "MXN",
   "initial_quantity": 8,
   "available_quantity": 8,
   "sold_quantity": 0,
   "sale_terms": [ …  ],
   "buying_mode": "buy_it_now",
   "listing_type_id": "gold_special",
   "start_time": "2024-05-07T12:57:08.016Z",
   "stop_time": "2044-05-02T04:00:00.000Z",
   "end_time": "2044-05-02T04:00:00.000Z",
   "expiration_time": "2024-07-26T12:57:08.119Z",
   "condition": "new",
   "permalink": "http://articulo.mercadolibre.com.mx/MLM-2061397137-apple-iphone-15-256-gb-rojo-_JM", /*the permalink will redirect to the UPP of the item*/
   "pictures": [ … ],
   "video_id": null,
   "descriptions": [],
   "accepts_mercadopago": true,
   "non_mercado_pago_payment_methods": [],
   "shipping": { … },
   "international_delivery_mode": "none",
   "seller_address": { … },
   "seller_contact": null,
   "location": {},
   "geolocation": { …  },
   "coverage_areas": [],
   "attributes": [
      … 
   ],
   "warnings": [ … ],
   "listing_source": "",
   "variations": [],
   "thumbnail_id": "759471-MLA71782897602_092023",
   "thumbnail": "http://mlm-s1-p.mlstatic.com/759471-MLA71782897602_092023-I.jpg",
   "status": "active",
   "sub_status": [],
   "tags": [ … ],
   "warranty": "Seller's warranty: 3 months",
   "catalog_product_id": null,
   "domain_id": "MLM-CELLPHONES",
   "seller_custom_field": null,
   "parent_item_id": null,
   "differential_pricing": null,
   "deal_ids": [
      "MLM23369",
      "MLM52903"
   ],
   "automatic_relist": false,
   "date_created": "2024-05-07T12:57:08.177Z",
   "last_updated": "2024-05-07T12:57:08.177Z",
   "health": null,
   "catalog_listing": false,
   "item_relations": [],
   "channels": [
       "marketplace",
       "mshops"
   ]
}

Item Modification

To make changes to existing items, you must continue executing a PUT to the /items resource. Mercado Libre will replicate this modification asynchronously across all items in the same User Product, as long as shared attributes like size guides are modified. It's important to remember that in the new model, creating variations through a POST or PUT call to the items resource will not be allowed.

Modify Family

You can modify the family_name through the following resource, considering that it can only be modified if the user-product items associated with the item you are trying to modify have not yet been sold.

Request:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Accept: application/json" -d
{
  "family_name": "New family name"
}
https://api.mercadolibre.com/items/$ITEM_ID/family_name

Response:

{
   "family_name": "New family name"
}

Possible Status:

A new error code is added for the validation of the family_name length.

• Id: 462, “Family Name length is over 120 characters”

Considerations:

What happens if the seller modifies the family_name field?
If the family_name associated with an item is modified, the item's title field is recalculated, and additionally, the modification will be replicated to the User Product, triggering two possible actions:

• The recalculation of the family_id, which will cause the User Product to be moved to another family if necessary.
• The new family_name will be replicated across all sales conditions (items) associated with the User Product.

What happens if someone tries to modify the item's title field?
A bad request error will be triggered.

Can an item change families?
Modifying item attributes can cause them to leave the family, for example, by changing the brand, model, etc.

Can the item's user_product_id change?
This is not an editable field. If the item's attributes change, such as the family_name, the user_product_id remains the same. Only the edited attributes of all sales conditions connected to this same User Product will be updated.

How will the new and old world coexist?
It will be possible to identify items under the new User Products model through the "user_product_listing" tag.

How will UP and catalog coexist?

• Item has no variations and is (catalog_listing = true): The catalog flow is not impacted, so the PDP is created with the catalog_product_id. For more details, see catalog publications.
• Item has no variations and is (catalog_listing = false): The UPP (User Products Page) is created with the item_id and user_product_id.

Consult a User Product

You can get the details of a User Product through the following call:

curl -X GET https://api.mercadolibre.com/user-products/$USER_PRODUCT_ID -H 'Authorization: Bearer $ACCESS_TOKEN'

Example of consulting a specific UP:

Request:

curl -X GET https://api.mercadolibre.com/user-products/MLBU22012 -H 'Authorization: Bearer $ACCESS_TOKEN'

Response:

{
   "id": "MLBU22012",
   "name": "iPhone 14 Pro Max",
   "user_id": 1295303699,
   "domain_id": "MLB-CELLPHONES",
   "attributes": [
       {
           "id": "BRAND",
           "name": "Brand",
           "values": [
               {
                   "id": "123",
                   "name": "Apple",
                   "struct": null
               }
           ]
       },
       {
           "id": "MODEL",
           "name": "Model",
           "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": "Item Condition",
           "values": [
               {
                   "id": "2230284",
                   "name": "New",
                   "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, /*Family of the UP*/
   "tags": [
       "test"
   ],
   "date_created": "2023-02-13T02:46:20.528+0000",
   "last_updated": "2023-02-13T02:46:20.528+0000"
}

Family Notifications

We will notify the seller when a family is altered, which occurs when a User Product experiences a change in one of the attributes involved in the calculation of the family, causing the product to migrate to another family.

The notification message will contain the family_id key with the ID of the affected family.

If the family has been modified, the message will include the ID of the new destination family. If a new family is created (as a result of the creation of a User Product), the ID of the new family will be included in the notification. Finally, if the original family is deleted because the User Product has migrated to another family, the ID of the previous family will be sent in the notification.

Example:

{​
"_id": "2e4f6253-ebcc-421d-9d0b-97f80290ac5d",
"topic": "user-products-families",
"resource": "/sites/$SITE_ID/user-products-families/$FAMILY_ID",
"user_id": 123456789,
"application_id": 213123389095511,
"sent": "2024-07-11T18:43:50.793Z",
"attempts": 1,
"received": "2024-07-11T18:43:50.699Z"
}

Consult the User Products of a Family

You can obtain the User Products associated with a particular family through the following call.

curl -X GET https://api.mercadolibre.com/sites/$SITE_ID/user-products-families/$FAMILY_ID -H 'Authorization: Bearer $ACCESS_TOKEN'

Example of the resource for a specific family and site:

curl -X GET https://api.mercadolibre.com/sites/MLA/user-products-families/9871232123 -H 'Authorization: Bearer $ACCESS_TOKEN'

Response:

{
   "user_products_ids": [
       "MLAU1234",
       "MLAU1235",
       "MLAU1236"
   ],
   "family_id": 9871232123,
   "site_id": "MLA",
   "user_id": 1234
}

Searching for items by User Product

You can search for items using a filter on the user_product_id field.

curl -X GET https://api.mercadolibre.com/users/$SELLER_ID/items/search?user_product_id=$USER_PRODUCT_ID -H 'Authorization: Bearer $ACCESS_TOKEN'

Example for a specific UP:

curl -X GET https://api.mercadolibre.com/users/1234/items/search?user_product_id=MLBU206642488 -H 'Authorization: Bearer $ACCESS_TOKEN'

Response:

{
   "seller_id": "1234",
   "results": [
       "MLB664681522",
       "MLB664648534",
       "MLB664648532",
       "MLB664635674"
   ],
   "paging": {
       "limit": 50,
       "offset": 0,
       "total": 4
   },
   "query": null,
   "orders": [
       … 
   ],
   "available_orders": [
      …
   ]
}

Eligibility of Items - UPTIN

Sellers will be able to migrate their items to the new price per variation model, introducing the concept of UPtin to refer to the process of migrating an item from the previous model to the new user products listing model.

Eligibility considerations:

An item will only be eligible for UPtin if:

• The "user_product_id" attribute of the original item is not null.
• It is not a duplicate User Product, meaning the same User Product is already created for the same variation.
• The original item is multivariable (items without a variations array are not eligible).

To check the eligibility of old items for the new User Products format, use the following resource.

Call:

curl -X GET https://api.mercadolibre.com/sites/$SITE_ID/items/$ITEM_ORIGINAL/user_product_listings/validate -H 'Authorization: Bearer $ACCESS_TOKEN'

Example:

curl -X GET https://api.mercadolibre.com/sites/MLA/items/MLA12345678/user_product_listings/validate -H 'Authorization: Bearer $ACCESS_TOKEN'

Response:

{
  "is_valid": true/false,
  "cause": [
        {
            "code": 0000,
            "message": "Item xxxx is not allowed to migrate.",
            "reference": "item.xxx"
        },...
    ]
}

The attributes indicate:

• is_valid: true indicates the item is a candidate for UPtin. False for non-candidate cases.

Item Migration

The migration will involve creating a new item for each variation contained in the original item. This process will be carried out asynchronously, meaning that while the migration is being completed, the original item will remain active, and the seller will continue selling with that item until all items of the original variations are created and activated.

Once the migration is completed, the original item will be closed (status = “closed”) and tagged with variations_migration_source, while the new ones will be tagged with variations_migration_uptin, indicating that the item has been closed or created due to the migration. We will send a notification on the items topic for each case (new items and closed item).

To execute the UPtin, you must use the following resource, specifying the item to migrate in the body request (you must make a request for each item to migrate).

Call:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/MLM/items/user_product_listings
{
"item_id": "MLM1234"
}

Response:

204

Migration Status

To know the migration status of each item, its variants, and the new items created, you can use the following resource.

Call:

curl -X GET https://api.mercadolibre.com/items/$ITEM_ORIGINAL/migration_live_listing? -H 'Authorization: Bearer $ACCESS_TOKEN'

Example:

curl -X GET https://api.mercadolibre.com/items/MLA123456/migration_live_listing? -H 'Authorization: Bearer $ACCESS_TOKEN'

Response:

{
   "old_item_id": "MLA123456",
   "migration_completed": "", 
   "new_items": [
       {
           "new_item_id": "MLA789012",
           "variation_id": 45674567
       {
           "new_item_id": "MLA789022",
           "variation_id": 987654
       }
   ],
   "date_created": "..",
   "last_updated": "..."
}

Status Response:

• Status 200 and date_created attribute is null indicates that the migration is still in progress.
• Status 200 and date_created attribute is not null indicates that the migration concluded successfully, showing the completion timestamp.
• Status 404 - migration was not possible.

Considerations:

The migration_completed attribute is a timestamp set when the item has been completely migrated to the new scheme. This date indicates that all assets of all variations have been updated in the new items generated for the family.

Migration Flow

Consider the following flow that applies to items eligible for migration, i.e., items with an array of variations and the user_product_listing tag.

Testing Activation

You can request activation in your test account through this form.

Next: Distributed Stock.