Documentação do Mercado Livre
Confira todas as informações necessárias sobre as APIs Mercado Livre.
Documentação
Campanhas de desconto por volume
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.
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
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.
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