This endpoint allows to create new shipments for the user based on the selected rate option. It requires an idempotency key to prevent duplicate shipment creation. The endpoint processes the shipment creation and returns the created shipment ID and the package IDs. In case of success, the request will return a response with status 200.
POST
REQUIRED
REQUIRED
400Bad request. The parameters sent are not valid.
bad_request
Invalid data was sent in the request body. Try sending the request again, validating all fields.
401Unauthorized. Invalid or missing credentials.
unauthorized
The value sent as Access Token is incorrect. Please check and try again with the correct value.
403Forbidden. You don't have permissions to access this resource.
forbidden
No permission to access the resource.
404Not found. The requested resource does not exist.
not_found
The requested resource was not found or the value sent for its identification does not exist. Validate the information sent in the parameters and try the request again.
417Expectation failed.
expectation_failed
Could not meet the expectation specified in the "Expect" header. Validate the information sent and try the request again.
curl -X POST \
'https://api.mercadopago.com/shipping/v1/shipments'\
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer APP_USR-4*********994754-12*********c73b4e1ac*********cef36b27c*********840' \
-H 'X-Idempotency-Key: 286b0d05-14c0-48cb-81db-96285d35a475' \
-d '{
"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": "06760",
"neighborhood": "Centro",
"references": "cerca del mercado"
}
},
"external_reference_id": "REF-123456",
"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
}
}
]
}'{
"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": {},
"origin": {
"zip_code": "06760",
"city": "Tlaquepaque",
"state": "Jalisco",
"country": "Mexico",
"neighborhood": "La Calerilla",
"address_line": "Calz de Guadalupe 432",
"references": "Casa blanca y azul."
},
"external_reference_id": "REF-123456",
"items": [
{
"title": "Producto",
"description": "Descripción del producto",
"unit_price": 100
}
]
}