Generating Shipping Documents

The Shipping Documents API is used to generate the shipping documents provided by Zalando for a Zalando Return Solutions (ZRS) parcel.

Please note: If you are going live with Zalando Shipment Solutions (ZSS) for outbound shipment to customers combined with ZRS as return service, then use this page for shipping documents enablement.

For outbound with Own logistics and return with ZRS, use the Shipping Documents API to generate the following documents:

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.

Printing guideline

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

Document type Size Resolution
Return labels A6 (10.5 x 14.8 cm) 300dpi

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.

ZRS shipping documents flow

Get Shipping Documents list by Order ID

To request shipping documents for a Zalando Order ID:

GET /zrs/shipping-documents?order_id=$ZALANDO_ORDER_UUID

Using httpie, this call would look like this:

http GET \
https://api-sandbox.merchants.zalando.com/zrs\
/shipping-documents?order_id=$ZALANDO_ORDER_UUID \
"Authorization:Bearer $ZDIRECT_ACCESS_TOKEN"

Response: Successful

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

{
  "documents": [
    {
      "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"
    }
  ],
  "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.

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 zrs/shipping-documents/$ZALANDO_DOCUMENT_UUID

Using httpie, this call would look like this:

http GET \
https://api-sandbox.merchants.zalando.com/zrs\
/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/zrs\
/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