Gerenciar promoções

Documentação do Mercado Livre

Confira todas as informações necessárias sobre as APIs Mercado Livre.

Última atualização em 24/11/2023

Gerenciar promoções

Importante:

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, finished, pending e candidate.

Paginação

Importante:

A partir de 4 de dezembro de 2023, teremos duas alterações:
- 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": "MLB2674512267",
       "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