Dynamic freight

Before starting with this development, you should have Mercado Libre's approval.

The purpose of the dynamic freight is to expedite sellers' freight terms and price selection with Mercado Envíos 1, as well as to improve buyers' experience, offering them more accurate information about the freight terms used by each seller. Besides, it expands the catalog for sellers with more than one distribution center, thus increasing sales.


→Integration dynamics →Response time →Contingency →API Contract →Errors

Integration dynamics

To integrate this feature, you should have an endpoint available for Mercado Libre to make a call and obtain the freight information shown on our platform at the purchase time.

Response time

The endpoint response time should be less than 400 ms. A few validations should be made before enabling the endpoint, including load validation to assess response time and to share, results with the integrator. After the timeout, the integration will not be approved and sellers may not enable it.

The current dynamic freight infrastructure is located in the US Eastern region (Virginia).


In the event of quote failures, we use MELI calculator as contingency tool to give buyers a response. Sellers load their price rates to this internal tool with the commercial advisor's support. The contingency will be triggered in the cases below:

  • The contingency will be triggered in the cases below:
  • Very high timeout rate (over 400 ms).
  • When the response to error_code is -1.

API Contract

As explained below, you should follow the contract rules to create an endpoint:

  • The integrator will name the endpoint, and he/she just needs to observe the “contract” for requests and responses.
  • The request includes just an item from a seller.

Find below a description of each of the items allowed in the payload:

destination (string)​: mandatory. Information of address for product delivery.

  • The zip code will be informed for Brazil, Argentina, and Mexico.
  • For Chile, region/district, separated by "/".
  • For Colombia, department/city.
  • For Uruguay, department/town.

buyer_id (string): optional. ID of user who is buying on Mercado Libre. To be available only when the user making the quote is logged on Mercado Libre platform.
seller_id (string)​​: mandatory. Account ID on Mercado Libre.
item_id (string): mandatory. ID of item registered on Mercado Libre.
store_id (string)​​: optional. Official store ID on Mercado Libre.
sku (string)​​: mandatory. ID of product to be purchased.
quantity (int)​​: mandatory. Quantity of an item to be purchased.
origin (string)​​: optional. Zip Code registered by seller.
price (float)​​: optional. Product unit price multiplied by the number of items chosen by buyer at quote time.
dimensions (object)​​: mandatory. Product size list.

  • length (float)​​: mandatory. Product length (in centimeters).
  • width (float)​​: mandatory. Product width (in centimeters).
  • height (float)​​: mandatory. Product height (in centimeters).
  • weight (float)​​: mandatory. Product weight (in kilograms).

When item quantity is higher than 1, marketplace has an algorithm to consolidate volumes with the best size combination for space optimization. In this case, integration should always consider the values sent in the POST and make no additional multiplication.



The response should have the quote relative to the purchased item.
There should be up to 2 (two) quotes per package, with the legend Regular or Express.
All response values are mandatory.
Find below a description of each of the items allowed in the payload:

packages (array)​​: Package list created by seller.
items (array)​​: Item list within the same package.

  • sku(string)​​: ID of item to be purchased.
  • seller_id(string)​​: ID of account selling product. It is generally a copy of the information already submitted in the request.
  • quantity (int)​​: Product quantity to be shipped.
  • stock(int)​​: Availability of product in stock per CD. If this information is not available, value -1 should be returned.
  • store_id (string)​​: optional. ID of store selling product. It is generally a copy of the information already submitted in the request.
  • error_code (int)​​: Code that will identify the product-related error type. The following sections will describe the list of allowed codes.

quotations (array)​​: Freight information for an item.

  • cost (float)​​: Actual freight cost. If this information is not available, the same price value should be returned.
  • price (float)​​: EFreight price to be submitted to buyer. This information is different from cost, since the freight may be partially or fully subsidized (free freight).
  • handling_time (int)​​: Time, in business days, allocated to product singling out and packing. It encompasses every process prior to actual package shipping. If this information is not available, value 0 should be returned.
  • shipping_time (int)​​: Package transit time, in business days (from truck loading to buyer delivery).
  • promise (int)​​: Addition of handling_time plus shipping_time values.
  • caption (string)​​: Name assigned to quote. The expected selection is Regular.
  • service_id (int) : Code identifying a service/carrier in the seller's environment. Valid values range from 0 to 99. The seller/integrator will be solely responsible for this unique code. Mercado Libre will be only responsible for sending this value.

If only one digit is sent, it will be automatically left padded with 0. And if sent with more than 2 digits, the information will not be integrated and 00 will be returned in the carrier's code.


    "packages": [
            "items": [
                    "sku": "00266983118",
                    "seller_id": "207740981",
                    "quantity": 1,
                    "stock": -1,
                    "error_code": 0,
                    "store_id": null
            "quotations": [
                    "cost": 66.6,
                    "price": 66.6,
                    "handling_time": 0,
                    "shipping_time": 39,
                    "promise": 39,
                    "caption": "Normal",
                    "service_id": 10


Since April 26, error code 1 will direct the quote for contingency.

Reminder: Errors occur on an item by item basis. The purpose is not to invalidate the quote or purchase of other items when only part of them has a problem. The conversion percentage tends to be higher than the one that invalidates all items. Find the errors below:

Parameter Description
-1 Integrator application internal error. The buyer will receive the quote from MELI calculator (contingency).
0 No error.
2 Invalid destination Zip Code.
3 Product unavailable for destination Zip Code.
4 The selected product does not exist.
or register to recieve the latest news about our API