Parcel Shipping via API | Cargoboard API

Besides freight, you can book parcel shipments through the same API — ideal if you ship many small packages per day and don't want to enter them manually.

Activating parcel mode

Parcel booking uses the standard /v1/quotations and /v1/orders endpoints, but you must send an additional header that switches the request into parcel mode:

Header	Value
`x-transport-type-parcel-is-active`	`true`

If this header is missing, the request is treated as a normal freight shipment.

curl --request POST \
     --url https://api-sandbox.cargoboard.com/v1/orders \
     --header 'Content-Type: application/json' \
     --header 'X-API-KEY: YourKeyHere' \
     --header 'x-transport-type-parcel-is-active: true' \
     --data '{ ... }'

Building the request

The body works like any other booking (see Place an Order), with these specifics for parcels:

Use the package type KT in each line.
Send one line per package, or use unitQuantity for several identical packages.
Dimensions in centimeters, weight in kilograms.

Example request

{
    "product": "STANDARD",
    "shipper": {
        "name": "Producer ABC GmbH & Co. KG",
        "address": {
            "street": "Examplestreet 12a",
            "postCode": "40239",
            "countryCode": "DE",
            "city": "Düsseldorf"
        },
        "pickupOn": "2026-12-01"
    },
    "consignee": {
        "name": "Consignee ABC AG",
        "address": {
            "street": "Examplestreet 5",
            "postCode": "41061",
            "countryCode": "DE",
            "city": "Mönchengladbach"
        }
    },
    "lines": [
        {
            "unitQuantity": 2,
            "unitPackageType": "KT",
            "content": "Spare parts",
            "unitLength": 40,
            "unitWidth": 30,
            "unitHeight": 20,
            "unitWeight": 5
        }
    ]
}

Sent with the header x-transport-type-parcel-is-active: true, this books 2 parcels of 40 × 30 × 20 cm at 5 kg each.

Size & weight limits

Each parcel must stay within these limits. Shipments that exceed them must be booked as freight, not parcel.

Parameter	Maximum
Weight per parcel (physical)	32 kg
Volumetric weight per parcel	70 kg
Length (longest side)	240 cm
Girth (longest side + 2 × width + 2 × height)	290 cm
Total weight per multi-parcel shipment	400 kg
Parcels per pickup location per day	20

📐
Volumetric weight
Volumetric weight = (L × W × H in cm) / 5000. Both limits apply per parcel: physical weight ≤ 32 kg and volumetric weight ≤ 70 kg.

❗️
Exceeding the limits
Parcels that exceed any of these limits may result in significant additional charges. If in doubt, book the shipment as freight.

🚚
More than 20 parcels per day?
Need more than 20 parcels/day from one location, or a fixed daily pickup? That requires a dedicated arrangement — contact [email protected] with your pickup location and average daily volume.

Value of goods & insurance

You can insure parcel shipments up to a goods value of € 40,000. Set the value of goods via the standard fields:

{
    "wantsInsurance": true,
    "valueOfGoodsAmount": 1500,
    "valueOfGoodsCurrency": "EUR"
}

Field	Notes
`wantsInsurance`	`true` to insure the shipment
`valueOfGoodsAmount`	Goods value — max € 40,000 for parcel
`valueOfGoodsCurrency`	`EUR`

Values above € 40,000 are not insurable via parcel; book such shipments as freight instead.

Available & unavailable services

Available add-ons

Service	Description	Surcharge
Signature required	Recipient signature on delivery	€ 1.65
Direct delivery	No rerouting or delivery to an alternative address	€ 2.08
Transport insurance	Up to € 40,000 goods value (see above)	per value

Not available for parcel

❌ Dangerous goods (incl. LQ / EQ).
❌ Neutral shipment (neutralData) — not supported for parcel.

Supported routes

Direction	Supported
Domestic DE → DE	✅
Export DE → EU	✅
Import EU → DE	✅
EU → EU (neither origin nor destination is DE)	❌ not offered

Good to know

Tracking is fully available to customers. Note that regular tracking only starts once the parcel is scanned at the pickup depot; before that there is only a pickup tracking status. Use the Track & Trace webhook or a customer tracking link.
Pickups can be scheduled up to 7 days in advance. A clear access description (and, if helpful, a note at the door for the driver) prevents most failed pickups.
Romania (UIT): Parcel shipments under 31.5 kg do not require a UIT code — regardless of goods value. This applies to parcel shipments only.
Address notes: For parcel, the free-text field is used for additional address information rather than break times / loading notes. Loading and unloading references do not apply to parcel.
Labels work the same way as for freight — see Print shipment label for an Order.