Shipments

Create one or multiple shipments in a single request. The API validates all fields, generates parcel numbers, enriches routing data, and returns PDF labels.

Endpoint: POST /api/v1/shipments Auth: Bearer JWT token required

---

Create Shipment

Request

Content-Type: application/json Body: array of shipment objects

[
  {
    "invoicingNumber": "12345678",
    "serviceCode": "PSD",
    "sender": { },
    "receiver": { },
    "parcelInfo": [ ],
    "customsData": { },
    "printOptions": { }
  }
]

Shipment root fields

Field	Type	Length	Required	Description
invoicingNumber	String	1–20	Mandatory	Customer billing number
numberOfParcels	Integer	—	Mandatory	Total parcels (1–20)
customerReferenceNumber1	String	0–35	Optional	Customer reference 1
customerReferenceNumber2	String	0–35	Optional	Customer reference 2
customerReferenceNumber3	String	0–35	Optional	Customer reference 3
customerReferenceNumber4	String	0–35	Optional	Customer reference 4
shipmentNote	String	0–70	Optional	Shipment note
parcelShopId	String	—	Conditional	Required for ParcelShop delivery services
clientSoftware	String	1-30	Optional	Client application name
clientVersion	String	1-10	Optional	Client application version

Address fields (sender / receiver / return)

Field	Type	Length	Required	Notes
name	String	1–35	Mandatory	Company or person name
name2	String	0–35	Optional	Additional name line
contact	String	0–35	Optional	Contact person
countryCode	String	2	Mandatory	ISO 3166-1 alpha-2
stateCode	String	2	Conditional	Required for US/CA
zipCode	String	1–9	Mandatory	Postal code
city	String	1–35	Mandatory	City
street	String	1–35	Mandatory	Street name and number
street2	String	0–35	Optional	Additional address line
houseNumber	String	0–8	Conditional	House Number
phone	String	0–30	Conditional	Required for GB — international format +CCNNNNNN
email	String	0–50	Conditional	Required for non-CH/LI countries (except GB)
eori	String	0–22	Conditional	Required for GB/NO international
vat	String	0–20	Conditional	Required for GB/NO international (non-CH)
language	String	2	Optional	ISO 639-1 (DE, EN, FR, IT)
reference	String	0–35	Optional	Address reference
note	String	0–70	Optional	Delivery instructions
gln	String	0–13	Optional	Global Location Number

Parcel info (parcelInfo[])

Array of parcel objects — one entry per physical parcel. The number of entries should match numberOfParcels.

Field	Type	Length	Required	Description
serviceCode	String	—	Mandatory	Parcel-level service code
optionCodes	Array<String>	—	Optional	Additional service option codes
content	String	—	Optional	Parcel content description (PCONTENT)
weight	Integer	—	Optional	Parcel weight in grams
reference1	String	0–35	Optional	Parcel reference 1
reference2	String	0–35	Optional	Parcel reference 2
reference3	String	—	Optional	Parcel reference 3
reference4	String	—	Optional	Parcel reference 4
higherInsurance	Object	—	Optional	Higher-insurance additional service (see below)
limitedQuantities	Object	—	Optional	Limited-quantities dangerous-goods data (see below)

higherInsurance fields:

Field	Type	Length	Required	Description
amount	Number	—	Mandatory	Insured amount
currency	String	3	Mandatory	ISO 4217 currency code

limitedQuantities fields:

Field	Type	Length	Required	Description
unNumber	String	—	Optional	UN dangerous-goods number
code	String	—	Optional	Substance code
packagingGroup	String	—	Optional	Packaging group
klass	String	—	Optional	Dangerous-goods class
subWeight	Integer	—	Optional	Substance weight

Customs data (customsData)

Required for international (non-domestic customs) shipments.

Field	Type	Length	Required	Description
shipmentType	String	1	Mandatory	Parcel type (PARCELTYPE)
value	Number	—	Mandatory	Customs value of goods (CAMOUNT)
currency	String	3	Optional	ISO 4217 currency for value
valueEx	Number	—	Optional	Additional customs value (CAMOUNTEX)
currencyEx	String	3	Optional	ISO 4217 currency for valueEx
reasonForExport	String	2	Mandatory	Reason-for-export code
termsOfDelivery	String	2	Mandatory	Incoterms / terms of delivery (CTERMS)
clearanceCleared	String	1	Mandatory	Clearance-cleared flag
opCode	String	3	Optional	Operation code
preAlertStatus	String	3	Optional	Pre-alert status
content	String	0–35	Optional	Customs content description (CCONTENT)
paper	String	1	Optional	Paperwork flag (CPAPER)
highLowValue	String	1	Optional	High/low value indicator
invoiceNumber	String	0–35	Optional	Commercial invoice number (CINVOICE)
date	Date (yyyy-MM-dd)	—	Mandatory	Invoice date (CINVOICEDATE)
exportMRN	String	0–209	Optional	Export Movement Reference Number (SHIPMRN)
documentTypes	Array<String>	≤20 items	Optional	Customs document types
comment	String	0–70	Optional	Customs comment (CCOMMENT)
comment2	String	0–70	Optional	Destination country registration (DESTCOUNTRYREG)
senderHMRC	String	0–15	Optional	Sender HMRC registration
senderInvoicingAddress	Object	—	Optional	Sender invoice address (address object)
receiverInvoicingAddress	Object	—	Optional	Recipient invoice address (address object)
numberOfInvoiceLines	Integer	—	Optional	Number of invoice lines (NUMBEROFARTICLE)
invoiceLines	Array<Object>	—	Conditional	Invoice line items (see below). Count between number of parcels and number of parcels + 20

invoiceLines[] fields:

Field	Type	Length	Required	Description
natureOfGoods	String	0–200	Optional	Nature of goods (CCONTENT)
hsCode	String	0–11	Optional	HS tariff code
productCode	String	0–255	Optional	Product code (CPRODCODE)
amount	Number	—	Optional	Line amount (CAMOUNTLINE)
grossWeight	Integer	—	Optional	Gross weight (CGROSSWEIGHT)
qItems	Integer	—	Mandatory	Quantity of items
countryOfOrigin	String	3	Optional	ISO country of origin (CORIGIN)

Print options

Field	Type	Required	Description
paperSize	String	Optional	A4 or A6 (default: A4)
startPosition	String	Optional	Label position on A4 sheet: UPPER_LEFT, UPPER_RIGHT, BOTTOM_LEFT, BOTTOM_RIGHT

---

Response

201 Created — all shipments created:

{
  "tracingId": "TRACE-123",
  "success": [
    {
      "id": 1,
      "parcelNumber": "05305000123456",
      "label": "base64-encoded-PDF..."
    }
  ],
  "failed": []
}

207 Multi-Status — partial success:

{
  "tracingId": "TRACE-456",
  "success": [ { "id": 1, "parcelNumber": "05305000123456", "label": "..." } ],
  "failed": [
    {
      "id": 2,
      "fieldErrors": {
        "receiver.countryCode": ["NOT_SUPPORTED"],
        "receiver.email": ["REQUIRED_FOR_INTERNATIONAL"]
      }
    }
  ]
}

Status codes:

Code	Description
201 Created	All shipments created successfully
207 Multi-Status	Some succeeded, some failed
400 Bad Request	Invalid request payload
401 Unauthorized	Missing or invalid token

---

Example

curl -X POST "https://label-print-shipments.dpd.ch/api/v1/shipments" \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "invoicingNumber": "12345678",
      "serviceCode": "PSD",
      "numberOfParcels": 1,
      "sender": {
        "name": "Sender AG",
        "countryCode": "CH",
        "zipCode": "8000",
        "city": "Zürich",
        "street": "Industriestrasse 25"
      },
      "receiver": {
        "name": "Receiver GmbH",
        "countryCode": "DE",
        "zipCode": "10115",
        "city": "Berlin",
        "street": "Alexanderplatz 1",
        "email": "info@receiver.de"
      },
      "parcelInfo": [
        { "weight": 2500 }
      ],
      "printOptions": {
        "paperSize": "A6"
      }
    }
  ]'

---

Print Manifest

Generate a manifest PDF that lists the shipments handed over to DPD for a given invoicing number. Supports traceability for the day's pickup — the file is returned as a PDF attachment and is intended to be printed and kept with the parcels.

Endpoint: POST /api/v1/shipments/print-manifest Produces: application/pdf Auth: Bearer JWT token required

The endpoint returns shipments owned by the authenticated user only. Filter the result with a date range (fromDate/toDate, applied to importedAt) and/or an explicit list of parcelNumbers — at least one of the two filters is required.

Request

Content-Type: application/json

{
  "invoicingNumber": "12345678",
  "fromDate": "2026-03-25",
  "toDate": "2026-04-29",
  "parcelNumbers": ["05305000123456", "05305000123457"],
  "address": {
    "reference": "PICKUP-001"
  },
  "printSettings": {
    "printRecipientReference": true,
    "printParcelReference1": true,
    "printParcelReference2": true,
    "printUserName": true,
    "printWeight": true,
    "sortOrderForManifest": "CONSIGNEE_ZIP"
  }
}

Field	Type	Required	Description
invoicingNumber	String	Mandatory	Invoicing number scoping the manifest
fromDate	Date (yyyy-MM-dd)	Conditional	Inclusive lower bound of importedAt. Required when parcelNumbers is not provided. Must be provided together with toDate
toDate	Date (yyyy-MM-dd)	Conditional	Inclusive upper bound of importedAt. Required when parcelNumbers is not provided. Must be provided together with fromDate
parcelNumbers	Array<String>	Conditional	Restrict the manifest to specific parcel numbers. Required when no date range is provided
address	Object	Optional	Pickup address used to scope the manifest. Only reference is read; all other address fields are ignored. The reference is resolved against the customer configuration. When omitted and the result set spans multiple pickups, the first encountered pickup is used and other shipments are silently dropped
printSettings	Object	Mandatory	Print settings applied to the generated manifest

printSettings fields

Field	Type	Required	Description
printRecipientReference	Boolean	Optional	Print the recipient reference column
printParcelReference1	Boolean	Optional	Print parcel reference 1
printParcelReference2	Boolean	Optional	Print parcel reference 2
printUserName	Boolean	Optional	Print the user name on the manifest
printWeight	Boolean	Optional	Print the parcel weight column
sortOrderForManifest	Enum	Mandatory	Sort order for shipments on the manifest

sortOrderForManifest values:

Value	Description
CONSIGNEE_ZIP	Sort by consignee zip code
CONSIGNEE_COUNTRY	Sort by consignee country
CONSIGNEE_NAME	Sort by consignee name
REFERENCE_1	Sort by parcel reference 1
PARCEL_NUMBER	Sort by parcel number

Common use case — today's manifest

The most frequent integration pattern is generating the manifest for shipments imported today, right before the driver pickup. Set fromDate and toDate to today's date (UTC days) and omit parcelNumbers to include everything for that invoicing number on that day:

{
  "invoicingNumber": "12345678",
  "fromDate": "2026-05-26",
  "toDate": "2026-05-26",
  "printSettings": {
    "printRecipientReference": true,
    "printParcelReference1": true,
    "printUserName": true,
    "printWeight": true,
    "sortOrderForManifest": "CONSIGNEE_ZIP"
  }
}

TODAY=$(date -u +%F)
curl -X POST "https://label-print-shipments.dpd.ch/api/v1/shipments/print-manifest" \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -o manifest.pdf \
  -d "{
    \"invoicingNumber\": \"12345678\",
    \"fromDate\": \"$TODAY\",
    \"toDate\": \"$TODAY\",
    \"printSettings\": {
      \"printRecipientReference\": true,
      \"printParcelReference1\": true,
      \"printUserName\": true,
      \"printWeight\": true,
      \"sortOrderForManifest\": \"CONSIGNEE_ZIP\"
    }
  }"

Notes:

• fromDate/toDate are matched against importedAt in UTC (start-of-day to end-of-day). Shipments imported after midnight UTC the next calendar day in your local zone will not appear.
• Provide address: {"reference": "PICKUP-001"} to scope to a specific pickup when the user has multiple.

Response

200 OK — manifest generated; body is the PDF stream.

Header	Value
Content-Type	application/pdf
Content-Disposition	attachment; filename="manifest.pdf"
Content-Length	PDF size in bytes

Status codes

Code	Description
200 OK	Manifest generated
400 Bad Request	Missing/invalid filter (e.g. only one of fromDate/toDate set, fromDate after toDate, both date range and parcelNumbers empty, missing printSettings, unresolvable address.reference)
401 Unauthorized	Missing or invalid token
404 Not Found	No shipments match the filter, or none match the requested pickup

Example

curl -X POST "https://label-print-shipments.dpd.ch/api/v1/shipments/print-manifest" \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -o manifest.pdf \
  -d '{
    "invoicingNumber": "12345678",
    "fromDate": "2026-03-25",
    "toDate": "2026-04-29",
    "parcelNumbers": ["05305000123456", "05305000123457"],
    "address": {
      "reference": "PICKUP-001"
    },
    "printSettings": {
      "printRecipientReference": true,
      "printParcelReference1": true,
      "printParcelReference2": true,
      "printUserName": true,
      "printWeight": true,
      "sortOrderForManifest": "CONSIGNEE_ZIP"
    }
  }'