AI resources

Create shipments

The Mercado Pago Shipping API allows you to manage shipments from sales generated with Checkout API. 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.

Shipment creation is available only to integrators authorized by Mercado Pago. If this feature is not yet enabled, check its availability in your Mercado Pago account.

Learn about the shipment management options and how to integrate them below.

Get shipping quotes

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 request to the endpoint /shipping/v1/shipments-ratesPOST 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.

It is only possible to get a quote for one package at a time. For shipments with multiple items, you must calculate the total dimensions of the package containing them. Consult the Shipping dimensions documentation to learn about the permitted dimensions and best practices.

curl
curl --location 'https://api.mercadopago.com/shipping/v1/shipments-rates' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{YOUR_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 ReferenceAPI.

Create shipments

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 request to the endpoint /shipping/v1/shipmentsPOST 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 {{YOUR_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--header 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \
--data '{
    "rates": {
        "shipment_rate_id": "be9fae0d-1079-471e-887d-55861965d10e",
        "option_id": "d7f61877-4a39-4f94-b6fb-d80a6351c714"
    },
    "payment_intent_id": "131245840212",
    "receiver": {
        "person": {
            "email": "test@testuser.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. It must always be provided. If the payment is processed with Mercado Pago, provide the payment ID, approved or rejected.	String	Required
`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",
            "tracking_url": "https://www.mercadopago.com.mx/shipping-tracking?id=000038774013",
            "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": "131245840212",
    "receiver": {
        "person": {
            "email": "test@testuser.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.tracking_url`	Link for the buyer to check the shipment status in real time.	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. Must always be informed when processed with Mercado Pago.	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 ReferenceAPI.

Get shipment information

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 request 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/shipmentsGET 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 {{YOUR_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. Must always be informed when processed with Mercado Pago.	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"
            },
            "tracking_url": "https://www.mercadopago.com.mx/shipping-tracking?id=000038774013",
            "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
`tracking_url`	Link for the buyer to check the shipment status in real time.	String
`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 ReferenceAPI.

Cancel shipments

To cancel an existing shipment, send a request to the endpoint /shipping/v1/shipments/{id}DELETE 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. Keep in mind that you can only cancel shipments that have not been dispatched yet or that have been returned to the seller after an unsuccessful delivery attempt. After 15 days, all generated shipments that have not been dispatched will be automatically canceled and the cost will be returned to the seller.

curl
curl --location --request DELETE 'https://api.mercadopago.com/shipping/v1/shipments/e522fa4a-c3f8-4f34-a353-16f45a012345' \
--header 'Authorization: Bearer {{YOUR_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 ReferenceAPI.

Generate labels

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 JSON format. The zip value generates a label in ZPL format.

If when consulting a shipment, the 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 request 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/{packageId}/labelGET.

curl
curl --location 'https://api.mercadopago.com/shipping/v1/shipments/{shipment_id}/packages/{package_id}/label' \
--header 'X-Content-Type: json' \
--header 'Authorization: Bearer {{YOUR_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`, `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 ReferenceAPI.

Track shipments

You can track dispatched packages using their tracking number. To do so, send a request to the endpoint /shipping/v1/shipments-tracking/{tracking_number}GET 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/{tracking_number}' \
--header 'Authorization: Bearer {{YOUR_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",
    "tracking_url": "https://www.mercadopago.com.mx/shipping-tracking?id=000038774013",
    "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
`tracking_url`	Link for the buyer to check the shipment status in real time.	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 ReferenceAPI.

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.

PreviousShipmentsLearn how to set up shipments and offer deliveries through Mercado Libre’s logistics.

NextBest practices for shipmentsIf you configure sales with shipping, see the best practices for package sizing.