Precio por variación

La iniciativa de precio por variación tiene como objetivo proporcionar al vendedor la capacidad de ofrecer diferentes condiciones de venta para las variantes de un mismo producto, lo que le permite aplicar sus estrategias de venta de manera más flexible y escalable.

Publicar un ítem

Tendremos 2 tipos de usuarios los que podrán publicar con el modelo anterior y los que podrán a comenzar a publicar con el nuevo modelo de User Products (convivirán ambos modelos). Dichos sellers podrás identificarlo a través del tag "user_product_seller" en el API de users.

Llamada:

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

Respuesta:

{
    "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"
    ]
}

Consideraciones

A continuación te presentamos algunas consideraciones que debes tener en cuenta al momento de querer publicar un ítem bajo el nuevo modelo de UP.

El nuevo campo family_name es un campo requerido que el vendedor deberá completar, dicho campo será una descripción genérica del ítem, que abarque a los distintos User Products de una misma familia, se recomienda usar texto genérico y representativo de los ítems, por ejemplo:

Family name: "Apple iPhone 256GB"
Item_1: "Apple iPhone 256GB Rojo"
Item_2: "Apple iPhone 256GB Azul"

Adicionalmente, el campo title no debe ser enviado por el vendedor ya que Mercado Libre lo completará automáticamente, con la información del ítem específico o del producto. Lo anterior se realiza con el objetivo de tener items más estandarizados, tomando como base el dominio, los atributos, el family_name, entre otros.

A modo de ejemplo, estaremos publicando dos ítems de una misma familia, comparten: family_name, dominio, condición, seller_id y GTIN.

Primer ítem, en color azul:

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 meses"
       },
       {
           "id": "WARRANTY_TYPE",
           "value_name": "Garantía del vendedor"
       }
   ],
   "buying_mode": "buy_it_now",
   "listing_type_id": "gold_special",
   "condition": "new",
   "pictures": [ … ],
   "attributes": [
       {
           "id": "BRAND",
           "value_name": "Apple"
       },
       {
           "id": "COLOR",
           "value_name": "Azul"
       },
       {
           "id": "GTIN",
           "value_name": "195949034862"
       },
       {
           "id": "RAM",
           "value_name": "6 GB"
       },
       {
           "id": "IS_DUAL_SIM",
           "value_name": "Sí"
       },
       {
           "id": "MODEL",
           "value_name": "iPhone 15"
       },
       {
           "id": "CARRIER",
           "value_name": "Desbloqueado"
       }
   ]
}'

Segundo item, en color rojo:

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 meses"
       },
       {
           "id": "WARRANTY_TYPE",
           "value_name": "Garantía del vendedor"
       }
   ],
   "buying_mode": "buy_it_now",
   "listing_type_id": "gold_special",
   "condition": "new",
   "pictures": [ … ],
   "attributes": [
       {
           "id": "BRAND",
           "value_name": "Apple"
       },
       {
           "id": "COLOR",
           "value_name": "Rojo"
       },
       {
           "id": "GTIN",
           "value_name": "195949034862"
       },
       {
           "id": "RAM",
           "value_name": "6 GB"
       },
       {
           "id": "IS_DUAL_SIM",
           "value_name": "Sí"
       },
       {
           "id": "MODEL",
           "value_name": "iPhone 15"
       },
       {
           "id": "CARRIER",
           "value_name": "Desbloqueado"
       }
   ]
}'

Ejemplo de respuesta para la creación de un ítem:

{
   "id": "MLM2061397137",
   "site_id": "MLM",
   "title": "Apple iPhone 256GB Rojo",
   "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", /*el permalink va a redirigir al UPP del 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": "Garantía del vendedor: 3 meses",
   "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"
   ]
}

Modificación de items

Para realizar cambios en los ítems existentes, deberás continuar ejecutando un PUT al recurso /items. Mercado Libre replicará esta modificación de manera asíncrona en todos los ítems del mismo User Product, siempre y cuando se modifiquen atributos compartidos, como la guía de talles. Es importante recordar que en el nuevo modelo no se permitirá la creación de variaciones mediante un llamada POST o PUT en el recurso de ítems.

Modificar familia

Podrás modificar el family_name a través del siguiente recurso, teniendo en cuenta que sólo podrá ser modificado si los ítems asociados user-product del ítem que se están queriendo modificar aún no tienen ventas.

Llamada:

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

Respuesta:

{
   "family_name": "Nuevo family name"
}

Posibles status:

Se agrega un nuevo código de error para la validación del largo del family_name.

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

Consideraciones:

¿Qué sucede si el vendedor modifica el campo family_name?
Si se modifica el family_name asociado a un ítem, se recalcula el campo título del ítem y adicionalmente la modificación se replicará al User Product, lo que disparará dos posibles acciones:

• El recálculo del family_id que hará que dicho User Product se traslade a otra familia de ser necesario.
• Se replicará el nuevo family_name en todas las condiciones de venta (ítems) asociadas al User Product.

¿Qué sucede si alguien intenta modificar el campo title del ítem?
Se dispara un error de tipo bad request.

¿Un ítem puede cambiar de familia?
Modificar los atributos de los ítems pueden hacer que salgan de la familia, por ejemplo, al cambiar marca, modelo, etc.

¿El user_product_id del item puede cambiar?
No es un campo editable. En caso de que cambien los atributos del item, tal y como el family_name, el user_product_id continúa siendo el mismo. Solo actualizarán los atributos editados de todas las condiciones de venta conectadas a este mismu User Products.

¿Cómo convivirá el nuevo y viejo mundo?
Será posible identificar los ítems bajo el nuevo modelo de User Products, a través del tag "user_product_listing"

¿Cómo convivirá UP y catálogo?

• Item no tiene variaciones y es (catalog_listing = true): El flujo de catálogo no se ve impactado, por lo que se crea la PDP con el catalog_product_id, para más detalle consulta publicaciones en catalogo.
• Item no tiene variaciones y es (catalog_listing = false): Se crea la UPP (User Products Page) con el item_id y user_product_id.

Consultar un User Product

Podrás obtener el detalle de un User Prodcut por medio del siguiente llamado:

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

Ejemplo consultando un UP específico:

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

Respuesta:

{
   "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, /*Familia del UP*/
   "tags": [
       "test"
   ],
   "date_created": "2023-02-13T02:46:20.528+0000",
   "last_updated": "2023-02-13T02:46:20.528+0000"
}

Notificaciones de familias

Notificaremos al vendedor cuando una familia sea alterada, esto se debe a que un User Product experimenta un cambio en alguno de los atributos comprometidos en el cálculo de la familia, lo que provoca que el producto migre a otra familia.

El mensaje de notificación contendrá la clave family_id con el ID de la familia afectada.

En caso de que la familia haya sido modificada, se enviará el mensaje con el ID de la nueva familia de destino. Si se crea una nueva familia (como resultado de la creación de un User Product), se incluirá el ID de la nueva familia en la notificación. Por último, si se elimina la familia original debido a que el User Product ha migrado a otra familia, se enviará el ID de la familia anterior en la notificación.

Ejemplo:

{​
"_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"
}

Consultar los User Products de una familia

Podrás obtener los User Products asociados a una familia en particular, por medio del siguiente llamado.

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

Ejemplo del recurso para una familia y un site en específico:

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

Respuesta:

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

Busqueda de items por User Product

Podrás hacer el search de ítems utilizando un filtro el campo user_product_id.

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

Ejemplo para un UP específico:

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

Respuesta:

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

Elegibilidad de los ítems - UPTIN

Los vendedores van a poder migrar sus ítems al nuevo modelo de precio por variación, por lo que introducimos el concepto de UPtin para referirnos al proceso de migrar un ítem que se encuentra en el modelo anterior hacia el nuevo modelo de publicación de user products.

Consideraciones de elegibilidad:

Un ítem sólo será elegible para UPtin si:

• El atributo "user_product_id" del ítem orginal es diferente de nulo.
• No es un User Products duplicado, es decir, ya tenga un mismo User products creado para la misma variación.
• El ítem original es multivariante (ítems sin array de variations no son elegibles).

Para consultar la elegibilidad de los ítems antiguos para el nuevo formato de User Products, deberás utilizar el siguiente recurso.

Llamada:

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

Ejemplo:

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

Respuesta:

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

Los atributos indican:

• is_valid: true, indica que el ítem es candidato a realizar UPtin. Y false para casos donde no sin candidatos.

Migración de ítems

La migración consistirá en crear un nuevo ítem por cada variación que contiene el ítem original, este proceso se realizará de manera asíncrona, por lo que mientras concluye la migración, el item original permanecerá activo y el seller seguirá vendiendo con dicho ítem hasta tanto se creen y activen todos los ítems de las variaciones originales.

Una vez concluída la migración, el ítem original será cerrado (status = “closed”) y tendrá el tag variations_migration_source y los nuevos se aplicará el tag variations_migration_uptin, que servirá de indicador de que el ítem fue cerrado, o creado, por la migración. Para los tags enviaremos una notificación en el tópico de ítems en cada caso (items nuevos y item cerrado).

Para ejecutar el UPtin deberás utilizar el siguiente recurso, indican el ítem a migrar en el body request (deberás realizar una petición por cada ítem a migrar).

Llamada:

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

Respuesta:

204

Status migración

Para que puedas conocer el status de migración de cada ítem, sus variantes y los nuevos ítems creados, será posible realizarlo a través del siguiente recurso.

Llamada:

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

Ejemplo:

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

Respuesta:

{
   "item_id": "MLA123456",
   "migration_completed": null, 
   "activation_completed": null, 
   "date_created": "2024-07-30T16:22:53Z",
   "last_updated": "2024-07-30T16:22:53Z",
   "new_items": [
       {
           "new_item_id": "MLA789012",
           "variation_id": 45674567,
           "migration_status": "pending | created"
       },
       {
           "new_item_id": "MLA789022",
           "variation_id": 987654,
           "migration_status": "pending | created"
       }
   ]
}

Status de respuesta:

• Status 404 - no fue posible realizar la migración.

Consideraciones:

• migration_completed: timestamp indica cuando se terminaron de crear todos los items hijos, luego se procede con activarlos.
• activation_completed: timestamp que se setea cuando el ítem ha sido completamente migrado al nuevo esquema, es decir, todos los ítems nuevos han sido activados y el ítem padre ha sido cerrado.
• date_created: timestamp que contiene la fecha en la que comenzó el proceso de migración.

El atributo migration_completed es un timestamp que se setea cuando el ítem ha sido completamente migrado al nuevo esquema. Esta fecha indica que todos los assets de todas las variaciones se han actualizado en los nuevos ítems generados de la familia.

No será posible realizar cambios en el ítem mientras esté en proceso de migración; recibirás un error 404.

Flujo de migración

Ten en cuenta el siguiente flujo que aplica para los ítems que son candidatos a migrar, es decir, ítems con array de variations y con el tag user_product_listing".

• Cuando comienza el proceso de UPtin, el ítem con variaciones se mantiene en status “active”.
• Se le agregan 2 tags de migración “variations_migration_pending” y “variations_migration_source”.
• Por cada variación se va a crear un ítem nuevo con la configuración de la variación.
• Los nuevos ítems contarán con family_name para ser agrupados por familia.
• Cada ítem nuevo se crea con status “paused” y también se le agregan 2 tags de migración “variations_migration_pending” y “variations_migration_uptin”.
• Por cada ítem que se cree se va a disparar una novedad en el tópico de notificaciones de ítems.
• Cuando la migración de todos los ítems se finaliza, entonces:
  • Se quita el tag “variations_migration_pending” del ítem antiguo quedando solamente el tag “variations_migration_source”.
  • Se quita el tag “variations_migration_pending” de los ítems nuevos que se crearon quedando solamente el tag “variations_migration_uptin”.
  • Se activan los ítems nuevos.
  • Se cierra el ítem viejo (status=closed).

Detalle de los tags:

• variations_migration_source: el ítem que tiene este tag fue origen del proceso de upt-in. Es un ítem con variaciones que se va a cerrar al finalizar el proceso de upt-in mediante el cual se crea un ítem nuevo por cada variación.
• variations_migration_uptin: el ítem que tiene este tag es resultado de un proceso de upt-in. Proviene de un ítem con variaciones que pasó por el proceso de upt-in.
• variations_migration_pending: se agrega tanto al ítem original como a los nuevos ítem-variación mientras se migran los assets del ítem original a los nuevos. Este tag será removido cuando finalice el proceso de upt-in.

Activación de pruebas

Podrás hacer una solicitud de activación en tu cuenta de pruebas a través de este formulario.

Siguiente: Stock Distribuido.