---
updatedAt: 2026-04-23T13:12:03.000Z
agentTools:
  projectIndex: https://cabify-api.readme.io/llms.txt
---

# Update a parcel by ID.

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 `returned`.

**Instructions only** (`pickup_info.instr`, `dropoff_info.instr`) can be updated in all other active states.


# OpenAPI definition

```json
{
  "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.\n",
    "version": "1.0.0",
    "title": "Cabify Logistics API",
    "contact": {
      "email": "p.delivery@cabify.com"
    }
  },
  "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.\n"
    }
  ],
  "paths": {
    "/v1/parcels/{parcel_id}": {
      "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:\n\n**All fields** can be updated when the parcel is in one of these states: `ready`, `pickupfailed`, `requestercancel`, or `returned`.\n\n**Instructions only** (`pickup_info.instr`, `dropoff_info.instr`) can be updated in all other active states.\n",
        "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"
                }
              }
            }
          },
          "429": {
            "description": "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.\n"
          }
        },
        "security": [
          {
            "bearer_token": []
          }
        ]
      }
    }
  },
  "externalDocs": {
    "description": "Cabify Logistics API documentation",
    "url": "https://developers.cabify.com"
  },
  "servers": [
    {
      "url": "https://logistics.api.cabify-sandbox.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearer_token": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "ParcelPointPickupInfo": {
        "type": "object",
        "required": [
          "contact"
        ],
        "description": "Information about the pickup point. You must provide at least one of the following location fields: `loc` (coordinates), `addr` (address string), or `hub_external_id` (reference to a registered hub). They may be combined; when `loc` is present the coordinates are used and `addr` is kept as informational only.\n",
        "properties": {
          "addr": {
            "type": "string",
            "description": "Full address where the parcel should be picked up.",
            "example": "Calle de Pradillo, 42, Madrid"
          },
          "contact": {
            "$ref": "#/components/schemas/NewParcelPickupContact"
          },
          "instr": {
            "type": "string",
            "nullable": true,
            "description": "Additional instructions for the driver at the pickup location.",
            "example": "Knock the door three times"
          },
          "loc": {
            "$ref": "#/components/schemas/Point"
          },
          "code": {
            "type": "string",
            "nullable": true,
            "description": "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.\n",
            "example": "ABC123"
          },
          "hub_external_id": {
            "type": "string",
            "description": "External ID of a client hub to use as the pickup location.",
            "example": "magic_store_santa_fe"
          }
        }
      },
      "ParcelPointDropoffInfo": {
        "type": "object",
        "required": [
          "contact"
        ],
        "description": "Information about the drop-off (destination) point. You must provide at least one of the following location fields: `loc` (coordinates), `addr` (address string), or `hub_external_id` (reference to a registered hub). They may be combined; when `loc` is present the coordinates are used and `addr` is kept as informational only.\n",
        "properties": {
          "addr": {
            "type": "string",
            "description": "Full address where the parcel should be delivered.",
            "example": "Calle de Pradillo, 42, Madrid"
          },
          "contact": {
            "$ref": "#/components/schemas/NewParcelDropoffContact"
          },
          "instr": {
            "type": "string",
            "nullable": true,
            "description": "Additional instructions for the driver at the drop-off location.",
            "example": "Knock the door three times"
          },
          "loc": {
            "$ref": "#/components/schemas/Point"
          },
          "hub_external_id": {
            "type": "string",
            "description": "External ID of a client hub to use as the drop-off location.",
            "example": "magic_store_santa_fe"
          }
        }
      },
      "ParcelDimensions": {
        "type": "object",
        "description": "Physical dimensions of the parcel.",
        "properties": {
          "height": {
            "type": "integer",
            "minimum": 0,
            "example": 10
          },
          "length": {
            "type": "integer",
            "minimum": 0,
            "example": 10
          },
          "width": {
            "type": "integer",
            "minimum": 0,
            "example": 10
          },
          "unit": {
            "type": "string",
            "description": "Unit of measure for the dimensions. Defaults to `cm` if omitted or set to an invalid value.",
            "enum": [
              "cm"
            ]
          }
        }
      },
      "ParcelWeight": {
        "type": "object",
        "description": "Weight of the parcel.",
        "properties": {
          "value": {
            "type": "integer",
            "minimum": 0,
            "example": 1500
          },
          "unit": {
            "type": "string",
            "description": "Unit of weight. Defaults to `g` (grams) if omitted or set to an invalid value.",
            "enum": [
              "g"
            ]
          }
        }
      },
      "NewParcelPickupContact": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "nullable": true,
            "description": "Name of the contact person at the pickup location.",
            "example": "John"
          },
          "phone": {
            "type": "string",
            "nullable": true,
            "description": "Phone number of the contact person at the pickup location.",
            "example": "+34666000000"
          }
        }
      },
      "NewParcelDropoffContact": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Name of the recipient at the drop-off location.",
            "example": "John"
          },
          "phone": {
            "type": "string",
            "nullable": true,
            "description": "Phone number of the recipient at the drop-off location.",
            "example": "+34666000000"
          }
        }
      },
      "Parcel": {
        "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"
          },
          "client_id": {
            "type": "string",
            "description": "The account that owns the parcel."
          },
          "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.\n",
            "example": "delivered"
          },
          "failure_reason": {
            "type": "string",
            "description": "If present, why the shipment request was rejected. Same values as `failure_reason` in the status endpoint.\n"
          },
          "pickup_info": {
            "$ref": "#/components/schemas/ParcelPointPickupInfo"
          },
          "dropoff_info": {
            "$ref": "#/components/schemas/ParcelPointDropoffInfo"
          },
          "dimensions": {
            "$ref": "#/components/schemas/ParcelDimensions"
          },
          "weight": {
            "$ref": "#/components/schemas/ParcelWeight"
          },
          "price": {
            "$ref": "#/components/schemas/Price"
          },
          "delivery_from": {
            "type": "string",
            "format": "date-time",
            "description": "Start of the delivery window, if the parcel has one, formatted according to RFC 3339, section 5.6.",
            "example": "2021-12-02T10:00:00Z"
          },
          "delivery_to": {
            "type": "string",
            "format": "date-time",
            "description": "End of the delivery window, if the parcel has one, formatted according to RFC 3339, section 5.6.",
            "example": "2021-12-02T14:00:00Z"
          }
        }
      },
      "Point": {
        "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
          }
        }
      },
      "RequestError": {
        "type": "object",
        "description": "Standard error response body returned when a request fails.",
        "required": [
          "errors"
        ],
        "properties": {
          "errors": {
            "type": "array",
            "description": "List of human-readable error messages describing what went wrong.",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "UpdateParcel": {
        "type": "object",
        "description": "Fields that can be updated on an existing parcel. Only fields included in the request will be modified.",
        "properties": {
          "external_id": {
            "type": "string",
            "description": "Your own identifier for this parcel. Must be unique across all your parcels.",
            "example": "parcel_001"
          },
          "pickup_info": {
            "$ref": "#/components/schemas/ParcelPointPickupInfo"
          },
          "dropoff_info": {
            "$ref": "#/components/schemas/ParcelPointDropoffInfo"
          },
          "dimensions": {
            "$ref": "#/components/schemas/ParcelDimensions"
          },
          "weight": {
            "$ref": "#/components/schemas/ParcelWeight"
          },
          "delivery_from": {
            "type": "string",
            "format": "date-time",
            "description": "Start of the requested delivery time window, formatted according to RFC 3339, section 5.6. The parcel will not be delivered before this time.\n",
            "example": "2021-12-02T10:12:07.753Z"
          },
          "delivery_to": {
            "type": "string",
            "format": "date-time",
            "description": "End of the requested delivery time window, formatted according to RFC 3339, section 5.6. The parcel should be delivered before this time.\n",
            "example": "2021-12-02T10:12:07.753Z"
          },
          "price": {
            "$ref": "#/components/schemas/Price"
          }
        }
      },
      "Price": {
        "type": "object",
        "description": "Price information for the parcel, used in cash-on-delivery scenarios.",
        "properties": {
          "declared_value": {
            "type": "integer",
            "description": "Declared value of the parcel's contents, in the smallest currency unit following the ISO 4217 standard (e.g. €6.30 → `630`).\n",
            "example": 630
          },
          "collected_value": {
            "type": "integer",
            "description": "Amount to be collected from the recipient upon delivery, in the smallest currency unit following the ISO 4217 standard (e.g. €6.30 → `630`).\n",
            "example": 630
          },
          "currency": {
            "type": "string",
            "description": "ISO 4217 currency code.",
            "example": "EUR"
          }
        }
      }
    }
  }
}
```