Generating Shipping Documents

Use the Shipping Documents API to generate the shipping documents needed to ship a ZSS parcel.

You may use the Shipping Documents API to generate the following documents:

Outbound Labels: Outbound (Shipping) labels display the key information for a carrier to transport a package to its end destination.

Return Labels: Each package must contain a pre-paid and pre-printed return label to enable the customer to return easily and free of charge.

Delivery Slips: A delivery note/slip accompanies the delivery of goods, specifying their type and quantity. This document serves as confirmation of the articles delivered to the end-customer and provides additional information (e.g. customer care contact, order number, bank details).

Printing guideline

The above documents have to be printed with the following specifications:

Document type Size Resolution
Outbound labels A6 (10.5 x 14.8 cm) 300dpi
Return labels A6 (10.5 x 14.8 cm) 300dpi
Delivery slips A4

Authentication

The zDirect API requires OAuth 2.0 authentication for all API calls. Use the Authentication API to generate access tokens as described in the Authentication section.

Getting Shipping Documents

You may get shipping documents either for the specified order ID or the specified shipment number. First you need to request the list of available documents as a json, and the download each document pdf separately. Here's a diagram that illustrates the flow of documents creation on Zalando side and their retrieval.

ZSS shipping documents flow

Get Shipping Documents list by Order ID

To request shipping documents for a Zalando Order ID:

GET /zss/shipping-documents?order_id={order_id}

Using httpie, this call would look like this:

http GET \
https://api-sandbox.merchants.zalando.com/zss\
/shipping-documents?order_id={order_id} \
"Authorization:Bearer $YOUR_ACCESS_TOKEN"

Response: Successful

You will receive an HTTP 200 reply to a successful request.

{
  "documents": [
    {
      "id": "9efd2e6c-c798-45e8-860d-4f3f5f55721a",
      "shipment_id": "decf4186-498d-40ed-9e9e-18cb4296717a",
      "order_id": "824ef3ec-d937-485d-a42d-3e10a52f8bf9",
      "shipment_number": "SN1234567890",
      "type": "OUTBOUND_LABEL",
      "parcel_id": "a6fd278d-f797-25e8-a60d-3f3f5f557ccc",
      "tracking_id": "trackingid1",
      "tracking_url": "https://tracking.url"
    },
    {
      "id": "9efd2e6c-c798-45e8-860d-4f3f5f55721b",
      "shipment_id": "decf4186-498d-40ed-9e9e-18cb4296717a",
      "order_id": "824ef3ec-d937-485d-a42d-3e10a52f8bf9",
      "shipment_number": "SN1234567890",
      "type": "RETURN_LABEL",
      "parcel_id": "a6fd278d-f797-25e8-a60d-3f3f5f557ccc",
      "tracking_id": "trackingid2",
      "tracking_url": "https://tracking.url"
    },
    {
      "id": "9efd2e6c-c798-45e8-860d-4f3f5f55721c",
      "shipment_id": "decf4186-498d-40ed-9e9e-18cb4296717a",
      "order_id": "824ef3ec-d937-485d-a42d-3e10a52f8bf9",
      "shipment_number": "SN1234567890",
      "type": "DELIVERY_SLIP"
    }
  ],
  "query": {
    "order_id": "824ef3ec-d937-485d-a42d-3e10a52f8bf9"
  }
}

Response: Error

You may get a http 400 - Bad Request response, if you either don't provide any filters in the request, or if a given order id is not in the uuid format.

Note

The generation of labels is undertaken asynchronously, which may result in increased delays. If you encounter missing labels, please attempt to download the missing label again after waiting for a period of 15-30 minutes.

Downloading Shipping Document file

To download a shipping document file, use the corresponding document's id from the response above. Use it to call the following API:

GET zss/shipping-documents/$ZALANDO_DOCUMENT_UUID

Using httpie, this call would look like this:

http GET \
https://api-sandbox.merchants.zalando.com/zss\
/shipping-documents/$ZALANDO_DOCUMENT_UUID \
"Authorization:Bearer $ZDIRECT_ACCESS_TOKEN"

You will receive an HTTP 200 reply to a successful request. By default, this API will respond with a raw PDF-document file content.

Getting Shipping Document details

If you want to get more details of any document, please set the Accept header value to application/json:

Using httpie, this call would look like this:

http GET \
https://api-sandbox.merchants.zalando.com/zss\
/shipping-documents/$ZALANDO_DOCUMENT_UUID \
"Accept: application/json"\
"Authorization:Bearer $ZDIRECT_ACCESS_TOKEN"

Response: Successful

{
  "id": "9efd2e6c-c798-45e8-860d-4f3f5f55721d",
  "shipment_id": "decf4186-498d-40ed-9e9e-18cb4296717a",
  "order_id": "824ef3ec-d937-485d-a42d-3e10a52f8bf9",
  "shipment_number": "SN1234567890",
  "type": "RETURN_LABEL",
  "parcel_id": "a6fd278d-f797-25e8-a60d-3f3f5f557ccc",
  "tracking_id": "tracking_id",
  "tracking_url": "https://tracking.url"
}

Response: Error

An unsuccessful query might return the following HTTP codes:

  • 400 - Bad Request if the document id is not in uuid format.
  • 404 - Not Found if the given document doesn't exist.
  • 410 - Gone if the shipping document is no longer available: the shipment was either shipped or cancelled.

With any error, a json body describing the problem is returned. For example, the following reply indicates that a malformed id was provided:

{
  "status": 400,
  "detail": "Parameter documentId has invalid format: can not convert String to UUID"
}

Additional Resources

Contact Support