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.

Inform Status

Report status of a shipment on route, when you inform the tracking number.

Request:

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

Inform Delivered

Report shipment has been delivered to the buyer. A product has been delivered to the buyer, so you must make a change in the status of the shipment to “delivered”. This status is final and irreversible.

Example DELIVERED:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X POST https://api.mercadolibre.com/marketplace/shipments/28262122315/tracking/status
  -d '{
    "tracking_id": "TKR123",
    "status": "delivered"
}'

Response:

{
    "status": "success"
}

Inform Not Delivered

Report shipment has been NOT delivered to the buyer. The status "not_delivered" is a final and irreversible state. It should only be used when there are no more delivery attempts. To mark the purchase as not delivered, you must report the status as "not_delivered"

Example NOT_DELIVERED:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X POST https://api.mercadolibre.com/marketplace/shipments/28262122315/tracking/status
  -d '{
    "tracking_id": "TKR123",
    "status": "not_delivered"
}'

Response:

{
    "status": "success"
}

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

Create additional shipping packages (Shipment Split)

If you have a problem when grouping different products in the same package (either because they are in different warehouses, or are fragile, or do not fit in the same box, etc.) you can use the feature that allows you to generate additional packages in order to ship all products.

Considerations

Possible values in the "reason" field

FRAGILE: fragile products.
ANOTHER_WAREHOUSE: another warehouses.
IRREGULAR_SHAPE: irregular shape.
OTHER_MOTIVE: other motive.
DIMENSIONS_EXCEEDED: dimensions exceeded.

Request:

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

{
	"reason": "IRREGULAR_SHAPE",
	"packs": [
		{
			"orders": [
				{
					"id": "2000000000000002",
					"quantity": 1
				}
			]
		},
		{
			"orders": [
				{
					"id": "2000000000000002",
					"quantity": 1
				}
			]
		}
	]
}

Response

The successful response will be just a "200 - OK" with an empty return.

{}

Post-Split Considerations

Since the resource does not return the newly created orders, it should be checked through the order or shipment notifications corresponding to the split.

With this, you will see the following impacts:

• Pack: The status of this order's pack will change to "status": "cancelled" and "status_detail": "splitted"
• Order: The order will also have "status": "cancelled" and in "cancel_detail": it will include the description"code": "pack_splitted"
• Shipments: The shipment will have "status": "cancelled" and "substatus": "pack_splitted"
• Finally, as a way to identify that the new order is related to the previous one that underwent the split, the shipment will have the field sibling_id with the number of the canceled shipment, as well as the Reason with the cause of the split

Errors

When managing a split, you may encounter the following errors. It is crucial that you understand the cause of each and know how to correct them, in order to efficiently handle the situation. Here is the information you need to identify and resolve these issues.

Body is a invalid:

{
    "message": "Invalid body",
    "error": "bad_request",
    "status": 400,
    "cause": []
}

The shipment does not belong to the seller that requests the split:

{
    "message": "The shipment 4397100000 does not belong to merchant: 1350000000",
    "error": "forbidden",
    "status": 403,
    "cause": []
}

Total items quantity does not match with original shipment:

{
    "message": "Order quantity mismatch. The total items quantity in the new packs should match the original shipment total quantity.",
    "error": "SPLIT_ERROR_400",
    "status": 400,
    "cause": null
}

Body has invalid reason data:

{
    "message": "Invalid body",
    "error": "bad_request",
    "status": 400,
    "cause": [
        "/reason: value must be one of \"FRAGILE\", \"ANOTHER_WAREHOUSE\", \"IRREGULAR_SHAPE\", \"DIMENSIONS_EXCEEDED\", \"OTHER_MOTIVE\""
    ]
}

Invalid shipment id:

{
    "message": "Invalid shipment id",
    "error": "bad_request",
    "status": 400,
    "cause": [
        "shipment not found"
    ]
}

Shipment already shipped:

{
    "message": "Shipment can't be splitted at this point. Invalid status.",
    "error": "SPLIT_ERROR_422",
    "status": 422,
    "cause": null
}

Package into more than two new packages:

{
    "message": "Invalid body",
    "error": "bad_request",
    "status": 400,
    "cause": [
        "/packs: you must specify exactly 2 packs"
    ]
}

Next: Compensations.