---
title: "Estimate the cost and timing of a shipment."
method: POST
path: "/v3/parcels/estimate"
tags: ["shipment"]
---

# Estimate the cost and timing of a shipment.

`POST /v3/parcels/estimate`

## Request

- Base URL: `https://logistics.api.cabify-sandbox.com`
- URL: `https://logistics.api.cabify-sandbox.com/v3/parcels/estimate`
- Auth: HTTP bearer

Calculates the estimated price, pickup time, and delivery time for the given parcels using the specified shipping type.

The response also includes the `asset_kind` (vehicle type) that would be assigned to each delivery. **This is only meaningful for `express` (on-demand) deliveries**: it is chosen deterministically as the smallest available vehicle — in `bicycle → moped → car` priority order — that can fit the whole delivery by weight, volume and largest-parcel dimensions and still complete the route in time. For `same_day`, `next_day` and other cross-dock modalities the returned value does not reflect the vehicle that will actually carry the parcel and should be ignored. See the `AssetKind` schema for the exact per-vehicle limits used to make this choice.

## Request body

- EstimateV3Request
  - `parcels` EstimateLocation[], required: List of parcels to estimate shipping for.
    - `external_id` string: Your own identifier for this parcel. Used to correlate estimate results with your own records.
    - `pickup_location` union, required: Pickup location. Provide either geographic coordinates or a text address.
      - Point: A geographic coordinate expressed as latitude and longitude.
        - `lat` number, float, required: Latitude in decimal degrees.
        - `lon` number, float, required: Longitude in decimal degrees.
      - Address
        - `address` string, required: Address of the location
    - `dropoff_location` union, required: Drop-off location. Provide either geographic coordinates or a text address.
      - Point: A geographic coordinate expressed as latitude and longitude.
        - `lat` number, float, required: Latitude in decimal degrees.
        - `lon` number, float, required: Longitude in decimal degrees.
      - Address
        - `address` string, required: Address of the location
    - `dimensions` ParcelDimensions: Physical dimensions of the parcel.
      - `height` integer
      - `length` integer
      - `width` integer
      - `unit` 'cm': Unit of measure for the dimensions. Defaults to `cm` if omitted or set to an invalid value.
    - `weight` ParcelWeight: Weight of the parcel.
      - `value` integer
      - `unit` 'g': Unit of weight. Defaults to `g` (grams) if omitted or set to an invalid value.
  - `shipping_type_id` string, required: Identifier of the shipping type to estimate, as returned for the pickup location by [GET /v1/shipping_types/available](https://developers.cabify.com/reference/shippingtypesavailable). Opaque and environment-dependent: send it back exactly as it was returned.
  - `pickup_time` string, date-time: Desired pickup time, formatted according to RFC 3339, section 5.6.
  - `with_return` boolean: Request a return leg: after the delivery, the rider goes back to the pickup point in the same journey. Returns must be enabled for the shipping type; asking for one on a shipping type without it fails with `shipping type not enabled for return`.

## Response `200`

Estimation calculated successfully.

- EstimateV3Response
  - `deliveries` DeliveryEstimate[], required
    - `parcels` EstimateLocation[]
      - `external_id` string: Your own identifier for this parcel. Used to correlate estimate results with your own records.
      - `pickup_location` union, required: Pickup location. Provide either geographic coordinates or a text address.
        - Point: A geographic coordinate expressed as latitude and longitude.
          - `lat` number, float, required: Latitude in decimal degrees.
          - `lon` number, float, required: Longitude in decimal degrees.
        - Address
          - `address` string, required: Address of the location
      - `dropoff_location` union, required: Drop-off location. Provide either geographic coordinates or a text address.
        - Point: A geographic coordinate expressed as latitude and longitude.
          - `lat` number, float, required: Latitude in decimal degrees.
          - `lon` number, float, required: Longitude in decimal degrees.
        - Address
          - `address` string, required: Address of the location
      - `dimensions` ParcelDimensions: Physical dimensions of the parcel.
        - `height` integer
        - `length` integer
        - `width` integer
        - `unit` 'cm': Unit of measure for the dimensions. Defaults to `cm` if omitted or set to an invalid value.
      - `weight` ParcelWeight: Weight of the parcel.
        - `value` integer
        - `unit` 'g': Unit of weight. Defaults to `g` (grams) if omitted or set to an invalid value.
    - `estimation` DeliveryEstimation, required: Estimated cost and timing details for a single parcel delivery.
      - `price` Money, required: A monetary amount represented in the smallest currency unit (e.g. cents).
        - `amount` integer, required: Amount in the smallest currency unit, following the ISO 4217 standard (e.g. €6.30 → `630`).
        - `currency` string, required: ISO 4217 currency code.
      - `asset_kind` 'bicycle' | 'moped' | 'car' | 'van': The vehicle type selected for this delivery. **Only meaningful for `express` (on-demand) deliveries**, where it is the smallest available vehicle — in `bicycle → moped → car` priority order — that can fit the whole delivery by weight, volume and dimensions and can complete the route within its allowed time. For `same_day`, `next_day` and other cross-dock modalities the value does not reflect the vehicle that will actually carry the parcel and should be ignored. See the `AssetKind` schema for the exact limits. Omitted if the upstream service does not return a vehicle type for the estimation.
      - `eta_to_pickup` string, date-time: Estimated time when the driver will arrive at the pickup location.
      - `eta_to_delivery` string, date-time: Estimated time when the parcel will be delivered to the recipient.

## Other responses

- `400`: Bad request. One or more fields failed validation.
- `401`: Unauthorized. Missing or invalid authentication token.
- `404`: The estimation could not be calculated. Check that the provided locations are within an operating area.
- `409`: The server state does not currently allow processing this estimation request.
- `429`: Too many requests. This API is rate limited per account and per endpoint. A 429 is an expected condition rather than a failed request: back off and retry it. The limits are not the same for every endpoint and can change, so handle the status instead of hard-coding a rate. See the Limits and reliability guide.
- `503`: The service is temporarily unavailable. Please try again later.

---

[API](https://skmtc.dev/cabify/apis/cabify-logistics-api.md) - [All operations](https://skmtc.dev/cabify/apis/cabify-logistics-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cabify/apis/cabify-logistics-api/revisions/dff49457aac9?raw)