Track the real-time status and location of your parcels at any point during their delivery.
openapi: 3.0.0
info:
description: 'Welcome to the Cabify Logistics API. This API allows you to create and manage parcel deliveries, track their status in real time, configure proof of delivery options, and receive live updates via webhooks. All requests must be authenticated using a Bearer token.
'
version: 1.0.0
title: Cabify Logistics delivery status API
contact:
email: p.delivery@cabify.com
servers:
- url: https://logistics.api.cabify.com
description: Production
- url: https://logistics.api.cabify-sandbox.com
description: Sandbox
tags:
- name: status
description: Track the real-time status and location of your parcels at any point during their delivery.
paths:
/v1/parcels/{parcel_id}/status:
get:
tags:
- status
summary: Get the current status of a parcel.
description: Returns the current state and tracking information for the specified parcel.
operationId: statusParcel
parameters:
- in: path
name: parcel_id
description: UUID of the parcel to track.
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Parcel status retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ParcelStatus'
'401':
description: Unauthorized. Missing or invalid authentication token.
'404':
description: No parcel found with the given ID.
security:
- bearer_token: []
/v1/parcels/{parcel_id}/timeline:
get:
tags:
- status
summary: Get the state history of a parcel.
description: 'Returns the ordered list of state-change events for the specified parcel. Only parcels updated within the last 30 days can be queried.
'
operationId: timelineParcel
parameters:
- in: path
name: parcel_id
description: UUID of the parcel whose history you want to retrieve.
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Timeline retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ParcelTimeline'
'401':
description: Unauthorized. Missing or invalid authentication token.
'403':
description: This parcel does not belong to your account.
'404':
description: No parcel found with the given ID.
security:
- bearer_token: []
components:
schemas:
AssetKind:
type: string
description: The type of vehicle assigned to carry the parcel.
enum:
- bicycle
- car
- moped
- scooter
- van
PickupFailed:
type: object
description: '**Deprecated.** Use `pickup_attempt` instead. Details of a failed pickup attempt.
'
properties:
reason:
type: string
description: '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.
'
enum:
- 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
example: address_wrong
failed_at:
type: string
format: date-time
description: Timestamp of the failed pickup event, formatted according to RFC 3339, section 5.6.
example: '2021-12-02T10:12:07.753Z'
driver_comments:
type: string
description: Comments left by the driver explaining why the pickup failed.
example: can't find the address
ParcelStatus:
type: object
properties:
id:
type: string
format: uuid
description: System-generated UUID for this parcel.
example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
external_id:
type: string
description: Your own identifier for this parcel, as provided when the parcel was created.
example: parcel_001
state:
type: string
description: '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.
'
enum:
- ready
- qualifiedforpickup
- pickingup
- intransit
- delivering
- delivered
- returning
- returned
- incident
- requestercancel
- internalcancel
- pickupfailed
- onroutetopickup
- readytopickup
- onroutetofinalhub
- receivedonfinalhub
- readytodispatch
- onroutetodelivery
- undelivered
- onroutetoreturn
- returnrejected
failure_reason:
type: string
description: '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.
'
enum:
- unknown
- payment_method_declined
- no_payment_methods
- requester_not_found_or_unauthorized
- product_does_not_exist
- invalid_pick_up_location
- delivery_already_exist
delivery_attempt:
type: object
properties:
id_proof_of_delivery:
type: object
nullable: true
properties:
recipient_name:
type: string
description: Name of the person who received the parcel.
example: Francisco
recipient_id_number:
type: string
example: 11111111T
description: Identity document number of the person who received the parcel.
photo_proof_of_delivery:
type: object
nullable: true
properties:
photo_urls:
type: array
items:
type: string
description: List of URLs of the photos taken by the driver as proof of delivery.
photo_url:
type: string
example: https://s3.amazon.com/photo.jpg
description: URL of the first photo taken by the driver as proof of delivery. Deprecated — use `photo_urls` instead.
comment_proof_of_delivery:
type: object
nullable: true
properties:
comment:
type: string
example: El paquete se ha dejado en la puerta
description: Comment left by the driver as proof of delivery.
fail_reason:
type: string
description: '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.
'
enum:
- 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
support_ticket:
type: string
nullable: true
description: ID of the support ticket opened by the driver when an incident occurs.
address:
type: string
nullable: true
description: Address where the delivery was attempted.
feedback:
type: string
nullable: true
description: Feedback provided by the driver when the parcel could not be delivered.
tracking:
type: object
nullable: true
properties:
eta_to_accept:
type: integer
nullable: true
description: Estimated time in seconds until a driver is assigned to this delivery.
example: 90
location:
type: object
nullable: true
properties:
lat:
type: number
format: float
example: 40.4489254
lon:
type: number
format: float
example: -3.6730293
routes:
type: object
properties:
pick_up:
description: Information about the route from the driver position to the pickup point. Available before the parcel has been picked up.
allOf:
- $ref: '#/components/schemas/ParcelStatusRoute'
drop_off:
description: Information about the route from the pickup point to the drop-off destination.
allOf:
- $ref: '#/components/schemas/ParcelStatusRoute'
tracking_url:
type: string
description: Public URL where the parcel's live tracking can be viewed.
asset:
$ref: '#/components/schemas/Asset'
driver:
type: object
nullable: true
description: Information about the assigned driver. Only present once a driver has been assigned.
properties:
photo_url:
type: string
description: URL of the driver's profile photo.
example: https://s3.amazon.com/photo.jpg
name:
type: string
description: Driver's full name.
example: Pepe
phone:
type: string
description: Driver's contact phone number.
example: '+34658478854'
pickup_failed:
$ref: '#/components/schemas/PickupFailed'
shipping_type:
type: object
nullable: true
description: The shipping type selected for this parcel's delivery.
properties:
id:
type: string
format: uuid
description: UUID of the shipping type.
example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
name:
type: string
description: Display name of the shipping type.
example: Same day default
modality:
$ref: '#/components/schemas/Modality'
Modality:
type: string
description: '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.
'
example: same_day
enum:
- express
- same_day
- next_day
- groceries
TimelineEvent:
type: object
required:
- state
- state_updated_at
properties:
state:
type: string
description: 'The lifecycle state the parcel transitioned into. See [parcel states](https://developers.cabify.com/reference/logistics-introduction#parcel) for a full description of each value.
'
enum:
- ready
- qualifiedforpickup
- pickingup
- intransit
- delivering
- delivered
- returning
- returned
- incident
- requestercancel
- internalcancel
- pickupfailed
- onroutetopickup
- readytopickup
- onroutetofinalhub
- receivedonfinalhub
- readytodispatch
- onroutetodelivery
- undelivered
- onroutetoreturn
- returnrejected
state_updated_at:
type: string
format: date-time
description: Timestamp when the parcel transitioned into this state, formatted according to RFC 3339, section 5.6.
example: '2021-12-02T10:12:07.753Z'
ParcelStatusRoute:
type: object
description: Route information between two points during a delivery.
required:
- eta
- path
properties:
eta:
type: integer
example: 120
description: Estimated time of arrival in seconds.
path:
type: string
example: fhdsa98fha87sdfhas76dgf8a
description: Encoded polyline representing the route path.
ParcelTimeline:
type: object
required:
- id
- timeline
properties:
id:
type: string
format: uuid
description: System-generated UUID for this parcel.
example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
external_id:
type: string
description: Your own identifier for this parcel, as provided when the parcel was created.
example: parcel_001
timeline:
type: array
description: Chronological list of state-change events for this parcel.
items:
$ref: '#/components/schemas/TimelineEvent'
Asset:
type: object
description: Details of the vehicle assigned to the delivery.
properties:
reg_plate:
type: string
nullable: true
description: Vehicle registration plate number.
example: 1111AAA
name:
type: string
description: Vehicle model name.
example: Audi A3
color:
type: string
description: Vehicle color.
example: black
asset_kind:
$ref: '#/components/schemas/AssetKind'
securitySchemes:
bearer_token:
type: http
scheme: bearer