Developers

Documentação do Mercado Livre

Confira todas as informações necessárias sobre as APIs Mercado Livre.

Última atualização em 19/12/2023

Campanhas de cupons do vendedor

Importante:

Essa campanha está disponível apenas para MLB.
A partir de 10 de janeiro de 2024, removeremos a versão antiga do recurso /seller-promotions.
Para obter a resposta com a nova versão, envie o parâmetro de consulta app_version=v2. Consulte a documentação de cada campanha para se atualizar sobre as mudanças.

Os vendedores podem criar suas próprias campanhas de cupons. Nesse tipo de campanha, o desconto é aplicado sobre o valor total da venda dos produtos participantes e é acumulativo com a promoção ativa (apenas um cupom por venda é permitido). Existem dois tipos de campanhas de cupons, aquelas com código de cupom, nas quais apenas os compradores que possuem esse código terão acesso ao desconto, e aquelas sem código de cupom onde todos os compradores que visualizam as publicações podem acessar esse desconto. Nesse caso, o Mercado Livre se encarregará de destacar o desconto por cupom nessas publicações que participam da campanha de cupons.

Nota:

O prazo máximo para este tipo de campanha é de 31 dias.

Para oferecer esse desconto, é necessário:

Ter uma reputação verde.
O item deve ter status igual a ativo ou pausado.
Condição igual a novo.
A exposição do item não pode ser gratuita.

Esses são os mesmos critérios para que o item participe de uma campanha de desconto individual, ou seja, se o item é candidato para essa campanha, automaticamente também atende aos critérios para participar de uma campanha de cupons do vendedor.

Criar campanha

Existem dois tipos de campanhas de cupons (com código ou sem código), mas também existem dois sub_type: FIXED_PERCENTAGE e FIXED_AMOUNT.

FIXED_AMOUNT: é o valor fixo de desconto, independente do preço total acumulado dos itens que participam desta campanha no carrinho do comprador.

FIXED_PERCENTAGE: é a porcentagem fixa de desconto e depende do preço total acumulado dos itens que participam desta campanha no carrinho do comprador.

Para criar uma campanha de cupons do vendedor, faça a seguinte chamada:

Exemplo "sub_type": "FIXED_AMOUNT" com código de cupom:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions?app_version=v2

  {
     "promotion_type": "SELLER_COUPON_CAMPAIGN",
     "name": "test_coupon",
     "sub_type": "FIXED_AMOUNT",
     "start_date": "2023-10-14T00:00:00",
     "finish_date": "2023-10-30T00:00:00",
     "fixed_amount": 200,
     "min_purchase_amount": 1000,
     "partial_coupon_code": "MYCODE",
     "budget": 10000
  }

Exemplo “sub_type”: “FIXED_AMOUNT” sem código de cupom:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions?app_version=v2

      {
         "promotion_type": "SELLER_COUPON_CAMPAIGN",
         "name": "test_coupon",
         "sub_type": "FIXED_AMOUNT",
         "start_date": "2023-10-14T00:00:00",
         "finish_date": "2023-10-30T00:00:00",
         "fixed_amount": 200,
         "min_purchase_amount": 1000,
         "budget": 10000
      }

Exemplo “sub_type”: “FIXED_PERCENTAGE” com código de cupom:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions?app_version=v2
      
      {
         "promotion_type": "SELLER_COUPON_CAMPAIGN",
         "name": "test_coupon",
         "sub_type": "FIXED_PERCENTAGE",
         "start_date": "2023-10-14T00:00:00",
         "finish_date": "2023-10-30T00:00:00",
         "fixed_percentage": 10,
         "min_purchase_amount": 1000,
         "max_purchase_amount": 200,
         "partial_coupon_code": "MYCODE",
         "budget": 10000
      }

Exemplo "sub_type": "FIXED_PERCENTAGE" sin código de cupom:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions?app_version=v2
      
      {
         "promotion_type": "SELLER_COUPON_CAMPAIGN",
         "name": "test_coupon",
         "sub_type": "FIXED_PERCENTAGE",
         "start_date": "2023-10-14T00:00:00",
         "finish_date": "2023-10-30T00:00:00",
         "fixed_percentage": 10,
         "min_purchase_amount": 1000,
         "max_purchase_amount": 200,
         "budget": 10000
      }

Campos da chamada

promotion_type (Obligatorio): tipo de campanha a ser criada, neste caso, SELLER_COUPON_CAMPAIGN.
name (Obligatorio): nome da campanha (apenas visível para o vendedor, o comprador não o verá).
sub_type (Obligatorio): subtipo de campanha a ser criado. Para campanhas de cupons do vendedor, os subtipos permitidos são FIXED_PERCENTAGE (porcentagem fixa) e FIXED_AMOUNT (valor fixo).
fixed_percentage: porcentagem de desconto da promoção. Somente obrigatório para o subtipo FIXED_PERCENTAGE.
fixed_amount: valor do desconto da promoção. Somente obrigatório para o subtipo FIXED_AMOUNT.
min_purchase_amount (Obligatorio): valor mínimo de compra para que o cupom seja aplicável.
max_purchase_amount: valor máximo de reembolso para o total da compra em que o cupom foi aplicado. Somente obrigatório para o subtipo FIXED_PERCENTAGE.
start_date (Obligatorio): data de início da campanha no formato local. Sempre considerará o início do dia como horário de início.
finish_date (Obligatorio): data de término da campanha no formato local. Sempre considerará o final do dia como horário de término.
partial_coupon_code: código parcial do cupom. Opcional. Apenas compradores com esse código poderão usá-lo para sua compra, e o valor final deste campo será composto pelos primeiros cinco caracteres do apelido do vendedor concatenados ao valor enviado (Máximo 10 caracteres). Caso este campo não seja enviado, todos os compradores que visualizarem as publicações do vendedor poderão usar esse cupom.
budget (Obligatorio): orçamento destinado à campanha. Uma vez esgotado, a campanha é encerrad.

Resposta sub_type FIXED_AMOUNT com código de cupom:

{
   "id": "C-MLB1",
   "type": "SELLER_COUPON_CAMPAIGN",
   "sub_type": "FIXED_AMOUNT",
   "fixed_amount": 200,
   "min_purchase_amount": 1000,
   "status": "pending",
   "start_date": "2023-10-14T00:00:00Z",
   "finish_date": "2023-11-01T02:59:59Z",
   "name": "test_coupon",
   "coupon_code": "NICKNMY_CODE",
   "redeems_per_user": 1,
   "budget": 10000,
   "remaining_budget": 10000,
   "used_coupons": 0
}

Resposta sub_type FIXED_AMOUNT sem código de cupom:

{
   "id": "C-MLB1",
   "type": "SELLER_COUPON_CAMPAIGN",
   "sub_type": "FIXED_AMOUNT",
   "fixed_amount": 200,
   "min_purchase_amount": 1000,
   "status": "pending",
   "start_date": "2023-10-14T00:00:00Z",
   "finish_date": "2023-11-01T02:59:59Z",
   "name": "test_coupon",
   "redeems_per_user": 1,
   "budget": 10000,
   "remaining_budget": 10000,
   "used_coupons": 0
}

Resposta sub_type FIXED_PERCENTAGE com código de cupom:

{
   "id": "C-MLB1",
   "type": "SELLER_COUPON_CAMPAIGN",
   "sub_type": "FIXED_AMOUNT",
   "fixed_percentage": 10,
   "min_purchase_amount": 1000,
   "max_purchase_amount": 200,
   "status": "pending",
   "start_date": "2023-10-14T00:00:00Z",
   "finish_date": "2023-11-01T02:59:59Z",
   "name": "test_coupon",
   "coupon_code": "NICKNMY_CODE",
   "redeems_per_user": 1,
   "budget": 10000,
   "remaining_budget": 10000,
   "used_coupons": 0
}

Resposta sub_type FIXED_PERCENTAGE sem código de cupom:

{
   "id": "C-MLB1",
   "type": "SELLER_COUPON_CAMPAIGN",
   "sub_type": "FIXED_AMOUNT",
   "fixed_percentage": 10,
   "min_purchase_amount": 1000,
   "max_purchase_amount": 200,
   "status": "pending",
   "start_date": "2023-10-14T00:00:00Z",
   "finish_date": "2023-11-01T02:59:59Z",
   "name": "test_coupon",
   "redeems_per_user": 1,
   "budget": 10000,
   "remaining_budget": 10000,
   "used_coupons": 0
}

Campos da Resposta

id: identificador da campanha no formato C-{siteId}XXXXX. Exemplo: "C-MLB123"
type: tipo da campanha (SELLER_COUPON_CAMPAIGN).
sub_type: subtipo da campanha (FIXED_AMOUNT ou FIXED_PERCENTAGE).
fixed_percentage: valor da porcentagem de desconto. Retorna sempre que a campanha for do subtipo FIXED_PERCENTAGE.
fixed_amount: valor do desconto em quantia fixa. Retorna sempre que a campanha for do subtipo FIXED_AMOUNT.
min_purchase_amount: valor mínimo de compra.
max_purchase_amount: valor máximo de reembolso. Retorna sempre que a campanha for do subtipo FIXED_PERCENTAGE.
status: estado da campanha. Pode ser pending (pendente) ou started (iniciada).
start_date: data de início da campanha.
finish_date: data de término da campanha.
name: nome usado para identificar a campanha.
coupon_code: código do cupom. Se o nickname do vendedor for NICKNAME1234, o coupon_code será NICKN + o código completado pelo usuário.
redeems_per_user: Quantidade de vezes que um usuário pode usar o cupom desta campanha. Sempre é 1, o comprador poderá utilizar o cupom apenas uma vez.
budget: orçamento destinado à campanha, totalmente responsabilidade do vendedor.
remaining_budget: orçamento restante da campanha.
used_coupons: quantidade total de cupons usados pelos compradores.

Atualizar campanha

Para atualizar a campanha, envie apenas os campos que deseja modificar. O único obrigatório é promotion_type, que deve estar sempre presente.

Campos que podem ser atualizados:

name
start_date
finish_date
budget
fixed_amount: somente para subtipo FIXED_AMOUNT.
fixed_percentage: somente para subtipo FIXED_PERCENTAGE.
min_purchase_amount
max_purchase_amount: somente para subtipo FIXED_PERCENTAGE.

Nota:

Para as campanhas no estado STARTED, só é possível modificar os seguintes campos:

finish_date
budget: só é possível aumentar.
name

Exemplo:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTION_ID?app_version=v2
    
    
    {
       "promotion_type": "SELLER_COUPON_CAMPAIGN",
       "name": "test_coupon_modified",
       "start_date": "2023-10-19T00:00:00",
       "finish_date": "2023-11-05T00:00:00",
       "fixed_percentage": 11,
       "min_purchase_amount": 1100,
       "max_purchase_amount": 270,
       "budget": 20000
    }

Respuesta:

{
       "id": "C-MLB1",
       "type": "SELLER_COUPON_CAMPAIGN",
       "sub_type": "FIXED_AMOUNT",
       "fixed_percentage": 11,
       "min_purchase_amount": 1100,
       "max_purchase_amount": 270,
       "status": "pending",
       "start_date": "2023-10-19T00:00:00Z",
       "finish_date": "2023-11-05T00:00:00Z",
       "name": "test_coupon_modified",
       "redeems_per_user": 1,
       "budget": 20000,
       "remaining_budget": 20000,
       "used_coupons": 0
    }

Excluir campanha

Para excluir uma campanha de cupons do vendedor, faça esta chamada:

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

Exemplo:

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

Resposta: Status 200 OK

Consultar detalhe da campanha

Para as campanhas de cupons do vendedor, existem dois subtipos e a opção de ter ou não o código do cupom:

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

Resposta sub_type FIXED_AMOUNT com código de cupom:

{
   "id": "C-MLB1082",
   "type": "SELLER_COUPON_CAMPAIGN",
   "sub_type": "FIXED_AMOUNT",
   "fixed_amount": 10,
   "min_purchase_amount": 100,
   "max_purchase_amount": 200,
   "status": "started",
   "start_date": "2023-09-14T03:00:00Z",
   "finish_date": "2023-10-01T02:59:59Z",
   "name": "test_coupon_004",
   "coupon_code": "NICKNCCODE004",
   "redeems_per_user": 1,
   "budget": 1000,
   "remaining_budget": 1000,
   "used_coupons": 0
}

Resposta sub_type FIXED_AMOUNT sem código de cupom:

{
   "id": "C-MLB1079",
   "type": "SELLER_COUPON_CAMPAIGN",
   "sub_type": "FIXED_AMOUNT",
   "fixed_amount": 50,
   "min_purchase_amount": 500,
   "max_purchase_amount": 1000,
   "status": "started",
   "start_date": "2023-09-14T03:00:00Z",
   "finish_date": "2023-10-01T02:59:59Z",
   "name": "test_coupon_002",
   "redeems_per_user": 1,
   "budget": 1000,
   "remaining_budget": 1000,
   "used_coupons": 0
}

Resposta sub_type FIXED_PERCENTAGE con código de cupom:

{
   "id": "C-MLB1081",
   "type": "SELLER_COUPON_CAMPAIGN",
   "sub_type": "FIXED_PERCENTAGE",
   "fixed_percentage": 5,
   "min_purchase_amount": 10,
   "max_purchase_amount": 100,
   "status": "started",
   "start_date": "2023-09-14T03:00:00Z",
   "finish_date": "2023-10-01T02:59:59Z",
   "name": "test_coupon_003",
   "coupon_code": "NICKNCODE003",
   "redeems_per_user": 1,
   "budget": 1000,
   "remaining_budget": 1000,
   "used_coupons": 0
}

Resposta sub_type FIXED_PERCENTAGE com código de cupom:

{
   "id": "C-MLB1067",
   "type": "SELLER_COUPON_CAMPAIGN",
   "sub_type": "FIXED_PERCENTAGE",
   "fixed_percentage": 5,
   "min_purchase_amount": 10,
   "max_purchase_amount": 100,
   "status": "started",
   "start_date": "2023-09-14T03:00:00Z",
   "finish_date": "2023-10-01T02:59:59Z",
   "name": "test_coupon_001",
   "redeems_per_user": 1,
   "budget": 1000,
   "remaining_budget": 1000,
   "used_coupons": 0
}

Estados

Estes são os diferentes estados pelos quais uma campanha de cupons do vendedor pode passar.

Estado	Descrição
pending	Promoção aprovada que ainda não iniciou.
started	Promoção ativa.
finished	Promoção finalizada.
deleted	Promoção excluída.

Consultar itens em uma campanha

Para conhecer os itens que fazem parte de uma campanha de cupons do vendedor, faça a seguinte consulta:

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

Resposta sub_type FIXED_AMOUNT:

{
             "results": [
                 {
                     "id": "MLB4096076774",
                     "status": "candidate",
                     "price": 0,
                     "original_price": 3346,
                     "fixed_amount": 200,
                     "start_date": "2023-12-07T00:00:00",
                     "end_date": "2024-01-06T23:59:59",
                     "sub_type": "FIXED_AMOUNT"
                 }
             ],
             "paging": {
                 "total": 1,
                 "limit": 50
             }
          }

Resposta sub_type FIXED_PERCENTAGE:

{
             "results": [
                 {
                     "id": "MLB4096076774",
                     "status": "candidate",
                     "price": 0,
                     "original_price": 3346,
                     "fixed_percentage": 15,
                     "start_date": "2023-12-07T00:00:00",
                     "end_date": "2024-01-06T23:59:59",
                     "sub_type": "FIXED_PERCENTAGE"
                 }
             ],
             "paging": {
                 "total": 1,
                 "limit": 50
             }
          }

Estado dos itens

Estes são os possíveis estados que os itens podem ter dentro deste tipo de campanha.

Estado	Descrição
candidated	Item candidato para participar da promoção.
pending	Item com promoção aprovada e programada.
started	Item ativo na campanha.
finished	Item removido da campanha.

Indicar itens para uma campanha

Uma vez que você tem itens candidatos a participar desta campanha, pode indicar quais produtos deseja incluir. Não são enviados preços, pois se trata de um cupom de desconto aplicado no checkout da compra do comprador.

Exemplo sub_type FIXED_PERCENTAGE:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
-d '{
  "promotion_id":"C-MLB1081",
  "promotion_type":"SELLER_COUPON_CAMPAIGN"


}'
https://api.mercadolibre.com/seller-promotions/items/MLB123456789?app_version=v2

Resposta:

{
   "price": 0,
   "original_price": 0,
   "promotion_name": "test_coupon_001",
   "fixed_percentage": 5
}

Os preços são sempre 0 porque a oferta não tem um preço, sendo um desconto aplicado no checkout da compra.

Importante:

Não é possível modificar um item na campanha, pois são valores ou porcentagens de desconto fixo e estão vinculados à configuração da campanha.

Eliminar campaña

Para excluir uma campanha de cupons do vendedor, realizar esta chamada:

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

Exemplo:

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

Resposta: Status 200 OK

Erros de validação

400 Bad Request

Mensagem de erro	Descrição
start_date cannot be earlier than today	A data de início da campanha não pode ser anterior à data atual.
finish_date cannot be earlier than start_date	A data de término não pode ser anterior à data de início da campanha.
maximum period cannot exceed the allowed	Quando se tenta atualizar alguma data (início, término ou ambas) e o novo período entre elas excede o limite permitido de 31 dias.
minimum period cannot be lower than allowed	Quando se tenta atualizar alguma data (início, término ou ambas), e o novo período entre elas é menor do que o permitido de 1 dia.
the field {field} not upgradable	Quando se tenta modificar um campo não permitido quando a promoção está no estado STARTED.
the promotion budget cannot be decreased	O budget só pode ser aumentado.
the name already exists	Já existe uma campanha de cupons do vendedor com o mesmo nome.
the fixed_percentage is greater than allowed	O máximo de porcentagem permitido é 70%. Se for enviado, por exemplo, fixed_percentage: 71..
the fixed_percentage is less than allowed	O mínimo permitido é 5%. Se for enviado, por exemplo, fixed_percentage: 4.
The max_purchase_amount should be greater than min value allowed {value}	O valor do campo max_purchase_amount deve ser maior que o mínimo permitido. Para a MLB, por exemplo, é 5.
The fixed_percentage applied to min purchase amount should be lower than max purchase amount value	O valor do benefício aplicado ao montante mínimo de compra deve ser menor que o valor do montante máximo de reembolso.
The promotion budget should be greater than max purchase amount value when campaign subtype is fixed percentage	Quando o budget é menor que o montante máximo de reembolso para este subtipo.
The fixed_amount should be greater than min value allowed {value}	O valor do campo fixed_amount deve ser maior que o mínimo permitido. Para todos os sites, é 0.
The fixed_amount should be lower than min purchase amount value	Quando o valor do campo fixed_amount é maior que o valor do campo min_puchase_amount. Por exemplo, quando se deseja oferecer um desconto fixo de 10, mas o valor mínimo de compra para que o cupom seja aplicado é de 5.
The min_puchase_amount {value} should be bigger than the min value: {min_value}	Quando o valor do campo min_puchase_amount é menor do que o cálculo do percentual mínimo permitido usando o valor do campo fixed_amount.
The min_puchase_amount {value} should be lower than the max value: {max_value}	Quando o valor do campo min_puchase_amount é maior do que o cálculo do percentual máximo permitido usando o valor do campo fixed_amount.
The promotion budget should be greater than benefit value when campaign subtype is fixed amount	Quando o orçamento é menor do que o montante fixo de desconto para este subtipo.