Documentation Mercado Libre

Check out all the necessary information about APIs Mercado Libre.
circulos azuis em degrade

Documentation

Last update 05/05/2026
FAQs › Mercado Envios — Shipping costs and quotes

Mercado Envios — Shipping costs and quotes


What minimum parameters should I send to /users/{user_id}/shipping_options/free to get a consistent quote?

The endpoint requires more context than just dimensions: it is recommended to send item_id or, if using dimensions, also item_price, listing_type_id, mode/logistic_type, and free_shipping if applicable. Sending only dimensions without other parameters may return list_cost=0 because there is not enough context to calculate the cost.

Recommendation
Include item_price, logistic_type, and listing_type_id or item_id in the query to get consistent quotes and avoid null values.
In what unit should I send the weight in the dimensions parameter (e.g. 0.7605)?

The weight in dimensions must be passed in grams as an integer (number_unit). Convert 0.7605 kg to grams (e.g. 761 g) and send as an integer value; the API does not accept fractions in kilograms for this field.

Recommendation
Normalize weights to whole grams before sending and round according to business rules to avoid format rejections.
How do I determine via API if the seller was charged for shipping or if it was subsidized (free shipping)? Which fields should I use?

To find out who paid for shipping, query /shipments/{id}/costs. receiver.cost reflects the final cost paid by the buyer; senders[].cost reflects the amount associated with the seller. If receiver.cost == 0, the buyer did not pay for shipping. If senders[].cost == 0, the seller was not charged. The promoted_amount and save fields are informational, but the determining values are receiver.cost and senders[].cost.

Recommendation
Use /shipments/{id}/costs and check receiver.cost and senders[].cost to determine the actual cost transfer between buyer and seller.
What does promoted_amount or save represent in cost objects?

promoted_amount may represent the final subsidized value; in some flows receiver.promoted_amount reflects the covered amount, but for calculating refunds and seller costs, use senders[].cost. The save field is informational and its usage may vary by internal logic; it should not always be used as a billing basis.

Recommendation
Use senders[].cost for financial calculations and treat promoted_amount/save as informational fields that require validation depending on context.
Why can the API quote differ from the value shown on the front-end?

Discrepancies can occur if not all required parameters are sent (dimensions, item_price, logistic_type), if there are front-end simulations, or if contingency rules exist. The recommendation is to use /shipments/{id}/costs to get the final cost that will be applied to the order.

Recommendation
Provide all required parameters in the query and use /shipments/{id}/costs for the definitive value applied to the order.
In what currency is the shipping cost returned by the /users/{user_id}/shipping_options/free endpoint?

The shipping cost is returned in the site's currency (e.g. BRL for MLB). If you work with prices in another currency, you must convert the returned value to the currency used in your calculation.

Recommendation
Factor the site's currency into your calculations and convert quotes as needed to maintain consistency.
Which API field reflects the final cost the seller pays for a shipment (for reconciliations)?

To find out what was charged to the seller, query senders[].cost in /shipments/{id}/costs; receiver.cost shows what the buyer pays. promoted_amount and discount fields explain subsidies or bonuses applied.

Recommendation
Use /shipments/{id}/costs (senders/receiver) as the source for reconciliations and combine with sale_fee_amount and discount fields to calculate subsidies.