Shipments

The Shipments resource includes all the information referred to the shipment to be made and required to complete the transaction. Remember that to work with the updated JSON, you should send the "x-format-new: true" parameter when you make the GET.

Contents

→Consult shipments
→Items associated with a shipment
→Shipping cost
    ↳Parameters
→Shipping payment
→Lead Time
→Response fields (Estimated time)
→Shipments with delay
→History
→Status y substatus Front vs. API
→Carrier information
   ↳Status and substatus information
→Non-combinable items
→Possible values in the "reason" field


Bear in mind that the new Orders JSON will no longer include Shipping data. The structure of the /shipments/shipment_id/ resource will remain the same, showing the basic information needed to make the shipment. We included the following changes to the JSON structure:


Consult shipments

Note:
You can access information about the different types of logistics in Mercado Shipos 2.
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/shipment_id
{
  "id": 0,
  "external_reference": "string",
   "status": "string",
  "substatus": "string",
  "date_created": "string",
  "last_updated": "string",
  "declared_value": 0,
  "dimensions": {
    "height": 0,
    "width": 0,
    "length": 0,
    "weight": 0
  },
  "logistic": {
    "direction": "forward",
    "mode": "me2",
    "type": "drop_off"
  },
  "source": {
    "site_id": "MLM",
    "market_place": "MELI",
    "application_id": null
  },
  "tracking_number": "string",
  "origin": {
    "type": "selling_address",
    "sender_id": 0,
    "shipping_address": {
      "id": 0,
      "address_id": 0,
      "address_line": "string",
      "street_name": "string",
      "street_number": 0,
      "comment": "string",
      "zip_code": "string",
      "city": {
        "id": "string",
        "name": "string"
      },
      "state": {
        "id": "string",
        "name": "string"
      },
      "country": {
        "id": "string",
        "name": "string"
      },
      "neighborhood": {
        "id": "string",
        "name": "string"
      },
      "municipality": {
        "id": "string",
        "name": "string"
      },
      "types": {
        "default_buying_address": 0
      },
      "agency": {
        "carrier_id": 0,
        "agency_id": "string",
        "description": "string",
        "phone": "string",
        "open_hours": "string"
      },
      "latitude": 0,
      "longitude": 0,
      "geolocation_type": "string",
      "is_valid_for_carrier": true
    }
  },
  "destination": {
    "type": "buying_address",
    "receiver_id": 0,
    "receiver_name": "string",
    "receiver_phone": "string",
    "comments": "string",
    "shipping_address": {
      "id": 0,
      "address_id": 0,
      "address_line": "string",
      "street_name": "string",
      "street_number": 0,
      "comment": "string",
      "zip_code": "string",
      "city": {
        "id": "string",
        "name": "string"
      },
      "state": {
        "id": "string",
        "name": "string"
      },
      "country": {
        "id": "string",
        "name": "string"
      },
      "neighborhood": {
        "id": "string",
        "name": "string"
      },
      "municipality": {
        "id": "string",
        "name": "string"
      },
      "types": {
        "default_buying_address": 0
      },
      "agency": {
        "carrier_id": 0,
        "agency_id": "string",
        "description": "string",
        "phone": "string",
        "open_hours": "string"
      },
      "latitude": 0,
      "longitude": 0,
      "geolocation_type": "string",
      "is_valid_for_carrier": true
    }
  },
  "lead_time": {
    "option_id": 0,
    "shipping_method": {
      "id": 0,
      "type": "standard",
      "name": "string",
      "deliver_to": "address"
    },
    "currency_id": "string",
    "cost": 0,
    "cost_type": "charged",
    "service_id": 0,
    "estimated_delivery_time": {
      "type": "known",
      "date": "string",
      "shipping": 0,
      "handling": 0,
      "unit": "string",
      "offset": {
        "date": "string",
        "shipping": 0
      },
      "time_frame": {
        "from": 0,
        "to": 0
      },
      "pay_before": "string"
    }
  },
  "tags": [
    "string"
  ]
}

To understand the meaning of each parameter, make this request:

curl -X OPTION -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/shipment_id
Note:
external_reference refers to the shipment-related pack number.


Items associated with a shipment

Shipment-related items are returned by resource /shipments/shipment_id/items. If the item contains variations (e.g., size or color in apparel), you can also see which corresponds to the order within the shipment. As we enable shipments with more than one item, the list will include each of them.


Note:
Every seller will only view their own products.
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/shipment_id/items

[
  {
    "item_id": "string",
    "description": "string",
    "quantity": 0,
    "variation_id": 0,
    "dimensions": {
      "height": 0,
      "width": 0,
      "length": 0,
      "weight": 0
    },
    "order_id": 0,
    "sender_id": 0
  }
]


Shipping costs

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.

Note:
We are working in a new version of this resource. The current answer will be kept throughout change implementation, and the "X-Costs-New = true" header should be used to access the new format, as explained below.
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/SHIPMENT_ID/costs
{
	"gross_amount": 24.55,
	"receiver": {
    	"user_id": 74425755,
    	"cost": 0,
    	"compensation": 0,
    	"save": 0,
    	"discounts": [
        	{
            	"rate": 1,
            	"type": "loyal",
            	"promoted_amount": 4.07
        	}
    		]
	},
	"senders": [
    	{
        	"user_id": 81387353,
        	"cost": 8.19,
        	"compensation": 0,
        	"save": 0,
        	"discounts": [
            	{
                	"rate": 0.6,
                	"type": "mandatory",
                	"promoted_amount": 12.29
            	}
        	]
    	}
	]
}

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.

Shipping payment

The /shipments/shipment_id/payments resource return the payments to shipment associated. Remember that the shipping payment will have details.

Request:

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

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/1111111111/payments

Response:

[
   {
       "payment_id": 1111111111,
       "user_id": 291760105,
       "amount": 17.7,
       "status": "approved"
   }
]


Lead Time

Everything related to shipment delivery times and service type, plus shipping and delivery deadlines are returned by resource /shipments/shipment_id/lead_time. While the basic shipment resource already includes useful information to make these estimates, here you will be able to view it in more detail for improved user experience.

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/shipment_id/lead_time
{
  "option_id": 0,
  "shipping_method": {
    "id": 0,
    "type": "standard",
    "name": "string",
    "deliver_to": "address"
  },
  "currency_id": "string",
  "cost": 0,
  "cost_type": "charged",
  "service_id": 0,
  "estimated_delivery_time": {
    "type": "known",
    "date": "string",
    "shipping": 0,
    "handling": 0,
    "unit": "string",
    "offset": {
      "date": "string",
      "shipping": 0
    },
    "time_frame": {
      "from": 0,
      "to": 0
    },
    "pay_before": "string"
  },
  "estimated_handling_limit": {
    "date":  "2016-12-30T12:32:35.000Z"
  },
  "estimated_delivery_extended": {
    "date":  "2016-12-30T12:32:35.000Z"
  },
  "estimated_delivery_limit": {
    "date":  "2016-12-30T12:32:35.000Z"
  },
  "estimated_delivery_final": {
    "date":  "2016-12-30T12:32:35.000Z"
  },
  "delay": [
    "shipping_delayed",
  ]
}

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


Response fields (Estimated time)

Deadlines for shipment dispatched and sent.
estimated_handling_limit: Deadline for seller to ship an item. Only the date is considered, since the time is entered just to maintain the structure. In other words, you have the whole day indicated in the field to ship the item before it automatically goes to delayed on the following day.
estimated_delivery_extended: Second delivery promise, if the original promise is not fulfilled.
estimated_delivery_limit: Deadline for the buyer to cancel the purchase and request a refund, provided that he/she has not received the shipment yet.
estimated_delivery_final: Final deadline to receive the shipment and define its final status, which may be either delivered or not_delivered, if a claim was filed. Find more information about shipping costs and handling time.


Shipments with delay

Important:
Sellers should dispatch their packages according to an indicated schedule to avoid damaging their reputation. Check the maximum schedule according to the type of logistics of the account:
- Argentina: as of July 5, 2021
- Brasil and México: as of July 12, 2021
- Chile and Uruguay: as of July 19, 2021
- Colombia: as of July 29, 2021

To find out about delayed shipments, use the /delays resource:

Request:

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

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/30143583389/delays

Response:

{
	"shipment_id": 30143583389,
	"delays": [{
		"type": "handling_delayed",
		"date": "2020-09-23T09:07:20Z",
		"source": "shipping-delays"
	}]
}
Notes:
- The sla_delayed type indicates that it exceeded the expected dispatch time defined by the SLA.
- When the shipment is not delayed, you will receive 404 error: "Delays Not Found for shipment".

Soon we will have an API to check the schedules and automate the process.



History

The status and sub-status history related to shipment life cycle is returned by resource /shipments/shipment_id/history.

Example:

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

[
  {
    "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"
  },

]


Status y substatus Front vs. API

Note that the substatus can change based on logistics types.


Tracking for Cross Docking

Front Description API - "status_history"
"En preparación" "We are preparing the package" status: handling
"En camino" "The seller shipped the package" status: ready_to_ship
substatus: picked_up, authorized_by_carrier
"Entered the distribution center of ....." status: ready_to_ship
substatus: in_hub
"Entregado" "we deliver the package" status: delivered

Tracking for Fulfillment

Front Description API - "status_history"
"En preparación" "We are preparing the package" status: handling
"En camino" "The package left the distribution center" status: shipped
"Entregado" "we deliver the package" status: delivered

Carrier information

The /shipments/shipment_id/carrier resource return the name and url to access the particular information of the carrier that is managing the shipment.

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/$SHIPMENT_ID/carrier
{
   "url":"string",
   "name":"string"
}

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/27691621451/carrier
{
   "url":"http://tracking.totalexpress.com.br/poupup_track.php?reid=3&pedido=14&nfiscal=1", 
   "name":"Total Express"
}

Status and substatus information

Find more information about the different shipment status and sub-status.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipment_statuses

Response:

{
    "id": "to_be_agreed",
    "name": "To be agreed",
    "substatuses": [
    ]
  },
  {
    "id": "pending",
    "name": "Pending",
    "substatuses": [
      {
        "id": "cost_exceeded",
        "name": "Cost exceeded"
      }
    ]
  },
  {
    "id": "handling",
    "name": "Handling",
    "substatuses": [
      {
        "id": "regenerating",
        "name": "Regenerating"
      },
      {
        "id": "waiting_for_label_generation",
        "name": "Waiting for label generation"
      }
    ]
  },
  {
    "id": "ready_to_ship",
    "name": "Ready to ship",
    "substatuses": [
      {
        "id": "ready_to_print",
        "name": "Ready to print"
      },
      {
        "id": "invoice_pending",
        "name": "Invoice pending"
      },
      {
        "id": "printed",
        "name": "Printed"
      },
      {
        "id": "in_pickup_list",
        "name": "In pikcup list"
      },
      {
        "id": "ready_for_pkl_creation",
        "name": "Ready for pkl creation"
      },
      {
        "id": "ready_for_pickup",
        "name": "Ready for pickup"
      },
      {
        "id": "picked_up",
        "name": "Picked up"
      },
      {
        "id": "stale",
        "name": "Stale Ready To Ship"
      },
      {
        "id": "in_hub",
        "name": "In hub"
      },
      {
        "id": "measures_ready",
        "name": "Measures and weight ready"
      },
      {
        "id": "waiting_for_carrier_authorization",
        "name": "Waiting for carrier authorization"
      },
      {
        "id": "authorized_by_carrier",
        "name": "Authorized by carrier"
      },
      {
        "id": "in_plp",
        "name": "In PLP"
      }
    ]
  },
  {
    "id": "shipped",
    "name": "Shipped",
    "substatuses": [
      {
        "id": "delayed",
        "name": "Delayed"
      },
      {
        "id": "waiting_for_withdrawal",
        "name": "Waiting for withdrawal"
      },
      {
        "id": "contact_with_carrier_required",
        "name": "Contact with carrier required"
      },
      {
        "id": "receiver_absent",
        "name": "Receiver absent"
      },
      {
        "id": "reclaimed",
        "name": "Reclaimed"
      },
      {
        "id": "not_localized",
        "name": "Not localized"
      },
      {
        "id": "forwarded_to_third",
        "name": "Forwarded to third party"
      },
      {
        "id": "soon_deliver",
        "name": "Soon deliver"
      },
      {
        "id": "refused_delivery",
        "name": "Delivery refused"
      },
      {
        "id": "bad_address",
        "name": "Bad address"
      },
      {
        "id": "negative_feedback",
        "name": "Stale shipped with negative feedback by buyer"
      },
      {
        "id": "need_review",
        "name": "Need to review carrier status to understand what happened"
      },
      {
        "id": "stale",
        "name": "Stale shipped"
      }
    ]
  },
  {
    "id": "delivered",
    "name": "Delivered",
    "substatuses": [
      {
        "id": "damaged",
        "name": "damaged"
      },
      {
        "id": "fulfilled_feedback",
        "name": "Fulfilled by buyer feedback"
      },
      {
        "id": "no_action_taken",
        "name": "No action taken by buyer"
      },
      {
        "id": "double_refund",
        "name": "Double Refund"
      }
    ]
  },
  {
    "id": "not_delivered",
    "name": "Not delivered",
    "substatuses": [
      {
        "id": "returning_to_sender",
        "name": "Returning to sender"
      },
      {
        "id": "retained",
        "name": "Retained"
      },
      {
        "id": "stolen",
        "name": "Stolen"
      },
      {
        "id": "returned",
        "name": "Returned"
      },
      {
        "id": "receiver_absent",
        "name": "Receiver absent"
      },
      {
        "id": "confiscated",
        "name": "confiscated"
      },
      {
        "id": "to_review",
        "name": "Closed shipment"
      },
      {
        "id": "destroyed",
        "name": "Destroyed"
      },
      {
        "id": "waiting_for_withdrawal",
        "name": "Waiting for withdrawal"
      },
      {
        "id": "negative_feedback",
        "name": "Stale shipped forced to not delivered due to negative feedback by buyer"
      },
      {
        "id": "claimed_me",
        "name": "Stale shipped with claim that was forced to not delivered"
      },
      {
        "id": "not_localized",
        "name": "Not localized"
      },
      {
        "id": "double_refund",
        "name": "Double Refund"
      }
    ]
  },
  {
    "id": "not_verified",
    "name": "Not verified",
    "substatuses": [
    ]
  },
  {
    "id": "cancelled",
    "name": "Cancelled",
    "substatuses": [
    ]
  },
  {
    "id": "closed",
    "name": "Closed",
    "substatuses": [
    ]
  },
  {
    "id": "error",
    "name": "Error",
    "substatuses": [
    ]
  },
  {
    "id": "active",
    "name": "Active",
    "substatuses": [
    ]
  },
  {
    "id": "not_specified",
    "name": "Not specified",
    "substatuses": [
    ]
  },
  {
    "id": "stale_ready_to_ship",
    "name": "Stale ready to ship",
    "substatuses": [
    ]
  },
  {
    "id": "stale_shipped",
    "name": "Stale shipped",
    "substatuses": [
    ]
  }


Non-combinable items

Important:
This resource does not apply to sales with Flex logistics.

If you have trouble grouping different products in the same package (because they are in different warehouses, they are fragile, they do not fit in the same box, etc.), you may use a resource that helps create additional packages to ship all the products.

Example:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -d
{
  "shipments": [
    {
      "reason": "text",
                   "description": "text"
      "orders": [
        {
          "id": "order_id",

        }
      ]
    }
  ]
}
https://api.mercadolibre.com/shipments/$SHIPMENT_ID/split


Possible values in the "reason" field

  • fragile
  • another_warehouse
  • irregular_shape
  • other_motive
Notes:
- “order_ID” displays the order that includes the product to be set aside from the original package.
- A new shipment with the order corresponding to the set aside “order_ID” will be created.
- The API will show no answer after the call, but status 201 only.
- Once a POST is made, a new shipment will be created, which will trigger the relevant notifications.

Important:
For more information, visit Logistic types.

Next: Payment Handling.

or register to recieve the latest news about our API