---
title: "Get the current status of a parcel."
method: GET
path: "/v1/parcels/{parcel_id}/status"
tags: ["status"]
---

# Get the current status of a parcel.

`GET /v1/parcels/{parcel_id}/status`

## Request

- Base URL: `https://logistics.api.cabify-sandbox.com`
- URL: `https://logistics.api.cabify-sandbox.com/v1/parcels/{parcel_id}/status`
- Auth: HTTP bearer

Returns the current state and tracking information for the specified parcel.

## Path parameters

- `parcel_id` string, uuid, required

## Response `200`

Parcel status retrieved successfully.

- ParcelStatus
  - `id` string, uuid: System-generated UUID for this parcel.
  - `external_id` string: Your own identifier for this parcel, as provided when the parcel was created.
  - `state` 'ready' | 'qualifiedforpickup' | 'pickingup' | 'intransit' | 'delivering' | 'delivered' | 'returning' | 'returned' | 'incident' | 'requestercancel' | 'internalcancel' | 'pickupfailed' | 'onroutetopickup' | 'readytopickup' | 'onroutetofinalhub' | 'receivedonfinalhub' | 'readytodispatch' | 'onroutetodelivery' | 'undelivered' | 'onroutetoreturn' | 'returnrejected' | 'scheduled' | 'deleted': The current lifecycle state of the parcel. See [parcel states](https://developers.cabify.com/reference/logistics-introduction#parcel) for a full description of each value.
  - `failure_reason` 'unknown' | 'payment_method_declined' | 'no_payment_methods' | 'requester_not_found_or_unauthorized' | 'product_does_not_exist' | 'invalid_pick_up_location' | 'delivery_already_exist': If present, indicates why the delivery was rejected. See [failure reasons](https://developers.cabify.com/reference/parcel-information#failure-reason) for a description of each value.
  - `delivery_attempt` object
    - `id_proof_of_delivery` object, nullable
      - `recipient_name` string: Name of the person who received the parcel.
      - `recipient_id_number` string: Identity document number of the person who received the parcel.
    - `photo_proof_of_delivery` object, nullable
      - `photo_urls` string[]: List of URLs of the photos taken by the driver as proof of delivery.
      - `photo_url` string: URL of the first photo taken by the driver as proof of delivery. Deprecated — use `photo_urls` instead.
    - `comment_proof_of_delivery` object, nullable
      - `comment` string: Comment left by the driver as proof of delivery.
    - `fail_reason` 'recipient_not_found' | 'rejected' | 'wrong_address' | 'zone_unsafe' | 'invalid_proof' | 'other' | 'invalid' | 'parcel_lost' | 'parcel_unreadable_barcode' | 'parcel_damaged' | 'parcel_stolen' | 'no_delivery_attempt' | 'postponed_by_customer' | 'place_closed' | 'no_keyword' | 'fraud_suspected' | 'unknown': Reason the delivery attempt failed. See [delivery attempt fail reasons](https://developers.cabify.com/reference/parcel-information#delivery-attempt-fail-reason) for a description of each value.
    - `support_ticket` string, nullable: ID of the support ticket opened by the driver when an incident occurs.
    - `address` string, nullable: Address where the delivery was attempted.
    - `feedback` string, nullable: Feedback provided by the driver when the parcel could not be delivered.
  - `tracking` object, nullable
    - `eta_to_accept` integer, nullable: Estimated time in seconds until a driver is assigned to this delivery.
    - `location` object, nullable
      - `lat` number, float
      - `lon` number, float
    - `routes` object
      - `pick_up` ParcelStatusRoute: Route information between two points during a delivery.
        - `eta` integer, required: Estimated time of arrival in seconds.
        - `path` string, required: Encoded polyline representing the route path.
      - `drop_off` ParcelStatusRoute: Route information between two points during a delivery.
        - `eta` integer, required: Estimated time of arrival in seconds.
        - `path` string, required: Encoded polyline representing the route path.
    - `tracking_url` string: Public URL where the parcel's live tracking can be viewed.
  - `asset` Asset: Details of the vehicle assigned to the delivery.
    - `reg_plate` string, nullable: Vehicle registration plate number.
    - `name` string: Vehicle model name.
    - `color` string: Vehicle color.
    - `asset_kind` 'bicycle' | 'moped' | 'car' | 'van': The type of vehicle selected to carry the parcels of a delivery. > **Only meaningful for `express` (on-demand) deliveries.** For > `same_day`, `next_day` and other cross-dock modalities the parcels > travel through hubs on multi-leg routes, and the vehicle that best > fits the whole route is used at each leg. The `asset_kind` returned for > those modalities is not a meaningful prediction of the vehicle that > will carry the parcel, so you should ignore it. The rest of this > description applies to `express` deliveries only. ## How the asset kind is selected (express) The asset kind is **not chosen randomly**: it is the result of a deterministic, priority-based selection. Given the set of vehicle types that are operationally available for the requested shipping type, area and route, the system picks the **cheapest, smallest suitable vehicle that can physically carry the whole delivery**. The selection is: 1. **Availability** — Start from the vehicle types that are enabled for the requested `shipping_type` in the delivery area, and that can reach every drop-off within their maximum allowed route time. Express deliveries use `bicycle`, `moped` and `car` only — **vans are not used for express**. 2. **Priority order** — Candidates are ordered from smallest/greenest to largest: `bicycle` → `moped` → `car`. 3. **Fit check** — Walking that order, the **first** vehicle whose limits are all satisfied by the delivery is selected. A vehicle "fits" only when **all** of the following hold for the combined parcels: - total volume ≤ the vehicle's maximum volume, - total weight ≤ the vehicle's maximum weight, - the largest single parcel's diagonal ≤ the vehicle's maximum diagonal. In short: **the asset kind is the smallest available vehicle in the `bicycle → moped → car` order that can fit the whole delivery by volume, weight and dimensions.** If no available vehicle can fit the delivery, the estimation fails instead of returning an asset kind. ## Selection thresholds (measure) Use the limits below to predict which asset kind an `express` delivery will get. The delivery is measured by its **total weight** (sum of all parcels), its **total volume** (sum of each parcel's width × height × length) and its **largest single parcel**, compared against the largest parcel each vehicle can accept (by the diagonal `√(w² + h² + l²)`). The first vehicle in priority order that satisfies all three limits is chosen. These are the platform default limits and may be overridden per delivery area, so treat them as guidance rather than a strict contract. | Asset kind | Priority | Max weight | Max single-parcel size (W × H × L) | Max volume (W·H·L) | Max route time | |------------|------------|------------|------------------------------------|--------------------|----------------| | `bicycle` | 1 (first) | 10,000 g | 45 × 45 × 45 | 91,125 | 9 min | | `moped` | 2 | 13,000 g | 45 × 45 × 45 | 91,125 | 4 h | | `car` | 3 (last) | 100,000 g | 95 × 85 × 50 | 403,750 | 6 h | Notes: - Weight limits are in **grams**, matching how the API represents parcel weight. Volume is the raw product of a parcel's width, height and length in the same units the parcel dimensions are sent in. - `bicycle` and `moped` share the same size and volume limits and differ mainly by weight capacity and how far they can travel, so heavier or longer routes fall through from `bicycle` to `moped` even when the parcel would otherwise fit a bike. - `van` is a valid value of this enum for non-express contexts, but it is **not selected for `express` deliveries**, so it is not listed above.
  - `driver` object, nullable: Information about the assigned driver. Only present once a driver has been assigned.
    - `photo_url` string: URL of the driver's profile photo.
    - `name` string: Driver's full name.
    - `phone` string: Driver's contact phone number.
  - `pickup_failed` PickupFailed: **Deprecated.** Use `pickup_attempt` instead. Details of a failed pickup attempt.
    - `reason` 'sender_no_show' | 'sender_too_late' | 'address_wrong' | 'address_not_found' | 'address_unsafe' | 'parcel_suspicious' | 'parcel_packaging' | 'parcel_too_big_or_heavy' | 'payment_requested' | 'payment_fake' | 'other_with_feedback' | 'place_closed' | 'delivery_not_found' | 'already_picked_up' | 'delivery_cancelled': Reason why the pickup failed. See [pickup failed reasons](https://developers.cabify.com/reference/parcel-information#pickup-failed-reason) for a description of each value.
    - `failed_at` string, date-time: Timestamp of the failed pickup event, formatted according to RFC 3339, section 5.6.
    - `driver_comments` string: Comments left by the driver explaining why the pickup failed.
  - `shipping_type` object, nullable: The shipping type selected for this parcel's delivery.
    - `id` string: Identifier of the shipping type.
    - `name` string: Display name of the shipping type.
    - `modality` 'express' | 'same_day' | 'next_day' | 'groceries': The delivery modality determines the timing and service level of the shipment. - `express`: On-demand delivery, typically within 1 hour. - `same_day`: Delivery scheduled for the same calendar day. - `next_day`: Delivery scheduled for the following calendar day. - `groceries`: Optimised for grocery and fresh-food deliveries.

## Other responses

- `401`: Unauthorized. Missing or invalid authentication token.
- `404`: No parcel found with the given ID.
- `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.

---

[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)