Gerenciar promoções

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). 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 participação	MARKETPLACE CAMPAIGN	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 por volume	VOLUME	Usuário aceita	Não	Sim	Não	Sim	Não
Desconto pré-acordado por item	PRE_NEGOTIATED	Usuário concordar e aceita	Não	Sim	Sim	Sim	Não

Disponibilidade de promoção por país

Site	Campanha tradicional (DEAL)	Campanha com 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

Consultar as promoções disponíveis para o 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'

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/users/631366846'

Resposta:


    {
	"results": [{
			"id": "MLB686",
			"type": "DEAL",
			"status": "started",
			"start_date": "2020-02-04T17:50:00Z",
			"finish_date": "2022-10-31T17:20:00Z",
			"deadline_date": "2020-01-30T02:00:00Z",
			"name": "HOTSALE"
		},
		{
			"id": "DOD-MLB1000",
			"type": "DOD",
			"status": "started",
			"start_date": "2000-01-01T00:00:00.000Z"
		},
		{
			"id": "LGH-MLB1000",
			"type": "LIGHTNING",
			"status": "started",
			"start_date": "2000-01-01T00:00:00.000Z"
		},
		{
			"id": "P-MLB379009",
			"type": "VOLUME",
			"status": "started",
			"start_date": "2021-03-25T16:40:00Z",
			"finish_date": "2021-04-30T18:00:00Z",
			"name": "test volume MLB",
			"benefits": {
				"type": "VOLUME",
				"meli_percent": 8,
				"seller_percent": 17,
				"name": "4x3",
				"buy_quantity": 4,
				"pay_quantity": 3,
				"item_discount_percent": 25
			}
		},
		{
			"id": "P-MLB380001",
			"type": "VOLUME",
			"status": "started",
			"start_date": "2021-03-25T19:00:00Z",
			"finish_date": "2021-04-30T18:00:00Z",
			"name": "test volume MLB BNSP",
			"benefits": {
				"type": "VOLUME",
				"meli_percent": 10,
				"seller_percent": 30,
				"name": "buy 4 save 40%",
				"buy_quantity": 4,
				"item_discount_percent": 40
			}
		},
		{
			"id": "P-MLB380002",
			"type": "VOLUME",
			"status": "started",
			"start_date": "2021-03-25T19:30:00Z",
			"finish_date": "2021-04-30T18:00:00Z",
			"name": "test volume MLB SPONTH",
			"benefits": {
				"type": "VOLUME",
				"meli_percent": 8,
				"seller_percent": 17,
				"name": "save 50% on 2nd",
				"buy_quantity": 2,
				"item_discount_percent": 25
			}
		},
		{
			"id": "P-MLB382001",
			"type": "MARKETPLACE_CAMPAIGN",
			"status": "started",
			"start_date": "2021-03-25T22:36:00Z",
			"finish_date": "2021-04-30T18:00:00Z",
			"name": "test cofondeada",
			"benefits": {
				"type": "REBATE",
				"meli_percent": 2,
				"seller_percent": 8
			}
		},
		{
			"id": "P-MLM394001",
			"type": "PRE_NEGOTIATED",
			"status": "started",
			"start_date": "2021-03-30T18:30:15.525Z",
			"finish_date": "2021-12-27T17:59:59.525Z",
			"deadline_date": "2021-05-27T17:59:59.525Z",
			"name": "Prueba descuento x item sin benefit"
		}
	],
	"paging": {
		"offset": 0,
		"limit": 50,
		"total": 7
	}
}

Campos de resposta

id: código de identificação da promoção.
type: tipo de oferta (DEAL, MARKETPLACE_CAMPAIGN, DOD, LIGHTNING, PRE NEGOTIATED).
status: Status.
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.

Consultar 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

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'  https://api.mercadolibre.com/seller-promotions/candidates/CANDIDATE- MLB1254949426-803130663

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).
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 status.

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/offers/$OFFERS_ID

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/offers/OFFER-MLB1970246686-42701792

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).
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'

Saiba mais sobre campanha tradicional, campanha com participação do Mercado Livre, desconto por volume e desconto pré-acordado por item. .

Status

Abaixo você encontra os possíveis status que os 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:

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTIONS_ID/items?promotion_type=PROMOTION_TYPE'

Além disso, poderá consultar itens de uma campanha tradicional, itens em uma campanha com participação do Mercado Livre e os itens que podem acessar descontos por volume.
Aqui você pode verificar os itens de uma oferta do dia, de uma oferta relâmpago e o status da campanha com um desconto pré-acordado por item.

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?promotion_type=DEAL&status=$STATUS&item_id=$ITEM_ID

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

Resposta:

{
   "results": [
       {
           "id": "MLA604400000",
           "status": "rejected",
           "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=approved

Resposta:

{
   "results": [
       {
            "id": "MLA639970000",
            "status": "started",
            "price": 4037,
            "original_price": 4427
        },
        {
            "id": "MLA639973333",
            "status": "started",
            "price": 6007,
            "original_price": 6587
        },
],
   "paging": [...]
}

Paginação

Para realizar a paginação você deve usar o parametro de searchAfter. O valor enviado nesse parâmetro é sempre o ultimo id do item retornado na chamada anterior.

Chamada:

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

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/MLB9377/items?promotion_type=DEAL&searchAfter=MLB2674512267'

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",
       "limit": 50,
       "total": 14424
   }
}

Nota:

Se não utilizar o parâmetro limit, serão retornados por padrão 50 itens do total. Você poderá adicionar um limit máximo de 50.

Participar de uma promoção

Você pode participar de diversos tipos de promoções e até oferecer um desconto individual para itens:

Consultar as promoções de itens

Para ofertas DEALS, retornaremos apenas itens com status aprovado (status = aprovado).
Não aprovaremos as campanhas em teste e elas permanecerão com o status pending_approval, ou seja, você não verá o preço na promoção.

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/items/$ITEM_ID

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/items/MLA876768946

Resposta:

[
  {
    "id": "2864-MLB876768946",
    "type": "PRICE_DISCOUNT",
    "status": "started",
    "price": 700,
    "top_price": 650,
    "start_date": "2020-09-09T00:00:00",
    "finish_date": "2020-09-15T00:00:00"
  },
  {
    "id": "MLB686",
    "type": "DEAL",
    "status": "started",
    "price": 680,
    "start_date": "2021-03-04T17:50:00Z",
    "finish_date": "2021-10-31T17:20:00Z",
    "deadline_date": "2021-03-03T02:00:00Z",
    "name": "HOT SALE"
  },
  {
    "id": "P-MLB119001",
    "type": "MARKETPLACE_CAMPAIGN",
    "status": "started",
    "start_date": "2021-04-15T18:37:40.881Z",
    "finish_date": "2021-04-30T18:37:40.881Z",
    "name": "10% en herramientas",
    "benefits": {
           "type": "REBATE",
           "meli_percent": 2,
           "seller_percent": 8
       }
  },
  {
       "id": "1504782-MLA874447795",
       "type": "DOD",
       "status": "started",
       "price": 789,
       "start_date": "2021-04-19T00:00:00",
       "finish_date": "2021-04-19T23:59:59.999999999"
   },
   {
       "id": "1499515-MLA915978647",
       "type": "LIGHTNING",
       "status": "started",
       "price": 745,
       "start_date": "2021-04-19T06:00:00",
       "finish_date": "2021-04-19T12:00:00",
       "remaining_stock": 3
   },
   {
       "id": "P-MLB379009",
       "type": "VOLUME",
       "status": "started",
       "start_date": "2021-03-25T16:40:00Z",
       "finish_date": "2021-04-30T18:00:00Z",
       "name": "test volume MLB",
       "benefits": {
           "type": "VOLUME",
           "meli_percent": 8,
           "seller_percent": 17,
           "name": "4x3",
           "buy_quantity": 4,
           "pay_quantity": 3,
           "item_discount_percent": 25
       }
   },
   {
       "id": "P-MLM394001",
       "type": "PRE_NEGOTIATED",
       "status": "started",
       "start_date": "2021-03-30T18:30:15.525Z",
       "finish_date": "2021-12-27T17:59:59.525Z",
       "deadline_date": "2021-05-27T17:59:59.525Z",
       "name": "Prueba descuento x item sin benefit",
       "offers": [
           {
               "id": "MLM848619385-f588cf87-e298-498e-82ad-285b16dd11d5",
               "original_price": 101,
               "new_price": 21,
               "status": "active",
               "start_date": "2021-05-10T16:00:00Z",
               "end_date": "2021-05-11T15:00:00Z",
               "benefits": {
                   "type": "REBATE",
                   "meli_percent": 9.9,
                   "seller_percent": 69.3
               }
           }
       ]
   }

]

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:

Atribuir campanha para teste

Para fazer testes com campanhas teste, envie os dados de seu usuário e/ou itens no seguinte formulário.
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