Ship products

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":

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 allows sellers to use their own shipping infrastructure of choice, but provides not tracking integration and requires the sellers to provide the tracking number of each individual shipping.
• 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": 12345,
      "cost": 0,
      "compensation": 0,
      "save": 0,
      "discounts": [
          {
              "rate": 1,
              "type": "ratio",
              "promoted_amount": 254.07
          }
      ],
      "cost_details": [],
      “compensations”: []
  },
  "senders": [
      {
          "user_id": 456789,
          "cost": 177.85,
          "compensations":[
            {
              "amount":173.27,
              "reason":"incorrect_dimensions",
              "comment":"Incorrect package dimensions"
            }
          ],
          "save": 76.22,
          "discounts": [
              {
                  "rate": 0.3,
                  "type": "mandatory",
                  "promoted_amount": 76.22
              }
          ],
      "compensation": 0
      }
  ]
}

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.
amount: valor de compensación.
reason: razón de compensación.
comment: comentarios adicionales sobre la compensación.
currency_id: local currency value.

Item´s free shipping cost

Get the free shipping cost of the marketplace items with the request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/shipping_options/free

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/1317418851/shipping_options/free?item_id=MLM1886904585

Response:

{
    "coverage": {
        "all_country": {
            "list_cost": 91.93,
            "currency_id": "MXN",
            "billable_weight": 150
        }
    }
}

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). See more information about Updates on label content for international shipments in Mexico.
  How to identifier:
  "mode": "me2"
  "logistic_type": "drop_off"
  "logistic_type": "cross_docking" (only for MLM)
  


• 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

Print shipping label

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

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

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.

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.