# Create shipment

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** `/shipping/v1/shipments`

## Request parameters

### Header

- `X-Idempotency-Key` (string, required)
  This feature allows you to safely retry requests without the risk of accidentally performing the same action more than once. This is useful for avoiding errors, such as creating two identical shipments. To ensure that each request is unique, it's important to use an exclusive value in the header of your request. We suggest using a UUID V4 or random strings. The header accepts values between 1 and 64 characters.

- `rates` (object, optional)
  Rate information from the quote endpoint.

  - `rates.shipment_rate_id` (string, optional)
  Shipment rate identifier obtained from the rates endpoint response.

  - `rates.option_id` (string, optional)
  Identifier of the selected rate option, obtained from the rates endpoint response.

- `payment_intent_id` (string, optional)
  Identifier of the payment associated with the shipment. Must always be informed when processed with Mercado Pago.

- `receiver` (object, optional)
  Recipient information (who will receive the package).

  - `receiver.person` (object, optional)
  Personal information of the recipient.

  - `receiver.person.email` (string, optional)
  Email of the recipient.

  - `receiver.person.full_name` (string, optional)
  Full name of the recipient.

  - `receiver.person.identification` (string, optional)
  Identity document of the recipient.

  - `receiver.person.phone` (string, optional)
  Phone number of the recipient.

  - `receiver.address` (object, optional)
  Address information of the recipient.

  - `receiver.address.floor` (string, optional)
  Floor of the apartment.

  - `receiver.address.apartment` (string, optional)
  Apartment number (internal).

  - `receiver.address.street_number` (string, optional)
  Street number (external).

  - `receiver.address.street_name` (string, optional)
  Street name.

  - `receiver.address.zip_code` (string, optional)
  Postal code of the destination address. It allows a maximum of 50 characters.

  - `receiver.address.neighborhood` (string, optional)
  Neighborhood or district of the address.

  - `receiver.address.references` (string, optional)
  Address details or complement.

- `external_reference_id` (string, optional)
  External reference that you can synchronize with your payment system to identify the shipment.

- `items` (array, optional)
  Information about the items to be shipped.

  - `items[].title` (string, optional)
  Title of the item.

  - `items[].quantity` (integer, optional)
  Quantity of items.

  - `items[].unit_price` (number, optional)
  Unit price of the item.

  - `items[].description` (string, optional)
  Description of the item.

  - `items[].fiscal_data` (object, optional)
  Fiscal data of the product.

  - `items[].fiscal_data.sat` (string, optional)
  SAT category of the item.

  - `items[].fiscal_data.sat_measurement_id` (string, optional)
  Unique identifier of the product measurement unit according to SAT units.

  - `items[].fiscal_data.measurement_unit` (string, optional)
  Measurement unit of the product.

  - `items[].fiscal_data.package_id` (string, optional)
  Package identifier.

  - `items[].fiscal_data.dangerous_material_id` (string, optional)
  Identifier for dangerous products.

  - `items[].dimensions` (object, optional)
  Item dimensions.

  - `items[].dimensions.unit` (string, optional)
  Measurement unit.

  - `items[].dimensions.height` (number, optional)
  Height of the item in centimeters.

  - `items[].dimensions.width` (number, optional)
  Width of the item in centimeters.

  - `items[].dimensions.length` (number, optional)
  Length of the item in centimeters.

  - `items[].dimensions.weight` (number, optional)
  Weight of the item in grams.

## Response parameters

- `shipments` (array, optional)
  Information about created shipments.

  - `shipments[].id` (string, optional)
  Unique identifier of the created shipment.

  - `shipments[].tracking_url` (string, optional)
  Link for the buyer to check the shipment status in real time.

  - `shipments[].packages` (array, optional)
  Packages included in the shipment.

  - `shipments[].packages[].id` (string, optional)
  Package identifier. Use this value to generate labels and query shipments.

- `idempotency_key` (string, optional)
  Idempotency key to avoid duplicates.

- `rates` (object, optional)
  Rate information used for the shipment.

  - `rates.shipment_rate_id` (string, optional)
  Shipment rate identifier.

  - `rates.option_id` (string, optional)
  Selected rate option identifier.

  - `rates.delivery_promise` (object, optional)
  Confirmed delivery promise.

  - `rates.delivery_promise.from` (string, optional)
  Start date of the delivery promise.

  - `rates.delivery_promise.to` (string, optional)
  End date of the delivery promise.

- `payment_intent_id` (string, optional)
  Identifier of the payment associated with the shipment. Must always be informed when processed with Mercado Pago.

- `receiver` (object, optional)
  Recipient information of the shipment.

- `origin` (object, optional)
  Origin address information.

  - `origin.zip_code` (string, optional)
  Postal code of the destination address. It allows a maximum of 50 characters.

  - `origin.city` (string, optional)
  Origin city.

  - `origin.state` (string, optional)
  Origin state.

  - `origin.country` (string, optional)
  Origin country.

  - `origin.neighborhood` (string, optional)
  Origin neighborhood.

  - `origin.address_line` (string, optional)
  Origin address line.

  - `origin.references` (string, optional)
  Address references.

- `external_reference_id` (string, optional)
  External reference that you can synchronize with your payment system to identify the shipment.

- `items` (array, optional)
  Items included in the shipment.

  - `items[].title` (string, optional)
  Title of the item sent in the package.

  - `items[].description` (string, optional)
  Description of the item sent in the package.

  - `items[].unit_price` (number, optional)
  Value of the item sent in the package.

## Errors

| Status | Error | Description |
| ------- | ------- | ----------- |
| 400 | bad_request | Invalid data was sent in the request body. Try sending the request again, validating all fields. |
| 401 | unauthorized | The value sent as Access Token is incorrect. Please check and try again with the correct value. |
| 403 | forbidden | No permission to access the resource. |
| 404 | 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. |
| 417 | expectation_failed | Could not meet the expectation specified in the "Expect" header. Validate the information sent and try the request again. |

## Request example

### cURL

```bash
curl -X POST \
  'https://api.mercadopago.com/shipping/v1/shipments' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -d '{
  "rates": {
  "shipment_rate_id": "be9fae0d-1079-471e-887d-55861965d10e",
  "option_id": "d7f61877-4a39-4f94-b6fb-d80a6351c714"
  },
  "payment_intent_id": "131245840212",
  "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": "24.50",
  "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
  }
  }
  ]
  }'
```

## Response example

```json
{
  "shipments": [
  {
  "id": "7311edef-a46e-4a42-a8e1-6a142fa7ee48",
  "tracking_url": "https://www.mercadopago.com.mx/shipping-tracking?id=000038774013",
  "packages": [
  {
  "id": null
  }
  ]
  }
  ],
  "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": {},
  "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": "24.50"
  }
  ]
}
```