Creating and Updating Shipping Notices

When you are ready to prepare a shipment for delivery to a Zalando Warehouse, use the Shipping Notices API to create your shipping notice and to update it, if necessary.

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.

Header Requirements

When creating a shipping notice for the first time, If-Match header shouldn't be provided.

Once a shipping notice has been created, all PUT and POST calls to the Shipping Notices API require an If-Match header with a valid ETag value for the shipping notice, and a content-type header with the value application/json. If for some reason the ETag value is unknown, then you can do a GET request for the intended resource and you will receive the latest ETag value in the response. For more information, see Shipping Notices API Headers in "Shipping Notices Overview."

Creating a Shipping Notice

Request Body

Use the following template as a guide for constructing the request body of your call:

{
  "zalando_merchant_id": "string",
  "carrier_name": "DHL",
  "requested_zalando_location_id": "string",
  "requested_zalando_location_name": "string",
  "pallets_count": 0,
  "colli_count": 0,
  "hanging_goods_count": 0,
  "earliest_delivery_date": "2020-04-21",
  "merchant_b2b_reference": "string",
  "contact_name": "string",
  "contact_email": "some_merchant@acme.com",
  "additional_contact_email": "some_merchant@acme.com",
  "comments": "string",
  "announced_items": {
    "items": [
      {
        "ean": "0123456789998", 
        "quantity": 0
      },
      {
        "ean": "0123456789999",
        "quantity": 0
      }
    ]
  }
}

Values for earliest_delivery_date must be specified using the format YYYY-MM-DD.

Create Shipping Notice

To create a new shipping notice entity in zDirect, use the following call:

POST /zfs/shipping-notices

The Shipping Notice ID will be automatically generated once the creation is successful.

The following example http call uses the local file notice.json as input to create a new shipping notice:

http POST \
https://api-sandbox.merchants.zalando.com\
/zfs/shipping-notices \
"Authorization:Bearer $YOUR_ACCESS_TOKEN" \
content-type:application/json \
if-match:$ETag_VALUE \
< notice.json

Updating Shipping Notices

If you need to update your shipping notice, use the PUT endpoint and specify the Shipping Notice ID to overwrite an existing shipping notice with new data.

You must submit a complete new request body and cannot, for example, update only a single attribute.

Please use the following call:

PUT /zfs/shipping-notices/{shipping_notice_ID}

If you update a shipping notice, any associated announced item sets and dispatch item sets will not be overwritten.

Note that only the most recent version of the shipping notice will be considered active data. Old versions of shipping notices will be maintained as historical records only.

Response Codes

HTTP Code Meaning
201 Shipping notice successfully created.
204 Shipping notice successfully updated.
400 Error. Additional information included.
500 Please contact zDirect Technical Support.
Contact Support