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 23/01/2025

Gerenciar promoções

Importante:
O novo filtro por estado já está disponível para filtrar os itens de uma campanha através do parâmetro de consulta status_item, que aceita os valores "active" ou "paused".

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 à 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 e SELLER_COUPON_CAMPAIGN).
status: estado da oferta (programada, ativa, inativa).

Nota:
O id da oferta é obtido por meio de uma notificação do tópico ofertas públicas.

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

A seguir, você pode encontrar os possíveis estados que os diferentes tipos de promoções podem ter:



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.


Filtros

Você pode aplicar filtros por item_id, status e status_item:

  • item_id: Permite filtrar por um item específico.
  • status: Permite filtrar pelo estado da oferta: started, pending ou candidate.
  • status_item: Permite filtrar pelo estado dos itens que fazem parte da campanha, podendo ser active ou paused.
Nota:
Quando o filtro status_item é enviado, apenas os itens correspondentes ao estado consultado serão retornados: "active" ou "paused". Se este parâmetro não for incluído, a consulta, por padrão, retornará apenas os itens ativos no Mercado Livre. Caso seja enviado um valor diferente de "active" ou "paused", será respondido com um 400 - Bad Request.

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_id:

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:

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": [...]
}

Exemplo de filtro por status_item:

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

Resposta:

  {
   "results": [
       {
            "id": "MLA639970000",
            "status": "started",
            "price": 4037,
            "original_price": 4427
        },
        {
            "id": "MLA639973333",
            "status": "started",
            "price": 6007,
            "original_price": 6587
        },
],
   "paging": [...]
}

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