Gerenciar promoções Mercado Shops

Conteúdos

Consultar promoções

→Promoções no Mercado Shops
↳Glossário de campos e parâmetros
→Consultar promoções

Gerenciar publicações com promoções

→Consultar promoções de uma publicação
→Consultar publicações por promoção
→Adicionar publicações a uma promoção
→Excluir uma publicação de uma promoção

Gerenciar promoções por loja

→Consultar promoções por loja
→Criar promoção por loja
→Modificar promoções por loja
→Excluir promoções por loja

Promoções no Mercado Shops

Com o recurso /seller-promotions você pode centralizar todos os tipos de promoções disponíveis no canal de Mercado Shops, como boleto (BOLETO), cupom (COUPON), descontos individuais (INDIVIDUAL), descontos tradicionais (TRADITIONAL e MASSIVE).
Além disso, no Mercado Shops você só precisa ter sua loja criada e ter itens para começar a usar a central de promoções do canal.

Glossário de campos e parâmetros

Campos	Descrição do campo	Valores possíveis para o campo e sua descrição
name	Nome da promoção.	String
code	Código de desconto.	String
description	Breve descrição da campanha de desconto.	String
discount_type	Tipo de desconto.	Os valores são “percent”: porcentagem e “fixed”: valor fixo.Para as massivas poderá contar com o valor “by_item”.
value	Valor de desconto aplicado.	Double
start_date	Data de início da promoção.	Valor do tipo string, p,e: "2021-11-01T00:00:00.000+0000".
end_date	Data fin da promoção (deve ser uma data maior que start_date).	Valor do tipo string, p,e: "2021-12-01T00:00:00.000+0000".
min_payment_amount	Valor mínimo de pagamento para aplicar o desconto.	Double
campaign_item_type	Este campo aplica para as campanhas tradicionais.	Os valores são “massive” ou “traditional”.
one_coupon_per_user	Identifica se a campanha do tipo cupom permite o uso do cupom mais de uma vez.	Booleano
status	Status da promoção.	Os valores são “active”: activo e “inactive”: inativo.
id	Id da promoção.	String
item_id	Id da publicação.	Poderá visualizá-la nas promoções individuais.
type	Tipo de campanha que o usuário deseja criar.	Os valores são “boleto”, “coupom”, “traditional”, “individual”.
target	Cobertura do produto, permite identificar se a campanha se aplica a todos os produtos, produtos selecionados ou se aplica a uma lista de produtos.	Os valores são “ALL_PRODUCTS”,” SELECTED_PRODUCTS”,”LISTED_PRODUCTS”.
shop_id	Identificador da loja/user.	Integer
value_discount	É o valor do desconto para o item (esse campo aplica apenas para a criação de campanhas massivas).	Double
discount_type	É o tipo de desconto que se aplica ao item (esse campo aplica apenas para a criação de campanhas massivas).	Os valores possíveis são “fixed_price” e “percent”.

Consultar promoções

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTION_ID?promotion_type=$TIPODEPROMOTION&channel=$CHANNEL

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/TR-496907760-202112031641564156?promotion_type=BOLETO&channel=mshops

Resposta de oferta tradicional:

'{
    "id": "TR-496907760-202112031641564156",
    "name": "Traditional Modificada 3",
    "status": "ACTIVE",
    "type": "TRADITIONAL",
    "start_date": "2120-03-14T00:00:00.000+00:00",
    "end_date": "2120-02-13T00:00:00.000+00:00",
    "target": "SELECTED_PRODUCTS",
    "discount_type": "PERCENT",
    "value": 10,
    "shop_id": 496907780,
    "campaign_item_type": "traditional"
}'

Resposta de cupom:

{
   "id": "10097749",
   "name": "Cupon OPEN PLATFORM",
   "status": "ACTIVE",
   "type": "coupon",
   "start_date": "2022-10-30T00:00:00.000+00:00",
   "end_date": "2022-10-31T00:00:00.000+00:00",
   "target": "ALL_PRODUCTS",
   "discount_type": "percent",
   "value": 10,
   "shop_id": 654461415,
   "description": "Esta es la descripción del cupon",
   "code": "TESTCODE",
   "use_limit": 1
}

Resposta de tradicional massiva:

{
   "id": "TRM-654461415-202202011726162616",
   "name": "Traditional Kike masiva prueba 3",
   "status": "ACTIVE",
   "type": "traditional",
   "start_date": "2120-03-14T00:00:00.000+00:00",
   "end_date": "2120-02-13T00:00:00.000+00:00",
   "target": "LISTED_PRODUCTS",
   "discount_type": "by_item",
   "shop_id": 654461415,
   "campaign_item_type": "massive"
}

Resposta por campanha não encontrada:

'{
    "message": "GET to /shops/635345120/discounts/00006720 returned 404 and {\"status_code\":404,\"code\":\"discount_not_found_exception\",\"message\":\"discount with campaign id 00006720 not found for shop 635345120\",\"stacktrace\":null,\"request_id\":\"2edcb000-aacf-41d4-834e-916e1bd922ac\"}",
    "error": "internal_server_error",
    "status": 500,
    "cause": []
}'

Resposta sobre promoções que não pertençam ao canal MShop:

'{
"message": "Invalid promotion type",
"error": "bad_request",
"status": 400,
"cause": []
}'

Parâmetros

promotion_type: tipo de promoção que vai consultar.
promotion_id: identificador da campanha/promoção a consultar.
channel: canal onde queremos consultar. Por padrão, disponibilizaremos marketplace.

Gerenciar publicações com promoções

Com o recurso /seller-promotions você pode gerenciar publicações com diferentes promoções, tanto para marketplace como Mercado Shops de forma diferenciada, permitindo fazer ações no nível da loja e não individual por itens.

Consultar promoções de uma publicação

Esta funcionalidade permite reconhecer todas as promoções que se estão ativas em uma publicação.

Chamada:

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

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/items/MLA932421975?channel=mshops

Resposta:

{
        "id": "TR-496907760-202112031641564156",
        "name": "Traditional Modificada 3",
        "status": "programmed",
        "type": "traditional",
        "start_date": "2120-03-13",
        "finish_date": "2120-02-12",
        "target": "SELECTED_PRODUCTS"
      "campaign_item_type": "traditional_campaign"
    }

Resposta se o item não existe:

{
    "message": "Item with id MLA082324822 not found",
    "error": "not_found",
    "status": 404,
    "cause": []
}

Resposta se não contam com acesso:

{
    "message": "Caller don't have permissions to access this item",
    "error": "forbidden",
    "status": 403,
    "cause": []
}

Parâmetros

Consultar publicações por promoção

Esta funcionalidade permite reconhecer todas as promoções que se estão ativas em uma publicação.

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTION_ID/items?channel=$CHANNEL&limit=$LIMIT&offset=$OFFSET

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/TR-496907760-202112031641564156/items?channel=mshops&limit=100&offset=0

Resposta:

{
   "items": [
       {
           "final_price": 90000,
           "id": "MLA1123020613",
           "original_price": 100000,
           "title": "Samsung Galaxy A10 32 Gb Azul 2 Gb Ram"
       },
       {
           "final_price": 1350,
           "id": "MLA897947944",
           "original_price": 1500,
           "title": "Sticker Tarjetas"
       },
       {
           "final_price": 1350,
           "id": "MLA838847599",
           "original_price": 1500,
           "title": "Billetera Ideal Para Gente Como Vos!"
       }
   ],
   "pagination": {
       "offset": 0,
       "limit": 100,
       "total": 3
   }
}

Parámetros

promotion_id: identificador da campanha/promoção a consultar.
user_id: identificação do vendedor o qual queremos conhecer as promoções que tem em sua loja.
channel: canal o qual queremos consultar. Por funcionalidade, disponibilizaremos marketplace.
limit: limite do número de publicações que devolve a consulta.
offset: número de publicações a omitir antes de começar a devolver as publicações pela consulta. (paginação)

Adicionar publicações a uma promoção

Chamada:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d {...}
https://api.mercadolibre.com/seller-promotions/users/$USER_ID/promotions/$PROMOTION_ID/items?channel=$CHANNEL

Exemplo para promoção tradicional:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
'{
    "items": [
        {
            "item_id": "MLA930546850"
        }
    ],
    "action": "add"
}'
https://api.mercadolibre.com/seller-promotions/users/496907760/promotions/10038085/items?channel=mshops

Exemplo para promoção massiva:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
{
   "items": [
       {
           "item_id": "MLA1112170643",
           "value_discount":10,
           "discount_type":"PERCENT"
       },
               {
           "item_id": "MLA931566278",
           "value_discount":10,
           "discount_type":"FIXED_PRICE"
       }
   ],
   "action": "add"
}
https://api.mercadolibre.com/seller-promotions/users/496907760/promotions/10038085/items?channel=mshops

Nota:

Considere que os campos de value_discount y discount_type, aplicam apenas para adicionar publicações para uma campanha massiva.

Resposta satisfatória:

{
    "status": "Success",
    "code": "201"
}

Parâmetros

promotion_id: identificador da campanha/promoção a consultar.
channel: canal onde queremos consultar. Por padrão, disponibilizaremos marketplace.
user_id: identificação do vendedor que queremos consultar as promoções que tem em sua loja.

Excluir uma publicação de uma promoção

Chamada:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d {...}
https://api.mercadolibre.com/seller-promotions/users/$USER_ID/promotions/$PROMOTION_ID/items?channel=$CHANNEL

Exemplo:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
'{
"items": [
{
"item_id": "MLA932423847"
}
],
"action": "delete"
}'

https://api.mercadolibre.com/seller-promotions/users/496907760/promotions/TR-496907760-202112031641564156/items?channel=mshops

Gerenciar promoções por loja

Com o recurso /seller-promotions você pode gerenciar diferentes promoções por cada loja do Mercado Shops de forma diferenciada.

Consultar promoções por loja

Com este recurso você pode consultar as promoções ativas de uma loja.

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/seller-promotions/users/$USER_ID?channel=$CHANNEL

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/users/496907760?channel=mshops

Resposta:

{
   "results": [
       {
           "id": "TR-496907760-202112031641564156",
           "name": "Traditional Modificada 3",
           "status": "ACTIVE",
           "type": "TRADITIONAL",
           "start_date": "2120-03-14T00:00:00.000+00:00",
           "end_date": "2120-02-13T00:00:00.000+00:00",
           "target": "SELECTED_PRODUCTS",
           "discount_type": "PERCENT",
           "value": 10,
           "shop_id": 496907780,
           "campaign_item_type": "traditional"
       },
       {
           "id": "INDIVIDUAL-MLB2038165685-202111021040184018",
           "status": "ACTIVE",
           "type": "INDIVIDUAL",
           "start_date": "2021-12-14T00:00:00.000+00:00",
           "end_date": "2021-12-20T00:00:00.000+00:00",
           "target": "SELECTED_PRODUCTS",
           "discount_type": "PERCENT",
           "value": 5,
           "shop_id": 496907780,
           "item_id": "MLB2038165685"
       },
       {
           "id": "10048392",
           "name": "Prueba usos",
           "status": "ACTIVE",
           "type": "coupon",
           "start_date": "2022-01-28T17:57:00.000+00:00",
           "end_date": "2022-10-29T05:00:00.000+00:00",
           "target": "ALL_PRODUCTS",
           "discount_type": "percent",
           "value": 20,
           "shop_id": 654461415,
           "description": "Usos",
           "code": "USOSCUPON",
           "use_limit": 1
       },
       {
           "id": "TRM-654461415-202201270318521852",
           "name": "Traditional Masivo",
           "status": "ACTIVE",
           "type": "traditional",
           "start_date": "2120-01-18T00:00:00.000+00:00",
           "end_date": "2120-02-13T00:00:00.000+00:00",
           "target": "LISTED_PRODUCTS",
           "discount_type": "by_item",
           "shop_id": 654461415,
           "campaign_item_type": "massive"
       }
   ]
}

Resposta com User_id inválido:

{
    "message": "Caller don't have permissions to access this user",
    "error": "forbidden",
    "status": 403,
    "cause": []
}

Parâmetros

user_id: identificação do vendedor que queremos consultar as promoções que tem em sua loja.
channel: canal onde queremos consultar. Por padrão, disponibilizaremos marketplace.

Criar promoção por loja

Com o seguinte recurso poderá criar uma promoção para la tienda completa, portanto ela será aplicada a todos os itens que estiverem ativos na mesma.

Chamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d 
{...}
https://api.mercadolibre.com/seller-promotions/users/$USER_ID?channel=$CHANNEL

Dependendo do tipo de promoção que publicar, o POST pode ter atributos como: "name", "discount_type", "value", "campaign_type", "start_date", "end_date", "target", "description", "code", "item_id", "min_payment_amount", "items", "action".

Exemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
'{
"name": "Nombre Promo Prueba",
"code": "PRUEBA3",
"description": "Descripción cupon",
"discount_type": "fixed",
"value": 50000,
"start_date": "2021-12-01T00:00:00.000+0000",
"end_date": "2021-12-02T00:00:00.000+0000",
"min_payment_amount": 50001,
"max_user_budget": 50000,
"budget": 100000,
"type": "coupon",
"one_coupon_per_user": true,
"status": "active"
}'
https://api.mercadolibre.com/seller-promotions/users/496907760?channel=mshops

Resposta de promoção criada:

{
    "id": "10029844",
    "name": "Nombre Promo Prueba",
    "status": "ACTIVE",
    "type": "COUPON",
    "start_date": "2021-12-01T00:00:00.000+00:00",
    "target": "ALL_PRODUCTS",
    "discount_type": "FIXED",
    "value": 50000,
    "shop_id": 496907780,
    "description": "Descripcion cupon",
    "code": "PRUEBA3"
}

Parâmetros:

user_id: identificação do vendedor que queremos consultar as promoções que tem em sua loja.
channel: canal onde queremos consultar. Por padrão, disponibilizaremos marketplace.

Parâmetros esperados por tipo de campanha:

PROPRIEDAD	BOLETO	COUPON	COUPON-FIXED	TRADITIONAL	TRADITIONAL-ITEM	TRADITIONAL-MASIVO	INDIVIDUAL
Name	Nome da promoção	Nome da promoção	Nome da promoção	Nome da promoção	Nome da promoção	Nome da promoção
Discount_type	PERCENT	PERCENT	FIXED	PERCENT	PERCENT	BY_ITEM
Value	Valor da promoção	Valor da promoção	Valor da promoção (preço fixo)	Valor da promoção	Valor da promoção		Valor da promoção
type	boleto	cupom	cupom	traditional	traditional	traditional	individual
start_date	Data de início	Data de início	Data de início	Data de início	Data de início	Data de início	Data de início
end_date	Data final	Data final	Data final	Data final	Data final	Data final	Data final
target				ALL_PRODUCTS	SELECTED_PRODUCTS	LISTED_PRODUCTS
min_payment_amount		Valor mínimo	Valor mínimo
Code		Código associado a promoção	Código associado a promoçãou
one_coupon_per_user			true ou false
items					Lista de itens na promoção
Item_id							Id do item
campaign_item_type				TRADITIONAL	TRADITIONAL	MASSIVE

Modificar promoções por loja

Com este recurso poder'realizar atualizações nas promoções de uma loja. Para isto é necessário ter o ID da loja e o ID da promoção que quiser modificar.

Chamada:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d {...}
https://api.mercadolibre.com/seller-promotions/users/$USER_ID/promotions/$PROMOTION_ID?channel=$CHANNEL

Explicações

Para cupom e cupom fixed poderá alterar as seguintes propriedades:

Name
Value (sempre e quando estiver programada)
start_date (sempre e quando estiver programada)
end_date (sempre e quando estiver programada)
Description
min Payment Amount (sempre e quando esteja programada)

Ao realizar uma alteração devem ser enviados ao menos os seguintes dados (assim apenas as propriedades antes mencionadas podem ser modificadas):

Name
Discount_type
Value
Type
start_date
end_date
start_date
code
min_payment_amount

Exemplo de coupon fixed:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
'{
"name": "Nombre Promo 1 fixed",
"discount_type": "fixed",
"value": 3000,
"type": "coupon",
"start_date": "2023-02-08T20:57:00.000+0000",
"end_date": "2023-12-02T00:00:00.000+0000",
"code": "PRUEBA3",
"min_payment_amount": 50005
}'
https://api.mercadolibre.com/seller-promotions/users/496907760/promotions/TR-496907760-202112031641564156?channel=mshops

Exemplo de cupom:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
'{
"name": "Nombre Promo 1 PERCENT",
"discount_type": "percent",
"value": 3000,
"type": "coupon",
"start_date": "2023-02-08T20:57:00.000+0000",
"end_date": "2023-12-02T00:00:00.000+0000",
"code": "PRUEBA3",
"min_payment_amount": 1
}'
https://api.mercadolibre.com/seller-promotions/users/496907760/promotions/TR-496907760-202112031641564156?channel=mshops

Explicações

Para boleto podem ser modificadas as seguites propriedades:

Name
Value (sempre e quando estiver programada)
start_date (sempre e quando estiver programada)
end_date (sempre e quando estiver programada)

Ao realizar uma alteração devem ser enviados ao menos os seguintes dados (assim apenas as propriedades antes mencionadas podem ser modificadas):

Name
Value
Type
start_date
end_date

Exemplo de boleto:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
'{
"name": "Nombre PROMO 1 BOLETO",
"value": 20,
"type": "boleto",
"start_date": "2022-02-08T20:57:00.000+0000",
"end_date": "2022-12-08T00:00:00.000+0000"
}'

https://api.mercadolibre.com/seller-promotions/users/496907760/promotions/TR-496907760-202112031641564156?channel=mshops

Explicações

Para tradicionais (ALL_PRODUCTS) poderá modificar as seguintes propriedades:

Name
start_date (sempre e quando estiver programada)
end_date (sempre e quando estiver programada)

Ao realizar uma alteração devem ser enviados ao menos os seguintes dados (assim apenas as propriedades antes mencionadas podem ser modificadas):

Name
Value
Type
start_date
end_date
target

Exemplo de tradicional ALL_PRODUCTS:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
'{
"name": "Traditional Mod",
"value":10,
"type": "traditional",
"start_date": "2022-02-18T08:00:00.000+0000",
"end_date": "2023-12-13T00:00:00.000+0000",
"target": "ALL_PRODUCTS"
}'
https://api.mercadolibre.com/seller-promotions/users/496907760/promotions/TR-496907760-202112031641564156?channel=mshops

Resposta com algum parâmetro incorreto:

{
    "message": "type mismatch for key [target]",
    "error": "bad_request",
    "status": 400,
    "cause": []
}

Parâmetros

user_id: identificação do vendedor que queremos consultar as promoções que tem em sua loja.
channel: canal onde queremos consultar. Por padrão, disponibilizaremos marketplace.
promotion_id: identificador da campanha/promoção a consultar.

Excluir promoções por loja

Chamada:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/users/$USER_ID/promotions/$PROMOTION_ID?channel=$CHANNEL

Ejemplo:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/users/496907760/promotions/INDIVIDUAL-MLA930546840-2021110811090191?channel=mshops