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 15/10/2024

Campanhas de desconto por quantidade

Os vendedores agora têm controle sobre a criação de campanhas de descontos por quantidade veiculadas no site. A principal característica desse tipo de campanha é que o desconto é aplicado quando é atingido um determinado número de itens de um produto. Adicionamos também o conceito de descontos em diferentes volumes e situações de desconto, além do novo conceito de “campanha combinável” e “campanha não combinável” que melhora a flexibilidade do desconto


Importante:

O antigo mecanismo de desconto por volume criado pelo Mercado Livre foi descontinuado, as campanhas criadas e ativadas anteriormente a essa mudança serão mantidas até sua finalização. Por se tratar de uma campanha customizada, o Mercado Livre não entra com coparticipação, semelhante a campanha do vendedor.

Visão do vendedor






Criar campanha

Para este tipo de campanha existem 3 subtipos:


  • BNGM(Buy N get M): pague 3 e leva 9.
  • BNSP(Buy N save P%): 50% OFF comprando 2.
  • SPONTH(Save P% on the Nth): 50% OFF na 2a unidade.

    • Para criar uma campanha de volume do vendedor execute a seguinte chamada:


    Exemplo BNGM enviando buy_quantity, pay_quantity e allow_combination permitindo combinar items diferentes:

    curl -X POST -H 'https://api.mercadolibre.com/seller-promotions/promotions?app_version=v2' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
  "promotion_type": "VOLUME",
  "sub_type": "BNGM",
  "buy_quantity": 3,
  "pay_quantity": 2,
  "allow_combination": true,
  "name": "DxV teste BNGM",
  "start_date": "2024-08-29T00:00:00",
  "finish_date": "2024-09-29T00:00:00"
}
'

    Resposta:

    {
   "id": "C-MLB5790",
   "type": "VOLUME",
   "sub_type": "BNGM",
   "status": "pending",
   "start_date": "2024-08-29T00:00:00",
   "finish_date": "2024-09-29T23:59:59",
   "name": "DxV teste BNGM",
   "buy_quantity": 3,
   "pay_quantity": 2,
   "allow_combination": true
}

    Exemplo BNSP enviando buy_quantity, discount_percentage e allow_combination não permitindo combinar itens diferentes:

    curl -X POST -H 'https://api.mercadolibre.com/seller-promotions/promotions?app_version=v2&version=test' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
  "promotion_type": "VOLUME",
  "sub_type": "BNSP",
  "buy_quantity": 5,
 "discount_percentage": 30,
  "allow_combination": false,
  "name": "DxV teste BNSP",
  "start_date": "2024-08-29T00:00:00",
  "finish_date": "2024-09-29T00:00:00"
}'

    Resposta:

    ​​{
   "id": "C-MLB5789",
   "type": "VOLUME",
   "sub_type": "BNSP",
   "status": "pending",
   "start_date": "2024-08-29T00:00:00",
   "finish_date": "2024-09-29T23:59:59",
   "name": "DxV teste BNSP",
   "buy_quantity": 5,
   "discount_percentage": 30,
   "allow_combination": false,
}

    Exemplo SPONTH enviando buy_quantity, discount_percentage e allow_combination permitindo combinar itens diferentes:

    curl -X POST -H 'https://api.mercadolibre.com/seller-promotions/promotions?app_version=v2&version=test' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
   "promotion_type": "VOLUME",
   "sub_type": "SPONTH",
   "buy_quantity": 2,
   "discount_percentage": 50,
   "allow_combination": true,
   "name": "DxV teste SPONTH",
  "start_date": "2024-08-29T00:00:00",
  "finish_date": "2024-09-29T00:00:00"
}'

    Resposta:

    {
   "id": "C-MLB5791",
   "type": "VOLUME",
   "sub_type": "SPONTH",
   "status": "pending",
   "start_date": "2024-08-29T00:00:00",
   "finish_date": "2024-09-29T23:59:59",
   "name": "DxV teste SPONTH",
   "buy_quantity": 2,
   "discount_percentage": 50,
   "allow_combination": true
}
  • promotion_type: VOLUME. Obrigatório.
  • name: nome da campanha. Obrigatório.
  • start_date y finish date:vigência da campanha. Obrigatório
  • allow_combination:caso true, permite a combinação de itens. Obrigatório.
  • sub_type:pode ser BNGM, BNSP ou SPONTH. Obrigatório.

    • De acordo com subtype, é necessário enviar 2 dos seguintes campos: buy_quantity, pay_quantity, discount_percentage.

  • BNGM: necessário enviar buy_quantity indicando a quantidade a comprar (ex. 9) e pay_quantity, indicando a quantidade que realmente se paga (ex. 3).
  • BNSP: É necessário enviar buy_quantity indicando a quantidade a comprar (ex. 2) e discount_percentage, indicando o percentual de desconto (ex. 50).
  • SPONTH: buy_quantity indicando a quantidade a comprar (ex. 2) e discount_percentage indicando o percentual de desconto na unidade (ex. 50).


    • Atualizar campanha

    Para atualizar as campanhas de desconto por volume se deve considerar os seguintes pontos:

  • Sempre deverá enviar o campo promotion_type (que deverá ter o valor VOLUME).
  • Não é possível modificar o start_date e finish date.
  • Para as campanhas ativas, somente é possível modificar o nome.

    • Para as campanhas já programadas, é necessário somente enviar os campos que deseja modificar, considerando os seguintes pontos:

  • Caso queira modificar os atributos de uma campanha (buy_quantity, pay_quantity, discount_percentage) ou modificar seu subtype, deverá indicar todos os atributos correspondentes segundo o subtipo, por más que não sofram modificações.

    • Exemplo:

    curl --location --request PUT 'https://api.mercadolibre.com/seller-promotions/promotions/C-MLB5783?app_version=v2&version=test' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
   "promotion_type": "VOLUME",
   "sub_type": "BNSP",
   "buy_quantity": 9,
   "discount_percentage": 30,
   "allow_combination": false,
   "name": "campanha de teste"
}'

    Resposta:

    {
   "id": "C-MLB5783",
   "type": "VOLUME",
   "sub_type": "BNSP",
   "status": "pending",
   "start_date": "2024-08-29T00:00:00",
   "finish_date": "2024-09-29T23:59:59",
   "name": "campanha de teste",
   "buy_quantity": 9,
   "discount_percentage": 30,
   "allow_combination": false
}


    Eliminar campanha

    Para eliminar uma campanha do vendedor deve fazer esta chamada:

    curl --location --request DELETE 'https://api.mercadolibre.com/seller-promotions/promotions/{{Promo-ID}}?promotion_type=VOLUME&app_version=v2' \
--header 'Authorization: Bearer {{token}}'

    A resposta bem-sucedida é um código 200 OK, com o corpo definido como nulo (null).



    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": "C-MLB5790",
   "type": "VOLUME",
   "sub_type": "BNGM",
   "status": "started",
   "start_date": "2024-08-29T03:00:00Z",
   "finish_date": "2024-09-30T02:59:59Z",
   "name": "DxV teste BNGM",
   "buy_quantity": 3,
   "pay_quantity": 2,
   "allow_combination": false
}

    Campos da resposta

  • id: identificador da campanha.
  • type: tipo de campanha (VOLUME).
  • sub_type: BNGM, BNSP ou SPONTH.
  • status: estado atual da campanha.
  • start_date e finish_date: vigência da campanha.
  • allow_combination: caso true, permite a combinação de itens
  • name: nome da campanha
  • buy_quantity: indica a quantidade a comprar
  • pay_quantity: indica a quantidade que realmente se paga
  • discount_percentage: indicando o percentual de desconto.
  • allow_combination: caso true, permite a combinação de itens.




    • 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": "MLB5000888672",
           "status": "candidate",
           "price": 0,
           "original_price": 105,
           "start_date": "2024-08-29T03:00:00Z",
           "end_date": "2024-09-30T02:59:59Z",
           "sub_type": "BNGM",
           "buy_quantity": 3,
           "pay_quantity": 2,
           "allow_combination": false
       },
       {
           "id": "MLB4816253882",
           "status": "candidate",
           "price": 0,
           "original_price": 115,
           "start_date": "2024-08-29T03:00:00Z",
           "end_date": "2024-09-30T02:59:59Z",
           "sub_type": "BNGM",
           "buy_quantity": 3,
           "pay_quantity": 2,
           "allow_combination": false
       },
       {
           "id": "MLB4816242302",
           "status": "candidate",
           "price": 0,
           "original_price": 130,
           "start_date": "2024-08-29T03:00:00Z",
           "end_date": "2024-09-30T02:59:59Z",
           "sub_type": "BNGM",
           "buy_quantity": 3,
           "pay_quantity": 2,
           "allow_combination": false
       }
   ],
   "paging": {
       "total": 3,
       "limit": 50
   }
}

    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

    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