Parcel

What is a Parcel?

A parcel is the fundamental entity in the Cabify Logistics platform. It represents a physical package that needs to be picked up from a sender location and delivered to a recipient location.

Each parcel contains all the information needed for the logistics operation: where to pick it up, where to deliver it, its physical characteristics, and contact details for both sender and recipient.

Key information in a parcel

A parcel holds the following groups of information:

• Identification: A platform-assigned unique id plus an optional external_id that you can set to your own order reference number.
• State: The current lifecycle state (e.g., ready, intransit, delivered). See Parcels life cycle for all possible states.
• Pickup info: The pickup location (coordinates, address, or hub reference), special instructions for the driver, and the sender's contact details (name, phone).
• Dropoff info: The delivery location, special instructions, and the recipient's contact details. The recipient name is always required.
• Dimensions and weight: Height, length, width (default unit: cm) and weight (default unit: g). These affect vehicle selection.
• Delivery window: Optional delivery_from and delivery_to timestamps indicating the desired delivery time range.
• Price: Optional pricing information including the currency, declared value of the contents, and an amount to collect from the recipient (cash on delivery).
• Failure reason: When a parcel enters a failed state, this field describes what went wrong.

Pickup and dropoff locations

Both pickup and dropoff locations support three ways of specifying the address. You must provide at least one of:

• Geographic coordinates (lat, lon): Precise location on the map.
• Address string: A human-readable text address.
• Hub external ID: A reference to a pre-configured warehouse or hub in the system.

You can combine these (e.g., coordinates plus a text address), if coordinates are present, we use this ones and address remains as informational only.

Parcel states

A parcel goes through multiple states during its lifecycle, from creation to delivery or return. For the full list of states and their transitions, see the Parcels life cycle section.

API reference

For the full request and response schemas, see the Logistics API Reference.