# Get shipments

This endpoint allows to retrieve a list of shipments using `package_id`, `external_reference_id`, `payment_id`, or `payment_intent_id` as filters. It returns detailed information about the shipments including status, addresses, packages, and tracking information. In case of success, the request will return a response with status 200.

**GET** `/shipping/v1/shipments`

## Request parameters

### Query

- `package_id` (string, optional)
  Unique identifier of the package to search for.

- `external_reference_id` (string, optional)
  Reference that you can synchronize with your payment system to identify the shipment. This field must have a maximum of 64 characters and must only contain numbers, letters, hyphens (-) and underscores (_). Special characters such as ([ ], (), '', @) are not allowed.

- `payment_id` (string, optional)
  Payment identifier associated with the shipment.

- `payment_intent_id` (string, optional)
  Payment intent identifier associated with the shipment. Must always be informed when processed with Mercado Pago.

## Response parameters

- `data` (array, optional)
  List of shipments found based on the search criteria.

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

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

  - `data[].shipment_status` (string, optional)
  Current status of the shipment. The possible values are:
Possible enum values:

  - `created`
  Shipment was created after payment.

  - `ready`
  Label can be generated; if `dispatch_date` is present, the label can only be generated 24 hours before this date and time.

  - `label_printed`
  Label was generated.

  - `shipped`
  Package was collected and is on its way to destination.

  - `out_for_delivery`
  Package left origin to destination address.

  - `soon_deliver`
  Package is near its destination.

  - `delivered`
  Package was delivered.

  - `not_delivered`
  Package was not delivered.

  - `canceled`
  Shipment was canceled.

  - `in_hub`
  Package is in a warehouse.

  - `rejected_in_hub`
  Package was rejected in warehouse.

  - `discarded`
  Package was discarded and will not return to sender.

  - `outbounded`
  Package left warehouse.

  - `impassable_area`
  Shipment route has an impassable area.

  - `receiver_absent`
  Package recipient is absent.

  - `refused_delivery`
  Package delivery was refused.

  - `bad_address`
  Carrier could not find destination address or it was invalid.

  - `damaged`
  Package was damaged.

  - `lost`
  Package was lost.

  - `stolen`
  Package was stolen.

  - `delayed`
  Package is delayed.

  - `estimated_delivery_updated`
  Estimated delivery date updated.

  - `returned`
  Package was returned to sender.

  - `on_route`
  Package is on route.

  - `failed`
  Shipment initialization failed.

  - `redirected`
  Shipment was redirected - phase changed.

  - `stuck`
  Shipment is stuck - phase change failed.

  - `picked_up`
  Package picked up.

  - `carrier_logistic_center_inbound`
  Package entered a warehouse.

  - `carrier_logistic_center_outbound`
  Package left a warehouse.

  - `sender_absent`
  Seller absent for pickup.

  - `refused_pickup`
  Package pickup was refused.

  - `sender_not_visited`
  Package pickup could not be performed.

  - `data[].active_phase` (string, optional)
  Current phase of the shipment.
Possible enum values:

  - `forward`
  Shipment is moving forward to the customer.

  - `reverse`
  Shipment is moving back to the seller.

  - `data[].created_at` (string, optional)
  Date and time when the shipment was created.

  - `data[].shipping_to` (object, optional)
  Destination address details.

  - `data[].shipping_to.address` (string, optional)
  Buyer's address information.

  - `data[].shipping_to.city_locality` (string, optional)
  City of the destination address.

  - `data[].shipping_to.state_province` (string, optional)
  State of the destination address.

  - `data[].shipping_to.complement` (string, optional)
  Complement of the destination address.

  - `data[].shipping_to.zip_code` (string, optional)
  Postal code of the address. Maximum 50 characters.

  - `data[].shipping_to.country_code` (string, optional)
  Country code of the destination address.

  - `data[].shipping_from` (object, optional)
  Origin address information for the shipment. Optional field that defaults to the seller's registered address if not provided.

  - `data[].shipping_from.phone` (string, optional)
  Phone number of the seller.

  - `data[].shipping_from.contact` (string, optional)
  Contact name of the seller.

  - `data[].shipping_from.address` (string, optional)
  Address of the seller.

  - `data[].shipping_from.city_locality` (string, optional)
  City of the seller.

  - `data[].shipping_from.state_province` (string, optional)
  State of the seller.

  - `data[].shipping_from.complement` (string, optional)
  Complement of the seller's address.

  - `data[].shipping_from.zip_code` (string, optional)
  Zip code of the seller.

  - `data[].shipping_from.country_code` (string, optional)
  Country code of the seller.

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

  - `data[].packages` (array, optional)

  - `data[].packages[].id` (string, optional)
  Unique identifier of the package.

  - `data[].packages[].dimensions` (object, optional)
  Object containing the package weight, width, height, length, and volume.

  - `data[].packages[].dimensions.weight` (number, optional)
  Weight of the package in grams.

  - `data[].packages[].dimensions.width` (number, optional)
  Width of the package in centimeters.

  - `data[].packages[].dimensions.height` (number, optional)
  Height of the package in centimeters.

  - `data[].packages[].dimensions.length` (number, optional)
  Length of the package in centimeters.

  - `data[].packages[].dimensions.volume` (number, optional)
  Volume of the package in cubic centimeters.

  - `data[].packages[].items` (array, optional)

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

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

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

  - `data[].packages[].price` (object, optional)
  Price information of the shipment.

  - `data[].packages[].price.amount` (string, optional)
  Shipping amount.

  - `data[].packages[].price.currency` (string, optional)
  Currency used in the shipment.

  - `data[].packages[].tracking_info` (object, optional)

  - `data[].packages[].tracking_info.tracking_number` (string, optional)
  Tracking number of the package.

  - `data[].packages[].tracking_info.last_status` (string, optional)
  Last status of the package tracking.
Possible enum values:

  - `created`
  Shipment was created after payment.

  - `ready`
  Label can be generated; if `dispatch_date` is present, the label can only be generated 24 hours before this date and time.

  - `label_printed`
  Label was generated.

  - `shipped`
  Package was collected and is on its way to destination.

  - `out_for_delivery`
  Package left origin to destination address.

  - `soon_deliver`
  Package is near its destination.

  - `delivered`
  Package was delivered.

  - `not_delivered`
  Package was not delivered.

  - `canceled`
  Shipment was canceled.

  - `in_hub`
  Package is in a warehouse.

  - `rejected_in_hub`
  Package was rejected in warehouse.

  - `discarded`
  Package was discarded and will not return to sender.

  - `outbounded`
  Package left warehouse.

  - `impassable_area`
  Shipment route has an impassable area.

  - `receiver_absent`
  Package recipient is absent.

  - `refused_delivery`
  Package delivery was refused.

  - `bad_address`
  Carrier could not find destination address or it was invalid.

  - `damaged`
  Package was damaged.

  - `lost`
  Package was lost.

  - `stolen`
  Package was stolen.

  - `delayed`
  Package is delayed.

  - `estimated_delivery_updated`
  Estimated delivery date updated.

  - `returned`
  Package was returned to sender.

  - `on_route`
  Package is on route.

  - `failed`
  Shipment initialization failed.

  - `redirected`
  Shipment was redirected - phase changed.

  - `stuck`
  Shipment is stuck - phase change failed.

  - `picked_up`
  Package picked up.

  - `carrier_logistic_center_inbound`
  Package entered a warehouse.

  - `carrier_logistic_center_outbound`
  Package left a warehouse.

  - `sender_absent`
  Seller absent for pickup.

  - `refused_pickup`
  Package pickup was refused.

  - `sender_not_visited`
  Package pickup could not be performed.

  - `data[].packages[].tracking_info.updated_at` (string, optional)
  Date and time when the package tracking was last updated.

  - `data[].dispatch_date` (object, optional)

  - `data[].dispatch_date.from` (string, optional)
  Date and time when the package dispatch is scheduled.

## 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. |
| 417 | expectation_failed | Could not meet the expectation specified in the `Expect` header. Validate the information sent and try the request again. |
| 500 | internal_server_error | An unexpected error occurred on the server. Try the request again. |

## Request example

### cURL

```bash
curl -X GET \
  'https://api.mercadopago.com/shipping/v1/shipments?package_id=<PACKAGE_ID>&external_reference_id=<EXTERNAL_REFERENCE_ID>&payment_id=<PAYMENT_ID>&payment_intent_id=<PAYMENT_INTENT_ID>' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'
```

## Response example

```json
{
  "data": [
  {
  "external_reference_id": "REF-123456",
  "shipment_id": "e522fa4a-c3f8-4f34-a353-16f45a012345",
  "shipment_status": "ready",
  "active_phase": "forward",
  "created_at": "2025-07-03T18:46:03.645897682",
  "shipping_to": {
  "address": "Dirección del comprador",
  "city_locality": "México",
  "state_province": "CDMX",
  "complement": "Detalle",
  "zip_code": "06760",
  "country_code": "MX"
  },
  "shipping_from": {
  "phone": "987-654-321",
  "contact": "Miguel Hernández",
  "address": "Dirección del vendedor",
  "city_locality": "México",
  "state_province": "CDMX",
  "complement": "Detalle",
  "zip_code": "03940",
  "country_code": "MX"
  },
  "tracking_url": "https://www.mercadopago.com.mx/shipping-tracking?id=000038774013",
  "packages": [
  {
  "id": null,
  "dimensions": null,
  "items": null,
  "price": null,
  "tracking_info": null
  }
  ],
  "dispatch_date": {
  "from": "2025-07-05T06:00:00Z"
  }
  }
  ]
}
```