Ship products

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

→Cost
→Shipment detail
→Shipping methods
→Print shipping labels
→Inform the tracking number
→Errors
→Get shipment items
→Get lead time
→Get status history
→Get carrier information


Cost

Shipment costs to be paid by the user are returned by resource /shipments/shipment_id/costs. Additionally, you will be able to 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 https://api.mercadolibre.com/marketplace/shipments/SHIPMENT_ID/costs?access_token=$ACCESS_TOKEN

Response:

curl -X GET https://api.mercadolibre.com/marketplace/shipments/SHIPMENT_ID/costs?access_token=$ACCESS_TOKEN
{
    "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
                }
            ]
        }
    ]
}

Parameters

gross_amount: total shipment cost without any discount.
discounts: displays a list which may be empty if there is no discount, or which may have one or more associated discounts.
senders: list adjusted to future Shopping Cart versions where a single shipment may include products from different sellers.
cost: displays the final shipping cost for each user.
currency_id: has the value of local currency.


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 like and implement it:

Request:

curl -X GET https://api.mercadolibre.com/marketplace/shipments/$SHIPMENT_ID?access_token=$ACCESS_TOKEN

Example:

curl -X GET http://api.mercadolibre.com/marketplace/shipments/28323627433?access_token=$ACCESS_TOKEN

Response:

{
    "id": 28323627433,
    "order_id": 2405558127,
    "site_id": "MLM",
    "status": "shipped",
    "substatus": "",
    "date_created": "2020-04-22T20:29:21.000-04:00",
    "last_updated": "2020-04-24T02:02:41.000-04:00",
    "tracking_number": "MMXQP002466223E",
    "tracking_method": "CBT MA",
    "sender_id": 462092513,
    "receiver_id": 236524924,
    "receiver_address": {
        "id": 199676845,
        "address_line": "ALLENDE 516",
        "street_name": "ALLENDE",
        "street_number": "516",
        "comment": "Referencia: FRENTE AL DIF MUNICIPAL Entre: REVOLUCION Y OBREGON",
        "zip_code": "85950",
        "city": {
            "id": "TUxNQ0hVQTI0MDk",
            "name": "Huatabampo"
        },
        "state": {
            "id": "MX-SON",
            "name": "Sonora"
        },
        "country": {
            "id": "MX",
            "name": "Mexico"
        },
        "neighborhood": {
            "id": null,
            "name": "OBREGON"
        },
        "municipality": {
            "id": null,
            "name": "Huatabampo"
        },
        "agency": null,
        "types": [
            "default_buying_address"
        ],
        "latitude": 26.825872,
        "longitude": -109.635576,
        "geolocation_type": "ROOFTOP",
        "geolocation_last_updated": "2020-03-15T04:15:06Z",
        "geolocation_source": "google-maps",
        "receiver_name": "CLAUDIA RIVERA URIAS",
        "receiver_phone": "6474265677"
    },
    "shipping_items": [
        {
            "id": "MLM741156304",
            "description": "Riel Para Puerta Corrediza, Tipo T De 1.83 Metros. Riel Para",
            "quantity": 1,
            "dimensions": "8.0x20.0x104.0,6200.0"
        }
    ],
    "date_first_printed": "",
    "logistic_type": "drop_off",
    "mode": "me2"
}
Important:
Now you can check the shipping details using the "x-format-new = true" header. From March 31, 2021 it will be mandatory.

Example:

curl -X GET \
'http://api.mercadolibre.com/marketplace/shipments/28323627433?access_token=$ACCESS_TOKEN' \
-H 'x-format-new: true'

Response:

{
   "id": 4008772,
   "status": "delivered",
   "substatus": "",
   "declared_value": 13,
   "currency_id": "USD",
   "date_created": "2020-08-31T14:27:04.000-04:00",
   "last_updated": "2020-08-31T14:38:01.000-04:00",
   "tracking_number": "123456",
   "tracking_method": "CBT",
   "origin": {
       "sender_id": 123123232,
       "shipping_address": {
           "address_id": 132323,
           "address_line": "XXXXXXX",
           "street_name": "XXXXXXX",
           "street_number": "XXXXXXX",
           "comment": null,
           "zip_code": "XXXXXXX",
           "city": {
               "id": "TUxDQ1NBTjk4M2M",
               "name": "Santiago"
           },
           "state": {
               "id": "CL-RM",
               "name": "RM (Metropolitana)"
           },
           "country": {
               "id": "CL",
               "name": "Chile"
           },
           "neighborhood": {
               "id": null,
               "name": "Santiago"
           },
           "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": "ROOFTOP",
           "geolocation_last_updated": "2020-02-12T17:16:06Z",
           "geolocation_source": "google-maps",
           "delivery_preference": ""
       },
       "type": "selling_address"
   },
   "destination": {
       "type": "buying_address",
       "receiver_id": 12312312,
       "receiver_name": "test",
       "receiver_phone": "123123123123123",
       "comments": "",
       "shipping_address": {
           "address_id": 1113024548,
           "address_line": "Testing Street 1450",
           "street_name": "Testing Street",
           "street_number": "1450",
           "comment": "Referencia: The Testing Cavern",
           "zip_code": "",
           "city": {
               "id": "TUxDQ1RPQzgyMTdi",
               "name": "Tocopilla"
           },
           "state": {
               "id": "CL-AN",
               "name": "Antofagasta"
           },
           "country": {
               "id": "CL",
               "name": "Chile"
           },
           "neighborhood": {
               "id": null,
               "name": "The Neighborhood"
           },
           "municipality": {
               "id": null,
               "name": null
           },
           "agency": {
               "agency_id": null,
               "carrier_id": null,
               "description": null,
               "open_hours": null,
               "phone": null,
               "type": null
           },
           "types": [
               "billing",
               "default_buying_address",
               "default_selling_address",
               "shipping"
           ],
           "latitude": -22.085798,
           "longitude": -70.193006,
           "geolocation_type": "APPROXIMATE",
           "geolocation_last_updated": "2020-06-23T18:49:51Z",
           "geolocation_source": "google-maps",
           "delivery_preference": ""
       }
   },
   "dimensions": {
       "height": 1,
       "length": 1,
       "weight": 454,
       "width": 1
   },
   "external_reference": null,
   "lead_time": {
       "option_id": 46201,
       "shipping_method": {
           "id": 503146,
           "type": "standard",
           "name": "Envío internacional",
           "deliver_to": "address"
       },
       "currency_id": "USD",
       "cost": 9.02,
       "list_cost": 9.02,
       "cost_type": "charged",
       "service_id": 462,
       "estimated_delivery_time": {
           "type": "known_frame",
           "date": "2020-09-17T00:00:00.000-03:00",
           "unit": "hour",
           "offset": {
               "date": "2020-09-25T00:00:00.000-03:00",
               "shipping": 120
           },
           "time_frame": {
               "from": "",
               "to": ""
           },
           "pay_before": "2020-09-01T01:00:00.000-03:00",
           "shipping": 264,
           "handling": 48,
           "schedule": null
       },
   },
   "source": {
       "site_id": "MLC"
   },
   "logistic": {
       "mode": "me2",
       "type": "drop_off",
       "direction": "forward"
   },
   "tags": [
       "test_shipment"
   ]
}

Parameters

shipment_id: unique shipment identifier.
access_token: access key to private resources.


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

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

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 -X GET https://api.mercadolibre.com/marketplace/shipments/$SHIPMENT_ID/labels?access_token=$ACCESS_TOKEN

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 -X POST https://api.mercadolibre.com/marketplace/shipments/$SHIPMENT_ID/tracking?access_token=$ACCESS_TOKEN 
  -d '{
    "tracking_id": "String",
    "tracking_url": "http://carrier.com",
    "carrier": "name carrier"
}'

Example:

curl -X POST https://api.mercadolibre.com/marketplace/shipments/28262122315/tracking?access_token=$ACCESS_TOKEN 
  -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 -X GET https://api.mercadolibre.com/marketplace/shipments/$SHIPMENT_ID/items?access_token=$ACCESS_TOKEN

Example:

curl -X GET https://api.mercadolibre.com/marketplace/shipments/12234123/items?access_token=$ACCESS_TOKEN

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 -X GET https://api.mercadolibre.com/marketplace/shipments/$SHIPMENT_ID/lead_time?access_token=$ACCESS_TOKEN

Example:

curl -X GET https://api.mercadolibre.com/marketplace/shipments/12234123/lead_time?access_token=$ACCESS_TOKEN

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 -X GET https://api.mercadolibre.com/marketplace/shipments/$SHIPMENT_ID/history?access_token=$ACCESS_TOKEN

Example:

curl -X GET https://api.mercadolibre.com/marketplace/shipments/12234123/history?access_token=$ACCESS_TOKEN

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 -X GET https://api.mercadolibre.com/marketplace/shipments/$SHIPMENT_ID/carrier?access_token=$ACCESS_TOKEN

Example:

curl -X GET https://api.mercadolibre.com/marketplace/shipments/12234123/carrier?access_token=$ACCESS_TOKEN

Response:

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

Next: Messaging after sale.