Preço por variação

A iniciativa de Preço por Variação (PxV) visa proporcionar ao vendedor a capacidade de oferecer diferentes condições de venda para as variações de um mesmo produto, permitindo aplicar suas estratégias de venda de maneira mais flexível e escalável.

Ativação de sellers

A ativação dos sellers para o novo modelo de User Products será realizada de forma progressiva. Enquanto não alcançarmos 100% dos sellers ativos no novo modelo, teremos dois tipos de vendedores: aqueles que ainda não estão ativos e devem continuar publicando com o modelo anterior, e aqueles que já estão ativos e deverão começar a publicar com o novo modelo, com a capacidade de oferecer diferentes condições de venda para as variantes de um mesmo produto.
Os sellers ativados terão a tag "user_product_seller" , a qual poderá ser identificada realizando uma chamada à API de users.

Chamada:

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

Resposta:

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

Considerações

O processo de ativação de um seller para o novo modelo consiste em ativar a tag user_product_seller e, posteriormente, realizar uma varredura dos itens sem variantes, aos quais será atribuído um family_name, adotando assim a nova estrutura de User Products

Estrutura de items

Uma vez que os sellers sejam ativados para o novo modelo, a estrutura para publicar um item muda. Portanto, se não forem realizadas as adaptações necessárias na aplicação, não será possível publicar utilizando o modelo anterior , pois ocorrerá um erro 400.

A tabela a seguir mostra o que muda na estrutura dos itens no novo modelo:

Com a mudança na estrutura dos itens e considerando que, uma vez ativado o User Products para o vendedor, este terá itens tanto no modelo antigo quanto no novo, é crucial ajustar a experiência de integração atual. Isso garantirá que, ao consultar os itens do vendedor, ambos os modelos coexistam sem problemas.

Recomendamos incluir as seguintes características para os itens do novo modelo de User Products na aplicação:

• Agrupar items por User Product.
• Agrupar User Products por familia.
• Mostrar o family_name e user_product_id de cada item.
• Restringir a edição do título do item.
• Permitir a edição do family_name do item.
• Ao consultar um User Product, mostrar o detalhes de suas variações.
• Permitir estabelecer diferentes condições de venda para cada variação.

Essas melhoras buscam otimizar a experiência do usuário e facilitar a gestão de itens sob o novo sistema.

Lógica de atributos para Família/User Products

Os atributos que podem variar entre as variantes de um User Product são definidos pelo Mercado Livre através dos chamados child PK, e dependem da categoria ou domínio em que o produto é publicado. É fundamental que todas as variantes tenham esses atributos que permitem a variação preenchidos de forma consistente; caso contrário, os produtos podem ficar desagrupados fora da mesma família. Além disso, é possível atribuir atributos específicos para cada variante, utilizando qualquer atributo que não seja PK (nem parent nem child), o que permite maior flexibilidade de informação entre variantes. A lista de atributos admitidos para cada categoria e domínio pode ser consultada através dos endpoints presentes nesta documentação.

Publicar um item

A seguir, apresentamos algumas considerações que você deve ter em conta ao publicar um item sob o novo modelo de UP.

O novo campo family_name é obrigatório e deve ser preenchido pelo vendedor.Este campo será um nome genérico que abrange os diferentes User Products de uma mesma família. Recomenda-se usar um texto genérico e representativo dos itens, por exemplo:

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

Além disso, o campo título não deve ser enviado pelo vendedor, pois o Mercado Livre o preencherá automaticamente com as informações do item específico ou do produto. Isso é feito com o objetivo de ter itens mais padronizados,, baseando-se no domínio, atributos, family_name, entre outros.

Como exemplo, estaremos publicando dois itens da mesma família que compartilham: family_name, domínio, condição, seller_id e GTIN.

Primeiro item, na cor 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, na cor vermelha:

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

Exemplo de resposta para a criação de um item:

{
   "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", /*O permalink vai redirecionar para o UPP do 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"

   ]
}

Modificação de itens

Para realizar alterações nos itens existentes, você deverá continuar executando um PUT para o recurso /items. O Mercado Livre replicará essa modificação de forma assíncrona em todos os itens do mesmo User Products, desde que sejam modificados atributos compartilhados. Os atributos sincronizáveis a nível de User Products são:

• Name (title do item)
• Family Name (family_name do item)
• Site Id (site_id do item)
• User Id (seller_id do item)
• Domain Id (domain_id do item)
• Catalog Product Id (catalog_product_id do item)
• Family Id (propio do user_product)
• Date Created (propio do user_product)
• Last Updated (propio do user_product)
• Attributes (Atributos do item + attributes_combination, no caso de o user product ser gerado a partir de uma variação do item)
• Pictures (pictures do item)
• Thumbnail (thumbnail do item)
• Tags (propio do user_product)

É importante lembrar que no novo modelo não será permitida a criação de variações por meio de uma chamada POST ou PUT no recurso de itens.

Editor de família

Além de modificar o family_name, também é possível aplicar mudanças que impactem em todos os membros de uma mesma família de forma simultânea, mantendo o family_id. Isso permite atualizar atributos compartilhados como o nome da família, o domínio e os atributos da família (incluindo child PKs e atributos custom), garantindo que todas as variantes do User Product permaneçam unidas.

Os atributos que são considerados da família são:

• Name — nome da família (family_name)
• Domain ID — domínio ao qual a família pertence
• Attributes Parent PK — atributos pai que definem a família (enviados por meio de value_id para evitar diferenças por idioma)

Somente é permitido modificar child PKs e atributos custom. É obrigatório enviar os novos atributos em todos os membros da família.

Chamada:

curl -X POST https://api.mercadolibre.com/user-products-families/{family_id}/tasks \
  -H 'Authorization: Bearer $ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "common_content": {
    "family_name": "family name",
    "domain_id": "MLA-FLASK",
    "attributes": [
      {
        "id": "BRAND",
        "values": [{ "id": "999", "name": "Stanley" }]
      },
      {
        "id": "MODEL",
        "values": [{ "id": null, "name": null }]
      }
    ]
  },
  "user_products": [
    {
      "id": "MLAU1234",
      "attributes": [
        { "id": "HANDLE_MODEL", "values": [{ "id": "123123", "name": "Plastico" }] },
        { "name": "my custom attribute", "values": [{ "name": "custom" }] },
        { "id": "SOME_ATTRIBUTE", "values": [{ "id": null, "name": null }] },
        { "name": "my other custom attribute", "values": [{ "name": null }] }
      ]
    },
    {
      "id": "MLAU999",
      "attributes": [
        { "id": "HANDLE_MODEL", "values": [{ "id": "98766", "name": "Metal" }] },
        { "name": "my custom attribute", "values": [{ "name": "custom" }] },
        { "id": "SOME_ATTRIBUTE", "values": [{ "id": null, "name": null }] },
        { "name": "my other custom attribute", "values": [{ "name": null }] }
      ]
    }
  ]
}'

Resposta:

{
  "task_id": "mlm_86e58b8d-78a3-43e6-a1e3-c1ffef6ea772",
  "status": "pending",
  "date_created": "2026-04-01T19:56:09.949+0000"
}

A tarefa é processada de maneira assíncrona. Para consultar o resultado da tarefa, utilize o seguinte recurso:

Chamada:

curl -X GET https://api.mercadolibre.com/user-products-families/tasks/{task_id} \
  -H 'Authorization: Bearer $ACCESS_TOKEN'

Resposta:

{
  "task_id": "mlm_86e58b8d-78a3-43e6-a1e3-c1ffef6ea772",
  "status": "processing",
  "user-products": [
    {
      "id": "MLAU1234",
      "status": "succeeded",
      "processed_date": "2026-04-01T19:56:10.000+0000",
      "last_updated": "2026-04-01T19:56:10.000+0000",
      "reasons": null
    },
    {
      "id": "MLAU999",
      "status": "pending",
      "processed_date": "2026-04-01T19:56:10.000+0000",
      "last_updated": "2026-04-01T19:56:10.000+0000",
      "reasons": null
    },
    {
      "id": "MLAU888",
      "status": "failed",
      "processed_date": "2026-04-01T19:56:10.000+0000",
      "last_updated": "2026-04-01T19:56:10.000+0000",
      "reasons": [
        {
          "code": "some.error",
          "message": "descriptive message",
          "type": "error",
          "cause_id": 15,
          "department": "some department"
        }
      ]
    }
  ],
  "date_created": "2026-04-01T19:56:09.949+0000",
  "last_updated": "2026-04-01T19:56:10.706+0000"
}

Códigos de status de resposta — POST:

Códigos de status de resposta — GET:

Códigos de erro na resposta da tarefa:

Os erros são informados dentro do campo reasons, tanto a nível de família quanto a nível de UP individual:

Adicionar variante (UP) a uma família

Este endpoint permite criar uma nova variante dentro de uma família de User Products já existente, sem modificar o family_id. Os dados da família (domain_id, family_name e os atributos PARENT_PK) são herdados automaticamente da família; o integrador deve enviar apenas os CHILD_PKs de variação, as imagens e, opcionalmente, os main_features.

Chamada:

curl -X POST https://api.mercadolibre.com/user-products-families/{family_id}/user-products \
  -H 'Authorization: Bearer $ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "attributes": [
    { "id": "COLOR", "values": [{ "id": null, "name": "Laranja" }] },
    { "id": "SIZE",  "values": [{ "id": null, "name": "G" }] }
  ],
  "pictures": [
    { "id": "759471-MLA71782897602_092023" }
  ],
  "main_features": [
    { "origin": "seller", "description": "Material respirável" },
    { "origin": "seller", "description": "Proteção UV" }
  ]
}'

Campos do request

Resposta (201 Created):

{
  "id": "MLBU4382473956",
  "name": "Boné Esportivo Dry Fit Laranja G",
  "family_name": "Boné Esportivo Dry Fit",
  "site_id": "MLB",
  "user_id": 3550453798,
  "domain_id": "MLB-HATS_AND_CAPS",
  "attributes": [
    { "id": "ITEM_CONDITION", "name": "Condição do item", "values": [{ "id": "2230284", "name": "Novo" }] },
    { "id": "MODEL",          "name": "Modelo",           "values": [{ "id": null, "name": "Dry Fit" }] },
    { "id": "BRAND",          "name": "Marca",            "values": [{ "id": null, "name": "Genérico" }] },
    { "id": "COLOR",          "name": "Cor",              "values": [{ "id": null, "name": "Laranja" }] },
    { "id": "SIZE",           "name": "Tamanho",          "values": [{ "id": null, "name": "G" }] }
  ],
  "pictures": [
    { "id": "759471-MLA71782897602_092023", "secure_url": "https://http2.mlstatic.com/D_759471-MLA71782897602_092023-O.jpg" }
  ],
  "thumbnail": {
    "id": "759471-MLA71782897602_092023",
    "secure_url": "https://http2.mlstatic.com/D_759471-MLA71782897602_092023-O.jpg"
  },
  "family_id": 1034108706118545,
  "tags": ["test", "primary"],
  "main_features": [
    { "description": "Material respirável", "origin": "seller" },
    { "description": "Proteção uv",         "origin": "seller" }
  ],
  "date_created": "2026-07-21T23:33:45.746+0000",
  "last_updated": "2026-07-21T23:33:45.746+0000"
}

Códigos de status de resposta:

Considerações

O que acontece se o vendedor modificar o campo family_name?
Se o family_name associado a um item for modificado, o campo de título do item será recalculado e, adicionalmente, a modificação será replicada no User Product, o que desencadeará duas possíveis ações:

• O recálculo do family_id, que fará com que o User Product seja transferido para outra família, se necessário.
• O novo family_name será replicado em todas as condições de venda (itens) associadas ao User Product.

O que acontece se alguém tentar modificar o campo title do item?
É gerado um erro do tipo bad request.

Um item pode mudar de família?
Modificar os atributos dos itens pode fazer com que saiam da família atual, por exemplo, ao alterar a marca, modelo, etc.

O user_product_id do item pode mudar?
Não é um campo editável. Em caso de modificação dos atributos do item, tal como o family_name, o user_product_id continua sendo o mesmo. Somente os atributos editados de todas as condições de venda conectadas a esse mesmo User Product serão atualizados.

Como o novo e o velho mundo coexistirão?
Será possível identificar os itens do novo modelo de User Products através da tag "user_product_listing"

Como UP e catálogo coexistirão?

• Item sem variações e com (catalog_listing = true): O fluxo do catálogo não é impactado, e a PDP é criada com o catalog_product_id. Para mais detalhes, consulte publicações em catálogo.
• Item sem variações e com (catalog_listing = false): A UPP (User Products Page) é criada com o item_id e user_product_id.

Consultar um User Product

Você pode obter os detalhes de um User Product por meio da seguinte chamada:

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

Exemplo de consulta a um UP específico:

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

Resposta:

{
   "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": "Condição do item",
           "values": [
               {
                   "id": "2230284",
                   "name": "Novo",
                   "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, /*Família do UP*/
   "tags": [
       "test"
   ],
   "date_created": "2023-02-13T02:46:20.528+0000",
   "last_updated": "2023-02-13T02:46:20.528+0000"
}

Notificações de famílias

Notificaremos o vendedor quando uma família for alterada, isso se deve ao fato de que um User Product experimenta uma mudança em algum dos atributos comprometidos no cálculo da família, o que faz com que o produto migre para outra família.

A mensagem de notificação conterá a chave family_id com o ID da família afetada.

No caso de a família ter sido modificada, a mensagem será enviada com o ID da nova família de destino. Se uma nova família for criada (como resultado da criação de um User Product), o ID da nova família será incluído na notificação. Finalmente, se a família original for eliminada devido à migração do User Product para outra família, o ID da família anterior será enviado na notificação.

Exemplo:

{​
"_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 os User Products de uma família

Você pode obter os User Products associados a uma família específica usando a seguinte chamada:

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

Exemplo do recurso para uma família e um site específicos:

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

Resposta:

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

Busca de itens por User Product

Você pode fazer um search de itens utilizando um filtro pelo 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'

Exemplo para um UP específico:

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

Resposta:

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

Adicionar condição de venda a um User Product

Uma vez que você tenha um User Product criado, pode adicionar uma condição de venda (item_id). Isso permite publicar o produto no marketplace com preço, tipo de publicação e configuração de envio específicos.

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

Campos permitidos

(*) Se o User Product tiver o atributo ITEM_CONDITION com valor "recondicionado", você deverá especificar WARRANTY_TYPE e WARRANTY_TIME em sale_terms.

(**) Só deve ser enviado se catalog_listing for true.

Exemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/user-products/MLBU3691277914/items -d '{
    "price": 45000,
    "category_id": "MLB37525",
    "currency_id": "BRL",
    "buying_mode": "buy_it_now",
    "listing_type_id": "gold_special"
}'

Resposta (201 Created):

{
    "id": "MLB2631229629",
    "site_id": "MLB",
    "title": "Boneco Funko The Office",
    "seller_id": 2378338310,
    "category_id": "MLB37525",
    "user_product_id": "MLBU3691277914",
    "price": 45000,
    "base_price": 45000,
    "currency_id": "BRL",
    "initial_quantity": 10,
    "available_quantity": 10,
    "buying_mode": "buy_it_now",
    "listing_type_id": "gold_special",
    "family_name": "Boneco Funko The Office",
    "family_id": 4260899048783356,
    "condition": "new",
    "permalink": "http://produto.mercadolivre.com.br/MLB-2631229629-boneco-funko-the-office-_JM",
    "status": "active",
    "attributes": [...],
    "pictures": [...],
    "shipping": {
        "mode": "me2",
        "free_shipping": true,
        "logistic_type": "xd_drop_off",
        "tags": [
            "mandatory_free_shipping",
            "self_service_in"
        ]
    },
    "tags": [
        "cart_eligible",
        "immediate_payment",
        "test_item"
    ],
    "date_created": "2025-12-18T23:04:18.314Z",
    "last_updated": "2025-12-18T23:04:18.314Z"
}

Exemplo com catálogo

{
    "price": 45000,
    "catalog_listing": true,
    "category_id": "MLB8618",
    "currency_id": "BRL",
    "catalog_product_id": "MLB36975305",
    "buying_mode": "buy_it_now",
    "listing_type_id": "gold_special"
}

Exemplo enviando todos os campos

{
    "shipping": {
        "free_shipping": true
    },
    "price": 45000,
    "catalog_listing": true,
    "channels": ["marketplace"],
    "tags": ["3x_campaign"],
    "category_id": "MLB8618",
    "sale_terms": [
        {
            "id": "WARRANTY_TYPE",
            "value_id": "2230279",
            "value_name": "Garantia de fábrica"
        },
        {
            "id": "WARRANTY_TIME",
            "value_name": "12 meses"
        }
    ],
    "currency_id": "BRL",
    "catalog_product_id": "MLB36975305",
    "buying_mode": "buy_it_now",
    "listing_type_id": "gold_special",
    "official_store_id": 134
}

Campos herdados do User Product

Os seguintes campos são obtidos automaticamente do User Product e NÃO devem ser enviados no body:

• available_quantity: É atribuído de acordo com o estoque do User Product.
• attributes: São herdados do User Product (ou do catalog_product_id se catalog_listing=true).
• pictures: São herdadas do User Product (ou do catalog_product_id se catalog_listing=true).
• domain_id: É atribuído o domínio do User Product.
• family_name: É atribuído o family_name do User Product.
• title: É gerado automaticamente a partir do family_name e atributos.

Elegibilidade de itens - UPTIN

Os vendedores poderão migrar seus itens para o novo modelo de preço por variação, introduzindo o conceito de UPtin para se referir ao processo de migrar um item do modelo anterior para o novo modelo de publicação de produtos do usuário.

Considerações de elegibilidade

Um item só será elegível para UPtin se:

• O atributo "user_product_id" do item original for diferente de nulo.
• Não é um User Products duplicado, ou seja, já tenha um mesmo User products criado para a mesma variação.
• O item original é multivariante (itens sem array de variations não são elegíveis). Em itens multivariantes se gera uma publicação para cada variação.

Para consultar a elegibilidade dos itens antigos para o novo formato de User Products, você deve usar o seguinte recurso:

Chamada:

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

Exemplo:

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

Resposta:

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

Os atributos indicam:

is_valid: true, indica que o item é candidato a realizar UPtin. E false para casos que não são candidatos.

Migração de itens

A migração consistirá em criar um novo item para cada variação que contém o item original. Este processo será realizado de maneira assíncrona, portanto, enquanto a migração não estiver concluída, o item original permanecerá ativo e o vendedor continuará vendendo com esse item até que todos os itens das variações originais sejam criados e ativados.

Uma vez concluída a migração, o item original será encerrado (status = "closed") e terá a tag variations_migration_source e os itens novos se aplicará a tag variations_migration_uptin , que servirá de indicador de que o item foi encerrado, ou criado, pela migração. Para estas tags enviaremos uma notificação no tópico de itens em cada caso (itens novos e item encerrado).

Para executar o UPtin, você deve usar o seguinte recurso, indicando o item a ser migrado no body request (você deve fazer uma solicitação para cada item a ser migrado).

Chamada:

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

Códigos de status de resposta

Status de migração

Para que você possa conhecer o status de migração de cada item, suas variantes e os novos itens criados, será possível realizar isso através do seguinte recurso:

Chamada:

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

Exemplo:

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

Resposta:

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

Códigos de status de resposta:

Considerações:

• migration_completed: timestamp que indica quando todos os itens filhos foram criados, depois disso, procede-se com a ativação.
• activation_completed: timestamp que é definido quando o item foi completamente migrado para o novo esquema, ou seja, todos os novos itens foram ativados e o item pai foi fechado.
• date_created: timestamp que contém a data em que o processo de migração começou.

O atributo migration_completed é um timestamp que é definido quando o item foi completamente migrado para o novo esquema. Esta data indica que todos os ativos de todas as variações foram atualizados nos novos itens gerados da família.

Não será possível realizar alterações no item enquanto estiver em processo de migração; você receberá um erro 404.

Fluxo de migração

Tenha em conta o seguinte fluxo que aplica para ítens que são candidatos a migrar, ou seja, ítens com array de variations.

• Quando começa o processo de UPtin, o item com variações permanece com status "ativo".
• São adicionadas 2 tags de migração: "variations_migration_pending" e "variations_migration_source".
• Para cada variação, será criado um novo item com a configuração da variação.
• Os novos itens terão family_name para serem agrupados por família.
• Cada novo item é criado com status "paused" e também são adicionadas 2 tags de migração: "variations_migration_pending" e "variations_migration_uptin".
• Para cada item criado, uma novidade será disparada no tópico de notificações de itens.
• Quando a migração de todos os itens é finalizada, então:
  • Remove-se a tag "variations_migration_pending" do item antigo, ficando apenas a tag "variations_migration_source".
  • Remove-se a tag "variations_migration_pending" dos novos itens criados, ficando apenas a tag "variations_migration_uptin".
  • Os novos itens são ativados.
  • O item antigo é fechado (status=closed).

Detalhe das tags:

• variations_migration_source: o item que possui essa tag foi a origem do processo de upt-in. É um item com variações que será fechado ao final do processo de upt-in, pelo qual se cria um novo item para cada variação.
• variations_migration_uptin: o item que possui essa tag é resultado de um processo de upt-in. Provém de um item com variações que passou pelo processo de upt-in.
• variations_migration_pending: é adicionada tanto ao item original quanto aos novos itens de variação enquanto os ativos do item original são migrados para os novos. Essa tag será removida quando o processo de upt-in for finalizado.

Seguinte: Estoque distribuído.