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
→Calculate over zip code and item dimensions
→Calculate over user & zip code
→Calculate over city on MCO
→Shipping costs by User, city and dimensions on MCO
→Brief description of the attributes
→Delivery promise type
→Considerations


Attributes description

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

Destination (destino): Receiver address details.

Attributes

  • zip_code (código postal): Destination zip code.
  • city (ciudad): Destination city info.

    • id: Destination city id.
    name (nombre): Destination city name.

  • state (estado): Destination state info.

    • id: Destination state id.
    name (nombre): Destination state name.

  • country (país): Destination country info.

    • id: Destination country id.
    name (nombre): Destination country name.

  • extended_attributes (atributos extendidos): Destination address additional info.

    • address (domicilio): Destination address line.
    owner_name (nombre del titular): Destination address owner.
    zip_code_type (tipo de código postal): Destination zip code type info.
    - type (tipo): Destination zip code type id.
    - Description (descripción): Destination zip code type name.
    city_type (tipo de ciudad): Destination city type id.
    city_name (nombre de la ciudad): Destination city name.
    version (versión): Internal version of this data in Zipcodes API.

Options (opciones): Collection of shipping costs for each available shipping method.


Attributes

  • id:Id of applied shipping rule.
  • name (nombre): Shipping method name.
  • currency_id (ID de moneda): Id of currency used to show shipping costs.
  • list_cost (costo de publicación): Real shipping costs, no free shipping applied.
  • cost (costo): Final shipping cost, free shipping could apply.
  • tracks_shipments_status (seguimiento del estado de los envíos): Indicates how this method may be tracked.

    • verified (verificado): Can be internally tracked.
    not_verified (no verificado): Tracking information must be provided by seller.
    no: Shipping method id for frontend processing.

  • display (mostrar) : Shipping method id for frontend processing.

    • always (siempre): Shipping method must be displayed.
    optional (opcional): Method may not be displayed because there exists a faster and cheaper one.

  • speed (velocidad): Delivery speed info.

    • shipping (envío): Average hours for delivery itself.
    handling (en manipulación): Average hours for shipment to be shipped by seller.


Calculate over zip code and item dimensions

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 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 -H 'Authorization: Bearer $ACCESS_TOKEN' 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 -H 'Authorization: Bearer $ACCESS_TOKEN' 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:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 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:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 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

Type: Delivery promise type.



Date: Range end/ending.

Shipping: Range of days amplitude.

time_frame: Delivery timeslot.

pay_before: Deadline for payment.

"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

To know the different types of delivery promise you must do the following GET: 

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/shipment_id/lead_time

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:In the case of being an exact date, ignoring the handling time, expressed in business days.

...
...
 "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.
or register to recieve the latest news about our API