Pickup Orders

Create scheduled recurring pickup orders. DPD will collect parcels from your location on specified days and time windows.

Endpoint	Auth
`POST /api/v1/pickup-orders`	Bearer JWT token required

Request

Query parameter: lang (optional) — e.g., de_CH, en_US, fr_CH, it_CH

Body: List<PickupOrderDTO>

Fields

Field	Type	Length	Required	Description
`invoicingNumber`	String	1–20	Mandatory	Customer billing number
`pickupDate`	String	10	Mandatory	Scheduled pickup date (`yyyy-MM-dd`), must be future
`weekDay`	Integer	—	Optional	Day of week (1=Mon … 7=Sun). Auto-calculated from `pickupDate` if omitted
`fromTime1`	String	5	Optional	Morning time window start (`HH:mm`)
`toTime1`	String	5	Optional	Morning time window end (`HH:mm`)
`fromTime2`	String	5	Optional	Afternoon time window start (`HH:mm`)
`toTime2`	String	5	Optional	Afternoon time window end (`HH:mm`)
`address`	AddressDTO	—	Mandatory	Pickup location address
`numberOfParcels`	Integer	—	Mandatory	Expected number of parcels (1–99)
`tour`	String	0–50	Optional	Tour/route identifier
`clientSoftware`	String	1–30	Mandatory	Client application name. The request is rejected if this is missing or blank
`clientVersion`	String	1–10	Mandatory	Client application version. The request is rejected if this is missing or blank

Time windows

You can specify up to two time windows (morning and afternoon). Leave afternoon fields empty for a single continuous window.

Window	Fields	Example
Morning	`fromTime1` / `toTime1`	`08:00` / `12:00`
Afternoon	`fromTime2` / `toTime2`	`13:00` / `17:00`

Example

curl -X POST "https://label-print-shipments.dpd.ch/api/v1/pickup-orders?lang=de_CH" \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "invoicingNumber": "12345678",
      "pickupDate": "<next working day, yyyy-MM-dd>",
      "weekDay": 5,
      "fromTime1": "08:00",
      "toTime1": "12:00",
      "fromTime2": "13:00",
      "toTime2": "17:00",
      "numberOfParcels": 15,
      "address": {
        "name": "Warehouse Location A",
        "countryCode": "CH",
        "zipCode": "8000",
        "city": "Zürich",
        "street": "Industriestrasse 45",
        "phone": "+41441234567",
        "email": "warehouse@company.ch",
        "reference": "WAREHOUSE-A"
      },
      "tour": "TOUR-ZH-WEST",
      "clientSoftware": "Customer App",
      "clientVersion": "4.0.0"
    }
  ]'

Response

201 Created — all orders created:

{
  "tracingId": "TRACE-321",
  "success": [
    { "tracingId": "123456789" }
  ],
  "failed": []
}

Each success[] item carries the tracingId assigned to the created order, plus identificationNumber echoed back when the request item supplied one. There is no id on a success item — id appears only on failed[] items.

Null fields are omitted from responses, so a success item commonly contains nothing but tracingId.

207 Multi-Status — partial success with field-level errors. Each failed[] item carries an identificationNumber (echoes the client-supplied value, when the request item had one), an errorCode; field violations are a flat fieldErrors[] array, each entry with its own path:

{
  "tracingId": "TRACE-322",
  "success": [],
  "failed": [
    {
      "identificationNumber": "client-supplied-id-5",
      "errorCode": "SYS-VALIDATION-FAILURE",
      "fieldErrors": [
        {
          "path": "numberOfParcels",
          "code": "SHP-VAL-NUMBEROFPARCELS-MAX-CHARACTERS",
          "message": "Number of parcels exceeds the maximum allowed length."
        },
        {
          "path": "address.countryCode",
          "code": "SHP-VAL-COUNTRYCODE-REQUIRED",
          "message": "Country code is required."
        }
      ]
    }
  ]
}

A transient failure (no fieldErrors — an outage is not a field problem) looks like this instead:

{
  "identificationNumber": "client-supplied-id-7",
  "errorCode": "SHP-ROUTING-ENGINE-UNAVAILABLE",
  "reason": "SHP-ROUTING-ENGINE-UNAVAILABLE: Routing engine is temporarily unavailable. Please try again."
}

Status codes:

Code	Description
`201 Created`	All pickup orders created
`207 Multi-Status`	Some succeeded, some failed
`400 Bad Request`	Validation error, or every item in the batch failed (whatever the cause, including a routing-engine outage)
`401 Unauthorized`	Missing or invalid token

Difference from Collection Requests

	Pickup Orders	Collection Requests
Frequency	Recurring (weekly schedule)	One-time
Time windows	Up to 2 (morning + afternoon)	Defined by DPD
Parcels limit	99	999
Weight field	Not required	Optional (grams)

Request​

Fields​

Time windows​

Example​

Response​

Difference from Collection Requests​