Documentação do Mercado Livre

Confira todas as informações necessárias sobre as APIs Mercado Livre.
circulos azuis em degrade

Documentação

Última atualização em 07/02/2024

Gerenciar promoções

Importante:
A partir de 10 de janeiro de 2024 eliminaremos a versão anterior do recurso /seller-promotions.
Para obter a resposta com a nova versão, envie a query param app_version=v2. Consulte a documentação de cada campanha para conhecer as mudanças.

Com o recurso /seller-promotions você pode centralizar todos os tipos de promoções disponíveis como Campanhas tradicionais (DEAL), Campanhas com participação do Mercado Livre (MARKETPLACE_CAMPAIGN), Descontos individuais (PRICE_DISCOUNT), Ofertas relâmpago (LIGHTNING), Ofertas do dia (DOD), Desconto por volume (VOLUME) e desconto pré-acordado por item (PRE NEGOTIATED), campaña del vendedor (SELLER_CAMPAIGN) y campaña smart (SMART). Além dos novos tipos de ofertas que disponibilizamos.


Características das promoções


Tipo de campanha Nome Definição de preço Sugestão de preço Bonificação MELI Stock para participar Deadline Aprovação
Tradicional DEAL Usuário define Não Não Não Sim Sim
Campanhas com co-participação MARKETPLACE CAMPAIGN Usuário aceita Não Sim Não Sim Não
Desconto por volume VOLUME Usuário aceita Não Sim Não Sim Não
Oferta do dia DOD Usuário define Sim Não Sim, informativo Não Não
Oferta relâmpago LIGHTNING Usuário define Sim Não Sim, obrigatório Não Não
Desconto pré-acordado por item PRE_NEGOTIATED Usuário concordar e aceita Não Sim Sim Sim Não
Campanha do vendedor SELLER CAMPAIGN Usuário define e aceita Não Não Não Sim Não
Campanha smart SMART Usuário aceita Não Sim Não Sim Não


Disponibilidade por país


Site Campanha tradicional
(DEAL)
Campanha com co-participação
(MARKETPLACE CAMPAIGN)
Desconto individual
(PRICE DISCOUNT)
Desconto por volume
(VOLUME)
Desconto pré-acordado por item
(PRE_NEGOTIATED)
Oferta do dia
(DOD)
Oferta relâmpago
(LIGHTNING)
MLA, MLB, MLM, MCO, MLC, MLU, MPE.
MLV

Promoções do vendedor

Lembre-se de que um usuário pode ter mais de um convite e de diferentes tipos.

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/users/$USER_ID?app_version=v2'

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/users/1356551933?app_version=v2'

Resposta:

{
    "results": [
        {
            "id": "P-MLB1806015",
            "type": "MARKETPLACE_CAMPAIGN",
            "status": "started",
            "start_date": "2023-04-20T02:00:00Z",
            "finish_date": "2023-08-01T02:00:00Z",
            "deadline_date": "2023-08-01T01:00:00Z",
            "name": "Campanha de teste v2",
            "benefits": {
                "type": "REBATE",
                "meli_percent": 5,
                "seller_percent": 25
            }
        },
        {
            "id": "P-MLB1806017",
            "type": "VOLUME",
            "status": "started",
            "start_date": "2023-04-20T03:00:00Z",
            "finish_date": "2023-08-01T02:00:00Z",
            "deadline_date": "2023-08-01T01:00:00Z",
            "name": "Leva 3 paga 2",
            "benefits": {
                "type": "VOLUME",
                "meli_percent": 9.9999,
                "seller_percent": 23.3331,
                "name": "3x2",
                "buy_quantity": 3,
                "pay_quantity": 2,
                "item_discount_percent": 33.333
            }
        },
        {
            "id": "P-MLB1806019",
            "type": "DEAL",
            "status": "started",
            "start_date": "2023-04-20T03:00:00Z",
            "finish_date": "2023-08-01T02:00:00Z",
            "deadline_date": "2023-08-01T01:00:00Z",
            "name": "deals de teste v2"
        },
        {
            "id": "P-MLB1809008",
            "type": "DEAL",
            "status": "started",
            "start_date": "2023-04-21T21:00:00Z",
            "finish_date": "2023-08-01T02:00:00Z",
            "deadline_date": "2023-08-01T01:00:00Z",
            "name": "Deals de test v2"
        },
        {
            "id": "P-MLB1809009",
            "type": "DEAL",
            "status": "started",
            "start_date": "2023-04-21T23:00:00Z",
            "finish_date": "2023-08-01T02:00:00Z",
            "deadline_date": "2023-08-01T01:00:00Z",
            "name": "campanha de teste tahi"
        }
    ],
    "paging": {
        "offset": 0,
        "limit": 50,
        "total": 5
    }
 }

Campos de resposta

id: código de identificação da promoção.
type: tipo de oferta (DEAL, MARKETPLACE_CAMPAIGN, DOD, LIGHTNING, PRE NEGOTIATED,SELLER_CAMPAIGN, SMART).
status: estados.
start_date: data de início da promoção.
finish_date: data de fim da promoção.
deadline_date: prazo máximo para aceitar o convite para participar da oferta.
name: nome da promoção.
deadline_date: prazo máximo para aceitar o convite para participar da promoção.
benefits: configurações de benefícios de promoção.


Itens candidatos

O recurso /seller-promotions/candidates permite identificar os itens convidados a fazer parte de uma promoção. Sempre que um item passa a ter o status candidate em uma promoção é enviada uma notificação com o candidate_id>, com esse recurso é possível identificar o item, a promoção e o status.


Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'  https://api.mercadolibre.com/seller-promotions/candidates/$CANDIDATE_ID?app_version=v2

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'  https://api.mercadolibre.com/seller-promotions/candidates/CANDIDATE- MLB1254949426-803130663?app_version=v2

Resposta:

{    
    "id": "CANDIDATE-MLB1254949426-803130663",    
    "item_id": "MLB1254949426",    
    "promotion_id": "P-MLB4629001",    
    "type": "MARKETPLACE_CAMPAIGN",    
    "status": {        
    "id": "candidate"    
  } 
}

Campos da resposta


id: código de identificação do candidato.
item_id: item associado ao candidato.
promotion_id: id da promoção.
type: tipo de promoção (DEAL, MARKETPLACE_CAMPAIGN, DOD, LIGHTNING, VOLUME, PRICE DISCOUNT, PRE_NEGOTIATED, SELLER_CAMPAIGN, SMART).
status: status do candidato.


Nota:
O id do candidato se obtêm através da notificação do tópico public candidate.

Consultar Ofertas

O recurso /seller-promotions/offers> permite identificar as alterações que ocorreram na oferta de um item. Todas as alterações são enviadas por meio de notificações com o offer_id, com esse recurso é possível identificar o item, a promoção e o estado.


Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/offers/$OFFERS_ID?app_version=v2

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/offers/OFFER-MLB1970246686-42701792?app_version=v2

Resposta:

{    
    "id": "OFFER-MLB1970246686-42701792",    
    "item_id": "MLB1970246686",    
    "promotion_id": "P-MLB3329001",    
    "type": "DEAL",    
    "status": {        
    "id": "ACTIVE"    
  } 
}

Campos da resposta
id: código de identificação da oferta.
item_id: item associado a oferta.
promotion_id: id da promoção.
type: tipo de promoção (DEAL, MARKETPLACE_CAMPAIGN, DOD, LIGHTNING, VOLUME, PRICE DISCOUNT, PRE_NEGOTIATED, SELLER_CAMPAIGN, SMART).
status: status da oferta (programmed, active, e inactive).


Nota:
O id da oferta se obtêm através da notificação do tópico public offers.

Consultar os detalhes da promoção

Realize a seguinte consulta para acessar os detalhes específicos de uma campanha tradicional, uma campanha com participação Mercado Livre e para os descontos por volume.

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTION_ID?promotion_type=$PROMOTION_TYPE&app_version=v2'

Para obter mais informação, acesse as documentações por campanha.


Estados

Abaixo você encontra os possíveis estados para diferentes tipos de promoções:


Consultar itens da promoção

Para conhecer os itens que fazem parte de uma determinada promoção pode-se fazer a seguinte consulta:

Nota:
Nesta consulta você irá obter o estado do item da campanha.

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTIONS_ID/items?promotion_type=PROMOTION_TYPE&app_version=v2'

Além disso, você pode consultar os itens de uma campanha.


  • Tradicional
  • Co-participaçãoe
  • Descontos por volume.
  • Oferta do dia
  • Oferta relâmpago
  • Desconto pré-acordado por item.
  • do vendedor.
  • Smart.


  • Filtros

    Você pode aplicar filtros por item ou status.


    Chamada:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTION_ID/items?promotion_type=PROMOTION_TYPE&status=$STATUS&item_id=$ITEM_ID&app_version=v2
    

    Exemplo de filtro por item:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/MLA1111/items?promotion_type=DEAL&item_id=MLA604400000&app_version=v2
    

    Resposta:

    {
       "results": [
           {
               "id": "MLA604400000",
               "status": "started",
               "price": 23968,
               "original_price": 28549
           }
       ],
       "paging": {...}
    }

    Exemplo de filtro por status started:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' /seller-promotions/promotions/MLA1111/items?promotion_type=DEAL&status=started&app_version=v2
    

    Resposta:

    {
       "results": [
           {
                "id": "MLA639970000",
                "status": "started",
                "price": 4037,
                "original_price": 4427
            },
            {
                "id": "MLA639973333",
                "status": "started",
                "price": 6007,
                "original_price": 6587
            },
    ],
       "paging": [...]
    }
    Nota:
    Os estados para filtrar são: started, pending e candidate.

    Paginação

    Importante:
    - O query param para enviar este valor começa a chamar-se search_after e já não searchAfter. Mas o searchAfter continuará a ser aceito durante algum tempo.
    - O valor de search_after será unificado para utilizar apenas valores diferentes, eliminando a ambiguidade.

    Para realizar a paginação você deve usar o parâmetro de search_after.
    Na resposta GET, devolvemos o parâmetro searchAfter, que será utilizado para recorrer aos resultados. É necessário recuperar este ID e efetuar o seguinte request com o query param search_after={search_after}. Este ID é um string, por isso devem aceitar string e utilizá-lo mais tarde nas suas chamadas.


    Nota:
    Se não utilizar o parâmetro limit, serão retornados por default 50 itens do total. Você poderá adicionar um limit máximo de 50.

    Chamada:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTIONS_ID/items?promotion_type=$PROMOTION_TYPE&app_version=v2&limit=50&search_after={$SEARCH_AFTER}'

    Exemplo de paginação:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/P-MLB13451002MLB9377/items?promotion_type=DEAL&app_version=v2&limit=50&search_after=d3e3fb02371ca8e49ceb3e998c4a1b8da189235497375e55d3027c7dacf5a4ef0175b2aaca4f4a0fdf31299947d82ba661037482172ba7f9cfb1b0250d3134aa71c889367aa7c1401e4c3ff5bd70ee14337dfaa18c99bbe5e52dc3a2c1b55b195131903ecbc60a1c639e01dbecf11b15126d4b38cdb6122182acde2eca1b1a42'

    Resposta:

    "results": [
           {
               "id": "MLB2674512266",
               "status": "candidate",
               "price": 0,
               "original_price": 0
           },
           {
               "id": "MLB2674506199",
               "status": "candidate",
               "price": 0,
               "original_price": 0
           },
           {
               "id": "MLB2674506138",
               "status": "candidate",
               "price": 0,
               "original_price": 0
           },
           {
               "id": "MLB2674505931",
               "status": "candidate",
               "price": 0,
               "original_price": 0
           },
           {
               "id": "MLB2674505924",
               "status": "candidate",
               "price": 0,
               "original_price": 0
     
     […]
     
     "paging": {
           "searchAfter": 
           "d3e3fb02371ca8e49ceb3e998c4a1b8da189235497375e55d3027c7dacf5a4ef0175b2aaca4f4a0fdf31299947d82ba661037482172ba7f9cfb1b0250d3134aa71c889367aa7c1401e4c3ff5bd70ee14337dfaa18c99bbe5e52dc3a2c1b55b195131903ecbc60a1c639e01dbecf11b15126d4b38cdb6122182acde2eca3b5b55",
           "limit": 50,
           "total": 14424
       }
    }


    Considerações

    • Será retornado earch_after em todas as páginas, exceto na última página.
    • A única forma de avançar na resposta (paginar) é através da utilização deste parâmetro.
    • Ao iterar os resultados, cada chamada devolverá o search_after que deve ser utilizado na chamada seguinte.
    • Utilize sempre o search_after que foi oferecido pela resposta ao request, que pode mudar e expirar (têm um TTL de 5 minutos).
    • Não é possível efetuar a paginação para trás.


    Como participar

    Você pode participar de diversos tipos de promoções e até oferecer um desconto individual para itens:


    Consultar as promoções de itens

    Aqui você pode obter todas as promoções que o item possuí e os estados das promoções no momento da consulta.

    Chamada:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/items/$ITEM_ID?app_version=v2

    Exemplo:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/items/MLB3538191898?app_version=v2

    Resposta:

    [
      {
          "type": "PRICE_DISCOUNT",
          "status": "candidate",
          "price": 4000,
          "start_date": "2023-04-26T00:00:00",
          "finish_date": "2023-05-10T00:00:00"
      },
      {
          "type": "DOD",
          "status": "candidate",
          "price": 4000,
          "start_date": "2023-04-28T00:00:00",
          "finish_date": "2023-04-28T23:59:59"
      },
      {
          "id": "P-MLB1817004",
          "type": "MARKETPLACE_CAMPAIGN",
          "status": "pending",
          "start_date": "2023-04-27T23:00:00Z",
          "finish_date": "2023-06-01T02:00:00Z",
          "deadline_date": "2023-06-01T01:00:00Z",
          "name": "Campanha teste 10",
          "benefits": {
              "type": "REBATE",
              "meli_percent": 3,
              "seller_percent": 27
          }
      },
      {
          "id": "MLB1345",
          "type": "DEAL",
          "status": "pending",
          "start_date": "2023-04-27T23:00:00-03:00",
          "finish_date": "2023-05-31T23:00:00-03:00",
          "name": "teste 20"
      },
      {
          "id": "C-MLB300",
          "type": "SELLER_CAMPAIGN",
          "sub_type": "FIXED_PERCENTAGE",
          "status": "started",
          "price": 4250,
          "top_price": 3500,
          "start_date": "2023-04-27T00:00:00",
          "finish_date": "2023-05-05T23:59:59",
          "name": "camp del seller 1"
      },
      {
          "id": "P-MLB1812010",
          "type": "SMART",
          "status": "started",
          "name": "test-smart-2",
          "offers": [
              {
                  "id": "OFFER-MLB3538191898-177685",
                  "original_price": 5000,
                  "new_price": 3000,
                  "prime_price": null,
                  "status": "active",
                  "start_date": "2023-04-26T11:40:00Z",
                  "end_date": "2023-05-30T15:47:00Z",
                  "benefits": {
                      "type": "REBATE",
                      "meli_percent": 20,
                      "seller_percent": 20
                  }
              }
          ]
      },
      {
          "id": "C-MLB302",
          "type": "SELLER_CAMPAIGN",
          "sub_type": "FLEXIBLE_PERCENTAGE",
          "status": "candidate",
          "start_date": "2023-04-27T12:04:00",
          "finish_date": "2023-05-05T00:00:00",
          "name": "camp del seller 2"
      }
    ]

    Modificar itens

    Para modificar os itens que estão participando de uma oferta, pode fazer isso da seguinte maneira:

    Nota:
    Para editar os descontos individuais (PRICE DISCOUNT), as ofertas do dia (DOD) e as ofertas relâmpago (LIGHTNING) você deve excluir a promoção e aplicá-la novamente.


    Eliminar itens

    Com este recurso é possível eliminar uma oferta do item antes que o prazo acabe:


    Campanha de teste

    Para fazer testes com campanhas teste, envie os dados de seu usuário e/ou itens no seguinte suporte.
    Lembre-se de que os usuários quanto itens devem ser testes.


    Nota:
    Você deve adicionar o parâmetro version=test dentro das chamadas para interagir com as promoções de teste.

    Próxima: Campanhas tradicionais