Documentação do Mercado Livre

Confira todas as informações necessárias sobre as APIs Mercado Livre.
circulos azuis em degrade

Documentação do

Última atualização em 05/05/2026
FAQs Mercado Envios — Custos e cotações

Mercado Envios — Custos e cotações


Quais parâmetros mínimos devo enviar a /users/{user_id}/shipping_options/free para obter uma cotação coerente?

O endpoint requer mais contexto do que apenas dimensions: é recomendável enviar item_id ou, se usar dimensions, também item_price, listing_type_id, mode/logistic_type e free_shipping se aplicável. Enviar apenas dimensions sem outros parâmetros pode retornar list_cost=0 porque não há contexto suficiente para calcular o custo.

Recomendação
Inclua item_price, logistic_type e listing_type_id ou o item_id na consulta para obter cotações coerentes e evitar valores nulos.
Em qual unidade devo enviar o peso no parâmetro dimensions (ex. 0.7605)?

O peso em dimensions deve ser passado em gramas como inteiro (number_unit). Converta 0.7605 kg para gramas (ex. 761 g) e envie como valor inteiro; a API não aceita frações em quilogramas nesse campo.

Recomendação
Normalize pesos para gramas inteiros antes de enviar e arredonde de acordo com as regras de negócio para evitar rejeições por formato.
Como determino, pela API, se o vendedor teve a cobrança do frete ou se este foi subsidiado (frete grátis)? Quais campos devo usar?

Para saber quem pagou o frete, consulte /shipments/{id}/costs. receiver.cost reflete o custo final pago pelo comprador; senders[].cost reflete o valor associado ao vendedor. Se receiver.cost == 0, o comprador não pagou o frete. Se senders[].cost == 0, o vendedor não foi cobrado. Os campos promoted_amount e save são informativos, mas os valores determinantes são receiver.cost e senders[].cost.

Recomendação
Use /shipments/{id}/costs e consulte receiver.cost e senders[].cost para determinar a transferência real de custos entre comprador e vendedor.
O que representa promoted_amount ou save nos objetos de custos?

promoted_amount pode representar o valor final subsidiado; em alguns fluxos receiver.promoted_amount reflete o valor coberto, mas para cálculo de reembolsos e custos ao vendedor, use senders[].cost. O campo save é informativo e seu uso pode variar conforme a lógica interna; nem sempre deve ser usado como base para faturamento.

Recomendação
Use senders[].cost para cálculos financeiros e trate promoted_amount/save como campos informativos que requerem validação conforme o contexto.
Por que a cotação pela API pode diferir do valor exibido no front?

As discrepâncias podem ocorrer se não forem enviados todos os parâmetros necessários (dimensions, item_price, logistic_type), se houver simulações no front ou se existirem regras de contingência. A recomendação é usar /shipments/{id}/costs para obter o custo final que será aplicado ao pedido.

Recomendação
Forneça todos os parâmetros necessários na consulta e consulte /shipments/{id}/costs para o valor definitivo aplicado ao pedido.
Em qual moeda é retornado o custo de envio pelo endpoint /users/{user_id}/shipping_options/free?

O custo de envio é retornado na moeda do site (ex. BRL para MLB). Se você trabalha com preços em outra moeda, deve converter o valor retornado para a moeda que usa em seu cálculo.

Recomendação
Considere a moeda do site em seus cálculos e converta as cotações conforme necessário para manter consistência.
Qual campo da API reflete o custo final que o vendedor paga por um envio (para conciliações)?

Para saber o que foi cobrado ao vendedor, consulte senders[].cost em /shipments/{id}/costs; receiver.cost mostra o que o comprador paga. promoted_amount e campos de discounts explicam subsídios ou bônus aplicados.

Recomendação
Use /shipments/{id}/costs (senders/receiver) como fonte para conciliações e combine com sale_fee_amount e campos de descontos para calcular subsídios.