Announced Item Sets

An announced item set includes the EANs and quantities of all items you plan to include in a shipment. Each shipping notice has only one active announced item set, which must include all items in the shipment.

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

When you are ready to lock your shipment, send an announcement confirmation. We will then set the shipping order state to ready_for_delivery_date, and you will no longer be able to update the announced item set. If you must make changes after this point, you will need to create a new shipping notice with a new shipping notice ID or contact zDirect Technical Support.

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 Announced 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 Announced Item Set

To add a new announced 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}/announced-item-sets

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

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

Response Codes

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

Updating Announced Item Sets

You may repeat the above operation and specify the same Shipping Notice ID to overwrite an existing announced 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 announced 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`	Announced item set successfully updated.
`400`	Error. Additional information included.

Sending an Announcement Confirmation

When you are ready to finalize your announced item set and you would like us to begin calculating your delivery date, use the Shipping Notices API to send an announcement confirmation to ZFS Operations.

Once we receive an announcement confirmation, we will change the shipping notice state to ready_for_delivery_date. You will no longer be able to update the announced item set for this shipping notice.

To send an announcement confirmation, make the following call with no request body:

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

The following example illustrates a valid httpie request to confirm the announcement:

http POST \
https://api-sandbox.merchants.zalando.com\
/zfs/shipping-notices/{shipping_notice_ID}/announcement-confirmations \
"Authorization:Bearer $YOUR_ACCESS_TOKEN" \
if-match:$ETag_VALUE

Response Codes

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

Getting Announced Item Sets

Getting All Announced Item Sets

To get all announced item sets for a shipping notice:

GET /zfs/shipping-notices/{shipping-notice-id}/announced-item-sets

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

This example illustrates the format of the returned JSON:

{
  "announced_item_sets": [
    {
      "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"
    }
  ],
  "next": "string"
}

Getting a Specific Announced Item Set

To get a specific announced item set:

GET /zfs/shipping-notices/{shipping_notice_ID}/announced-item-sets/{announced_item_set_ID}

The returned JSON will resemble the example shown above.

Announced Item Set ID

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

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

In this example, the announced item set ID is a0855da9-18c4-4c09-a99d-3f5af7099b0c:

{
  "announced_item_sets": [
    {
      "self": "https://api-sandbox.merchants.zalando.com/zfs/shipping-notices/60b65f3f-1937-430f-b338-07076cd72293/announced-item-sets/a0855da9-18c4-4c09-a99d-3f5af7099b0c",
      ...

Response Codes

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

Contact Support