--- title: "Create new parcels." method: POST path: "/v1/parcels" tags: ["parcels"] --- # Create new parcels. `POST /v1/parcels` 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). ## Request body - NewParcels - `parcels` NewParcel[], required - `external_id` string — Your own identifier for this parcel. Use this field to correlate parcels in the Cabify system with records in your own system. Must be unique across all your parcels. - `pickup_info` ParcelPointPickupInfo, required — Information about the pickup point. You must provide exactly one of the following location fields: `loc` (coordinates), `addr` (address string), or `hub_external_id` (reference to a registered hub). - `addr` string — Full address where the parcel should be picked up. - `contact` NewParcelPickupContact, required - `name` string, nullable — Name of the contact person at the pickup location. - `phone` string, nullable — Phone number of the contact person at the pickup location. - `instr` string, nullable — Additional instructions for the driver at the pickup location. - `loc` 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. - `code` string, nullable — Alphanumeric code (typically 4–6 characters) shown to the driver to confirm the pickup. Only one code is shown per delivery, so only use this field when the delivery consists of a single parcel. - `hub_external_id` string — External ID of a client hub to use as the pickup location. - `dropoff_info` ParcelPointDropoffInfo, required — Information about the drop-off (destination) point. You must provide exactly one of the following location fields: `loc` (coordinates), `addr` (address string), or `hub_external_id` (reference to a registered hub). - `addr` string — Full address where the parcel should be delivered. - `contact` NewParcelDropoffContact, required - `name` string — Name of the recipient at the drop-off location. - `phone` string, nullable — Phone number of the recipient at the drop-off location. - `instr` string, nullable — Additional instructions for the driver at the drop-off location. - `loc` 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. - `hub_external_id` string — External ID of a client hub to use as the drop-off 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. - `price` Price — Price information for the parcel, used in cash-on-delivery scenarios. - `declared_value` integer — Declared value of the parcel's contents, in the smallest currency unit following the ISO 4217 standard (e.g. €6.30 → `630`). - `collected_value` integer — Amount to be collected from the recipient upon delivery, in the smallest currency unit following the ISO 4217 standard (e.g. €6.30 → `630`). - `currency` string — ISO 4217 currency code. - `delivery_from` string, date-time — Start of the requested delivery time window, formatted according to RFC 3339, section 5.6. The parcel will not be delivered before this time. - `delivery_to` string, date-time — End of the requested delivery time window, formatted according to RFC 3339, section 5.6. The parcel should be delivered before this time. ## Response `200` Success - Parcels - `parcels` Parcel[], required - `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. - `pickup_info` ParcelPointPickupInfo — Information about the pickup point. You must provide exactly one of the following location fields: `loc` (coordinates), `addr` (address string), or `hub_external_id` (reference to a registered hub). - `addr` string — Full address where the parcel should be picked up. - `contact` NewParcelPickupContact, required - `name` string, nullable — Name of the contact person at the pickup location. - `phone` string, nullable — Phone number of the contact person at the pickup location. - `instr` string, nullable — Additional instructions for the driver at the pickup location. - `loc` 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. - `code` string, nullable — Alphanumeric code (typically 4–6 characters) shown to the driver to confirm the pickup. Only one code is shown per delivery, so only use this field when the delivery consists of a single parcel. - `hub_external_id` string — External ID of a client hub to use as the pickup location. - `dropoff_info` ParcelPointDropoffInfo — Information about the drop-off (destination) point. You must provide exactly one of the following location fields: `loc` (coordinates), `addr` (address string), or `hub_external_id` (reference to a registered hub). - `addr` string — Full address where the parcel should be delivered. - `contact` NewParcelDropoffContact, required - `name` string — Name of the recipient at the drop-off location. - `phone` string, nullable — Phone number of the recipient at the drop-off location. - `instr` string, nullable — Additional instructions for the driver at the drop-off location. - `loc` 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. - `hub_external_id` string — External ID of a client hub to use as the drop-off 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. - `price` Price — Price information for the parcel, used in cash-on-delivery scenarios. - `declared_value` integer — Declared value of the parcel's contents, in the smallest currency unit following the ISO 4217 standard (e.g. €6.30 → `630`). - `collected_value` integer — Amount to be collected from the recipient upon delivery, in the smallest currency unit following the ISO 4217 standard (e.g. €6.30 → `630`). - `currency` string — ISO 4217 currency code. - `created_at` string, date-time — Timestamp when the parcel was created, formatted according to RFC 3339, section 5.6. - `updated_at` string, date-time — Timestamp of the most recent update to the parcel, formatted according to RFC 3339, section 5.6. ## Other responses - `400` — Bad request. One or more fields failed validation. - `401` — Unauthorized. Missing or invalid authentication token. - `409` — Conflict. A parcel with the provided `external_id` already exists. - `422` — Unprocessable entity. The request is well-formed but contains semantic errors. --- [API](https://skmtc.dev/cabify/apis/ride-hailing-api.md) · [All operations](https://skmtc.dev/cabify/apis/ride-hailing-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/cabify/ride-hailing-api/revisions/8da1cb1270df/schema)