Documentação do Mercado Livre

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

Documentação do

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

Gerenciar promoções

Importante:
Já está disponível para MLV e MEC as campanhas de desconto individual (PRICE_DISCOUNT), ofertas relâmpago (LIGHTNING), ofertas do dia (DOD) e campanhas tradicionais (DEAL).

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), desconto pré-acordado por item (PRE NEGOTIATED), campanha do vendedor (SELLER_CAMPAIGN), campanhas com co-participação automatizada (SMART), campanha de preços competitivos (PRICE_MATCHING), campanha de liquidação de estoque Full (UNHEALTHY_STOCK) e campanhas de cupons do vendedor (SELLER_COUPON_CAMPAIGN). Além dos novos tipos de ofertas que disponibilizamos.


Características das promoções


Nome da campanha Tipo da campanha 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
Campanhas com co-participação automatizada SMART Usuário aceita Não Sim Não Sim Não
Campanha de preços competitivos PRICE_MATCHING Usuário aceita Não Sim Não Sim Não
Campanha de liquidação de estoque Full UNHEALTHY_STOCK Usuário concordar e aceita Não Sim Sim 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)
Campanhas com co-participação automatizada
(SMART)
Campanha de preços competitivos
(PRICE_MATCHING)
Campanha de liquidação de estoque Full
(UNHEALTHY_STOCK)
Campanha do vendedor
(SELLER_CAMPAIGN)
MLA, MLB, MLM, MCO, MLC, MLU, MPE.
MLV e MEC

Nota:
A campanha de cupons do vendedor (SELLER_COUPON_CAMPAIGN) esta disponível somente para MLB.

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, VOLUME, PRICE DISCOUNT, PRE_NEGOTIATED, SELLER_CAMPAIGN, SMART, PRICE_MATCHING, UNHEALTHY_STOCK y SELLER_COUPON_CAMPAIGN).
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, PRICE_MATCHING, UNHEALTHY_STOCK y SELLER_COUPON_CAMPAIGN).
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, PRICE_MATCHING, UNHEALTHY_STOCK y SELLER_COUPON_CAMPAIGN).
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.


    Delete massivo de ofertas

    É possível eliminar em massa todas as ofertas que estão no item.

    Nota:
    Este delete massivo não se aplica para casos de ofertas de campanhas do tipo DOD e LIGHTNING. Para essas ofertas, é necessário continuar eliminando uma campanha por vez.

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

    Exemplo:

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

    Resposta:

    
     {
       "successful_ids": [
           {
               "offer_id": "OFFER-MLA1399846831-10000081416",
               "error": null
           },
           {
               "offer_id": "OFFER-MLA1399846831-10000081567",
               "error": null
           }
       ],
       "errors": []
    }

    Em casos que o item tenha campanhas que não podem ser deletadas de forma massiva, a chamada terá uma resposta http 200, porém o response irá conter as mensagens de erros.


    Exemplo onde nenhuma oferta pode ser eliminada:

    
    {
       "successful_ids": [],
       "errors": [
           {
               "offer_id": "OFFER-MLA1399846831-10000081416",
               "error": "The offer of type DOD not allowed for delete."
           },
           {
               "offer_id": "OFFER-MLA1399846831-10000081828",
               "error": "The offer could not be deleted. Try again."
           }
       ]
    }

    Exemplo onde as ofertas foram eliminadas corretamente e também ocorreram erros:

    
    {
       "successful_ids": [
           {
               "offer_id": "OFFER-MLA1399846831-10000081416",
               "error": null
           },
           {
               "offer_id": "OFFER-MLA1399846831-10000081417",
               "error": null
           }
       ],
       "errors": [
           {
               "offer_id": "OFFER-MLA1399846831-10000081418",
               "error": "The offer of type DOD not allowed for delete."
           },
           {
               "offer_id": "OFFER-MLA1399846831-10000081419",
               "error": "The offer could not be deleted. Try again."
           }
       ]
    }

    Possíveis erros

    423_ENTITY_LOCKED: A solicitação não pôde ser processada porque o item está temporariamente bloqueado para realizar solicitações. A solicitação pode ser tentada novamente após alguns segundos.

    400_BAD_REQUEST: Quando o formato do item é inválido.


    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