REST API (v1) to create, update, ship, cancel, track, and delete parcels; estimate shipping cost and timing; manage client hubs; configure proof of delivery; register webhook subscriptions; and integrate with ecommerce platforms (Shopify, Tiendanube, VTEX). OAuth2 client-credentials Bearer authentication; real-time parcel updates via webhooks.
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 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: parcels
description: 'A parcel is the package you need to ship. Each parcel is identified by a unique ID and
contains a pickup point (where the driver collects the package) and a drop-off point (the destination).
Parcels must be created before they can be shipped.
'
- name: delivery
description: 'Operations for managing the delivery lifecycle. Use these endpoints to trigger a shipment,
cancel an active delivery, or check whether a pickup location falls within an operating area.
'
- name: webhooks
description: 'Subscribe to event-driven notifications to receive live updates about parcel status changes,
location updates, and proof of delivery codes.
'
- name: hubs
description: 'A hub is a physical location (such as a warehouse or store) where parcels are stored until
they are ready to be picked up by a driver. You can reference a hub in pickup or drop-off information
using its external ID.
'
- name: status
description: Track the real-time status and location of your parcels at any point during their delivery.
paths:
/v1/parcels:
post:
tags:
- parcels
summary: Create new parcels.
description: 'Create one or more parcels to be shipped. Note that creating a parcel does not trigger
a delivery — you must call `/v1/parcels/ship` afterwards to schedule the pickup.
Each parcel requires a pickup and a drop-off location. You can provide a location using one of
the following fields in the `pickup_info` or `dropoff_info` schemas: `loc` (coordinates), `addr`
(address string), or `hub_external_id` (reference to a registered hub).
'
operationId: addParcels
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/NewParcels'
description: List of parcels you want to create.
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Parcels'
'400':
description: Bad request. One or more fields failed validation.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
'401':
description: Unauthorized. Missing or invalid authentication token.
'409':
description: Conflict. A parcel with the provided `external_id` already exists.
'422':
description: Unprocessable entity. The request is well-formed but contains semantic errors.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
security:
- bearer_token: []
get:
tags:
- parcels
summary: List parcels filtered by state.
description: Returns a paginated list of parcels that match the specified states.
operationId: getParcels
parameters:
- name: states
in: query
description: 'Filter results by one or more parcel states. See [parcel states](https://developers.cabify.com/reference/logistics-introduction#parcel)
for a description of each value.
'
required: true
schema:
type: array
items:
type: string
description: 'The current lifecycle state of a parcel. See [parcel states](https://developers.cabify.com/reference/logistics-introduction#parcel)
for a full description of each value.
'
enum:
- ready
- qualifiedforpickup
- onroutetopickup
- pickingup
- intransit
- delivering
- delivered
- returning
- returned
- incident
- requestercancel
- internalcancel
- pickupfailed
- ready_to_pickup
- on_route_to_final_hub
- received_on_final_hub
- ready_to_dispatch
- on_route_to_delivery
- undelivered
- onroutetoreturn
- returnrejected
- name: page
in: query
description: Page number to retrieve (0-based).
required: true
schema:
type: number
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedParcels'
'400':
description: Bad request. One or more query parameters failed validation.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
'401':
description: Unauthorized. Missing or invalid authentication token.
security:
- bearer_token: []
/v1/parcels/deliver/cancel:
post:
tags:
- delivery
summary: Cancel the delivery of the specified parcels.
description: 'Cancels an in-progress delivery for the given parcels, when cancellation is still
permitted. Delivery cannot be cancelled once the parcel has been picked up. Cancellation is allowed
in the following states: `qualifiedforpickup`, `onroutetopickup`, and `pickingup`. Please note
that cancellation may incur costs.
'
operationId: cancelParcels
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CancelParcels'
responses:
'202':
description: Cancellation request accepted and is being processed.
'401':
description: Unauthorized. Missing or invalid authentication token.
'404':
description: One or more parcels were not found.
'409':
description: 'One or more parcels cannot be cancelled due to their current state. Cancellation
is only allowed in the `qualifiedforpickup`, `onroutetopickup`, or `pickingup` states.
'
security:
- bearer_token: []
/v1/parcels/{parcel_id}/proof_configuration:
post:
tags:
- parcels
summary: Set proof of delivery configuration for a parcel.
description: Creates or replaces the proof of delivery methods configured for the specified parcel.
operationId: createProofConfigurationParcel
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateProofConfiguration'
parameters:
- in: path
name: parcel_id
description: UUID of the parcel to configure proof of delivery for.
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Configuration saved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ProofConfiguration'
'401':
description: Unauthorized. Missing or invalid authentication token.
'404':
description: No parcel found with the given ID.
security:
- bearer_token: []
get:
tags:
- parcels
summary: Get proof of delivery configuration for a parcel.
description: Returns the proof of delivery methods currently configured for the specified parcel.
operationId: proofConfigurationParcel
parameters:
- in: path
name: parcel_id
description: UUID of the parcel whose proof of delivery configuration you want to retrieve.
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Proof of delivery configuration retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ProofConfiguration'
'401':
description: Unauthorized. Missing or invalid authentication token.
'404':
description: No parcel found with the given ID.
security:
- bearer_token: []
/v1/parcels/delete:
post:
tags:
- parcels
summary: Delete parcels by ID.
description: 'Permanently deletes the specified parcels. Only parcels that have not yet been shipped
can be deleted. This is an **all-or-nothing** operation — if any parcel cannot be deleted, none
of the parcels in the request will be deleted.
'
operationId: deleteParcels
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteParcels'
responses:
'202':
description: All specified parcels were successfully deleted.
'401':
description: Unauthorized. Missing or invalid authentication token.
'404':
description: One or more parcels were not found.
security:
- bearer_token: []
/v1/webhooks/{hook}:
delete:
tags:
- webhooks
summary: Unsubscribe from a webhook.
description: Removes the webhook subscription for the specified event type.
operationId: deleteWebhook
parameters:
- in: path
name: hook
description: The event type to unsubscribe from.
required: true
schema:
type: string
enum:
- parcel
- parcelLocation
- proofCodeGenerated
responses:
'200':
description: Webhook subscription removed successfully.
'401':
description: Unauthorized. Missing or invalid authentication token.
security:
- bearer_token: []
/v1/parcels/deliver/pickup:
get:
tags:
- delivery
summary: Check whether a pickup location is within an operating area.
description: 'Verifies that the given pickup location is covered by the delivery service. You can
provide either a text address (`address`) or geographic coordinates (`pickup_point`).
'
parameters:
- in: query
name: address
description: 'Full address to check (e.g. `Calle Pradillo 42, Madrid`). You must provide either
`address` or `pickup_point` (or both).
'
required: false
example: Calle%20Pradillo%2042%2C%20Madrid (Calle Pradillo 42, Madrid)
schema:
type: string
- in: query
name: pickup_point
description: 'Geographic coordinates of the pickup location, formatted as `latitude,longitude`.
You must provide either `address` or `pickup_point` (or both).
'
required: false
example: 40.456367,-3.690587
schema:
type: string
operationId: deliverPickup
responses:
'200':
description: The pickup location is within an operating area.
'404':
description: The pickup location is not within any operating area.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
security:
- bearer_token: []
/v3/parcels/estimate:
post:
tags:
- shipment
summary: Estimate the cost and timing of a shipment.
description: 'Calculates the estimated price, pickup time, and delivery time for the given parcels
using the specified shipping type.
'
operationId: EstimateShipParcels
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EstimateV3Request'
responses:
'200':
description: Estimation calculated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/EstimateV3Response'
'400':
description: Bad request. One or more fields failed validation.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
'401':
description: Unauthorized. Missing or invalid authentication token.
'404':
description: The estimation could not be calculated. Check that the provided locations are within
an operating area.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
'409':
description: The server state does not currently allow processing this estimation request.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
'503':
description: The service is temporarily unavailable. Please try again later.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
security:
- bearer_token: []
/v1/hubs:
get:
tags:
- hubs
summary: List all client hubs.
description: Returns all hubs associated with your account.
responses:
'200':
description: Hubs retrieved successfully.
content:
application/json:
schema:
type: object
description: A collection of client hubs.
required:
- client_hubs
properties:
client_hubs:
type: array
items:
$ref: '#/paths/~1v1~1hubs~1none~1%7Bhub_external_id%7D/get/responses/200/content/application~1json/schema'
security:
- bearer_token: []
post:
tags:
- hubs
summary: Create a new client hub.
description: 'Creates a new hub associated with your account. Hubs represent physical locations
(such as stores or warehouses) from which parcels can be picked up or delivered to.
'
requestBody:
content:
application/json:
schema:
type: object
description: Request body for creating a new client hub.
required:
- external_id
- address
properties:
external_id:
type: string
description: A unique identifier you define to reference this hub. This ID is used in
parcel pickup and drop-off configurations.
address:
type: string
description: Full street address of the hub.
location:
type: object
description: A geographic coordinate expressed as latitude and longitude.
required:
- lat
- lon
properties:
lat:
type: number
format: float
description: Latitude in decimal degrees.
example: 40.4489254
lon:
type: number
format: float
description: Longitude in decimal degrees.
example: -3.6730293
instructions:
type: string
description: Additional instructions for drivers arriving at this hub (e.g. access codes,
gate numbers).
contact:
type: object
description: Primary contact person at this hub.
properties:
name:
type: string
description: Full name of the contact person.
phone:
type: string
description: Phone number of the contact person.
responses:
'200':
description: Hub created successfully.
content:
application/json:
schema:
type: object
description: Response returned after successfully creating a hub.
properties:
id:
type: string
description: System-generated ID of the newly created hub.
example: 4f627a06d74011ec97dd06d73193996d
'401':
description: Unauthorized. Missing or invalid authentication token.
security:
- bearer_token: []
/v1/hubs/none/{hub_external_id}:
get:
tags:
- hubs
summary: Get a client hub by its external ID.
description: Returns the details of a specific hub identified by your external ID.
parameters:
- in: path
name: hub_external_id
description: The external ID you assigned to the hub.
required: true
schema:
type: string
responses:
'200':
description: Hub retrieved successfully.
content:
application/json:
schema:
type: object
description: Full details of a client hub.
properties:
hub_id:
type: string
description: System-generated ID of the hub.
external_id:
type: string
description: Your external ID for this hub.
address:
type: string
description: Full street address of the hub.
location:
$ref: '#/paths/~1v1~1hubs/post/requestBody/content/application~1json/schema/properties/location'
instructions:
type: string
description: Additional instructions for drivers arriving at this hub.
contact:
type: object
description: Primary contact person at this hub.
properties:
name:
type: string
description: Full name of the contact person.
phone:
type: string
description: Phone number of the contact person.
'401':
description: Unauthorized. Missing or invalid authentication token.
'404':
description: No hub found with the given external ID.
security:
- bearer_token: []
put:
tags:
- hubs
summary: Update a client hub by its external ID.
description: Updates the details of a specific hub identified by your external ID.
parameters:
- in: path
name: hub_external_id
description: The external ID you assigned to the hub.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
description: Request body for updating an existing client hub. Only included fields will
be modified.
properties:
address:
type: string
description: Updated full street address of the hub.
location:
$ref: '#/paths/~1v1~1hubs/post/requestBody/content/application~1json/schema/properties/location'
instructions:
type: string
description: Updated instructions for drivers arriving at this hub.
contact:
type: object
description: Updated primary contact person at this hub.
properties:
name:
type: string
description: Full name of the contact person.
phone:
type: string
description: Phone number of the contact person.
responses:
'200':
description: Hub updated successfully.
'401':
description: Unauthorized. Missing or invalid authentication token.
security:
- bearer_token: []
/v1/parcels/{parcel_id}:
get:
tags:
- parcels
summary: Get a parcel by ID.
description: Returns the full details of a parcel identified by its UUID.
operationId: getParcel
parameters:
- in: path
name: parcel_id
description: UUID of the parcel to retrieve.
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Parcel found and returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Parcel'
'401':
description: Unauthorized. Missing or invalid authentication token.
'404':
description: No parcel found with the given ID.
security:
- bearer_token: []
put:
tags:
- parcels
summary: Update a parcel by ID.
description: 'Update editable fields of an existing parcel. The set of fields that can be modified
depends on the parcel''s current state:
**All fields** can be updated when the parcel is in one of these states: `ready`, `pickupfailed`,
`requestercancel`, or `returnedtoorigin`.
**Instructions only** (`pickup_info.instr`, `dropoff_info.instr`) can be updated in all other
active states.
'
operationId: updateParcel
parameters:
- in: path
name: parcel_id
description: UUID of the parcel to update.
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateParcel'
description: Fields of the parcel you want to update. Only the provided fields will be changed.
required: true
responses:
'200':
description: Parcel updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Parcel'
'400':
description: Bad request. One or more fields failed validation.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
'401':
description: Unauthorized. Missing or invalid authentication token.
'403':
description: This parcel does not belong to your account.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
'409':
description: The parcel cannot be updated in its current state.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
'422':
description: Unprocessable entity. The request is well-formed but contains semantic errors.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
security:
- bearer_token: []
/v1/parcels/{parcel_id}/tip:
get:
tags:
- parcels
summary: Get the tip for a parcel.
description: '> **Note:** This feature is not available to all clients. Please contact us before
using it.
Returns the tip configured for the specified parcel, if one exists.
'
operationId: getTipParcel
parameters:
- name: parcel_id
in: path
description: UUID of the parcel whose tip you want to retrieve.
required: true
style: simple
explode: false
schema:
type: string
format: uuid
responses:
'200':
description: Tip retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Tip'
'204':
description: No tip exists for the specified parcel.
'401':
description: Unauthorized. Missing or invalid authentication token.
'403':
description: This parcel does not belong to your account, or your account is not allowed to
use the tipping feature.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
'404':
description: No parcel found with the given ID.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
security:
- bearer_token: []
post:
tags:
- parcels
summary: Add a tip for a parcel delivery.
description: '> **Note:** This feature is not available to all clients. Please contact us before
using it.
Adds a tip for the driver in the event of a successful delivery. The tip can be set at any
point before the parcel is delivered. The tip amount must be formatted according to ISO 4217
(e.g. €6.30 → `630` in EUR).
'
operationId: tipParcel
parameters:
- name: parcel_id
in: path
description: UUID of the parcel to tip.
required: true
style: simple
explode: false
schema:
type: string
format: uuid
requestBody:
description: 'The tip amount to create for the parcel. The amount must follow the ISO 4217 standard
(e.g. €6.30 → `630` in EUR).
'
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTip'
required: true
responses:
'200':
description: Tip created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Tip'
'401':
description: Unauthorized. Missing or invalid authentication token.
'403':
description: This parcel does not belong to your account, or your account is not allowed to
use the tipping feature.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
'404':
description: No parcel found with the given ID.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
'409':
description: A tip already exists for this parcel.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
'429':
description: The parcel's current state does not allow adding a tip.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
security:
- bearer_token: []
/v1/users:
get:
tags:
- users
summary: List users belonging to your account.
description: Returns all Cabify users associated with your account.
operationId: getUsers
responses:
'200':
description: Users retrieved successfully.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
'401':
description: Unauthorized. Missing or invalid authentication token.
'404':
description: No users found for this client.
'500':
description: An unexpected server error occurred.
'503':
description: The service is temporarily unavailable. Please try again later.
security:
- bearer_token: []
/v1/webhooks:
get:
tags:
- webhooks
summary: List your active webhook subscriptions.
description: Returns all active webhook subscriptions registered for your account.
operationId: getWebhook
responses:
'200':
description: Webhook subscriptions retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ResponseWebhookSubscriptions'
'401':
description: Unauthorized. Missing or invalid authentication token.
security:
- bearer_token: []
post:
tags:
- webhooks
summary: Subscribe to parcel update notifications.
description: "Register a webhook to receive real-time notifications when parcels are updated.\n\n\
**Securing your webhook endpoint:**\n1. Include a custom authorization header in the subscription\
\ request. Our API will forward\n it with every notification:\n ```\n Authorization: Bearer\
\ <your-auth-token>\n ```\n2. For enhanced security using OAuth (client credentials), contact\
\ us to set up authentication\n with a `clientId` and `clientSecret`.\n"
operationId: subscribeWebhook
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookSubscription'
description: The webhook subscription details, including the event type and your callback URL.
required: true
responses:
'201':
description: Webhook subscription created successfully.
'400':
description: Bad request. One or more fields failed validation.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
'401':
description: Unauthorized. Missing or invalid authentication token.
security:
- bearer_token: []
callbacks:
parcel:
'{$request.body#/callback_url}':
post:
parameters:
- in: header
name: '{$request.body#/headers/name}'
schema:
type: string
- in: header
name: '{$request.body#/headers/value}'
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ParcelStatusHook'
responses:
'200':
description: Success
parcelLocation:
'{$request.body#/callback_url}':
post:
parameters:
- in: header
name: '{$request.body#/headers/name}'
schema:
type: string
- in: header
name: '{$request.body#/headers/value}'
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ParcelLocation'
responses:
'200':
description: Success
proofCodeGenerated:
'{$request.body#/callback_url}':
post:
parameters:
- in: header
name: '{$request.body#/headers/name}'
schema:
type: string
- in: header
name: '{$request.body#/headers/value}'
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ProofCodeGenerated'
responses:
'200':
description: Success
/v1/parcels/{parcel_id}/label:
get:
tags:
- parcels
summary: Get the shipping label for a parcel.
description: 'Returns the shipping label for the specified parcel as a PDF. This label is scanned
by t
# --- truncated at 32 KB (91 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cabify/refs/heads/main/openapi/cabify-logistics-openapi.yml