Documentação do Mercado Livre
Confira todas as informações necessárias sobre as APIs Mercado Livre.
Documentação do
Última atualização em 04/08/2023
Shipments
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
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
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.
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.
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/paymentsExample:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/1111111111/paymentsResponse:
[
{
"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.
Consult delayed shipments
Sellers must ship their packages at specific times in order not to affect their reputation. Use these links in your app so that your sellers have access to this information (Argentina, Brazil, Mexico, Chile, Uruguay, and Colombia).
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/$SHIPMENT_ID/delaysExample:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/30143583389/delaysResponse:
{
"shipment_id": 30143583389,
"delays": [{
"type": "handling_delayed",
"date": "2020-09-23T09:07:20Z",
"source": "shipping-delays"
}]
}
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_statusesResponse:
[
{
"id": "to_be_agreed",
"name": "To be agreed",
"substatuses": []
},
{
"id": "pending",
"name": "Pending",
"substatuses": [
{
"id": "cost_exceeded",
"name": "Cost exceeded"
},
{
"id": "under_review",
"name": "Under review (e.g. fraud)"
},
{
"id": "reviewed",
"name": "Reviewed"
},
{
"id": "fraudulent",
"name": "fraudulent"
},
{
"id": "waiting_for_payment",
"name": "Waiting for shipping payment to be accredited"
},
{
"id": "shipment_paid",
"name": "Shipping cost has been paid"
},
{
"id": "creating_route",
"name": "Route has been created"
},
{
"id": "manufacturing",
"name": "Manufacturing"
},
{
"id": "buffered",
"name": "Buffered"
},
{
"id": "creating_shipping_order",
"name": "Creating shipping order"
}
]
},
{
"id": "handling",
"name": "Handling",
"substatuses": [
{
"id": "regenerating",
"name": "Regenerating"
},
{
"id": "waiting_for_label_generation",
"name": "Waiting for label generation"
},
{
"id": "invoice_pending",
"name": "Invoice pending"
},
{
"id": "waiting_for_return_confirmation",
"name": "Waiting for return confirmation"
},
{
"id": "return_confirmed",
"name": "Return Confirmed"
},
{
"id": "manufacturing",
"name": "Manufacturing"
},
{
"id": "agency_unavailable",
"name": "Agency unavailable"
}
]
},
{
"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": "ready_for_dropoff",
"name": "Ready for drop off"
},
{
"id": "picked_up",
"name": "Picked up"
},
{
"id": "stale",
"name": "Stale Ready To Ship"
},
{
"id": "dropped_off",
"name": "Dropped off in Melipoint"
},
{
"id": "delayed",
"name": "Delayed"
},
{
"id": "claimed_me",
"name": "Stale shipment claimed by buyer"
},
{
"id": "waiting_for_last_mile_authorization",
"name": "Waiting for last mile authorization"
},
{
"id": "rejected_in_hub",
"name": "Rejected in hub"
},
{
"id": "in_transit",
"name": "In transit"
},
{
"id": "in_warehouse",
"name": "In Warehouse"
},
{
"id": "ready_to_pack",
"name": "Ready to Pack"
},
{
"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 MELI"
},
{
"id": "in_packing_list",
"name": "In packing list"
},
{
"id": "in_plp",
"name": "In PLP"
},
{
"id": "on_hold",
"name": "On hold"
},
{
"id": "packed",
"name": "Packed"
},
{
"id": "on_route_to_pickup",
"name": "On route to pickup"
},
{
"id": "picking_up",
"name": "Picking up"
},
{
"id": "shipping_order_initialized",
"name": "Shipping order initialized"
},
{
"id": "looking_for_driver",
"name": "looking for driver"
}
]
},
{
"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": "changed_address",
"name": "Changed 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": "operator_intervention",
"name": "Need operator intervention"
},
{
"id": "claimed_me",
"name": "Stale shipped that was claimed by the receiver"
},
{
"id": "retained",
"name": "Retained when package is on going"
},
{
"id": "out_for_delivery",
"name": "Package is out for delivery"
},
{
"id": "delivery_failed",
"name": "Delivery failed"
},
{
"id": "waiting_for_confirmation",
"name": "waiting for confirmation"
},
{
"id": "at_the_door",
"name": "Shipment at buyers door"
},
{
"id": "buyer_edt_limit_stale",
"name": "Buyer edt limit stale"
},
{
"id": "delivery_blocked",
"name": "Delivery blocked"
},
{
"id": "awaiting_tax_documentation",
"name": "Awaiting tax documentation"
},
{
"id": "dangerous_area",
"name": "Dangerous area"
},
{
"id": "buyer_rescheduled",
"name": "Buyer rescheduled"
},
{
"id": "failover",
"name": "Failover"
},
{
"id": "picked_up",
"name": "Picked up"
},
{
"id": "dropped_off",
"name": "Dropped off"
},
{
"id": "at_customs",
"name": "At customs"
},
{
"id": "delayed_at_customs",
"name": "Delayed at customs"
},
{
"id": "left_customs",
"name": "Left customs"
},
{
"id": "missing_sender_payment",
"name": "Missing sender payment"
},
{
"id": "missing_sender_documentation",
"name": "Missing sender documentation"
},
{
"id": "missing_recipient_documentation",
"name": "Missing recipient documentation"
},
{
"id": "missing_recipient_payment",
"name": "Missing recipient payment"
},
{
"id": "import_taxes_paid",
"name": "Import taxes paid"
}
]
},
{
"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": "inferred",
"name": "Inferred Delivery"
}
]
},
{
"id": "not_delivered",
"name": "Not delivered",
"substatuses": [
{
"id": "returning_to_sender",
"name": "Returning to sender"
},
{
"id": "receiver_absent",
"name": "Receiver absent"
},
{
"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": "not_localized",
"name": "Not localized"
},
{
"id": "double_refund",
"name": "Double Refund"
},
{
"id": "cancelled_measurement_exceeded",
"name": "Shipment cancelled for measurement exceeded"
},
{
"id": "returned_to_hub",
"name": "Returned to hub"
},
{
"id": "returned_to_agency",
"name": "Returned to agency"
},
{
"id": "picked_up_for_return",
"name": "Picked up for return"
},
{
"id": "claimed_me",
"name": "Not delivered that was claimed by the receiver"
},
{
"id": "returning_to_warehouse",
"name": "Returning to Warehouse"
},
{
"id": "returning_to_hub",
"name": "Returning to Hub"
},
{
"id": "soon_to_be_returned",
"name": "Soon to be returned"
},
{
"id": "return_failed",
"name": "Return failed"
},
{
"id": "in_storage",
"name": "In storage"
},
{
"id": "pending_recovery",
"name": "Pending recovery"
},
{
"id": "agency_unavailable",
"name": "Agency unavailable"
},
{
"id": "rejected_damaged",
"name": "Rejected damaged"
},
{
"id": "refused_delivery",
"name": "Refused delivery"
},
{
"id": "refunded_by_delay",
"name": "Refunded by delay"
},
{
"id": "delayed",
"name": "Delayed"
},
{
"id": "delayed_to_hub",
"name": "Delayed to hub"
},
{
"id": "shipment_stopped",
"name": "Shipment stopped"
},
{
"id": "awaiting_tax_documentation",
"name": "Awaiting tax documentation"
},
{
"id": "retained",
"name": "Retained"
},
{
"id": "stolen",
"name": "Stolen"
},
{
"id": "returned",
"name": "Returned"
},
{
"id": "confiscated",
"name": "confiscated"
},
{
"id": "damaged",
"name": "Package damaged in hub"
},
{
"id": "lost",
"name": "Package lost"
},
{
"id": "recovered",
"name": "Recovered"
},
{
"id": "returned_to_warehouse",
"name": "Returned to Warehouse"
},
{
"id": "not_recovered",
"name": "Not recovered"
},
{
"id": "detained_at_customs",
"name": "Detained at customs"
},
{
"id": "detained_at_origin",
"name": "Detained at origin"
},
{
"id": "unclaimed",
"name": "Unclaimed by seller"
},
{
"id": "import_tax_rejected",
"name": "Import tax rejected"
},
{
"id": "import_tax_expired",
"name": "Import tax expired"
},
{
"id": "rider_not_found",
"name": "Rider not found"
}
]
},
{
"id": "not_verified",
"name": "Not verified",
"substatuses": []
},
{
"id": "cancelled",
"name": "Cancelled",
"substatuses": [
{
"id": "recovered",
"name": "Recovered"
},
{
"id": "label_expired",
"name": "Label Expired"
},
{
"id": "cancelled_manually",
"name": "Cancelled Manually"
},
{
"id": "fraudulent",
"name": "Cancelled Fraudulent"
},
{
"id": "return_expired",
"name": "Return expired"
},
{
"id": "return_session_expired",
"name": "Return session expired"
},
{
"id": "unfulfillable",
"name": "Unfulfillable"
},
{
"id": "closed_by_user",
"name": "User changes the type of shipping and cancels the previous"
},
{
"id": "pack_splitted",
"name": "The pack was split by the cart splitter so the shipment gets cancelled"
},
{
"id": "shipped_outside_me",
"name": "Shipped outside me"
},
{
"id": "shipped_outside_me_trusted",
"name": "Shipped outside me by trusted seller"
},
{
"id": "inferred_shipped",
"name": "Inferred shipped"
},
{
"id": "service_unavailable",
"name": "Service unavailable"
},
{
"id": "dismissed",
"name": "Dismissed"
},
{
"id": "time_expired",
"name": "Time expired"
},
{
"id": "pack_partially_cancelled",
"name": "Pack partially cancelled"
},
{
"id": "rejected_manually",
"name": "Rejected manually"
},
{
"id": "closed_store",
"name": "Closed store"
},
{
"id": "out_of_range",
"name": "Out of range"
}
]
},
{
"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": []
}
]
Create additional shipping packages
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
- All subpacks have a unique package_id assigned
- None subpackage has a package_id assigned
Previous conditions implied that package_id can be not used, but if you decide to use it all subpack have to have a unique pakage_id.
- The shipment must have an order quantity greater than 2 or have more than one order.
- The order_id represents the order that contains the product that must be separated from the original package.
- A new shipment will be created with the order corresponding to the section order_id and will trigger the corresponding notifications.
- The same shipment can only be split into two boxes at a time and it cannot be split multiple times.
Request:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/$SHIPMENT_ID/split -d
{
"reason": "DIMENSIONS_EXCEEDED",
"packs": [{
"package_id": 12345, --- OPTIONAL FIELD ---
"orders": [{
"id": 123123123123,
"quantity": 2
}]
},
{
"package_id": 345677, --- OPTIONAL FIELD ---
"orders": [{
"id": 123123123123,
"quantity": 1
},
{
"id": 2424242424242,
"quantity": 1
}
]
}
]
}
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.
For more information, visit Logistic types.
Next: Payment Handling.