Create shipments
The Mercado Pago Shipping API allows you to manage shipments from sales generated with Checkout Pro. Leveraging Mercado Libre's logistics, you can get quotes and create shipments, manage them, and track packages, offering a better shopping experience to your customers.
Learn about the shipment management options and how to integrate them below.
It is possible to estimate the value of a shipment based on the package volume and the postal codes of the origin and destination points. This quote returns an option_id and a shipment_rate_id that you will use later to create the shipment.
To get a quote, send a POST to the endpoint /shipping/v1/shipments-rates including your Access TokenPrivate key of the application created in Mercado Pago that is used in the backend. You can access it through Your integrations > Integration data. and the parameters described in the table below.
curl
curl --location 'https://api.mercadopago.com/shipping/v1/shipments-rates' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer [Access Token]' \ --data '{ "packages": [ { "declared_value": 1500, "quantity": 1, "dimensions": { "weight": 500, "width": 30, "height": 30, "length": 30 } } ], "shipping_from": { "zip_code": "06760" }, "shipping_to": { "zip_code": "06720" } }'
| Field | Description | Type | Required |
packages | Contains the package information for the quote. | Array | Required |
packages.declared_value | Value of the package to be shipped. Does not include the estimated shipping cost. | Number | Required |
packages.quantity | Quantity of packages. The only allowed value is 1. | Number | Required |
packages.dimensions | Object containing the package dimensions. The maximum allowed values are: - Each side must be maximum 150 cm. - The total dimensions limit must not exceed 330 cm. - The maximum weight is 30 kg (real or volumetric). | Object | Required |
packages.dimensions.height | Package height in centimeters. | Number | Required |
packages.dimensions.width | Package width in centimeters. | Number | Required |
packages.dimensions.length | Package length in centimeters. | Number | Required |
packages.dimensions.weight | Package weight in grams. | Number | Required |
shipping_from.zip_code | Postal code of the origin address. If this value is provided, it will be used to calculate the quote. Otherwise, the Shipping data configured in Mercado Pago will be applied. | String | Optional |
shipping_to.zip_code | Postal code of the destination address. | String | Required |
If the request is correct, the response will return the shipping quote, which may contain more than one option varying in price and/or delivery time.
json
{ "shipment_rate_id": "be9fae0d-1079-471e-887d-55861965d10e", "rates": [ { "options": [ { "id": "3c86ea36-fef7-4a9e-9092-d4eb6e744834", "pricing": { "base_price": "87", "price": "87", "discounts": [] }, "method": "standard", "pay_before": "2025-10-27T00:00:00-06:00", "delivery_promise": { "shipping_from": "2025-10-28T12:00:00-06:00", "shipping_to": "2025-10-30T12:00:00-06:00" }, "delivery_days": { "from": 3, "to": 5 } } ], "packages": [ { "quantity": 1, "dimensions": { "weight": "500", "width": "30", "height": "30", "length": "30" } } ] } ], "shipping_to": { "zip_code": "06720", "country_id": "MX", "city_id": "TUxNQ0NVQTczMTI", "state_id": "MX-DIF" } }
| Field | Description | Type |
shipment_rate_id | Quote identifier. Use this value as shipment_rate_id when creating the shipment. | String |
rates | List of quotes for the package based on the provided address. | Array |
options | List of available quote options. | Array |
id | Shipping option identifier. Use this value as option_id when creating the shipment from the quote. | String |
base_price | Gross shipping value. | Number |
price | Net shipping value. | Number |
method | Delivery method. Currently the responses can be: standard, for standard offers, and economic, for cheaper offers. | String |
pay_before | Expected date to guarantee the generated shipping promise. | Date |
delivery_promise.shipping_from | Initial date of the delivery promise. | String |
delivery_promise.shipping_to | Final date of the delivery promise. | String |
delivery_days.from | Minimum business days for the delivery promise. | Integer |
delivery_days.to | Maximum business days for the delivery promise. | Integer |
packages.quantity | Quantity of quoted packages. | Number |
packages.dimensions | Dimensions of the quoted package. | Object |
shipping_to.zip_code | Postal code of the destination address. | String |
shipping_to.city_id | Identifier of the destination address city. | String |
shipping_to.state_id | Abbreviation of the destination address state. | String |
shipping_to.country_id | Abbreviation of the destination address country. | String |
To learn about the errors that this request can return, access our API Reference.
Once you get a quote, you can create a shipment using the information you received in the quote response. If the response returned multiple options, choose the one that best fits your needs.
To create a shipment, send a POST to the endpoint /shipping/v1/shipments including your Access TokenPrivate key of the application created in Mercado Pago that is used in the backend. You can access it through Your integrations > Integration data. and the parameters described in the table below, including the quote identifiers.
curl
curl --location 'https://api.mercadopago.com/shipping/v1/shipments' \ --header 'Authorization: Bearer [Access Token]' \ --header 'Content-Type: application/json' \ --header 'X-Idempotency-Key: [Idempotency Key]' \ --data '{ "rates": { "shipment_rate_id": "be9fae0d-1079-471e-887d-55861965d10e", "option_id": "d7f61877-4a39-4f94-b6fb-d80a6351c714" }, "payment_intent_id": "1378330711-d13353c3-525c-442e-b101-27b892b2746d", "receiver": { "person": { "email": "john.doe@example.com", "full_name": "John Doe", "identification": "12345678901", "phone": "+5511999999999" }, "address": { "floor": "2", "apartment": "201", "street_number": "123", "street_name": "Calle de las Flores", "zip_code": "01234567", "neighborhood": "Centro", "references": "cerca del mercado" } }, "external_reference_id": "ext-ref-12345", "items": [ { "title": "Smartphone Samsung Galaxy", "quantity": 1, "unit_price": 7999, "description": "White", "fiscal_data": { "sat": "12345678", "sat_measurement_id": "SAT001", "measurement_unit": "UN", "package_id": "PKG001", "dangerous_material_id": "DM000" }, "dimensions": { "unit": "G", "height": 15, "width": 8, "length": 1, "weight": 200 } } ] }'
| Field | Description | Type | Required |
X-Idempotency-Key | Header. Key to ensure each request is unique and avoid duplicate shipment creation. We recommend using a UUID V4 or random strings. Accepts values between 1 and 64 characters. | String | Required |
rates | Quote information for the package and provided address. | Object | Required |
rates.shipment_rate_id | Quote identifier, obtained in the response to that request. | String | Required |
rates.option_id | Selected quote option identifier, obtained in the response to that request. | String | Required |
payment_intent_id | Identifier of the payment associated with the shipment. | String | Optional |
receiver | Receiver information (who will receive the package). | Object | Required |
receiver.person | Receiver's personal information. | Object | Required |
receiver.person.email | Receiver's email address. | String | Required |
receiver.person.full_name | Receiver's full name. | String | Required |
receiver.person.identification | Receiver's identification document. | String | Optional |
receiver.person.phone | Receiver's phone number. | String | Required |
receiver.address | Receiver's address information. | Object | Required |
receiver.address.floor | Apartment floor. | String | Optional |
receiver.address.apartment | Apartment number (internal). | String | Optional |
receiver.address.street_number | Street number (external). | String | Required |
receiver.address.street_name | Street name. | String | Required |
receiver.address.zip_code | Postal code of the address. | String | Required |
receiver.address.neighborhood | Neighborhood or district of the address. | String | Optional |
receiver.address.references | Address details or complement. | String | Optional |
external_reference_id | Information on the label to identify an external reference. | String | Optional |
items | Information about the items to ship. | Array | Required |
items.title | Item title. | String | Required |
items.quantity | Quantity of items. | Number | Required |
items.unit_price | Item unit price. | Number | Required |
items.description | Item description. | String | Optional |
items.fiscal_data | Product fiscal data. | Object | Required |
items.fiscal_data.sat | SAT category of the item. | String | Required |
items.fiscal_data.sat_measurement_id | Unique identifier of the product measurement unit according to SAT units. | String | Required |
items.fiscal_data.measurement_unit | Product measurement unit. | String | Required |
items.fiscal_data.package_id | Package identifier. | String | Required |
items.fiscal_data.dangerous_material_id | Identifier for dangerous products. | String | Optional |
items.dimensions | Item size. Consult the sizing best practices to learn about the permitted limits. | Object | Optional |
items.dimensions.height | Item height in centimeters. Consult the sizing best practices. | Number | Required |
items.dimensions.width | Item width in centimeters. Consult the sizing best practices. | Number | Required |
items.dimensions.length | Item length in centimeters. Consult the sizing best practices. | Number | Required |
items.dimensions.weight | Item weight in grams. Consult the sizing best practices. | Number | Required |
items.dimensions.unit | Measurement unit. Consult the sizing best practices. | String | Required |
If the request is sent correctly, the response will return the data of the created shipment.
json
{ "shipments": [ { "id": "7311edef-a46e-4a42-a8e1-6a142fa7ee48", "packages": [ { "id": "f0c6e696-becb-4c9a-92c4-40422052583b" } ] } ], "idempotency_key": "unique-key-12345", "rates": { "shipment_rate_id": "52194ade-d6a9-4e9e-a582-c0897343849a", "option_id": "741e1150-5493-47e4-9720-ceca12d30af9", "delivery_promise": { "from": "2025-10-28T12:00:00-06:00", "to": "2025-10-30T12:00:00-06:00" } }, "payment_intent_id": "1378330711-d13353c3-525c-442e-b101-27b892b2746d", "receiver": { "person": { "email": "john.doe@example.com", "full_name": "John Doe", "identification": "12345678901", "phone": "+5511999999999" }, "address": { "floor": "2", "apartment": "201", "street_number": "123", "street_name": "Calle de las Flores", "zip_code": "01234567", "neighborhood": "Centro", "references": "cerca del mercado" } }, "origin": { "zip_code": "45601", "city": "Tlaquepaque", "state": "Jalisco", "country": "Mexico", "neighborhood": "La Calerilla", "address_line": "Calz de Guadalupe 432", "references": "200 Referencia: Casa blanca y azul." }, "external_reference_id": "ext-ref-12345", "items": [ { "title": "Smartphone Samsung Galaxy", "quantity": 1, "unit_price": 7999, "description": "White", "fiscal_data": { "sat": "12345678", "sat_measurement_id": "SAT001", "measurement_unit": "UN", "package_id": "PKG001", "dangerous_material_id": "DM000" }, "dimensions": { "unit": "G", "height": 15, "width": 8, "length": 1, "weight": 200 } } ] }
| Field | Description | Type |
shipments | Information of the created shipments. | Array |
shipments.id | Unique identifier of the shipment. | String |
shipments.packages | Packages included in the shipment. | Array |
shipments.packages.id | Identifier of the shipped package. Use this value to generate labels and consult shipments. | String |
idempotency_key | Idempotency key to avoid duplicates. | String |
rates | Information of the quote used. | Object |
rates.delivery_promise | Confirmed delivery promise. | Object |
rates.delivery_promise.from | Initial date of the delivery promise. | String |
rates.delivery_promise.to | Final date of the delivery promise. | String |
payment_intent_id | Identifier of the payment associated with the shipment. | String |
receiver | Information of the shipment receiver. | Object |
origin | Information of the origin address. | Object |
external_reference_id | External reference provided in the request. | String |
items | Items included in the shipment. | Array |
To learn about the errors that this request can return, access our API Reference.
It is possible to consult a shipment and obtain its complete data once created. This query will allow you to access the package identifier (packages.id) and the tracking number (tracking_number), among other data.
To do so, send a GET with your Access TokenPrivate key of the application created in Mercado Pago that is used in the backend. You can access it through Your integrations > Integration data. to the endpoint /shipping/v1/shipments with the necessary query parameters.
curl
curl --location 'https://api.mercadopago.com/shipping/v1/shipments?package_id=1c5dce04-dc5e-4fed-b7f1-08c192977c70' \ --header 'Authorization: Bearer [Access Token]'
Optionally, you can also send the following parameters as query parameters to filter the query:
| Parameter | Description | Type | Required |
package_id | Identifier of the package to consult. | String | Optional |
external_reference_id | External reference of the shipment. | String | Optional |
payment_id | Identifier of the associated payment. | String | Optional |
payment_intent_id | Identifier of the payment intent. | String | Optional |
If the request is correct, the response will be like the example below.
json
{ "data": [ { "external_reference_id": "ext-ref-12345", "shipment_id": "7311edef-a46e-4a42-a8e1-6a142fa7ee48", "shipment_status": "ready", "active_phase": "forward", "created_at": "2026-02-09T20:17:16.637Z", "shipping_to": { "address": "Calle 789", "city_locality": "Ciudad de México", "state_province": "MX", "complement": "calle sin salida", "zip_code": "07000-000", "country_code": "MX" }, "shipping_from": { "phone": "5513997343432", "contact": "Nicolas", "address": "Calle 123, 100", "city_locality": "Ciudad de México", "state_province": "MX", "complement": "calle sin salida", "zip_code": "11520", "country_code": "MX" }, "packages": [ { "id": "1c5dce04-dc5e-4fed-b7f1-08c192977c70", "dimensions": { "height": 50, "length": 12, "width": 50, "weight": 30, "volume": 2 }, "items": [ { "title": "Product", "description": "Product description", "unit_price": 100 } ], "price": { "amount": "12.0", "currency": "MXN" }, "tracking_info": { "tracking_number": "1c5dce04-dc5e-4fed-b7f1-08c192977c70", "last_status": "ready", "updated_at": "2026-02-09T20:17:16.637Z" } } ], "dispatch_date": { "from": "2025-06-10T09:30:00.073890622Z" } } ] }
| Field | Description | Type |
external_reference_id | External reference of the shipment. | String |
shipment_id | Unique identifier of the shipment. | String |
shipment_status | Current status of the shipment. | String |
active_phase | Active phase of the shipment: forward (shipment to the customer) or reverse (return). | String |
created_at | Date and time of shipment creation. | Date |
shipping_to | Information of the destination address with complete details of the receiver. | Object |
shipping_from | Information of the origin address with sender details. | Object |
packages | Packages included in the shipment. | Array |
packages.id | Package identifier. Use this value to generate labels. | String |
packages.dimensions | Package dimensions (height, length, width, weight, and volume). | Object |
packages.items | Articles included in the package. | Array |
packages.price | Package price information. | Object |
packages.tracking_info | Package tracking information. | Object |
packages.tracking_info.tracking_number | Package tracking number. Use this value to track the shipment. | String |
packages.tracking_info.last_status | Last recorded status of the package. | String |
dispatch_date | Estimated dispatch date of the shipment. | Object |
To learn about the errors that this request can return, access our API Reference.
To cancel an existing shipment, send a DELETE request to the endpoint /shipping/v1/shipments/{shipment_id} including your Access TokenPrivate key of the application created in Mercado Pago that is used in the backend. You can access it through Your integrations > Integration data. and the identifier of the shipment to cancel in the path.
curl
curl --location --request DELETE 'https://api.mercadopago.com/shipping/v1/shipments/e522fa4a-c3f8-4f34-a353-16f45a012345' \ --header 'Authorization: Bearer [Access Token]'
If the request is correct, the shipment will be canceled and the response will return a 204 No Content status.
To learn about the errors that this request can return, access our API Reference.
With the Labels API, you can generate the labels that contain all the information necessary to dispatch the packages of your sold products. You can choose whether you want the label to be generated in PDF, ZIP, or ZPL for download, or in JSON format.
dispatch-date parameter is present, labels can only be generated 24 hours before the date and time defined in that field.To generate the label, send a GET with your Access TokenPrivate key of the application created in Mercado Pago that is used in the backend. You can access it through Your integrations > Integration data. and the parameters indicated in the table below to the endpoint /shipping/v1/shipments/{id}/packages/{package_id}/label.
curl
curl --location 'https://api.mercadopago.com/shipping/v1/shipments/1371769672-9785ed21-f66d-4290-a628-434343434/packages/678029ce4265b922a299999/label' \ --header 'X-Content-Type: json' \ --header 'Authorization: Bearer [Access Token]'
| Field | Description | Type | Required |
shipment_id | Path. Shipment identifier, which can be obtained by consulting shipment information or through Webhook notification. | String | Required |
package_id | Path. Package identifier, which can be obtained by consulting shipment information or through Webhook notification. | String | Required |
X-Content-Type | Header. Desired output format for the label. Possible formats are: pdf, zpl, zip, json. | String | Required |
The response may vary depending on the output format specified in the request, but will always contain a label identifier (id) and its content (label). If it was requested to be generated in a PDF, ZIP, or ZPL file, it will contain the file for download.
json
[ { "id": 43539204818, "label": "String" } ]
To learn about the errors that this request can return, access our API Reference.
You can track dispatched packages using their tracking number. To do so, send a GET to the endpoint /shipping/v1/shipments-tracking/{tracking_number} including your Access TokenPrivate key of the application created in Mercado Pago that is used in the backend. You can access it through Your integrations > Integration data. and the package tracking number (tracking_number) in the request path.
curl
curl --location 'https://api.mercadopago.com/shipping/v1/shipments-tracking/343434ereer-3344e33rre3' \ --header 'Authorization: Bearer [Access Token]'
If the data sent is correct, the response will contain the package information along with the shipment events, as presented in the response below.
json
{ "tracking_number": "343434ereer-3344e33rre3", "package": { "id": "1", "external_reference_id": "External reference", "dimensions": { "height": 10, "length": 10, "width": 10, "weight": 10, "volume": 10 }, "items": [ { "name": "Product", "description": "Product description", "value": 2007.66 } ], "price": { "amount": 2007.66, "currency": "MXN" } }, "tracking": [ { "type": "forward", "events": [ { "status": "created", "date": "2024-08-22T13:40:00.095Z" }, { "event_name": "ready", "event_date": "2025-06-09T18:40:24.749252964Z" }, { "status": "shipped", "date": "2024-08-23T10:40:00.095Z" }, { "status": "in_hub", "date": "2024-08-23T11:40:00.095Z" }, { "status": "outbounded", "date": "2024-08-23T13:40:00.095Z" }, { "status": "out_for_delivery", "date": "2024-08-23T13:45:00.095Z" }, { "status": "delivered", "date": "2024-08-23T14:45:00.095Z" } ] } ] }
| Field | Description | Type |
tracking_number | Shipment tracking code of the package. | String |
package | Package data. | Object |
package.id | Unique identifier of the shipped package. | String |
package.external_reference_id | External reference of the package. | String |
package.dimensions | Package dimensions (height, length, width, weight, and volume). | Object |
package.items | Information of the items included in the package. | Array |
package.price | Shipping price data of the package. | Object |
package.price.amount | Shipping value. | Number |
package.price.currency | Currency used. | String |
tracking | Details of the shipment history. | Array |
tracking.type | Direction in which the shipment moves: forward when the package is on its way to the customer; reverse when the package is returning to the origin address. | String |
tracking.events | List of shipment events. | Array |
tracking.events.status | Status of the shipment event. Consult the possible statuses in the section below. | String |
tracking.events.date | Date of update of the event status. | String |
tracking.events.event_name | Event name (when available). | String |
tracking.events.event_date | Event date (when available). | String |
To learn about the errors that this request can return, access our API Reference.
Possible shipment statuses
Below, you can consult the possible statuses of a shipment along with its description and association with the direction in which the shipment moves.
| Status | Description | Phase |
created | The shipment was created after payment was made. | Forward / Reverse |
ready | The shipment label can now be generated. When dispatch-date is present, you can only generate the label 24 hours before this date and time. | Forward |
label_printed | The label was generated. | Forward / Reverse |
shipped | The package was picked up and is on its way to its destination. | Forward / Reverse |
out_for_delivery | The package left the origin location towards the destination address. | Forward |
soon_deliver | The package is close to its destination. | Forward |
delivered | The package was delivered. | Forward |
not_delivered | The package was not delivered. | Forward / Reverse |
canceled | The shipment was canceled. | Forward |
in_hub | The package is in a warehouse. | Forward |
rejected_in_hub | The package was rejected at the warehouse. | Forward |
discarded | The package was discarded and will not return to the sender. | Reverse |
outbounded | The package left the warehouse. | Forward |
impassable_area | The shipment route has an impassable area. | Forward |
receiver_absent | The package receiver is absent. | Forward |
refused_delivery | The package delivery was refused. | Forward |
bad_address | The carrier could not find the destination address or it was not valid. | Forward / Reverse |
damaged | The package was damaged. | Forward / Reverse |
lost | The package was lost. | Forward / Reverse |
stolen | The package was stolen. | Forward / Reverse |
delayed | The package is delayed. | Forward |
estimated_delivery_updated | Estimated delivery date updated. | Forward |
returned | The package was returned to the sender. | Reverse |
on_route | The package is on its way. | Forward |
failed | Failure in shipment initialization. | - |
redirected | The shipment was redirected (changed phase). | Reverse |
stuck | The shipment is stuck (failure in phase change). | Forward / Reverse |
picked_up | Package picked up. | Reverse |
carrier_logistic_center_inbound | The package entered a warehouse. | Forward / Reverse |
carrier_logistic_center_outbound | The package left a warehouse. | Forward / Reverse |
sender_absent | Seller absent for pickup. | Reverse |
refused_pickup | The package pickup was refused. | Forward |
sender_not_visited | Package pickup could not be completed. | Forward |
For more information about best practices when working with shipping dimensions, consult the Shipping dimensions documentation.