Ship products

Important:
Sellers who are operating from China to Brazil through their own logistics or ME1, are being migrated to remote partner carriers or ME2. Get more information.

The Mercado Libre's shipping department handles all the information about how a product goes from one seller to user. In this guide, you can learn more about the shipment resource, how to print labels, get shipment details like status shipment and more buyer information about address. Also you can inform the tracking to users.

Contents

→Shipment detail
→Shipment cost
→Shipping methods
→Migration Brazil ME2
    ↳Seller operates with own logistic
    ↳Seller operates with Sinostar (ME1)
→Print shipping labels
→Inform the tracking number
→Errors
→Get shipment items
→Get lead time
→Get status history
→Get carrier information


Shipment detail

With this resource you will get shipment details like the status shipment and more buyer information about address name (street, numer, zip code, state, country, etc.). Make a request to the GET method to implement it, it is mandatory to use in the header "x-format-new = true":

Note:
The "receiver_address" field now is equivalent to "destination.shipping_address" field.

Request:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'x-format-new: true' -X GET https://api.mercadolibre.com/marketplace/shipments/$SHIPMENT_ID

Example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'x-format-new: true' -X GET https://api.mercadolibre.com/marketplace/shipments/40531399184

Response:

{
   "id": 40531399184,
   "status": "ready_to_ship",
   "substatus": "printed",
   "declared_value": 15.1,
   "currency_id": "USD",
   "date_created": "2021-04-21T18:07:25.000-04:00",
   "last_updated": "2021-04-26T18:24:06.000-04:00",
   "tracking_number": "MMXQP014735497E",
   "tracking_method": "CBT MA",
   "origin": {
       "sender_id": 526127536,
       "shipping_address": {
           "address_id": 1087531691,
           "address_line": "XXXXXXX",
           "street_name": "XXXXXXX",
           "street_number": "XXXXXXX",
           "comment": null,
           "zip_code": "XXXXXXX",
           "city": {
               "id": "TUxNQ0NVQTMwNDU",
               "name": "Cuautitlan Izcalli"
           },
           "state": {
               "id": "MX-MEX",
               "name": "Estado De México"
           },
           "country": {
               "id": "MX",
               "name": "Mexico"
           },
           "neighborhood": {
               "id": null,
               "name": "Cuautitlan Izcalli"
           },
           "municipality": {
               "id": null,
               "name": null
           },
           "agency": {
               "agency_id": null,
               "carrier_id": null,
               "description": null,
               "open_hours": null,
               "phone": null,
               "type": null
           },
           "types": [
               "billing",
               "default_selling_address",
               "shipping"
           ],
           "latitude": 0,
           "longitude": 0,
           "geolocation_type": "APPROXIMATE",
           "geolocation_last_updated": "2020-02-12T13:50:08Z",
           "geolocation_source": "google-maps",
           "delivery_preference": ""
       },
       "type": "selling_address"
   },
   "destination": {
       "type": "buying_address",
       "receiver_id": 650079057,
       "receiver_name": "Mara asas",
       "receiver_phone": "922 3232333",
       "comments": "",
       "shipping_address": {
           "address_id": 1132588531,
           "address_line": "lalalalala 12312",
           "street_name": "lalalalala",
           "street_number": "12312",
           "comment": "Referencia: asdasd",
           "zip_code": "01030",
           "city": {
               "id": "TUxNQ0FMVjY3MDg",
               "name": "Alvaro Obregón"
           },
           "state": {
               "id": "MX-DIF",
               "name": "Distrito Federal"
           },
           "country": {
               "id": "MX",
               "name": "Mexico"
           },
           "neighborhood": {
               "id": null,
               "name": "Axotla"
           },
           "municipality": {
               "id": null,
               "name": null
           },
           "agency": {
               "agency_id": null,
               "carrier_id": null,
               "description": null,
               "open_hours": null,
               "phone": null,
               "type": null
           },
           "types": [
               "default_buying_address"
           ],
           "latitude": 19.355034,
           "longitude": -99.174821,
           "geolocation_type": "ROOFTOP",
           "geolocation_last_updated": "2020-09-23T20:17:30Z",
           "geolocation_source": "google-maps",
           "delivery_preference": "business"
       }
   },
   "dimensions": {
       "height": 3,
       "length": 45,
       "weight": 345,
       "width": 33
   },
   "external_reference": null,
   "lead_time": {
       "option_id": 721103001,
       "shipping_method": {
           "id": 501645,
           "type": "standard",
           "name": "Envío internacional",
           "deliver_to": "address"
       },
       "currency_id": "USD",
       "cost": 0,
       "list_cost": 0,
       "cost_type": "free",
       "service_id": 721,
       "estimated_delivery_time": {
           "type": "known_frame",
           "date": "2021-05-13T00:00:00.000-05:00",
           "unit": "hour",
           "offset": {
               "date": "2021-05-20T00:00:00.000-05:00",
               "shipping": 120
           },
           "time_frame": {
               "from": "",
               "to": ""
           },
           "pay_before": "2021-04-22T00:00:00.000-05:00",
           "shipping": 312,
           "handling": 72,
           "schedule": null
       }
   },
   "source": {
       "site_id": "MLM"
   },
   "logistic": {
       "mode": "me2",
       "type": "drop_off",
       "direction": "forward"
   },
   "tags": [
       "test_shipment"
   ]
}

Parameters

shipment_id: unique shipment identifier.


Most important response fields

mode: This is a set of shipping methods available. They have different shipping times and costs. Possible values are:

  • me1 (Mercado Envios mode 1): This method offers a shipping calculator to calculate the shipping cost for every order allowing the seller to choose the shipping service of his choice, but choosing a carrier and tracking number management is handled by the seller.
  • me2 (Mercado Envios mode 2): This method provides the seller a prepaid label and tracking number code with a predefined carrier. Seller does not have to worry with choosing a carrier and handling the tracking number. The shipping company chosen by Mercado Libre.

logistic_type: Represents the type of shipment operation.
If the carrier offers service for more than one operation, this attribute can help you know if you have to collect at a Hub (Fulfillment) or if the shipment will be dispatched at a branch (Drop Off).
tracking_number: The tracking number allows buyers to know the status of the packages and the estimated delivery time.

status:

  • pending: shipment created
  • handling: the payment for this shipment was processed
  • ready_to_ship: authorization code from carrier received
  • shipped: shipment in transit
  • delivered: shipment delivered
  • not_delivered: shipment was not delivered
  • cancelled: shipment was cancelled

Shipment cost

Get the shipment costs to be paid by the user. In addition, view the savings for shipping more than one product in the same box (once this feature is enabled) with the “save” parameter, if applicable.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'x-format-new: true' https://api.mercadolibre.com/marketplace/shipments/SHIPMENT_ID/costs

Response:

{
    "gross_amount": 508.14,
    "currency_id": "USD",
    "receiver": {
        "user_id": 00000001,
        "cost": 0,
        "compensation": 0,
        "save": 0,
        "discounts": [
            {
                "rate": 1,
                "type": "ratio",
                "promoted_amount": 254.07
            }
        ],
        "cost_details": []
    },
    "senders": [
        {
            "user_id": 00000002,
            "cost": 177.85,
            "compensation": 0,
            "save": 76.22,
            "discounts": [
                {
                    "rate": 0.3,
                    "type": "mandatory",
                    "promoted_amount": 76.22
                }
            ]
        }
    ]
}

Response fields

gross_amount: total cost of the shipment without any discount.
discounts: represents a list that can be empty if there is no discount, and if not, it can have one or more associated discounts.
senders: is a list adapted to future versions of the Shopping Cart where a single shipment may contain products from different sellers.
cost: final shipping cost that corresponds to each user.
currency_id: local currency value.


Shipping methods

Remote Partnered Carrier: Mercado Libre generates the shipping label and exposes the tracking id (shipping status "ready_to_ship"). After that, seller needs to print label and deliver the package to the Carrier.
Remote seller own logistic: seller needs to generate shipping label and set tracking information through Mercado Libre API.
Next you can identify the differents logistic types, also known the actions to do by the seller, and consider the steps ahead. The seller have to download the shipping label when the status shipment is "handling".


  • Fulfillment by Mercado Libre (FBM): Mercado Libre takes care of shipping the order, there is no action needed from the seller. The shipping status are automatically transitioned by Mercado Libre. There is no action required from the seller.
    How to identifier:
    "mode": "me2"
    "logistic_type": "fulfillment"

  • Remote partnered carrier (i.e: Wish, MailAméricas): the shipping status "ready_to_ship" means the shipping label is generated and able to be downloaded. Then the seller deliver the package to the carrier and finally Mercado Libre update the status (from ready_to_ship to shipped).
    How to identifier:
    "mode": "me2"
    "logistic_type": "drop_off"

  • Remote seller own logistic: with the shipping status "handling", seller needs to set tracking information and then the shipment is updated to "shipped" status.
    How to identifier:
    "mode": "me1"
    "logistic_type": "default"

Errors

HTTP Code Error Message
403 forbidden Invalid caller.id
403 forbidden Can not identify the user
404 not_found Resource not found
500 internal_server_error Oops! Something went wrong...
401 not_found invalid_token
400 bad_request {"message":"Malformed access_token: TOKEN_NOT_VALID","error":"bad_request","status":400,"cause":[]}
400 bad_request Param not valid

Migration Brazil ME2

Seller operates with own logistic

  • Mercado Libre will define which carrier the seller will be using moving forward. In this first phase, they will be operating either with Sinostar or Mail Americas.
  • Mercado Libre will charge the seller the cost of the shipment based on these prices (for both carriers the tariff is the same). Consequently the seller should not pay to their carrier the cost of the shipment.
  • Mercado Libre will provide the shipping label, the seller should download the label from Global Selling or API.
  • The seller doesn’t need to provide the tracking number, Mercado Libre will track the shipment events and transition the shipment. Get more information.
  • The order will be paid upon based on the carrier's delivered event not when a fixed time frame is met.
  • Shipments handled to the carrier past 96 hours will hurt the seller's reputation.

Seller operates with Sinostar (ME1)

  • Mercado Libre will define which carrier the seller will be using moving forward. In this first phase, they will be operating either with Sinostar or Mail Americas.
  • Mercado Libre will charge the seller the cost of the shipment based on these prices (for both carriers the tariff is the same). Consequently the seller should not pay Sinostar the cost of the shipment.
  • Mercado Libre will provide the shipping label, the seller should download the label from Global Selling or API. Consequently the seller won't be getting the label from Sinostar.
  • The seller does not need to provide the tracking number, Mercado Libre will track the shipment events and transition the shipment.
  • Shipments handled to the carrier past 96 hours will hurt the seller's reputation.

A label is a file to use when delivering the product. It was already paid by the buyer when the purchase flow ended. Once the buyer paid for the order, the seller must print the label. In order to obtain a label, the status of the shipments must be ready_to_ship. That means the payment was processed and the label is available to the seller. The resource to obtain a tag receives a shipping ID and an access token and returns the tag in PDF format.


Request:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/shipments/$SHIPMENT_ID/labels

Example:



Errors

HTTP Code Error Message
403 forbidden Invalid caller.id
403 forbidden Can not identify the user
404 not_found Resource not found
500 internal_server_error Oops! Something went wrong...
401 not_found invalid_token
400 bad_request {"message":"Malformed access_token: TOKEN_NOT_VALID","error":"bad_request","status":400,"cause":[]}
400 bad_request Invalid shipment id
401 not_found invalid_token
401 unauthorized_scopes Unauthorized shipments: 28140669939: Shipment status is 'delivered'

Inform the tracking

This endpoint allows you to report the tracking of a shipment, which must be entered by parameter. It is important that sellers provide the tracking number so that buyers can know the status of packages and the estimated delivery time. At this stage, we include the tracking number and the order status is updated for dispatch.

Request:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X POST https://api.mercadolibre.com/marketplace/shipments/$SHIPMENT_ID/tracking 
  -d '{
    "tracking_id": "String",
    "tracking_url": "http://carrier.com",
    "carrier": "name carrier"
}'

Example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X POST https://api.mercadolibre.com/marketplace/shipments/28262122315/tracking 
  -d '{
    "tracking_id": "String",
    "tracking_url": "http://carrier.com",
    "carrier": "name carrier"
}'

Response:

{
    "status": "success"
}

Parameters

id: is the number of the shipment to modify.
access_token:It is the token that must be generated with the provided credentials and the application generated by the seller or the integrator.


Fields

tracking_id: tracking number provided by the carrier.
tracking_url: carrier tracking website.
carrier: carrier name.


Errors

HTTP Code Error Message
403 forbidden Invalid caller.id
403 forbidden Can not identify the user
404 not_found_shipping_id Not found shipping with id
500 internal_server_error Oops! Something went wrong...
401 not_found invalid_token
400 bad_request {"message":"Malformed access_token: TOKEN_NOT_VALID","error":"bad_request","status":400,"cause":[]}
400 bad_request Param not valid

Get shipment items

The /marketplace/shipments/$SHIPMENT_ID/items resourse returns the items associated to a shipment. If the ítem has variations, like clothing size or colour, you can see which ones correspond to the order within the shipment. As we enable shipments with more than one item, the list will have each of them.

Note:
Each seller only see our products.

Request:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/shipments/$SHIPMENT_ID/items

Example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/shipments/12234123/items

Response:

[
    {
        "item_id": "MLB14385311",
        "variation_id": null,
        "description": "Test item",
        "quantity": 1,
        "manufacturing_time": null,
        "dimensions": {
            "height": 10,
            "width": 10,
            "length": 10,
            "weight": 318
        },
        "order_id": "123123123",
        "sender_id": 123123123
    }
]

Get lead time

The /marketplace/shipments/$SHIPMENT_ID/lead_time returns information related to the delivery times of a shipment and type of service, adding the dispatch and delivery deadlines. Although the shipment base resource already provides information to make these estimates, here you can view it in more detail, which will help to provide a better user experience.

Request:

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

Example:

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

Response:

{
  "option_id": 7214410001,
  "shipping_method": {
    "id": 501645,
    "name": "Envío internacional",
    "type": "standard",
    "deliver_to": "address"
  },
  "currency_id": "USD",
  "cost": 4.03,
  "list_cost": 4.03,
  "cost_type": "free",
  "service_id": 731,
  "delivery_type": "estimated",
  "estimated_schedule_limit": {
    "date": null
  },
  "buffering": {
    "date": null
  },
  "estimated_delivery_time": {
    "type": "known_frame",
    "date": "2020-11-06T00:00:00.000-05:00",
    "unit": "hour",
    "offset": {
      "date": "2020-11-23T00:00:00.000-05:00",
      "shipping": 240
    },
    "time_frame": {
      "from": null,
      "to": null
    },
    "pay_before": "2020-09-29T00:00:00.000-05:00",
    "shipping": 624,
    "handling": 48,
    "schedule": null
  },
  "estimated_delivery_limit": {
    "date": "2020-12-09T00:00:00.000-05:00",
    "offset": 288
  },
  "estimated_delivery_final": {
    "date": "2021-03-19T00:00:00.000-05:00",
    "offset": 1920
  },
  "estimated_delivery_extended": {
    "date": "2020-11-30T00:00:00.000-05:00",
    "offset": 120
  },
  "estimated_handling_limit": {
    "date": "2020-09-30T00:00:00.000-05:00"
  },
  "delay": [
    "handling_delayed"
  ]
}

The cost_type field can be "free", "charged" or "partially_free".


Response fields (estimated times)

estimated_handling_limit: deadline for the seller to dispatch. It is considered that only the date is taken into account since the time is only entered to maintain a structure. That is, you have the full day that appears in the field, to carry out the dispatch before it is marked delayed the next day.
estimated_delivery_extended: second delivery promise, in case the original is not fulfilled.
estimated_delivery_limit: deadline for the buyer to cancel the purchase and request a refund, as long as the shipment has not yet arrived.
estimated_delivery_final: final date as the deadline for the shipment to arrive and the final status that can be delivered is determined or, in case of a claim, not_delivered.


Get status history

The /marketplace/shipments/$SHIPMENT_ID/history resource return the status and substatus history associated to shipment cycle.

Request:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/shipments/$SHIPMENT_ID/history

Example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/shipments/12234123/history

Response:

[
  {
    "status": "ready_to_ship",
    "substatus": "printed",
    "date": "2016-12-30T12:32:35.000Z"
  },
  {
    "status": "handling",
    "substatus": "waiting_for_label_generation",
    "date": "2016-12-30T12:32:35.000Z"
  }
]

Get carrier information

The /marketplace/shipments/$SHIPMENT_ID/carrier return the carrier information like name carrier and the URL.

Request:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/shipments/$SHIPMENT_ID/carrier

Example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/shipments/12234123/carrier

Response:

{
  "url": "tracking URL",
  "name": "Carrier Name"
}

Next: Messaging after sale.