Dispatch Item Sets

You must send a dispatch item set with the EAN and quantity of each item in the shipment whenever possible. There may be some partners for whom it is not possible to send a dispatch item set for logistical reasons, but it should be treated as mandatory. If you do not submit a dispatch item set, we will use your final announced item set as the dispatch item set. In this case, the final announced item set must include all physical items shipped to Zalando.

If necessary, you may update the dispatch item set by POSTing a complete new set as many times as needed. Only the most recent dispatch item set is considered actual data.

When you are ready to lock your dispatch item set, send a dispatch confirmation. We will then set the shipping order state to ready_for_receive, and you will no longer be able to update the dispatch item set.

Note that we must receive a dispatch confirmation before our warehouses are able to receive goods.

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

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. For more information, see Shipping Notices API Headers in "Shipping Notices Overview."

Creating Dispatch Item Sets

Request Body

Include the EAN and quantity of all items you intend to ship with the shipment in the request body as shown:

{
  "items": [
    {
      "ean": "0191476239145",
      "quantity": 2
    }
  ]
}

Create Dispatch Item Set

To add a new dispatch item set to a shipping notice, use the following call to post a JSON request body like the one described above:

POST /zfs/shipping-notices/{shipping_notice_ID}/dispatch-item-sets/

The following example httpie call uses the local file dispatch.json as input to create a new dispatch item set:

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

Response Codes

HTTP Code	Meaning
`201`	Dispatch item set successfully created.
`400`	Error. Additional information included.

Updating Dispatch Item Sets

You may repeat the above operation and specify the same Shipping Notice ID to overwrite an existing dispatch item set with new data.

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

Note that only the most recent dispatch item set will be considered active data. Old versions of the announced item set will be maintained as historical records only.

Response Codes

HTTP Code	Meaning
`201`	Dispatch item set successfully updated.
`400`	Error. Additional information included.

Creating a Dispatch Confirmation

Note

We must receive a dispatch confirmation before our warehouses are able to receive goods.

A dispatch confirmation tells ZFS Operations that you are satisfied with your item set and are ready to request an inbound tour.

When you send a dispatch confirmation, we will change the state of the shipping notice from ready_for_dispatch to ready_for_receive. You will no longer be able to update the dispatch item set for this shipping notice.

If you have not created a dispatch item set, the most recent announced item set will be considered the final item set.

Do not send more than one dispatch confirmation for each shipping notice, or you will cause conflicts.

To make a dispatch confirmation, make the following call with no request body:

POST /zfs/shipping-notices/{shipping_notice_ID}/dispatch-confirmations

Response Codes

HTTP Code	Meaning
`201`	Dispatch confirmation successfully created.
`400`	Error. Additional information included.

Getting Dispatch Item Sets

Getting All Dispatch Item Sets

To get all dispatch item sets for a shipping notice:

GET /zfs/shipping-notices/{shipping_notice_ID}/dispatch-item-sets

The request returns a paginated query result containing a list of dispatch item sets for the specified shipping notice, sorted by creation time in descending order.

The returned JSON is in this format:

{
  "dispatchitem-sets": [
    {
      "self": "string",
      "items": [
        {
          "ean": "0191476239145",
          "quantity": 2,
          "sku": "TH341G023-K1100XL000",
          "validation_state": "string"
        }
      ],
      "items_total": 2,
      "items_valid": 2,
      "validation_state": "string",
      "validation_description": "string"
    }
  ],
  "next": "string"
}

Getting a Specific Dispatch Item Set

To get a specific dispatch item set:

/zfs/shipping-notices/{shipping_notice_ID}/dispatch-item-sets/{dispatch_item_set_ID}

The returned JSON will resemble this example:

{
  "self": "string",
  "items": [
    {
      "ean": "0191476239145",
      "quantity": 0,
      "sku": "TH341G023-K1100XL000",
      "validation_state": "string"
    }
  ],
  "items_total": 0,
  "items_valid": 0,
  "validation_state": "string",
  "validation_description": "string"
}

Dispatch Item Set ID

To get a dispatch item set ID, get all dispatch item sets, and you will find the dispatch item set ID in the self URL of the dispatch item set you are interested in:

"self": "https://api-sandbox.merchants.zalando.com/zfs/shipping-notices/{shipping_notice_ID}/dispatch-item-sets/{dispatch_item_set_id}",

In this example, the dispatch item set ID is fe86ae8c-d9f7-4020-a7d3-7937c586249b:

{
  "dispatch_item_sets": [
    {
      "self": "https://api-sandbox.merchants.zalando.com/zfs/shipping-notices/60b65f3f-1937-430f-b338-07076cd72293/dispatch-item-sets/fe86ae8c-d9f7-4020-a7d3-7937c586249b",
      ...

Response Codes

HTTP Code	Meaning
`200`	Dispatch item set or sets returned in reply body.
`400`	Error. Additional information included.

Contact Support