Shipment Handling

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

→New Resources
→Items
→Costs
    ↳Parameters
→Lead Time
→Descripción de los tiempos de estimación
→History
   →Carrier information
   ↳Status and substatus information
→Payments
→Available parameters
→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:

curl -X GET https://api.mercadolibre.com/shipments/shipment_id?access_token=$ACCESS_TOKEN
{
  "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 call:

curl -X OPTION https://api.mercadolibre.com/shipments/shipment_id?access_token=$ACCESS_TOKEN
Note:
external_reference refers to the shipment-related pack number.


New resources

The new Shipments resource version shows new supplementary resources that offer detailed information for more efficient work. Find below a detailed description of such resources. Check our API docs.


Items

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 https://api.mercadolibre.com/shipments/shipment_id/items?access_token=$ACCESS_TOKEN

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


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


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 https://api.mercadolibre.com/shipments/shipment_id/lead_time?access_token=$ACCESS_TOKEN
{
  "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",
  ]
}

Note: Bear in mind that the cost_type field may be "free", "charged" or "partially_free".


Estimated time description

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.


History

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

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

[
  {
    "status": "string",
    "substatus": "string",
    "date": "2016-12-30T12:32:35.000Z"
  }
]

Example:

https://api.mercadolibre.com/shipments/1234567899/history?access_token=$ACCESS_TOKEN

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

]

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

  {
          "url": "string",
          "name": "string"

  }

Ejemplo:

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

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


Payments

'Shipment-related payments are returned by resource /shipments/shipment_id/payments. Now that the shipment payment will be specified, bear in mind that you will be able to get basic information about it with this resource. payment_id works just like order IDs.

curl -X GET https://api.mercadolibre.com/shipments/shipment_id/payments
[
  {
    "payment_id": 0,
    "amount": 0,
    "status": "string"
  }
]


Available parameters

Find below the values available for each parameter:
logistic.direction: forward, return
logistic.mode: me2, me1, custom
logistic.type: default, drop_off, xd_drop_off, cross_docking, fulfillment
source.site_id: sites
source.market_place: Mercado Libre, OFF l
ead_time.shipping_method.type:
next_day, express, standard, same_day
lead_time.shipping_method.deliver_to: address, agency
lead_time.currency_id: currencies
lead_time.cost_type: free, partially_free, charged
lead_time.delay: handling_delayed, shipping_delayed, shipping_delayed_extended
destination/origin.type: agency, buying_address, selling_address
discount.type: loyal, special


Non-combinable items

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 https://api.mercadolibre.com/shipments/shipment_id/split?access_token=token

JSON:

	{
  "shipments": [
    {
      "reason": "text",
                   “description”: “text”
      "orders": [
        {
          "id": "order_id",

        }
      ]
    }
  ]
}

Bear in mind that this resource is intended to avoid package problems, and it should not be used in all cases. We will soon improve this process.


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.

Next: Payment Handling.