# Get shipping rates

This endpoint allows to get shipping rates of a package for a determined address. It calculates the available shipping options with their respective costs and delivery times based on package dimensions and origin/destination addresses. In case of success, the request will return a response with status 200.

**POST** `/shipping/v1/shipments-rates`

## Request parameters

- `packages` (array, optional)
  List of packages to be shipped. Currently supports only one package per request.

  - `packages[].declared_value` (number, optional)
  Declared value of the package for insurance purposes. This value represents the monetary value of the contents.

  - `packages[].quantity` (integer, optional)
  Number of packages to be shipped.

  - `packages[].dimensions` (object, optional)
  Object containing information about the item size including weight, width, height, and length.

  - `packages[].dimensions.weight` (number, optional)
  Weight of the item in grams. Must be a positive number and the maximum is 30000 g (actual or volumetric).

  - `packages[].dimensions.width` (number, optional)
  Width of the item in centimeters. Must be a positive number and the maximum is 150 cm. The total dimension limit must not exceed 330 cm.

  - `packages[].dimensions.height` (number, optional)
  Height of the item in centimeters. Must be a positive number and the maximum is 150 cm. The total dimension limit must not exceed 330 cm.

  - `packages[].dimensions.length` (number, optional)
  Length of the item in centimeters. Must be a positive number and the maximum is 150 cm. The total dimension limit must not exceed 330 cm.

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

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

- `shipping_to` (object, optional)
  Destination address information for the shipment. This is required to calculate shipping rates.

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

## Response parameters

- `shipment_rate_id` (string, optional)
  Unique identifier for the rate calculation session, automatically generated by the system. This ID should be used as "shipment_rate_id" when creating a shipment.

- `rates` (array, optional)
  List of quotes for the package based on the information provided.

  - `rates[].options` (array, optional)
  List of available rate options.

  - `rates[].options[].id` (string, optional)
  Identifier of the package.

  - `rates[].options[].pricing` (object, optional)

  - `rates[].options[].pricing.base_price` (string, optional)
  Gross value of the shipment before discounts.

  - `rates[].options[].pricing.price` (string, optional)
  Net value of the shipment after discounts.

  - `rates[].options[].pricing.discounts` (array, optional)
  List of applied discounts.

  - `rates[].options[].method` (string, optional)
  Shipping method type.
Possible enum values:

  - `standard`
  Standard offer.

  - `economic`
  Cheaper offer.

  - `rates[].options[].pay_before` (string, optional)
  Expected date to guarantee the generated shipping promise.

  - `rates[].options[].delivery_promise` (object, optional)
  Delivery promise information.

  - `rates[].options[].delivery_promise.shipping_from` (string, optional)
  Estimated delivery start date.

  - `rates[].options[].delivery_promise.shipping_to` (string, optional)
  Estimated delivery end date.

  - `rates[].options[].delivery_days` (object, optional)
  Estimated delivery days information.

  - `rates[].options[].delivery_days.from` (integer, optional)
  Minimum number of delivery days.

  - `rates[].options[].delivery_days.to` (integer, optional)
  Maximum number of delivery days.

  - `rates[].packages` (array, optional)
  List of packages with quantity and dimensions.

  - `rates[].packages[].quantity` (integer, optional)
  Number of packages to be shipped.

  - `rates[].packages[].dimensions` (object, optional)
  Object containing information about the item size including weight, width, height, and length.

  - `rates[].packages[].dimensions.weight` (number, optional)
  Weight of the item in grams. Must be a positive number and the maximum is 30000 g (actual or volumetric).

  - `rates[].packages[].dimensions.width` (number, optional)
  Width of the item in centimeters. Must be a positive number and the maximum is 150 cm. The total dimension limit must not exceed 330 cm.

  - `rates[].packages[].dimensions.height` (number, optional)
  Height of the item in centimeters. Must be a positive number and the maximum is 150 cm. The total dimension limit must not exceed 330 cm.

  - `rates[].packages[].dimensions.length` (number, optional)
  Length of the item in centimeters. Must be a positive number and the maximum is 150 cm. The total dimension limit must not exceed 330 cm.

- `shipping_to` (object, optional)
  Destination address information.

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

  - `shipping_to.country_id` (string, optional)
  Country code of the destination address.

  - `shipping_to.city_id` (string, optional)
  City identifier of the destination address.

  - `shipping_to.state_id` (string, optional)
  State code of the destination address.

## 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. |
| 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. |
| 500 | internal_server_error | An unexpected error occurred on the server. Try the request again. |

## Request example

### cURL

```bash
curl -X POST \
  'https://api.mercadopago.com/shipping/v1/shipments-rates' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -d '{
  "packages": [
  {
  "declared_value": 1500,
  "quantity": 1,
  "dimensions": {
  "weight": 500,
  "width": 30,
  "height": 30,
  "length": 30
  }
  }
  ],
  "shipping_from": {
  "zip_code": "06760"
  },
  "shipping_to": {
  "zip_code": "06760"
  }
  }'
```

## Response example

```json
{
  "shipment_rate_id": "be9fae0d-1079-471e-887d-55861965d10e",
  "rates": [
  {
  "options": [
  {
  "id": null,
  "pricing": null,
  "method": null,
  "pay_before": null,
  "delivery_promise": null,
  "delivery_days": null
  }
  ],
  "packages": [
  {
  "quantity": null,
  "dimensions": null
  }
  ]
  }
  ],
  "shipping_to": {
  "zip_code": "06760",
  "country_id": "MX",
  "city_id": "TUxNQ0NVQTczMTI",
  "state_id": "MX-DIF"
  }
}
```