Shipping Notices Overview

When you need to ship articles to Zalando Warehouses, use the Shipping Notices API to communicate with ZFS Operations about planned shipments.

Shipping Notices

A shipping notice is a container for two types of data sets about your shipments:

  • Announced Item Sets: A declaration of all the items that you plan to ship to Zalando, specified as EANs and quantities.
  • Dispatch Item Sets: Similar to an announced item set, a dispatch item set is used as the final declaration of all items in a shipment.

Providing dispatch item sets is not mandatory, but we strongly recommend doing so whenever possible. When they are not provided, the last announced item set will be used as the dispatch item set.

All items in an item set are considered one shipment, even if they physically ship on more than one truck.

Item sets may be updated until you confirm that they are finalized. When you update an item set, the new item set overwrites the previous version. We retain a record of old versions for historical purposes, but only the most recent item set is considered valid data.

Shipping Overview

Shipping articles to Zalando Warehouses has the following steps.

  1. Partner PUTs a new shipping notice to the API along with a Shipping Notice ID (v4 UUID) that they provide. We set the shipping notice state to initial.
  2. Partner GETs the shipping notice and records its Advice ID.
  3. Partner creates an announced item set and PUTs it to the shipping notice.
  4. If necessary, partner resubmits an updated announced item set as many times as needed.
  5. When the planned shipment is ready, partner POSTs an announcement confirmation. We set the shipping notice state to ready_for_delivery_date. The announced item set can not longer be modified, and any new changes will require creating a new shipping notice or contacting zDirect Technical Support.
  6. ZFS Operations sets a delivery date for the shipment based on customer request, Warehouse capacity, and other factors.
  7. Partner GETs the shipping notice regularly until the delivery date is set.
  8. Once the partner has the delivery date, they prepare the actual shipment for that date.
  9. Partner POSTs a dispatch item set with final declaration of shipment contents. We set the shipping notice state to ready_for_dispatch.
  10. Partner sends dispatch confirmation and we set the shipping notice state to ready_for_receive. Note that we must receive a dispatch confirmation before our warehouses are able to receive goods.
  11. Partner ships items.
  12. Partner can use the Tours endpoint to track shipments, and the Stock Movements API to track the inbound receive process.

All of these steps are described in greater detail below.

Shipping Notice Example

The following example shows a complete shipping notice:

{
  "self": "https://api-sandbox.merchants.zalando.com/zfs/shipping-notices/e7eab8ae-38e1-427b-950d-466bea9df67a",
  "zalando_merchant_id": "your_merchant_identifier",
  "zalando_advice_id": "99200000",
  "merchant_b2b_reference": "some merchant specific location reference",
  "comments": "some additional message to ZFS operations team",
  "requested_zalando_location_id": "b6f6cf2b-5e63-4693-a658-99748b871d7e",
  "carrier_name": "DHL",
  "pallets_count": 1,
  "colli_count": 10,
  "hanging_goods_count": 0,
  "earliest_delivery_date": "2024-03-05T00:00:00+01:00",
  "contact_email": "some_merchant@acme.com",
  "state": "ready_for_receive",
  "delivery_type": "palletized",
  "last_modified_date": "2024-03-07T12:04:28.346989Z",
  "ticket_id": "AVS-1336677",
  "last_announced_item_set_resource_id": "c89eccb5-f04f-46bc-af0c-a0b17cc4cc3c",
  "announced_item_sets": "https://api-sandbox.merchants.zalando.com/zfs/shipping-notices/e7eab8ae-38e1-427b-950d-466bea9df67a/announced-item-sets",
  "dispatch_item_sets": "https://api-sandbox.merchants.zalando.com/zfs/shipping-notices/e7eab8ae-38e1-427b-950d-466bea9df67a/dispatch-item-sets",
  "bookings": [
    {
      "resource_id": "e5a66d99-10dd-421f-8c04-e2d3683d8f26",
      "shipping_notice_resource_id": "1d5533dc-e116-43d6-afb2-4548dfb9ff1a",
      "requested_delivery_date": "2024-03-15",
      "requested_location_id": "b6f6cf2b-5e63-4693-a658-99748b871d7e",
      "confirmed_location_id": "b6f6cf2b-5e63-4693-a658-99748b871d7e",
      "confirmed_at": "2024-03-07T12:01:06.779666Z",
      "confirmed_delivery_date": "2024-03-15",
      "created_at": "2024-03-07T12:01:04.459292Z",
      "created_by": "Name of the creator of the shipping notice",
      "confirmed_by": "Name of the person who confirmed the shipping notice",
      "automatically_scheduled": true,
      "booking_type": "booking | rebooking",
      "ticket_id": "AVS-1336674",
      "source_system": "ZDIRECT",
      "created_by_user": "Ellen Högberg",
      "confirmed_by_user": "Ellen Högberg",
      "confirmed_by_system": "ZDIRECT"
    }
  ]
}

Shipping Notice ID and Zalando Advice ID

Each shipping notice has two unique identifiers, the Shipping Notice ID, and the Zalando Advice ID.

When you create a new shipping notice, you must provide a Shipping Notice ID. This value must be a unique v4 UUID.

When the new shipping notice is posted, we assign it a Zalando Advice ID. This ID is used to identify the shipment at the warehouse, and is required for some API calls.

To get the Zalando Advice ID for a shipping notice, get the shipping notice as described in Getting Shipping Notices.

Shipping Notice State

The status of a shipping notice is defined by the state attribute. The state is read-only and is controlled by Zalando.

For a description of shipping notice states and their meaning, see Shipping Overview above.

Shipping Notice Q&A

How do I select the "requested_zalando_location_id"?

Please align the preferred inbound location for your shipments with the ZFS-Ops team. Usually there are three different location IDs available, if no other location is provided and aligned with the ZFS-Ops team.

  • Moenchengladbach UUID: 1e57b2b6-907b-4676-8766-339a1d596e59
  • Erfurt UUID: 32eff430-f835-44ce-947a-4a1fdce1c615
  • Lahr UUID: b6f6cf2b-5e63-4693-a658-99748b871d7e

What is the "merchant_b2b_reference"?

It might be that for some reason you rather want to operate with your own identifier when shipment or inbound information is provided via APIs. You can put any value you like into this field, which has a 1 on 1 relation with shipping_notice and zalando_advice_ID.

This reference is also part of the Stock Movement Inbound tracking information.

Pallets and Colli count?

If you want to deliver just a few boxes (colli) you don't need to deliver on pallet. You can use a CEP carrier, hence a slot booking via Mercareon is not required.

Please note that for more than 9 colli a pallet count > 0 and a slot booking for truck delivery is required!

Shipping Notices API Headers

All PUT and POST calls to the Shipping Notices API require the following request headers:

  • An If-Match header with a valid ETag value for the shipping notice (details below), and
  • The content-type header with the value application/json.

Note

The first call to create the shipping notice does not require an ETag, as the resource does not yet exist.

The following example illustrates a valid httpie request with the required headers:

http POST
https://api-sandbox.merchants.zalando.com\
/zfs/shipping-notices/{shipping_notice_ID}/announcement-confirmations \
authorization:'Bearer $YOUR_ACCESS_TOKEN' \
content-type:application/json \
if-match:32668545-2b1a-4ac6-917b-2f36fa59623a \

If-Match Collision Detection

The Shipping Notices API uses ETag versioning for shipping notices and their sub-resources, including all announced item sets and dispatch item sets. This prevents problems caused by concurrent updates to the same resource.

When you make a request to get or modify a shipping notice or item set, the reply header will include the updated ETag for the shipping notice. You must provide the current shipping notice ETag as an If-Match value in the header of your next request. 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.

You may optionally include an If-None-Match header with any GET request for a shipping notice or sub-resource containing an ETag. If the specified ETag does match, then the Shipping Notices API will return the HTTP status code 304 (Not Modified) with an empty body. Otherwise you can just ignore adding the If-None-Match header for the GET request and you will still get the shipping notice or sub-resource in the response. Please be aware that these ETag values need to be stored on your side as they are later on needed for any PUT or POST requests.

For more information on ETags, see the ETag in the MDN Web Docs.

Contact Support