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 05/12/2023

Campanhas de desconto por volume

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.

Os vendedores são convidados periodicamente a participar de diversas campanhas realizadas no site. A principal característica desse tipo de campanha é que um desconto é aplicado quando um determinado número de itens de um produto é atingido. Por exemplo, compre 4 e pague 3, 2x1 ou 50% de desconto no segundo item. Além disso, o Mercado Livre assume um percentual do desconto oferecido.
Se o vendedor recebeu um convite e deseja participar, você pode utilizar os seguintes recursos.


Visão do vendedor






Consultar os detalhes de uma campanha

Para obter os detalhes de uma campanha com desconto por volume, faça a seguinte consulta:


Exemplo:

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

Resposta:

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

Campos específicos desta campanha

Benefits: detalhe dos benefícios da promoção.

  • type: tipo de benefício.
  • meli_percent: porcentagem de contribuição do Mercado Livre.
  • seller_percent: porcentagem de contribuição do vendedor.
  • name: nome do desconto.
  • buy_quantity: número necessário de itens para acessar o desconto.
  • pay_quantity: quantidade de itens pagos.
  • item_discount_percent: porcentagem de desconto em cada item.


  • Tipos de desconto

    Estes são os diferentes tipos de descontos que existem neste tipo de campanha:

    • Leva 4 paga 3
    • 70% OFF comprando 2
    • 70% OFF na 2ª unidade


    • Estados

      Esses são os diferentes status pelos quais uma campanha com desconto por volume pode passar.

      Estados Descrição
      pending Promoção aprovada, mas que ainda não começou.
      started Promoção ativa.
      finished Promoção finalizada.


      Consultar os itens em uma campanha

      Para conhecer os itens candidatos e/ou que fazem parte de uma campanha com desconto por volume, faça a seguinte consulta:


      Chamada:

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

      Resposta:

      {
        "results": [
            {
                "id": "MLB3500418540",
                "status": "candidate",
                "price": 1333.34,
                "original_price": 2000,
                "meli_percentage": 10,
                "seller_percentage": 23.3,
                "start_date": "2023-04-20T03:00:00Z",
                "end_date": "2023-08-01T02:00:00Z"
            }
        ],
        "paging": {
            "offset": 0,
            "limit": 50,
            "total": 1
        }
      }

      Ao criar uma campanha, todos os itens aplicáveis ​​a ela são selecionados. O estado inicial (status) dos itens é candidato e sem um ID de oferta atribuído. Assim que o vendedor incorpora um item à campanha, seu status é modificado e um offer_id exclusivo é atribuído a ele.



      Estados do item

      A tabela a seguir contém os possíveis estados que os itens podem assumir neste tipo de campanha.

      Estados Descrição
      candidate Item candidato a participar da promoção.
      pending Item com promoção aprovada e programada.
      started Item ativo na campanha.
      finished IItem eliminado da campanha.


      Indicar itens para uma campanha

      Nota:
      Veja que para indicar e excluir esta campanha, alteramos o texto de deal_id a promotion_id.

      Após ter sido convidado a participar neste tipo de campanha, indique quais produtos deseja incluir nela.

      Chamada:

      curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
      -d '{
         "promotion_id":"$PROMOTION_ID",
         "promotion_type":"$PROMOTION_TYPE"
      }' 
      https://api.mercadolibre.com/seller-promotions/items/$ITEM_ID?app_version=v2

      Exemplo:

      curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
      -d '{
         "promotion_id":"P-MLB379009",
         "promotion_type":"VOLUME"
      }'
      https://api.mercadolibre.com/seller-promotions/items/MLB1834747833&app_version=v2

      Resposta:

      {
        "offer_id": "MLB1834747833-9eafadd4-16d2-49ae-b272-9a7a34585cb8",
        "price": 1800,
        "original_price": 2000
      }

      Parâmetros

      promotion_id: identificação da promoção.
      promotion_type: tipo de promoção (VOLUME).



      Modificar itens

      Não é possível modificar diretamente o preço de um item participante de uma campanha com desconto por volume. Para realizar uma alteração de preço, você deve seguir os seguintes passos:

      • Eliminar o item da campanha;
      • Modificar o preço do item como sincronização normal de preço;
      • Incluir o item novamente na campanha.

      • Nota:
        Os itens que participam das campanhas de desconto por volume não têm preço fixo, portanto, se um item estiver participando e seu preço aumentar, ele sairá automaticamente da oferta e você não poderá adicioná-lo novamente.
        - Recomendamos que você valide se o item está participando de uma campanha com desconto por volume ao fazer uma alteração de preço (manual ou automática) .

        Excluir itens

        Com este recurso você pode excluir a oferta do item.

        Chamada:

        curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/items/$ITEM_ID?promotion_type=$PROMOTION_TYPE&promotion_id=$PROMOTION_ID&offer_id=$OFFER_ID

        Exemplo:

        curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/items/MLA632979587?promotion_type=VOLUME&promotion_id=1804&offer_id=MLA876618673-9eafadd4-16d2-49ae-b272-9a7a34585cb8&app_version=v2'

        Resposta: Status 200 OK


        Conheça mais sobre Desconto por volume.


        Próxima: Desconto pré-acordado por item