Last update 07/06/2022

Dynamic freight

This functionality is only available to certified partners. To get development approval, you must contact your Development Partner.

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. Look at the last webinar:

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 or 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 (object)​: 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 (int): 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 (int)​​: mandatory. Account ID on Mercado Libre.
declared_value (float)​​: optional. It is the value that will be declared on the invoice.
item_id (string): mandatory. ID of item registered on Mercado Libre.
variation_id (int): mandatory. variation identification chosen by the buyer for the purchase, it has data only when the quote corresponds to an item with variation.
category_id (string): optional. category ID from ítem in 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 (object)​​: 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 grams).

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 request and make no additional multiplication.


   "seller_id": 123333,
   "buyer_id": 432123,
   "declared_value": 95.99,
   "items": [
           "id": "MLB1223500643",
           "variation_id": 3123212,
           "category_id": "MLB1234",
           "price": 15.5,
           "quantity": 1,
           "SKU": "ITXEV8URJCPUN0UP",
           "store_id": 231,
           "dimensions": {
               "height": 10,
               "width": 10,
               "length": 15,
               "weight": 500
   "destination": {
       "type": "zipcode",
       "value": "88063038"
   "origin": {
       "type": "zipcode",
       "value": "88063038"
- The response should have the quote relative to the purchased item.
- Several quotes may be sent, all having the distinction of term / promise of delivery and price.
- 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.
item_id (string): required. It is the identification of the item registered in Mercado Libre.
variation_id (int): required. It is the identification of the variant chosen by the buyer.

  • 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.
  • 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.

  • 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.
  • service (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.



In case there is any internal error, any item is associated with an error, the structure of the response must be as follows. For error code 3 (without coverage), the HTTP Status must be 400 (bad request) and for any other error code or internal error associated with the fee, it must be 500 (internal server error).


    "message": "any message",
    "error_code": 1

Use cache

For the adoption of the response cache, RFC IETF 7234 will be used. (See more). This RFC was defined by the community and brings together HTTP request caching best practices.

HTTP verb

For the implementation it, the HTTP verb of the shipping quote endpoints of the POST for GET will be changed. This will be necessary so that the semantics of the is adequate to the HTTP protocol, in which, it is suggested that only the GET requests should be cached.


In addition, the header will be added in the calls and responses of the request to the partners.
For the requests will be added to the headers:

Attribute Value
If-None-Match Identifier of the resource (quote) in question (header ETag). It is used to verify if the version of the resource is still valid. It is valid if the partner returns HTTP status 304 with no content. Otherwise, it returns a new version of the resource and a new ETag.

In turn, for the responses of the integrators, it will be necessary to add the headers:

Attribute Value
Cache-Control Used to specify the directives for the response cache. You must adapt are:
1. no-store: (optional) indicates that the response should not be cached. This directive is used, the other nao are necessary;
2. must-revalidate: you must check if the answer is valid with the integrator. This should return the HTTP Status 304 if it is still valid or 200 with the new value for the quote. This validation is optional and it is up to the integrator to adopt it or not. If you don't adapt it, the max-age will be used to define the TTL of the response in the cache.
3. private: (mandatory) the response must not be stored by any intermediary proxy.
4. max-age: (mandatory) maximum time in seconds that the response is valid.
Age Time in seconds since the resource version became valid. In the absence of this control by the partners, you must send the zero value (0).
ETag Resource version identifier. It is mandatory to use it.

Response contract

We will add a new attribute destinations in the request response and it must contain all the destinations that the quote can be used. This attribute will be a list of strings and can contain only the destination for which the quote was requested. With that, with a single quote, you can avoid N other calls.
Below presents an example response where the returned ETag header is verified that the cached response is still valid.
Ejemplo de llamada con validación caché.

Headers Status Body
- Cache-Control:private;max-age:1000000
- Age:50000
- ETag:0943dc18-a8d7-4508-97a9-ba9221fa
304 No content

Finally, presents a sample response where the partner indicates that the appointment should not be cached. It must contain the no-store directive in the Cache-Control header.

Response example without allowing the cache.

Headers Status Body
- Cache-Control:no-store 200 { "destinations": ["01227901", "42324323"], "packages": [{ "items": [{ "sku": "213123", "seller_id": "31231", "quantity": 1, "stock": -1, "error_code": 0, "store_id": "1234" }], "quotations": [{ "cost": 66.6, "price": 66.6, "handling_time": 0, "shipping_time": 39, "promise": 39, "caption": "Normal", "service_id": 01 }] }] }

Sample response with cache:

Headers Status Body
- Age:0
- ETag:0943dc18-a8d7-4508-97a9-ba9221fa
200 Equal body of the quote response


The error code 1 wirect 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.
banner footer

Subscribe to our Newletter

or register to recieve the latest news about our API