AI resources
Create payment with shipment
Through the preference, it is possible to create a payment with an associated shipment. This way, you can offer customers home delivery of purchased products leveraging Mercado Libre's logistics without extra effort from the business.
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.
To create a payment with an associated shipment, create a preference by sending a request to the endpoint /checkout/preferencesPOST, including your Access TokenPrivate key of the application created in Mercado Pago, used in the backend. You can access it through Your integrations > Integration data > Testing > Test credentials. The test Access Token starts with the prefix `APP_USR`. and the items and shipments nodes as indicated in the table below.
curlcurl --location 'https://api.mercadopago.com/checkout/preferences' \ --header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \ --header 'Content-Type: application/json' \ --data '{ "external_reference": "External reference 123", "items": [ { "title": "Product 1", "description": "Product 1 description", "picture_url": "image.jpg", "quantity": 1, "currency_id": "MXN", "unit_price": 100, "fiscal_data": { "sat": "23241500", "sat_measurement_id": "H87", "measurement_unit": "Piece", "package_id": "4G", "dangerous_material_id": "M2340" }, "dimensions": { "unit": "G", "height": 3, "width": 11, "length": 18, "weight": 100 } }, { "title": "Product 2", "description": "Product 2 description", "picture_url": "image.jpg", "quantity": 1, "currency_id": "MXN", "unit_price": 110, "fiscal_data": { "sat": "23241500", "sat_measurement_id": "H87", "measurement_unit": "Piece", "package_id": "4G", "dangerous_material_id": "M2340" }, "dimensions": { "unit": "G", "height": 3, "width": 10, "length": 18, "weight": 90 } }, ], "shipments": { "dimensions": "21x15x6.5,360", "free_methods_types": [ { "id": "standard" } ], "local_pickup": false, "mode": "me2", "stock_origin_id": "id", "receiver_address": { "zip_code": "06250", "street_name": "Ex-Hipódromo de Peralvillo", "street_number": null, "floor": "", "apartment": "", "neighborhood": Colonia, "city_name": Cuauhtémoc, "state_name": Ciudad de México, "country_name": México } } }'
| Field | Description | Type | Required |
external_reference | Reference that you can synchronize with your payment system to identify the shipment. This field must have a maximum of 64 characters and should only contain numbers, letters, hyphens (-) and underscores (_). Special characters like ([ ], (), '', @) are not allowed. | String | Optional |
items | Information about the items sold to be shipped. | Array | Required |
items.title | Item title that will be displayed during the payment process, in the checkout, activities and emails. | String | Required |
items.description | Item description. | String | Optional |
items.picture_url | Item image URL. | String | Optional |
items.quantity | Quantity of items. This property is used to calculate the total purchase cost. | Number | Required |
items.currency_id | Unique identifier of the currency involved in the transaction. The only possible value is Mexican pesos (MXN). | String | Optional |
items.unit_price | Unit price of the item. This property is used together with the quantity property to determine the purchase cost. | Number | Required |
items.fiscal_data | Object containing the product's fiscal data. | Object | Required to create shipments. If you send it, you must also include the shipments attribute. |
items.fiscal_data.sat | SAT category of the item. Check the possible values by accessing the following link. | String | Required |
items.fiscal_data.sat_measurement_id | Unique identifier of the product's unit of measurement. | String | Required |
items.fiscal_data.measurement_unit | Product unit of measurement according to SAT Units | String | Required |
items.fiscal_data.package_id | Identifier of the product's packaging type. | String | Required |
items.fiscal_data.dangerous_material_id | Identifier for dangerous products. | String | Optional |
items.dimensions | Object containing information about the item's size. | Object | Optional |
items.dimensions.unit | Unit of measurement for the item. Must be cm (centimeters). | String | Required |
items.dimensions.height | Item height in centimeters. | Number | Required |
items.dimensions.width | Item width in centimeters. | Number | Required |
items.dimensions.length | Item length in centimeters. | Number | Required |
items.dimensions.weight | Item weight in grams. | Number | Required |
shipments | Shipment information. | Object | Required |
shipments.dimensions | Package size, which will be used to define the shipping cost. The format must be cm x cm x cm, g. If it contains more than one item, its size should be calculated considering the sum of the dimensions of all items, always ensuring that the maximum allowed dimensions per package are not exceeded.Check the best practices for sizing by accessing the documentation. | String | Required |
shipments.free_methods_type | Shipping method identifier. Should only be sent when offering free shipping, with the value standard. This free shipping is only possible when the sale value is greater than the shipping cost. If the shipping cost is borne by the buyer, the field should not be sent. | String | Optional |
shipments.local_pickup | Indicates whether you want to offer package pickup at a branch. For this solution, enter false. | Boolean | Required |
shipments.mode | Shipping mode. For this solution, enter me2. | String | Required |
shipments.stock_origin_id | Identifier of the package's origin address, which must be requested from the Mercado Pago team. If there is more than one pickup address, the stock_origin_id of the origin address must be informed. | String | Optional |
shipments.receiver_address | Details of the destination address. Sending it is recommended to offer the best shopping experience and, if necessary, the data can be reused. | Object | Optional |
shipments.receiver_address.zip_code | Postal code of the destination address. | String | Optional |
shipments.receiver_address.street_name | Destination street name. | String | Optional |
shipments.receiver_address.street_number | Destination address number. | String | Optional |
shipments.receiver_address.floor | Destination apartment floor. | String | Optional |
shipments.receiver_address.apartment | Destination apartment number. | String | Optional |
shipments.receiver_address.neighborhood | Destination address neighborhood. | String | Optional |
shipments.receiver_address.city_name | Destination address city. | String | Optional |
shipments.receiver_address.state_name | Destination address state. | String | Optional |
shipments.receiver_address.country_name | Destination address country. | String | Optional |
If the request is sent successfully, the payment with shipment will have been created and the response will look like the example below.
json{ "additional_info": "", "auto_return": "", "back_urls": { "failure": "", "pending": "", "success": "" }, "binary_mode": false, "client_id": "6607075136335166", "collector_id": 2681149695, "coupon_code": null, "coupon_labels": null, "date_created": "2025-10-15T15:30:39.775-04:00", "date_of_expiration": null, "expiration_date_from": null, "expiration_date_to": null, "expires": false, "external_reference": "External reference 123", "id": "2681149695-c464c4e0-1834-4e81-9956-25a3cc1e8db8", "init_point": "https://www.mercadopago.com.mx/checkout/v1/redirect?pref_id=2681149695-c464c4e0-1834-4e81-9956-25a3cc1e8db8", "internal_metadata": null, "items": [ { "id": "", "category_id": "", "currency_id": "MXN", "description": "Product 1 description", "title": "Product 1", "quantity": 1, "unit_price": 100, "fiscal_data": { "sat": "23241500", "sat_measurement_id": "H87", "measurement_unit": "Piece", "package_id": "4G", "dangerous_material_id": "M2340" }, "dimensions": { "unit": "G", "height": 3, "width": 11, "length": 18, "weight": 100 } }, { "id": "", "category_id": "", "currency_id": "MXN", "description": "Product 2 description", "title": "Product 2", "quantity": 1, "unit_price": 110, "fiscal_data": { "sat": "23241500", "sat_measurement_id": "H87", "measurement_unit": "Piece", "package_id": "4G", "dangerous_material_id": "M2340" }, "dimensions": { "unit": "G", "height": 3, "width": 10, "length": 18, "weight": 90 } }, ], "marketplace": "NONE", "marketplace_fee": 0, "metadata": {}, "notification_url": null, "operation_type": "regular_payment", "payer": { "phone": { "area_code": "", "number": "" }, "address": { "zip_code": "", "street_name": "", "street_number": null }, "email": "", "identification": { "number": "", "type": "" }, "name": "", "surname": "", "date_created": null, "last_purchase": null }, "payment_methods": { "default_card_id": null, "default_payment_method_id": null, "excluded_payment_methods": [ { "id": "" } ], "excluded_payment_types": [ { "id": "" } ], "installments": null, "default_installments": null }, "processing_modes": null, "product_id": null, "preference_expired": false, "redirect_urls": { "failure": "", "pending": "", "success": "" }, "sandbox_init_point": "https://sandbox.mercadopago.com.mx/checkout/v1/redirect?pref_id=2681149695-c464c4e0-1834-4e81-9956-25a3cc1e8db8", "site_id": "MLM", "shipments": { "mode": "me2", "local_pickup": false, "dimensions": "21x15x6.5,360", "free_methods": [], "free_methods_types": [ { "id": "standard" } ], "default_shipping_method": null, "receiver_address": { "zip_code": "06250", "street_name": "Ex-Hipódromo de Peralvillo", "street_number": null, "floor": "", "apartment": "", "city_name": "Cuauhtémoc", "state_name": "Ciudad", "country_name": "México", "neighborhood": "Colonia" }, "stock_origin_id": "id" }, "total_amount": null, "last_updated": null, "financing_group": "" }
The
sandbox_init_point field appears in the response, but it is not functional. For integration testing, use init_point.If necessary, you can cancel the created shipment. To do so, fully cancel the payment associated with it through the endpoint /v1/payments/{id}PUT.
If you choose to create payments with shipments, you can use our shipment management APIs, which will allow you to optimize your pre and post-sale experience.
To rate a shipment, send a request to the endpoint /shipping/v1/shipments-ratesPOST including your Access TokenPrivate key of the application created in Mercado Pago, used in the backend. You can access it through Your integrations > Integration data > Testing > Test credentials. The test Access Token starts with the prefix `APP_USR`. and the parameters described in the table below. Keep in mind that only one package can be quoted at a time.
curlcurl --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 shipping rate. | Array | Required |
packages.declared_value | Value of the package to be shipped. Does not include the estimated shipping cost. | Number | Required |
packages.quantity | Number of packages. The only allowed value is 1. | Number | Required |
packages.dimensions | Object containing the package dimensions. The allowed maximums are: - Each side must have a maximum of 150 cm. - The total dimension limit must not exceed 330 cm. - The maximum weight is 30 kg (actual 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 offer. 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 rate, 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 | Rate identifier. Use this value as shipment_rate_id when creating the shipment. | String |
rates | List of rates for the package based on the provided address. | Array |
options | List of available rate options. | Array |
id | Shipping option identifier. Use this value as option_id when creating the shipment from the rate. | String |
base_price | Gross shipping value. | Number |
price | Net shipping value. | Number |
method | Delivery method. The only possible response to this field is standard, for free shipping. | String |
pay_before | Expected payment date to ensure 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 | Number of rated packages. | Number |
packages.dimensions | Rated package dimensions. | Object |
packages.dimensions.height | Package height. | Number |
packages.dimensions.width | Package width. | Number |
packages.dimensions.length | Package length. | Number |
packages.dimensions.weight | Package weight. | Number |
shipping_to.zip_code | Postal code of the destination address. | String |
shipping_to.city_id | City identifier of the destination address. | String |
shipping_to.state_id | State abbreviation of the destination address. | String |
shipping_to.country_id | Country abbreviation of the destination address. | String |
To learn about the errors this request may return, go to our API ReferenceAPI.
Configure Webhook notifications to receive alerts about shipments and their status changes.
To do so, you need to indicate the URLs to which they will be sent by following the step-by-step below:
- Go to Your integrations and select the application integrated with Checkout Pro for which you want to activate notifications.
- In the left menu, select Webhooks > Configure notifications.
- Select the Production mode tab and provide an
HTTPS URLto receive notifications with your production integration.
- Select the Shipments (Mercado Pago) event to receive notifications, which will be sent in
JSONformat via anHTTPS POSTto the URL specified above.
- Finally, click Save configuration. This will generate a secret key exclusive to the application, which will allow you to validate the authenticity of the received notifications, ensuring they were sent by Mercado Pago. Keep in mind that this generated key has no expiration date and its periodic renewal is not mandatory, although it is recommended. To do so, just click the Reset button.
If you want more information on how to simulate sending a notification, validate its origin, or what actions are necessary after receiving them, go to Configure notifications.