Recursos Cross

Confira os principais recursos das nossas APIs
circulos azuis em degrade

Documentação do

Você pode usar esta documentação para as seguintes unidades de negócio:

Última atualização em 08/09/2023

Preços de produtos

Importante:
Eliminaremos progresivamente:
  • Os campos price, base_price e original_price da API de /itens
  • O GET /prices/types/standard/channels/mshops utilizado para Mercado Shops
Por favor, utilize esta documentação para gerenciar preços de Mercado Livre e Mercado Shops.

Pode consultar os preços relativos a um produto e contexto (parâmetro para identificar o canal e/ou nível de comprador) para saber o valor exato da venda. Lembre-se disso para crear un anúncio e editá-lo você deve continuar fazendo isso por meio da API /items. Em breve, habilitaremos o endpoint para editar preços.

No Mercado Livre você pode ver os preços da seguinte forma:



Notificações sobre preços

Importante:
Em breve, quando o campo de preços for descontinuado da API /items, as notificações de itens não comunicarão mais as alterações de preços.

Para receber notificações sobre preços, você deve assinar o tópico items_prices . Após receber a notificação deverá consultar o recurso de /prices.


Obter preço de venda atual

Para conhecer o preço de venda, deve-se saber que os preços podem ser de tipo standard (preços por default sem promociones associadas) ou promoção (promocionais, o preço tem uma promoção).

Com o seguinte request identificar o preço de venda vencedor de um produto e filtre os preços por canal de vendas e/ou nível de comprador. Além disso, receberá informação sobre as promoções associadas ao artigo com o preço vencedor, que é apresentado ao comprador. Caso o token não pertença ao vendedor e item consultado, você não receberá informações do array de metadata (tipo de promoção associada).

Context: parâmetro opcional para filtrar canal de vendas e/ou nível de comprador. Recomendamos que você envie pelo menos um canal por vez e, opcionalmente, você pode adicionar cada loyalty_level. Valores possíveis:


CHANNEL (Canal de vendas)

  • channel_marketplace: canal Mercado Livre.
  • channel_mshops: canal Mercado Shops disponível para MLA, MLB, MLM, MLC y MCO. Conheça mais sobre Mercado Shops.
  • channel_proximity, mp_merchants e mp_links: canal de produtos publicados no Mercado Pago. Em breve estarão disponíveis.

LOYALTY_LEVEL (Nivel do comprador) não disponível em MLU e MPE

  • buyer_loyalty_3
  • buyer_loyalty_4
  • buyer_loyalty_5
  • buyer_loyalty_6

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/sale_price?context=$CHANNEL,LOYALTY_LEVEL

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA3191390879/sale_price?context=channel_marketplace,buyer_loyalty_3

Resposta:

{
    "price_id": "145",
    "amount": 39200.0,
    "regular_amount": 49000.0,
    "currency_id": "ARS",
    "reference_date": "2023-06-08T19:06:56Z",
    "metadata": {
        "promotion_id": "OFFER-MLA13456789-1122334455", --- Não aparece sem token de proprietário
        "promotion_type": "custom" --- Não aparece sem token de proprietário
    }
}

Descrição dos campos

price_id: ID do preço.
amount: preço da venda do produto.
regular_amount: preço original do produto, em casos que tenham promoção. O preço de strikeout do preço vencedor também é calculado e pode ser obtido de várias fontes. Não será necessariamente o mesmo que o 'regular_amount' do recurso /prices.
currency_id: ID da moeda à qual o campo amount e regular_amount se refere.
reference_date: data para a qual está calculando o preço de venda.
metadata: informações privadas do usuário relacionadas à promoção associada.

Importante:
Caso o item tenha preço promocional, os seguintes campos vão estar relacionados a Promoções. Você pode usá-los como entrada para realizar consultas específicas sobre promoções de marketplace e promoções de mshops.
promotion_id: ID da promoção. Com esse ID você pode consultar a oferta (item, promoção e estado). .
promotion_type: tipo de promoção Não é informado de qual campanha o item é.

Quando a promoção está ativa:

  • Caso o preço do item seja aumentado, as promoções serão descartadas, portanto não serão exibidas e não será necessário consultar a API de Promoções.
  • Se o preço for reduzido, o desconto do vendedor será ajustado. Se o preço ficar abaixo da oferta, o Mercado Livre a eliminará.

Quando a promoção está programada:

  • Não será refletido
  • Se você atualizar o preço DEALS, ele não será impactado até a data indicada.

Com a API de promoções, você pode consultar promoções filtrando por seu estado (started, finished, pending e candidate).
Só as ofertas CUSTOM e PRICE_DISCOUNT são reportadas como personalizadas. Isso ocorre porque elas podem ser criadas de 2 maneiras:

  • De forma individual, colocando uma oferta custom a um ítem.
  • De forma massiva como parte de uma campanha de vendedor de porcentagem de desconto. Isto é, criar uma campanha de 5% de desconto e subir itens a esta campanha

Isso significa que para todos esses itens foram criadas ofertas CUSTOM/PRICE_DISCOUNT com 5% de desconto. Não existem outros tipos de campanhas que também sejam personalizadas.


Obter preços do produto

Conheça todos os tipos de preços (standard e promotion), desde que válidos, que um produto pode ter nos diferentes canais onde é divulgado.
Caso o token não pertença ao vendedor e item consultado, você não receberá informações nos campos start_time nem end_time relacionados a promoções associadas (price type: promotion).


Chamada:

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

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA1222333/prices

Resposta:

{
    "id": "MLA1222333",
    "prices": [
        {
            "id": "52",
            "type": "standard",
            "amount": 49000,
            "regular_amount": null,
            "currency_id": "ARS",
            "last_updated": "2023-05-25T16:03:32Z",
            "conditions": {
                "context_restrictions": [
                    "channel_marketplace"
                ],
                "start_time": null,
                "end_time": null
            }
        },
        {
            "id": "28",
            "type": "standard",
            "amount": 50000,
            "regular_amount": null,
            "currency_id": "ARS",
            "last_updated": "2023-05-16T21:15:34Z",
            "conditions": {
                "context_restrictions": [
                    "channel_mshops"
                ],
                "start_time": null,
                "end_time": null
            }
        },
        {
            "id": "54",
            "type": "promotion",
            "amount": 46550.0,
            "regular_amount": 49000.0,
            "currency_id": "ARS",
            "last_updated": "2023-06-08T14:07:08Z",
            "conditions": {
                "context_restrictions": [
                    "channel_marketplace"
                ],
                "start_time": "2023-06-01T02:30:00Z", --- Não aparece sem token de proprietário                
                 "end_time": "2023-06-19T03:00:00Z"--- Não aparece sem token de proprietário            }
        },
        {
            "id": "55",
            "type": "promotion",
            "amount": 44100.0,
            "regular_amount": 49000.0,
            "currency_id": "ARS",
            "last_updated": "2023-06-08T14:07:08Z",
            "conditions": {
                "context_restrictions": [
                    "channel_marketplace",
                    "buyer_loyalty_3"
                ],
                "start_time": "2023-06-01T02:30:00Z",
                "end_time": "2023-06-19T03:00:00Z"
            }
        },
        {
            "id": "56",
            "type": "promotion",
            "amount": 44100.0,
            "regular_amount": 49000.0,
            "currency_id": "ARS",
            "last_updated": "2023-06-08T14:07:08Z",
            "conditions": {
                "context_restrictions": [
                    "channel_marketplace",
                    "buyer_loyalty_4"
                ],
                "start_time": "2023-06-01T02:30:00Z",
                "end_time": "2023-06-19T03:00:00Z"
            }
        },
        {
            "id": "57",
            "type": "promotion",
            "amount": 44100.0,
            "regular_amount": 49000.0,
            "currency_id": "ARS",
            "last_updated": "2023-06-08T14:07:08Z",
            "conditions": {
                "context_restrictions": [
                    "channel_marketplace",
                    "buyer_loyalty_5"
                ],
                "start_time": "2023-06-01T02:30:00Z",
                "end_time": "2023-06-19T03:00:00Z"
            }
        },
        {
            "id": "58",
            "type": "promotion",
            "amount": 44100.0,
            "regular_amount": 49000.0,
            "currency_id": "ARS",
            "last_updated": "2023-06-08T14:07:08Z",
            "conditions": {
                "context_restrictions": [
                    "channel_marketplace",
                    "buyer_loyalty_6"
                ],
                "start_time": "2023-06-01T02:30:00Z",
                "end_time": "2023-06-19T03:00:00Z"
            }
        }
    ]
}

Descrição dos campos

id: ID do produto.
price: array com informações relacionadas ao preço.

  • id: id do preço.
  • type: tipo de preço. Pode ser: standard (valor indicado pelo vendedor sem promoções) ou promoção (preço promocional).
  • amount: preço do produto.
  • regular_amount: preço original do produto, em casos que tenham promoção.
  • currency_id: ID da moeda à qual o campo de valor regular_amount se refere.
  • last_updated: última data de atualização.

conditions: array de condições sob as quais o preço pode ser aplicado.

  • context_restrictions: canal ao qual se aplica o preço ou nível de loyalty. Conceitualmente são restrições que só 'concorrem' para ser o preço de venda se o contexto atender a esses valores, portanto fica restrito a esses valores.
  • start_time/end_time: data de início e término do preço. As informações confidenciais serão ocultadas se você consultar um item com um token que não pertença ao item.

Editar preços tipo standard

Importante:
Esta API ainda não está disponível. Em breve substituirá o PUT de itens para editar preços.

Antes de utilizar este recurso, execute GET em /items/$ITEM_ID/prices para saber o preço standard do item e depois enviar no body do JSON as conditions (canal de vendas), o amount (novo preço) e currency_id (moeda local) que você deseja alterar. Em todos os casos, você deve enviar os canais de venda onde o preço padrão é publicado.
Por exemplo, se tens um artigo com preço no canal marketplace e mshops, mas queres apenas editar mshops, deves enviar os 2 context_restrictions no corpo JSON, tal como recebes da API /prices.


Parâmetros obrigatórios

prices: array listagem de preços pelo canal.
conditions: condições de preços. Você deve enviar context_restrictions como parte das condições de preço. Dita quais restrições você terá ao acertar na busca do Preço de Venda.
amount: valor do preço. Máximos e mínimos se aplicam dependendo do país e da categoria do produto.
currency_id: moeda de preço. Verifique as moedas disponíveis pelos sites ou detalhe de moedas.

Chamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' https://api.mercadolibre.com/items/$ITEM_ID/prices/standard
{
    "prices": [
        {
            "conditions": {
                "context_restrictions": ["channel_marketplace"]
            },
            "amount":400,
            "currency_id":"USD"
        },
        {
            "conditions": {
                "context_restrictions": ["channel_mshops"]
            },
            "amount":450,
            "currency_id":"USD"
        }
    ]
}
Nota:
Você receberá o erro 400 se:
- você envia um nó sem restrição de contexto e, em seguida, um ou mais nós com restrições de contexto. Por padrão, se você enviar o nó de preço sem restrições de contexto, editará os preços standard.
- você envia mais de um nó sem restrição por contexto.
- você envia um ou mais nós restritos ao contexto com valores de canal inválidos.
- você não envia um ou mais nós restritos ao contexto com valores de canal que o item possui no campo de canais (/items).