Documentación Mercado Libre

Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.
circulos azuis em degrade

Documentación

Última actualización 21/12/2022

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.


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.


Shipping costs according to item and zip_code

Calculates shipping costs for an item by sending only the Item_id and zip_code (CP or CEP) parameters.

Call:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/shipping_options?zip_code=$ZIP_CODE

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLB2997181655/shipping_options?zip_code=06233903

Response:

{
    "destination": {
        "zip_code": "06233903",
        "city": {
            "id": "BR-SP-31",
            "name": "Osasco"
        },
        "state": {
            "id": "BR-SP",
            "name": "São Paulo"
        },
        "country": {
            "id": "BR",
            "name": "Brasil"
        },
        "extended_attributes": {
            "address": "Avenida das Nações Unidas 3003",
            "zip_code_type": {
                "type": "GU",
                "description": "Grande Usuario"
            },
            "city_type": "CI",
            "city_name": "Osasco",
            "neighborhood": "Bonfim",
            "status": "active"
        }
    },
    "buyer": {
        "id": 0,
        "loyalty_level": 1,
        "shipping_level": "1"
    },
    "options": [
        {
            "id": 1423196752,
            "option_hash": "ae1bd0a2dbfe1358ec28585f4e432cae",
            "name": "Expresso",
            "currency_id": "BRL",
            "base_cost": 13.5,
            "cost": 0,
            "list_cost": 22.74,
            "display": "recommended",
            "shipping_method_id": 511948,
            "shipping_method_type": "sedex",
            "shipping_option_type": "address",
            "estimated_delivery_time": {
                "type": "known_frame",
                "date": "2022-12-01T00:00:00-03:00",
                "unit": "hour",
                "offset": {
                    "date": "2022-12-05T00:00:00-03:00",
                    "shipping": 48
                },
                "time_frame": {
                    "from": null,
                    "to": null
                },
                "pay_before": "2022-11-29T00:00:00-03:00",
                "shipping": 24,
                "handling": 48,
                "schedule": null
            },
            "discount": {
                "promoted_amount": 13.5,
                "rate": 1,
                "type": "ratio",
                "show_loyal_benefit": false
            }
        }
    ],
    "custom_message": {
        "display_mode": null,
        "reason": ""
    },
    "app_version": "2.1"
}

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: Estimated delivery date. In case of range: range start/beginning.
Shipping: Time it takes the carrier to deliver the shipment.In case of range: range start/beginning.
Handling: Time it takes for the seller to dispatch the shipment. Unit: Unidad de tiempo para los atributos shipping, handling y offset.shipping.
Offset: Applies only for ranges.

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.