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

---

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–99)
serviceCode	String	—	Mandatory	DPD service code (PSD, PSI, PL, PBOX, RET)
mpsId	String	—	Optional	Master Parcel Shipment ID for grouping
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–255	Optional	Shipment note
parcelShopId	String	—	Conditional	Required for ParcelShop delivery services
clientSoftware	String	—	Optional	Client application name
clientVersion	String	—	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	Required for NL
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

Print options

Field	Type	Required	Description
labelFormat	String	Optional	A4 or A6 (default: A4)
labelStartPosition	Integer	Optional	Label position on A4 sheet (1–4)

---

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": {
        "labelFormat": "A6"
      }
    }
  ]'