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

Desconto individual

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 que desejam oferecer uma oferta individual para seus itens com os seguintes recursos poderão fazê-lo. Eles terão a possibilidade de aplicar, eliminar e consultar o desconto.


Para oferecer este desconto é necessário:

  • Tenha uma reputação verde.
  • O item deve ter um status igual a ativo ou pausado.
  • Condição igual a nova.
  • A exibição do item não pode ser gratuita.
  • E apenas para MLA esse tipo de desconto não está disponível nas categorias de livros.


Oferecer desconto

Para este tipo de oferta, você deve atender a alguns requisitos. Saiba mais sobre como oferecer descontos.


Nota:
Agora no body, para oferecer descontos você deve enviar preços, não porcentagens (deal_price em vez de discount_percent e top_deal_price em vez de top_discount_percent).

Chamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN'
-d '{
   "deal_price": $DEAL_PRICE,
   "top_deal_price": $TOP_DEAL_PRICE,
   "start_date": "$START_DATE",
   "finish_date": "$FINISH_DATE",
   "promotion_type": "PRICE_DISCOUNT"
}'
https://api.mercadolibre.com/seller-promotions/items/$ITEM_IDapp_version=v2

Exemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN'
-d '{
   "deal_price": 20,
   "top_deal_price": 30,
   "start_date": "2023-04-19T00:00:00",
   "finish_date": "2024-04-20T00:00:00",
   "promotion_type": "PRICE_DISCOUNT"
}'
https://api.mercadolibre.com/seller-promotions/items/MLA876768946?app_version=v2'

Resposta:

{
    "price": 70,
    "original_price": 100
}

Parâmetros

deal_price: preço do item com desconto para todos os compradores.
top_deal_price: preço do item com desconto para os melhores compradores (com Mercado Pontos nível 3 a 6) (opcional).
start_date: data de início do desconto.
finish_date: data de fim do desconto.


Considerações

  • É possível segmentar a oferta de desconto, estabelecendo um preço geral para todos os compradores, e um menor para nossos compradores fiéis (com Mercado Pontos nível3 a 6).
  • O desconto geral deve ser no mínimo 5% menor que o desconto de usuários dos níveis 3 a 6, para descontos de até 35%. Para descontos maiores que 35%, a diferença deve ser de no mínimo 10%, ou seja, garantimos melhores descontos aos níveis mais altos.
  • O desconto máximo deve ser menor a 80% e o desconto mínimo maior o igual a 5%.
  • Se o preço do produto é alterado para mais, os descontos serão removidos automaticamente.
  • Se o produto estiver associado a uma oferta do tipo DEAL na data de início do desconto, o desconto do tipo PRICE_DESCOUNT só será aplicado quando a outra oferta for finalizada.
  • O prazo máximo para um desconto do tipo PRICE_DESCOUNT é de 31 dias.
Nota:
Para usuários de TESTE é necessário que a conta tenha reputação verde e o item tenha no mínimo 1 venda com o preço atual.


Estado do item

Possíveis estado que os itens podem assumir quando deseja aplicar um desconto individual.



Estado Descrição
started Desconto ativo no item.
finished Desconto finalizado.
pending Desconto programado.
sync_requested Processo de ativação pendente.
restore_requested Processo pendente de exclusão do desconto..
candidate Item candidato a participar da promoção.


Excluir desconto individual para um item

Chamada:

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

Exemplo:

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

Para ofertas do tipo PRICE_DISCOUNT exclua todo o desconto, não é possível finalizar o desconto por níveis.


Resposta: Status 200 OK



Erros

Desconto fora do range estabelecido.

{
   "key":"buyer_discount_not_in_range",
   "message":"buyers_discount_percentage parameter must be in range (5, 80)"
}
{
   "key":"best_buyer_discount_not_in_range",
   "message":"buyers_discount_percentage parameter must be in range (5, 80)"
}

Diferença entre descontos para níveis 1-2 e níveis 3-6 fora da margem estabelecida

{
   "key":"discount_below_10_percent_difference",
   "message":"The best buyer discount difference cannot be below 10% when buyers discount is above 35%"
}
{
   "key":"discount_below_5_percent_difference",
   "message":"The discount difference cannot be below 5%"
}

Quando o desconto não for suficiente e o vendedor precisar aplicar um desconto maior, retornaremos:

{
    "key": "error_credibility_price",
    "message": "The price is not credible."
}

Conheça mais sobre Desconto individual.


Próxima: Ofertas do dia