Create a parcel

Creating a parcel registers a package with us: where it is collected, where it goes, who to contact at each end, and what it looks like physically.

❗️

Creating does not ship

A created parcel sits in the ready state and nothing is collected. To have it picked up you must then request its shipment. See Parcels life cycle for the states that follow.

See Parcel for what the entity holds.

Request

curl --request POST \
  --url https://logistics.api.{{BASE_ENV_URL}}/v1/parcels \
  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "parcels": [
      {
        "external_id": "order_1042",
        "pickup_info": {
          "loc": { "lat": 40.456367, "lon": -3.690587 },
          "addr": "Calle de Pradillo, 42, Madrid",
          "instr": "Ask for the shift manager",
          "contact": { "name": "Magic Store", "phone": "+34600000000" }
        },
        "dropoff_info": {
          "addr": "Gran Via 1, Madrid",
          "contact": { "name": "Ada Lovelace", "phone": "+34600000001" }
        },
        "dimensions": { "height": 10, "length": 20, "width": 15, "unit": "cm" },
        "weight": { "value": 1500, "unit": "g" }
      }
    ]
  }'

You may create several parcels in one call: parcels is an array.

Locating the pickup and the dropoff

Both pickup_info and dropoff_info require at least one of:

• loc — coordinates, as { "lat": ..., "lon": ... }.
• addr — a human-readable address.
• hub_external_id — the external ID of a hub you have registered.

They can be combined. When loc is present the coordinates are used and addr is kept as informational only, so a precise loc with a friendly addr is the safest combination.

contact is required on both ends; the recipient's name is always needed.

Optional fields worth knowing

Response

200 returns the created parcels, each with the platform-assigned id you will use everywhere else — to ship, to track and to get the label.

When it fails

See Error handling.