Mercado Envios mode 1

This guide explains how to work with all the resources our API provides to successfully list and manage listings with shipping mode me1. It also explains how to post tracking numbers to provide the buyers with the tracking information.

Contents:

Opting in for using ME1

To start using MercadoEnvios mode 1 you have get in touch with your MercadoLibre commercial assessor, since this mode is only available to VIP users and it’s activated by our Shipping developer’s team for each individual case.

Offering ME1 on your products

It’s quite simple to list an item with me1. Post the free shipping options and dimensions of the package whenever they are available.
If sellers do not provide package dimensions on their listing, category standard dimensions will be used.
URL to POST

https://api.mercadolibre.com/items?access_token=

JSON for the body

{
   "title":"Item de teste",
   "category_id":"MLA48786",
   "price":1200,
   "currency_id":"ARS",
   "available_quantity":2,
   "buying_mode":"buy_it_now",
   "listing_type_id":"bronze",
   "condition":"new",
   "description":"test",
   "pictures":[
      {
         "source":"http://upload.wikimedia.org/wikipedia/commons/f/fd/Ray_Ban_Original_Wayfarer.jpg"
      },
      {
         "source":"http://en.wikipedia.org/wiki/File:Teashades.gif"
      }
   ],
   "shipping":{
      "local_pick_up":false,
      "mode": "me1",
      "dimensions":"10x10x20,700"
   }
}

Dimensions

After being marked with me1 mode, you can add dimensions to your existing listings. Altering the dimensions of an item doesn’t affect its relevance in search results and there is no restriction to alter dimensions if the item has sales.
Each category has it’s own standard dimensions, but you can add the values you want, as long as they’re between the range of allowed values. Take a look a this guide to know allowed values for each site.

Know standard dimensions for a given category

Example:

curl -X GET https://api.mercadolibre.com/categories/MLM165702/shipping


Add dimensions

curl -X PUT -H "Content-Type: application/json" -d ‘{
   "shipping":{
      "dimensions":"10x10x20,700",
      "mode": "me1"
   }
}’ https://api.mercadolibre.com/items/:item_id?access_token=

Free shipping

Sellers have the option to list items offering one of the shipping methods for free.
Please check this entry to learn the details and how to list with free shipping.

Shipping Cost Calculator

There’s a resource on our API to calculate shipping costs for a given dimension, category and zip code destination.
There are 2 resources the shipping calculator can choose to better suit your available parameters; both of them return the same result.
URL

https://api.mercadolibre.com/users/:user_id/shipping_options?category_id=:category_id&dimensions=:dim&zip_code=13565905


https://api.mercadolibre.com/items/:item_id/shipping_options?zip_code=13565905

Response:

{
  "destination": - {
    "zip_code": "01001000",
    "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": "Praça da Sé",
      "owner_name": null,
      "zip_code_type": - {
        "type": "LO",
        "description": "Logradouro",
      },
      "city_type": "CP",
      "city_name": "São Paulo",
      "version": 6,
    },
  },
  "options": - [
    - {
      "id": 18310062,
      "name": "Normal",
      "currency_id": "BRL",
      "list_cost": 13.86,
      "cost": 13.86,
      "tracks_shipments_status": "not_verified",
      "display": "recommended",
      "speed": - {
        "shipping": 72,
        "handling": 24,
      },
    },
    - {
      "id": 18310061,
      "name": "Expresso",
      "currency_id": "BRL",
      "list_cost": 14.88,
      "cost": 14.88,
      "tracks_shipments_status": "not_verified",
      "display": "always",
      "speed": - {
        "shipping": 24,
        "handling": 24,
      },
    },
  ],
}


Attribute description

  • currency_id: The currency in which the price is charged.
  • list cost: The cost for this shipping option.
  • cost: The actual cost to be paid, for “free shipping” cost is 0.
  • tracks_shipments_status: Indicates how this method may be tracked.
  • tracks_shipments_status.verified : Can be internally tracked.
  • tracks_shipments_status.not_verified : Tracking information must be provided by seller.
  • tracks_shipments_status.no : Cannot be tracked.
  • speed.shipping: Promise of time to deliver, expressed in hours.
  • speed.handling: Promise of handling time, expressed in hours.

Shipping status

Some configurations of ME1 support automatic tracking, so shipping status will be updated by us. If this is not your case, then you’ll be responsible for sending a tracking number and update the shipping status. This is not mandatory but we suggest you to do it so you improve your chances of getting better feedback from the buyers.
Status:
pending
Shipment is created with this state.
handling
Payment has been received for this shipment.
shipped
Carrier has informed shipment departure.

Add tracking number

Is essential that sellers provide tracking number for their shipments, allowing the buyers to be aware of the status of their packages and estimated delivery time.
All you have to do is a PUT to the shipment with the service_id and tracking_number attributes.

curl -X PUT -H "Content-Type: application/json" -d  ‘{
  "tracking_number": "TR1234567891",
  "service_id": 1
}’  https://api.mercadolibre.com/shipments/:shipment_id?access_token=&ACCESS_TOKEN

Update shipping status

To update the shipping status on the order you need to make a PUT to the shipment.
To know the shipment_id you can make a call to orders, like this example:
Example:

curl -X GET https://api.mercadolibre.com/orders/{Order_id}/shipments



Initial shipping status is “pending”. Once you identify the shipping_id, you can update to another status.

Update status to handling

Example:

curl -X PUT -H "Content-Type: application/json" -d '{"status": "handling"}' https://api.mercadolibre.com/shipments/{Shipment_id}

Update status to shipped

Example:

curl -X PUT -H "Content-Type: application/json" -d '{shipping_option: {id:27569508},receiver_address: {"contact":"Roberto Gomez Bolaño","phone":"12345", address_line:"Avenida siempre viva updated", comment:"Casa azul.",zip_code:"90040060", "city": {"id": "TUxCQ1BPUjgwZTJl","name": "Porto Alegre"}, "state": {"id": "BR-RS","name": "Rio Grande do Sul"}, country: {id:"BR", name:"Argentina"}}}' https://api.mercadolibre.com/shipments/{Shipment_id}


Please rate this