Calculate shipping costs & handling time

On our Marketplace sellers will have a shipping calculator on the item description page so buyers will know the cost for the shipping and estimated handling time.
You can use our resources to calculate this basing on the information you have.

Contents:

Attributes description

Let’s see a quick description of each attribute you’ll find on our calculator resource.

destination
Receiver address details.
Attributes
zip_code
Destination zip code.
city
Destination city info.
Attributes
id
Destination city id.
name
Destination city name.
state
Destination state info.
Attributes
id
Destination state id.
name
Destination state name.
country
Destination country info.
Attributes
id
Destination country id.
name
Destination country name.
extended_attributes
Destination address additional info.
Attributes
address
Destination address line.
owner_name
Destination address owner.
zip_code_type
Destination zip code type info.
Attributes
type
Destination zip code type id.
description
Destination zip code type name.
city_type
Destination city type id.
city_name
Destination city name.
version
Internal version of this data in Zipcodes API.
options
Collection of shipping costs for each available shipping method.
Attributes
id
Id of applied shipping rule.
name
Shipping method name.
currency_id
Id of currency used to show shipping costs.
list_cost
Real shipping costs, no free shipping applied.
cost
Final shipping cost, free shipping could apply.
tracks_shipments_status
Indicates how this method may be tracked
Attributes
verified
Can be internally tracked.
not_verified
Tracking information must be provided by seller.
no
Cannot be tracked.
display
Shipping method id for frontend processing.
Attributes
always
Shipping method must be displayed.
optional
Method may not be displayed because there exists a faster and cheaper one.
speed
Delivery speed info.
Attributes
shipping
Average hours for delivery itself.
handling
Average hours for shipment to be shipped by seller.

 

Calculate over zip code and item dimensions

Example:

curl -X GET https://api.mercadolibre.com/sites/MLB/shipping_options?zip_code_from=01310909&zip_code_to=01310909&dimensions=16x16x16,1500

Response:

{
  "destination": {
    "zip_code": "01310909",
    "city": {
      "id": "BR-SP-44",
      "name": "São Paulo"
    },
    "state": {
      "id": "BR-SP",
      "name": "São Paulo"
    },
    "country": {
      "id": "BR",
      "name": "Brasil"
    },
    "extended_attributes": {
      "address": "Avenida Paulista, 688",
      "owner_name": "Edifício Santa Filippa",
      "zip_code_type": {
        "type": "LO",
        "description": "Logradouro"
      },
      "city_type": "CI",
      "city_name": "São Paulo",
      "neighborhood": "Bela Vista",
      "status": "active"
    }
  },
  "options": [
    {
      "id": 27554373,
      "name": "Normal",
      "shipping_method_id": 100009,
      "currency_id": "BRL",
      "list_cost": 9.66,
      "cost": 9.66,
      "tracks_shipments_status": "not_verified",
      "display": "recommended",
      "speed": {
        "shipping": 96,
        "handling": 48
      },
      "estimated_delivery": {
        "date": "2016-02-26T00:00:00.000-02:00",
        "pay_before": null,
        "time_from": null,
        "time_to": null
      },
      "estimated_delivery_time": {
        "type": "known_frame",
        "date": "2016-02-24T00:00:00.000-02:00",
        "shipping": 48,
        "handling": 48,
        "unit": "hour",
        "offset": {
          "date": "2016-02-26T00:00:00.000-02:00",
          "shipping": 48
        },
        "time_frame": {
          "from": null,
          "to": null
        },
        "pay_before": null
      },
      "discount": {
        "rate": 0,
        "type": "none",
        "promoted_amount": 0
      }
    },
    {
      "id": 27551043,
      "name": "Expresso",
      "shipping_method_id": 182,
      "currency_id": "BRL",
      "list_cost": 9.83,
      "cost": 9.83,
      "tracks_shipments_status": "not_verified",
      "display": "always",
      "speed": {
        "shipping": 48,
        "handling": 48
      },
      "estimated_delivery": {
        "date": "2016-02-24T00:00:00.000-02:00",
        "pay_before": null,
        "time_from": null,
        "time_to": null
      },
      "estimated_delivery_time": {
        "type": "known_frame",
        "date": "2016-02-23T00:00:00.000-02:00",
        "shipping": 24,
        "handling": 48,
        "unit": "hour",
        "offset": {
          "date": "2016-02-24T00:00:00.000-02:00",
          "shipping": 24
        },
        "time_frame": {
          "from": null,
          "to": null
        },
        "pay_before": null
      },
      "discount": {
        "rate": 0,
        "type": "none",
        "promoted_amount": 0
      }
    }
  ]
}

 

Calculate over user & zip code

Example:

curl -X GET https://api.mercadolibre.com/users/190990642/shipping_options?zip_code=01310909&dimensions=16x16x16,1500

Response:

{
  "destination": {
    "zip_code": "01310909",
    "city": {
      "id": "BR-SP-44",
      "name": "São Paulo"
    },
    "state": {
      "id": "BR-SP",
      "name": "São Paulo"
    },
    "country": {
      "id": "BR",
      "name": "Brasil"
    },
    "extended_attributes": {
      "address": "Avenida Paulista, 688",
      "owner_name": "Edifício Santa Filippa",
      "zip_code_type": {
        "type": "LO",
        "description": "Logradouro"
      },
      "city_type": "CI",
      "city_name": "São Paulo",
      "neighborhood": "Bela Vista",
      "status": "active"
    }
  },
  "options": [
    {
      "id": 27555383,
      "name": "Normal",
      "shipping_method_id": 100009,
      "currency_id": "BRL",
      "list_cost": 11.86,
      "cost": 11.86,
      "tracks_shipments_status": "not_verified",
      "display": "recommended",
      "speed": {
        "shipping": 96,
        "handling": 48
      },
      "estimated_delivery": {
        "date": "2016-03-01T00:00:00.000-02:00",
        "pay_before": null,
        "time_from": null,
        "time_to": null
      },
      "estimated_delivery_time": {
        "type": "known_frame",
        "date": "2016-02-26T00:00:00.000-02:00",
        "shipping": 48,
        "handling": 48,
        "unit": "hour",
        "offset": {
          "date": "2016-03-01T00:00:00.000-02:00",
          "shipping": 48
        },
        "time_frame": {
          "from": null,
          "to": null
        },
        "pay_before": null
      },
      "discount": {
        "rate": 0,
        "type": "none",
        "promoted_amount": 0
      }
    },
    {
      "id": 27843879,
      "name": "Expresso",
      "shipping_method_id": 182,
      "currency_id": "BRL",
      "list_cost": 16.48,
      "cost": 16.48,
      "tracks_shipments_status": "not_verified",
      "display": "always",
      "speed": {
        "shipping": 48,
        "handling": 48
      },
      "estimated_delivery": {
        "date": "2016-02-26T00:00:00.000-02:00",
        "pay_before": null,
        "time_from": null,
        "time_to": null
      },
      "estimated_delivery_time": {
        "type": "known_frame",
        "date": "2016-02-25T00:00:00.000-02:00",
        "shipping": 24,
        "handling": 48,
        "unit": "hour",
        "offset": {
          "date": "2016-02-26T00:00:00.000-02:00",
          "shipping": 24
        },
        "time_frame": {
          "from": null,
          "to": null
        },
        "pay_before": null
      },
      "discount": {
        "rate": 0,
        "type": "none",
        "promoted_amount": 0
      }
    }
  ]
}

 

Calculate over city on MCO

You can calculate shipping costs for a given site. On MCO is different from other sites since you the calculation is done over city_from, city_to and dimensions parameters. As you can see in the following example, this resource allows multi-get. You need to link the city codes one by one.
Example:

curl -X GET https://api.mercadolibre.com/sites/MCO/shipping_options?city_from=Q08tRENCb2dvdA&city_to=TUNPQ0NBUjcwNTYz,TUNPQ01FRGRjNjc4&dimensions=10x10x10,1000

Response:

{
  "TUNPQ01FRGRjNjc4": {
    "destination": {
      "zip_code": null,
      "city": {
        "id": "TUNPQ01FRGRjNjc4",
        "name": "Medellín"
      },
      "state": {
        "id": "CO-ANT",
        "name": "Antioquia"
      },
      "country": {
        "id": "CO",
        "name": "Colombia"
      }
    },
    "options": [
      {
        "id": 523836053,
        "name": "Servientrega Normal",
        "shipping_method_id": 501745,
        "currency_id": "COP",
        "list_cost": 7500,
        "cost": 7500,
        "tracks_shipments_status": "not_verified",
        "display": "recommended",
        "speed": {
          "shipping": 24,
          "handling": 72
        },
        "estimated_delivery": {
          "date": "2016-02-26T00:00:00.000-05:00",
          "pay_before": null,
          "time_from": null,
          "time_to": null
        },
        "estimated_delivery_time": {
          "type": "known",
          "date": "2016-02-26T00:00:00.000-05:00",
          "shipping": 24,
          "handling": 72,
          "unit": "hour",
          "offset": {
            "date": null,
            "shipping": null
          },
          "time_frame": {
            "from": null,
            "to": null
          },
          "pay_before": null
        },
        "discount": {
          "rate": 0,
          "type": "none",
          "promoted_amount": 0
        }
      }
    ]
  },
  "TUNPQ0NBUjcwNTYz": {
    "destination": {
      "zip_code": null,
      "city": {
        "id": "TUNPQ0NBUjcwNTYz",
        "name": "Cartagena De Indias"
      },
      "state": {
        "id": "CO-BOL",
        "name": "Bolivar"
      },
      "country": {
        "id": "CO",
        "name": "Colombia"
      }
    },
    "options": [
      {
        "id": 523835977,
        "name": "Servientrega Normal",
        "shipping_method_id": 501745,
        "currency_id": "COP",
        "list_cost": 7500,
        "cost": 7500,
        "tracks_shipments_status": "not_verified",
        "display": "recommended",
        "speed": {
          "shipping": 48,
          "handling": 72
        },
        "estimated_delivery": {
          "date": "2016-02-29T00:00:00.000-05:00",
          "pay_before": null,
          "time_from": null,
          "time_to": null
        },
        "estimated_delivery_time": {
          "type": "known",
          "date": "2016-02-29T00:00:00.000-05:00",
          "shipping": 48,
          "handling": 72,
          "unit": "hour",
          "offset": {
            "date": null,
            "shipping": null
          },
          "time_frame": {
            "from": null,
            "to": null
          },
          "pay_before": null
        },
        "discount": {
          "rate": 0,
          "type": "none",
          "promoted_amount": 0
        }
      }
    ]
  }
}

 

Shipping costs by User, city and dimensions on MCO

If you want, you can calculate the shipping costs for an specific user to a given city and dimensions. As you can see in the following example, this resource allows multi-get. You need to concatenate the city codes one by one.
Example:

GET https://api.mercadolibre.com/users/454271894/shipping_options?city_to=Q08tRENCb2dvdA,TUNPQ01FRGRjNjc4&dimensions=15x15x15,650

Response:

{
    "destination": {
        "zip_code": null,
        "city": {
            "id": "Q08tRENCb2dvdA",
            "name": "Bogotá"
        },
        "state": {
            "id": "CO-DC",
            "name": "Bogota D.C."
        },
        "country": {
            "id": "CO",
            "name": "Colombia"
        }
    },
    "options": [
        {
            "id": 11110,
            "name": "Servientrega Estandar",
            "shipping_method_id": 501745,
            "currency_id": "COP",
            "list_cost": 7.5,
            "cost": 7.5,
            "tracks_shipments_status": "verified",
            "display": "recommended",
            "speed": {
                "shipping": 48,
                "handling": null
            },
            "estimated_delivery": {
                "date": null,
                "pay_before": null,
                "time_from": null,
                "time_to": null
            },
            "discount": {
                "rate": 0
            }
        }
    ],
    "settings": {
        "allow_add_cost": null
    }
}

 

Shipping costs over Item and city on MCO

Calculate shipping costs for an Item sending only the Item_id and City_to parameters.
Example:

GET https://api.mercadolibre.com/items/MCO415774919/shipping_options?city_to=Q08tRENCb2dvdA

Response:

{
  "destination": {
    "zip_code": null,
    "city": {
      "id": "Q08tRENCb2dvdA",
      "name": "Bogotá"
    },
    "state": {
      "id": "CO-DC",
      "name": "Bogota D.C."
    },
    "country": {
      "id": "CO",
      "name": "Colombia"
    }
  },
  "options": [
    {
      "id": 523835933,
      "name": "Servientrega Normal",
      "shipping_method_id": 501745,
      "currency_id": "COP",
      "list_cost": 5000,
      "cost": 0,
      "tracks_shipments_status": "verified",
      "display": "recommended",
      "speed": {
        "shipping": 24,
        "handling": 72
      },
      "estimated_delivery": {
        "date": "2015-06-22T00:00:00.000-05:00",
        "pay_before": null,
        "time_from": null,
        "time_to": null
      },
      "discount": {
        "rate": 0,
        "type": "none",
        "promoted_amount": 0
      }
    }
  ]
}

 

Brief description of the attributes

AttributesJSON Response

"estimated_delivery_time": {
    "type": "known|known_frame|unknown_frame",
    "date": 2015-09-10T00: 00: 00: 000-03: 00",
"shipping": 72,
"handling": 24,
"unit": "hour",
"offset": {
    "date": null,
    "shipping": null
},
"time_frame": {
    "from": "12: 00",
    "to": "15: 00"
},
"pay_before": null
}

Delivery promise type

known: Exact date and handling time known.

...
...
 "estimated_delivery_time": {
        "type": "known",
        "date": "2015-09-10T00:00:00:000-03:00",
        "shipping": 72,
        "handling": 24,
        "unit": "hour",
        "offset": {
          "date": null,
          "shipping": null
        },
        "time_frame": {
          "from":"12:00",
          "to": "15:00"
        },
        "pay_before": null
      },
      …

1

Unknown: Exact date and handling time unknown.

...
...
 "estimated_delivery_time": {
        "type": "unknown",
        "date": null,
        "shipping": 72,
        "handling": null,
        "unit": "hour",
        "offset": {
          "date": null,
          "shipping": null
        },
        "time_frame": {
          "from":"null",
          "to": "null"
        },
        "pay_before": null
      },
      …

3

known_frame: Specific date and handling time known.

...
...
 "estimated_delivery_time": {
        "type": "known_frame",
        "date": "2015-09-10T00:00:00:000-03:00",
        "shipping": 72,
        "handling": 24,
        "unit": "hour",
        "offset": {
          "date": "2015-09-12T00:00:00:000-03:00",
          "shipping": 48
        },
        "time_frame": {
          "from":"12:00",
          "to": "15:00"
        },
        "pay_before": null
      },
      ...

2

unknown_frame: Business days range and handling time unknown.

...
...
 "estimated_delivery_time": {
        "type": "unknown_frame",
        "date": "null",
        "shipping": 72,
        "handling": null,
        "unit": "hour",
        "offset": {
          "date": "null",
          "shipping": 48
        },
        "time_frame": {
          "from":"null",
          "to": "null"
        },
        "pay_before": null
      },
      ...

4

Considerations

  • Business days range defined by the limits [“shipping”, “shipping” + “offset.shipping”].
  • Delivery dates (“date” and “offset.date”) exist if the handling time is know.
  • “time_frame” applies only to carriers that handle well-defined frames.
  • “pay_before” only applies to carriers that handle well-defined frames.
  • These changes will be reflected at GET /shipments/$ID, GET /orders/$ID/shipments and GET /orders/$ID.

Please rate this